Esegui la migrazione della configurazione della build da Groovy a Kotlin

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

Kotlin è preferito a Groovy per la scrittura di script Gradle perché è più leggibile e offre un migliore controllo in fase di compilazione e supporto 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 alla migrazione più completa, consulta la documentazione ufficiale di Gradle.

Spostamenti

Nota: Kotlin è la lingua predefinita per la configurazione di build a partire da Android Studio Giraffe. Se utilizzi AGP 8.1 e il DSL Kotlin per la configurazione del build, ti consigliamo di utilizzare Gradle 8.1 per un'esperienza ottimale.

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 dei file di script si basano sulla lingua in cui è scritto il file di compilazione:

• I file di compilazione di 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, pertanto devi applicare queste modifiche a tutti gli script di compilazione.

Aggiungere parentesi alle chiamate di metodo

Suggerimento: come primo passaggio, anche prima di modificare le estensioni dei file, aggiungi le parentesi al codice Groovy. In questo modo, la conversione a Kotlin è più semplice.

Groovy ti consente di omettere le parentesi nelle chiamate ai metodi, 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

Suggerimento: prima di modificare le estensioni dei file, aggiungi = al codice Groovy. In questo modo, la conversione a Kotlin è più semplice.

Il DSL Groovy ti consente di omettere l'operatore di assegnazione = quando assegni 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 di Groovy e Kotlin:

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

• Interpolazioni di stringhe nelle espressioni con puntini: in Groovy puoi utilizzare solo il prefisso $ per le interpolazioni di stringhe nelle espressioni con puntini, ma Kotlin richiede che le espressioni con puntini siano racchiuse tra parentesi graffe. Ad esempio, in Groovy puoi utilizzare $project.rootDir come mostrato nello snippet seguente:

      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 compilazione durante la migrazione dei relativi contenuti. Ad esempio, seleziona un file di build, ad esempio il file settings.gradle. Rinomina il file in settings.gradle.kts e converti i relativi contenuti 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. Puoi avere una combinazione di file di compilazione Kotlin e Groovy in un progetto, quindi prenditi il tempo necessario per eseguire la migrazione con attenzione.

Sostituisci def con val o var

Sostituisci def con val o var, che è la modalità di definizione delle variabili in Kotlin. Questa è una dichiarazione di variabile in Groovy:

def building64Bit = false

Questo è lo stesso codice scritto in Kotlin:

val building64Bit = false

Prefisso le proprietà booleane con is

Groovy utilizza la logica di deduzione delle proprietà baseada sui 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, per gli elementi booleani buildTypes DSL, devi anteporre is. Questo codice illustra 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 da 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>"]

Questo è lo 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']

Questo è lo 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 i tipi di build di debug, release e altri senza doverli prima creare. 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 compilazione benchmark.

buildTypes {
 debug {
   ...
 }

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

Eseguire la migrazione dal blocco buildscript al blocco dei plug-in

Se la tua build utilizza il blocco buildscript {} per aggiungere plug-in al progetto, devi eseguire il refactoring per 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 compilazione, Android Studio è a conoscenza del contesto anche quando la compilazione non va a buon fine. Questo contesto consente di apportare correzioni ai file DSL 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 del plug-in è la stringa utilizzata quando li applichi utilizzando apply plugin. Ad esempio, i seguenti ID plug-in fanno parte del plug-in Android per 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.

È possibile fare riferimento ai plug-in Kotlin con più ID plug-in. Ti consigliamo di utilizzare l'ID plug-in con nome spaziato e di eseguire il refactoring dalla versione abbreviata all'ID plug-in con nome spaziato in base alla tabella seguente:

ID dei plug-in di abbreviazioni	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 scoprire 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. Devi specificare l'ID e la versione del plug-in qui. 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 specificare solo 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()
    }
}

Convertire il blocco dei 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 lo stesso 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:

• Se hai una configurazione ProGuard, consulta Attivare l'ottimizzazione, l'offuscamento e la riduzione.
• Se hai un blocco signingConfig {}, consulta la sezione Rimuovere le informazioni sulla firma dai file di compilazione.
• Se utilizzi proprietà a livello di progetto, consulta Configurare proprietà a livello di progetto.

Attenzione: anche se Gradle ti consente di definire proprietà a livello di progetto a livello di modulo, evita di farlo, perché i moduli che condividono queste proprietà vengono accoppiati. L'accoppiamento dei moduli rende più difficile l'esportazione successiva di un modulo come progetto autonomo e impedisce a Gradle di utilizzare l'esecuzione parallela dei progetti per velocizzare le build multi-modulo.

Problemi noti

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

Come segnalare i 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 issue tracker pubblico di Google.

Altre risorse

Per un esempio funzionante di file di build di Gradle scritti in Kotlin, consulta l'app di esempio Ora su Android su GitHub.