Esegui la migrazione della configurazione della build da Groovy a Kotlin

Il plug-in Android 4.0 per Gradle ha aggiunto il supporto per l'utilizzo di Kotlin nella configurazione della build Gradle in sostituzione di Groovy, il linguaggio di programmazione tradizionalmente utilizzato nei file di configurazione Gradle.

Kotlin è preferito rispetto a Groovy per la scrittura di script Gradle, perché Kotlin è più leggibile e offre un migliore controllo del tempo di compilazione e supporto per IDE.

Sebbene al momento Kotlin offra un'integrazione migliore nell'editor di codice di Android Studio rispetto a Groovy, le build che utilizzano Kotlin tendono ad essere più lente di quelle che utilizzano Groovy, quindi prendi in considerazione le prestazioni di compilazione quando decidi se eseguire la migrazione.

Questa pagina fornisce informazioni di base sulla conversione dei file di compilazione Gradle della tua app Android da Groovy a Kotlin. Per una guida più completa alla migrazione, consulta la documentazione ufficiale di Gradle.

Spostamenti

A partire da Android Studio Giraffe, i nuovi progetti utilizzano per impostazione predefinita il DSL Kotlin (build.gradle.kts) per la configurazione di build. Ciò offre un'esperienza di editing migliore rispetto al Groovy DSL (build.gradle) con evidenziazione della sintassi, completamento del codice e navigazione alle dichiarazioni. Per scoprire di più, consulta la Guida introduttiva a Gradle Kotlin DSL.

Termini comuni

DSL Kotlin: si riferisce principalmente al DSL Kotlin del plug-in Gradle per Android o, occasionalmente, al DSL Kotlin di Gradle sottostante.

In questa guida alla migrazione, i termini "Kotlin" e "Kotlin DSL" vengono utilizzati in modo intercambiabile. Analogamente, "Groovy" e "Groovy DSL" vengono utilizzati in modo intercambiabile.

Denominazione dei file di script

I nomi delle estensioni del file di script si basano sulla lingua in cui è scritto il file di build:

  • I file di build Gradle scritti in Groovy utilizzano l'estensione del nome file .gradle.
  • I file di compilazione di Gradle scritti in Kotlin utilizzano l'estensione del nome del file .gradle.kts.

Converti la sintassi

Esistono alcune differenze generali nella sintassi tra Groovy e Kotlin, quindi devi applicare queste modifiche a tutti gli script di build.

Aggiungere parentesi alle chiamate di metodo

Groovy consente di omettere le parentesi nelle chiamate al metodo, mentre Kotlin le richiede. Per eseguire la migrazione della configurazione, aggiungi le parentesi a questo tipo di chiamate ai metodi. Questo codice mostra come configurare un'impostazione in Groovy:

compileSdkVersion 30

Questo è lo stesso codice scritto in Kotlin:

compileSdkVersion(30)

Aggiungere = alle chiamate di assegnazione

Il DSL Groovy ti consente di omettere l'operatore di assegnazione = durante l'assegnazione delle proprietà, mentre Kotlin lo richiede. Questo codice mostra come assegnare proprietà in Groovy:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Questo codice mostra come assegnare le proprietà in Kotlin:

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Converti stringhe

Ecco le differenze tra le stringhe tra Groovy e Kotlin:

  • Virgolette doppie per le stringhe: mentre Groovy consente di definire le stringhe utilizzando virgolette singole, Kotlin richiede virgolette doppie.

  • Interpolazione di stringhe su espressioni tratteggiate: in Groovy, puoi utilizzare solo il prefisso $ per le interpolazioni di stringhe nelle espressioni tratteggiate, ma Kotlin richiede di racchiudere le espressioni tratteggiate con parentesi graffe. Ad esempio, in Groovy puoi utilizzare $project.rootDir come mostrato nel seguente snippet:

        myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"

    In Kotlin, tuttavia, il codice precedente chiama toString() su project, non su project.rootDir. Per ottenere il valore della directory principale, racchiudi l'espressione ${project.rootDir} tra parentesi graffe:

        myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"

    Per scoprire di più, consulta Modelli di stringhe nella documentazione di Kotlin.

Rinominare le estensioni dei file

Aggiungi .kts a ogni file di build man mano che esegui la migrazione dei relativi contenuti. Ad esempio, seleziona un file di build, come il file settings.gradle. Rinomina il file in settings.gradle.kts e converti i contenuti del file in Kotlin. Assicurati che il progetto venga ancora compilato dopo la migrazione di ogni file di compilazione.

Esegui la migrazione prima dei file più piccoli, acquisisci esperienza e poi passa ad altri. In un progetto è possibile avere una combinazione di file di build Kotlin e Groovy, quindi fai con attenzione lo spostamento.

Sostituisci def con val o var

Sostituisci def con val o var, che è il modo in cui definisci le variabili in Kotlin. Questa è una dichiarazione di variabile in Groovy:

def building64Bit = false

Si tratta dello stesso codice scritto in Kotlin:

val building64Bit = false

Prefisso le proprietà booleane con is

Groovy utilizza la logica di detrazione delle proprietà in base ai nomi delle proprietà. Per una proprietà booleana foo, i relativi metodi dedotti possono essere getFoo, setFoo o isFoo. Pertanto, una volta convertito in Kotlin, devi modificare i nomi delle proprietà in metodi dedotti che non sono supportati da Kotlin. Ad esempio, buildTypes gli elementi booleani DSL devono essere preceduti dal prefisso is. Questo codice mostra come impostare le proprietà booleane in Groovy:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

Di seguito è riportato lo stesso codice in Kotlin. Tieni presente che le proprietà sono precedute dal prefisso is.

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

Convertire elenchi e mappe

Gli elenchi e le mappe in Groovy e Kotlin sono definiti utilizzando una sintassi diversa. Groovy utilizza [], mentre Kotlin chiama i metodi di creazione della raccolta esplicitamente utilizzando listOf o mapOf. Assicurati di sostituire [] con listOf o mapOf durante la migrazione.

Ecco come definire un elenco in Groovy e Kotlin:

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

Si tratta dello stesso codice scritto in Kotlin:

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

Ecco come definire una mappa in Groovy e Kotlin:

def myMap = [key1: 'value1', key2: 'value2']

Si tratta dello stesso codice scritto in Kotlin:

val myMap = mapOf("key1" to "value1", "key2" to "value2")

Configurare i tipi di build

Nel DSL Kotlin sono disponibili implicitamente solo i tipi di build di debug e release. Tutti gli altri tipi di build personalizzate devono essere creati manualmente.

In Groovy puoi utilizzare il debug, il rilascio e alcuni altri tipi di build senza prima crearli. Il seguente snippet di codice mostra una configurazione con i tipi di compilazionedebug, release ebenchmark in Groovy.

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

Per creare la configurazione equivalente in Kotlin, devi creare esplicitamente il tipo di build benchmark.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

Eseguire la migrazione dal blocco buildscript al blocco plugins

Se la build utilizza il blocco buildscript {} per aggiungere plug-in al progetto, devi eseguire il refactoring in modo da utilizzare invece il blocco plugins {}. Il blocco plugins {} semplifica l'applicazione dei plug-in e funziona bene con i cataloghi di versioni.

Inoltre, quando utilizzi il blocco plugins {} nei file di build, Android Studio riconosce il contesto anche quando la build non va a buon fine. Questo contesto consente di apportare correzioni ai file DSL di Kotlin perché permette all'IDE Studio di eseguire il completamento del codice e fornire altri suggerimenti utili.

Trovare gli ID plug-in

Mentre il blocco buildscript {} aggiunge i plug-in al percorso di classe di compilazione utilizzando le coordinate Maven del plug-in, ad esempio com.android.tools.build:gradle:7.4.0, il blocco plugins {} utilizza invece gli ID dei plug-in.

Per la maggior parte dei plug-in, l'ID plug-in è la stringa utilizzata quando li applichi utilizzando apply plugin. Ad esempio, i seguenti ID plug-in fanno parte del plug-in Android Gradle:

  • com.android.application
  • com.android.library
  • com.android.lint
  • com.android.test

Puoi trovare l'elenco completo dei plug-in nel repository Maven di Google.

Più ID plug-in possono fare riferimento ai plug-in Kotlin. Ti consigliamo di utilizzare l'ID plug-in con spazio dei nomi e di modificare la dimensione da abbreviazione a ID plug-in con spazio dei nomi nella seguente tabella:

ID plug-in in forma breve ID plug-in con spazio dei nomi
kotlin org.jetbrains.kotlin.jvm
kotlin-android org.jetbrains.kotlin.android
kotlin-kapt org.jetbrains.kotlin.kapt
kotlin-parcelize org.jetbrains.kotlin.plugin.parcelize

Puoi anche cercare i plug-in nel Gradle Plugin Portal, nel Maven Central Repository e nel Google Maven repository. Leggi Sviluppo di plug-in Gradle personalizzati per saperne di più sul funzionamento degli ID plug-in.

Esegui il refactoring

Una volta che conosci gli ID dei plug-in che utilizzi, svolgi i seguenti passaggi:

  1. Se hai ancora repository per i plug-in dichiarati nel blocco buildscript {}, spostali nel file settings.gradle.

  2. Aggiungi i plug-in al blocco plugins {} nel file build.gradle di primo livello. Qui devi specificare l'ID e la versione del plug-in. Se il plug-in non deve essere applicato al progetto principale, utilizza apply false.

  3. Rimuovi le voci classpath dal file build.gradle.kts di primo livello.

  4. Applica i plug-in aggiungendoli al blocco plugins {} nel file build.gradle a livello di modulo. Qui devi solo specificare l'ID del plug-in, perché la versione viene ereditata dal progetto principale.

  5. Rimuovi la chiamata apply plugin per il plug-in dal file build.gradle a livello di modulo.

Ad esempio, questa configurazione utilizza il blocco buildscript {}:

// Top-level build.gradle file
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
        ...
    }
}

// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")

Questa è una configurazione equivalente che utilizza il blocco plugins {}:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.4.0' apply false
   id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   id 'org.jetbrains.kotlin.android'
   ...
}

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Converti il blocco plug-in

L'applicazione dei plug-in dal blocco plugins {} è simile in Groovy e Kotlin. Il seguente codice mostra come applicare i plug-in in Groovy quando utilizzi cataloghi di versioni:

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

Il seguente codice mostra come fare la stessa cosa in Kotlin:

// Top-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application) apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

Il seguente codice mostra come applicare i plug-in in Groovy quando non utilizzi i cataloghi delle versioni:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

Il seguente codice mostra come fare lo stesso in Kotlin:

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version "7.3.0" apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

Per ulteriori dettagli sul blocco plugins {}, consulta Applicare i plug-in nella documentazione di Gradle.

Vari

Per esempi di codice Kotlin per altre funzionalità, consulta le seguenti pagine di documentazione:

Problemi noti

Al momento, un problema noto è che la velocità di compilazione potrebbe essere inferiore con Kotlin rispetto a Groovy.

Come segnalare problemi

Per istruzioni su come fornire le informazioni di cui abbiamo bisogno per valutare il problema, consulta Dettagli per gli strumenti di compilazione e i bug di Gradle. Quindi, segnala un bug utilizzando lo strumento pubblico di segnalazione dei problemi di Google.

Altre risorse

Per un esempio pratico dei file di build Gradle scritti con Kotlin, consulta l'app di esempio Now In Android su GitHub.