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()
suproject
, non suproject.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:
Se hai ancora repository per plug-in dichiarati nel blocco
buildscript {}
, spostali nel filesettings.gradle
.Aggiungi i plug-in al blocco
plugins {}
nel filebuild.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, utilizzaapply false
.Rimuovi le voci
classpath
dal filebuild.gradle.kts
di primo livello.Applica i plug-in aggiungendoli al blocco
plugins {}
nel filebuild.gradle
a livello di modulo. Devi solo specificare l'ID del plug-in qui perché la versione viene ereditata dal progetto principale.Rimuovi la chiamata
apply plugin
per il plug-in dal filebuild.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:
- Se hai una configurazione ProGuard, consulta Attivare la riduzione, l'offuscamento e l'ottimizzazione.
- Se hai un blocco
signingConfig {}
, consulta Rimuovere le informazioni di firma dai file di build. - Se utilizzi proprietà a livello di progetto, consulta Configurare le proprietà a livello di progetto.
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.