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 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 build Gradle della tua app per 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 il DSL Kotlin (build.gradle.kts) per impostazione predefinita per la configurazione della build. Ciò offre un'esperienza di modifica migliore rispetto al DSL Groovy (build.gradle) con evidenziazione della sintassi, completamento del codice e navigazione verso le 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, "Kotlin" e "Kotlin DSL" sono 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, quindi devi applicare queste modifiche a tutti gli script di build.

Aggiungere parentesi alle chiamate di metodo

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

compileSdkVersion 30

Si tratta dello 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
}

Convertire le 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 la sezione Modelli di stringa nella documentazione di Kotlin.

Rinominare le estensioni di 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 prima la migrazione dei file più piccoli, fai esperienza e poi vai avanti. 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 è 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

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, 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 vengono definiti con 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

Nella DSL di Kotlin sono disponibili 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 build benchmark.

buildTypes {
 debug {
   ...
 }

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

Eseguire la migrazione dal blocco buildscript al blocco plugins

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 catalogi delle 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 correggere i file DSL Kotlin 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 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 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 spazio dei nomi e di modificare la dimensione da abbreviazione a ID plug-in con spazio dei nomi nella seguente tabella:

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 identificati gli ID dei plug-in utilizzati, 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 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 gli esempi di codice di Kotlin per altre funzionalità, consulta le seguenti pagine della 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 classificare il problema, consulta Dettagli sui bug di Gradle e degli strumenti di creazione. Quindi, segnala un bug utilizzando lo strumento 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.