Esegui la migrazione della configurazione della build da Groovy a Kotlin

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

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

Sebbene Kotlin al momento offra una migliore integrazione nell'editor di codice di Android Studio rispetto a Groovy, le build con Kotlin tendono a essere più lente rispetto a quelle con 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 Android da Groovy a Kotlin. Per una guida alla migrazione più completa, consulta la documentazione ufficiale di Gradle.

Sequenza

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

Termini comuni

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

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

Denominazione dei file di script

I nomi delle estensioni dei file di script sono basati 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 build 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 in tutti gli script di build.

Aggiungi parentesi alle chiamate al metodo

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

compileSdkVersion 30

Questo è lo stesso codice scritto in Kotlin:

compileSdkVersion(30)

Aggiungi = alle chiamate dei compiti

Groovy DSL consente di omettere l'operatore di assegnazione = durante l'assegnazione delle proprietà, mentre Kotlin lo richiede. Questo codice mostra come assegnare le 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 di stringa tra Groovy e Kotlin:

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

  • Interpolazione di stringhe nelle espressioni punteggiate: in Groovy, puoi utilizzare solo il prefisso $ per le interpolazioni di stringhe nelle espressioni punteggiate, ma Kotlin richiede di disporre le espressioni punteggiate 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 root, inserisci l'espressione ${project.rootDir} tra parentesi graffe:

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

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

Rinominare le estensioni dei file

Aggiungi .kts a ogni file di build man mano che esegui la migrazione dei suoi contenuti. Ad esempio, seleziona un file di build, come il file settings.gradle. Rinomina il file in settings.gradle.kts e converti il contenuto del file in Kotlin. Assicurati che il progetto continui a essere compilato dopo la migrazione di ogni file di build.

Esegui prima la migrazione dei file più piccoli, acquisisci esperienza e poi vai avanti. In un progetto puoi usare una combinazione di file di build Kotlin e Groovy, quindi dedica del tempo a questo passaggio.

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

Questo è lo stesso codice scritto in Kotlin:

val building64Bit = false

Fai precedere le proprietà booleane da is

Groovy utilizza una logica di detrazione delle proprietà basata sui nomi delle proprietà. Per una proprietà booleana foo, i metodi dedotti possono essere getFoo, setFoo o isFoo. Dopo la conversione in Kotlin, devi cambiare i nomi delle proprietà con i metodi dedotti non supportati da Kotlin. Ad esempio, per gli elementi booleani DSL di 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
            ...
        }
    ...

Converti elenchi e mappe

Gli elenchi e le mappe in Groovy e Kotlin vengono definiti utilizzando una sintassi diversa. Groovy utilizza [], mentre Kotlin chiama esplicitamente i metodi di creazione delle raccolte 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 tra 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")

Configura i tipi di build

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

In Groovy puoi utilizzare il debug, la release e alcuni altri tipi di build senza doverli creare 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 invece eseguire il refactoring del blocco plugins {}. Il blocco plugins {} semplifica l'applicazione dei plug-in e funziona bene con i catalogi delle versioni.

Inoltre, quando utilizzi il blocco plugins {} nei file di build, Android Studio riconosce il contesto anche quando la build ha esito negativo. Questo contesto aiuta ad apportare correzioni ai file Kotlin DSL perché consente all'IDE di 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 della build utilizzando le coordinate Maven del plug-in, ad esempio com.android.tools.build:gradle:7.4.0, il blocco plugins {} utilizza 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 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.

Ai plug-in Kotlin possono fare riferimento più ID plug-in. Ti consigliamo di utilizzare l'ID plug-in con spazio dei nomi e di passare dalla forma abbreviata all'ID plug-in con spazio dei nomi utilizzando la tabella seguente:

ID plug-in in forma breve ID plug-in Namepaced
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 sul Portale plug-in Gradle, nel Repository Maven Central e nel Repository Maven di Google. Per saperne di più sul funzionamento degli ID plug-in, consulta la pagina Sviluppo di plug-in Gradle personalizzati.

Esegui il refactoring

Una volta identificati gli ID dei plug-in in uso, procedi nel seguente modo:

  1. Se hai ancora repository per 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 non è necessario applicare il plug-in 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. Devi solo specificare l'ID del plug-in qui 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 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 catalogi 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 Applicazione dei plug-in nella documentazione di Gradle.

Vari

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

Problemi noti

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

Come segnalare problemi

Per istruzioni su come fornire le informazioni necessarie per classificare il problema, consulta Dettagli sugli strumenti di build e bug di Gradle. Quindi, segnala un bug utilizzando l'Issue Tracker pubblico di Google.

Altre risorse

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