Il plug-in Android per Gradle 4.0 ha aggiunto il supporto per l'utilizzo di Kotlin nella configurazione di compilazione Gradle in sostituzione 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 un migliore 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 rispetto a quelle che utilizzano Groovy, quindi considera 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.
Cronologia
A partire da Android Studio Giraffe, i nuovi progetti utilizzano Kotlin DSL (build.gradle.kts) per impostazione predefinita per la configurazione di compilazione. In questo modo, l'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
Kotlin DSL:si riferisce principalmente al Kotlin DSL del plug-in Android per Gradle o, occasionalmente, al Kotlin DSL di Gradle sottostante.
In questa guida alla migrazione, "Kotlin" e "Kotlin DSL" vengono utilizzati in modo intercambiabile. Analogamente, "Groovy" e "Groovy DSL" sono utilizzati 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 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 ai metodi
Groovy consente di omettere le parentesi nelle chiamate ai metodi, mentre Kotlin le richiede. Per eseguire la migrazione della configurazione, aggiungi le parentesi a questi tipi di chiamate al metodo. Questo codice mostra come configurare un'impostazione in Groovy:
compileSdkVersion 30
Questo è lo stesso codice scritto in Kotlin:
compileSdkVersion(30)
Aggiungi = alle chiamate di assegnazione
Il DSL Groovy consente di omettere l'operatore di assegnazione = quando assegni le 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 tra le stringhe in Groovy e Kotlin:
Virgolette doppie per le stringhe:mentre Groovy consente di definire le stringhe utilizzando le virgolette singole, Kotlin richiede le 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.rootDircome mostrato nel seguente snippet:myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"In Kotlin, tuttavia, il codice precedente chiama
toString()suproject, non suproject.rootDir. Per ottenere il valore della directory root, 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.
Rinomina le estensioni dei file
Aggiungi .kts a ogni file di build man mano che ne esegui 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 comunque compilato dopo la migrazione di ogni file di build.
Esegui prima la migrazione dei file più piccoli, acquisisci esperienza e poi procedi. In un progetto puoi avere una combinazione di file di build Kotlin e Groovy, quindi prenditi il tempo necessario per eseguire il passaggio 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
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 metodi dedotti possono essere getFoo, setFoo o isFoo. Pertanto, una volta eseguita la conversione in Kotlin, devi modificare i nomi delle proprietà nei 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 dal prefisso 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 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 rispetto a 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 rispetto a 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
Nel DSL Kotlin, solo i tipi di build di debug e di release sono disponibili implicitamente. Tutti gli altri tipi di build personalizzate devono essere creati manualmente.
In Groovy puoi utilizzare i tipi di build di debug, di release e alcuni altri tipi di build 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 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 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 se la build non va a buon fine. Questo contesto aiuta ad apportare correzioni ai file DSL Kotlin perché consente all'IDE di Studio di eseguire il completamento del codice e fornire altri suggerimenti utili.
Trova 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 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.applicationcom.android.librarycom.android.lintcom.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 plug-in con spazio dei nomi e di rifattorizzare l'ID plug-in da abbreviato a con spazio dei nomi in base alla seguente tabella:
| ID plug-in abbreviati | 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 centrale Maven e nel repository Maven di Google. Leggi Sviluppo di plug-in Gradle personalizzati per scoprire di più sul funzionamento degli ID plug-in.
Esegui il refactoring
Una volta individuati gli ID dei plug-in che utilizzi, segui questi passaggi:
Se hai ancora repository per i plug-in dichiarati nel blocco
buildscript {}, spostali nel filesettings.gradle.Aggiungi i plug-in al blocco
plugins {}nel filebuild.gradledi primo livello. Qui devi specificare l'ID e la versione del plug-in. Se non è necessario applicare il plug-in al progetto principale, utilizzaapply false.Rimuovi le voci
classpathdal filebuild.gradle.ktsdi primo livello.Applica i plug-in aggiungendoli al blocco
plugins {}nel filebuild.gradlea livello di modulo. Qui devi specificare solo l'ID del plug-in, perché la versione viene ereditata dal progetto principale.Rimuovi la chiamata
apply pluginper il plug-in dal filebuild.gradlea 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 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 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 maggiori dettagli sul blocco plugins {}, consulta Applicazione dei plug-in nella documentazione di Gradle.
Varie
Per esempi di codice Kotlin per altre funzionalità, consulta le seguenti pagine della documentazione:
- Se hai una configurazione ProGuard, consulta Attiva la riduzione, l'offuscamento e l'ottimizzazione.
- Se hai un blocco
signingConfig {}, consulta Rimuovi le informazioni di firma dai file di build. - Se utilizzi le proprietà a livello di progetto, consulta Configura le proprietà a livello di progetto.
Problemi noti
Un problema noto è che la velocità di build 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 i bug degli strumenti di build e di Gradle. Poi, segnala un bug utilizzando l'Issue Tracker pubblico di Google.
Altre risorse
Per un esempio pratico di file di build Gradle scritti con Kotlin, consulta l'app di esempio Now in Android su GitHub.