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 build Gradle in sostituzione di Groovy, il linguaggio di programmazione tradizionalmente utilizzato nei file di configurazione 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 Kotlin offra attualmente una migliore integrazione nell'editor di codice di Android Studio rispetto a Groovy, le build che utilizzano Kotlin tendono a essere più lente di quelle che utilizzano Groovy, quindi valuta le prestazioni della build quando decidi se eseguire la migrazione.

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

Spostamenti

A partire da Android Studio Giraffe, i nuovi progetti utilizzano Kotlin DSL (build.gradle.kts) per impostazione predefinita per la configurazione della build. Offre un'esperienza di modifica migliore rispetto a 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

Kotlin DSL:si riferisce principalmente a Android Gradle Plugin Kotlin DSL o, occasionalmente, a Gradle Kotlin DSL sottostante.

In questa guida alla migrazione, "Kotlin" e "Kotlin DSL" vengono utilizzati in modo intercambiabile. Allo stesso modo, "Groovy" e "Groovy DSL" sono usati in modo intercambiabile.

Denominazione dei file di script

I nomi delle estensioni dei file di script si basano sul linguaggio 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 Gradle scritti in Kotlin utilizzano l'estensione del nome 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.

Aggiungi parentesi alle chiamate di metodi

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

compileSdkVersion 30

Ecco lo stesso codice scritto in Kotlin:

compileSdkVersion(30)

Aggiungere = alle chiamate dei compiti

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
}

Convertire le stringhe

Ecco le differenze tra le stringhe in Groovy e Kotlin:

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

  • Interpolazione di stringhe su espressioni con punti:in Groovy, puoi utilizzare solo il prefisso $ per le interpolazioni di stringhe su espressioni con punti, ma Kotlin richiede di racchiudere le espressioni con punti 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 saperne di più, consulta Modelli di stringhe nella documentazione di Kotlin.

Rinominare le estensioni dei file

Aggiungi .kts a ogni file di build durante la migrazione dei 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 build.

Esegui la migrazione prima dei file più piccoli, acquisisci esperienza e poi procedi. Puoi avere un mix di file di build Kotlin e Groovy in un progetto, quindi prenditi il tempo necessario per eseguire attentamente 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

Ecco lo stesso codice scritto in Kotlin:

val building64Bit = false

Aggiungi il prefisso is alle proprietà booleane

Groovy utilizza la logica di deduzione 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 convertiti in Kotlin, devi modificare i nomi delle proprietà con i metodi dedotti che non sono supportati da Kotlin. Ad esempio, per gli elementi booleani DSL buildTypes, devi aggiungere il 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 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 delle raccolte in modo esplicito 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>"]

Ecco 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']

Ecco 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 personalizzati devono essere creati manualmente.

In Groovy puoi utilizzare i tipi di build debug, release e alcuni altri senza crearli prima. Il seguente snippet di codice mostra una configurazione con i tipi di build debug, release e benchmark 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") {
    ...
 }
}

Esegui la migrazione da 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 il blocco plugins {}. Il blocco plugins {} semplifica l'applicazione dei plug-in e funziona bene con i cataloghi delle versioni.

Inoltre, quando utilizzi il blocco plugins {} nei file di build, Android Studio è consapevole del contesto anche quando la build non va a buon fine. Questo contesto aiuta a correggere i file Kotlin DSL perché consente 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 classpath di build utilizzando le coordinate Maven del plug-in, ad esempio com.android.tools.build:gradle:7.4.0, il blocco plugins {} utilizza invece gli ID 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 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 tramite più ID plug-in. Ti consigliamo di utilizzare l'ID plugin con spazio dei nomi e di eseguire il refactoring dalla notazione abbreviata all'ID plugin con spazio dei nomi utilizzando la tabella seguente:

ID plug-in in forma abbreviata 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 portale dei plug-in Gradle, nel repository Maven Central e nel repository Maven di Google. Leggi Sviluppo di plug-in Gradle personalizzati per scoprire di più su come funzionano gli ID plug-in.

Esegui il refactoring

Una volta che conosci gli ID dei plug-in che utilizzi, procedi nel seguente modo:

  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 qui 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 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")

Ecco 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 i cataloghi delle 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 eseguire la stessa operazione 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 eseguire la stessa operazione 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 la sezione Applicazione dei 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 necessarie per la valutazione del problema, consulta Dettagli per i bug di Gradle e degli strumenti di compilazione. Poi, segnala un bug utilizzando lo strumento Issue Tracker pubblico di Google.

Altre risorse

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