Eseguire la migrazione a Kotlin integrato

Il plug-in Android per Gradle 9.0 introduce il supporto integrato di Kotlin e lo attiva per impostazione predefinita. Ciò significa che non devi più applicare il plug-in org.jetbrains.kotlin.android (o kotlin-android) nei file di build per compilare i file sorgente Kotlin. Grazie a Kotlin integrato, i file di build sono più semplici e puoi evitare problemi di compatibilità tra AGP e il plug-in kotlin-android.

Nota: Kotlin integrato sostituisce solo il plug-in kotlin-android. Se stai scrivendo un modulo di libreria Kotlin Multiplatform (KMP), devi comunque applicare il plug-in org.jetbrains.kotlin.multiplatform e il plug-in com.android.kotlin.multiplatform.library. Inoltre, l'utilizzo del plug-in org.jetbrains.kotlin.multiplatform insieme al plug-in com.android.library o com.android.application non è più consentito quando è abilitato Kotlin integrato.

Attiva Kotlin integrato

Per avere il supporto Kotlin integrato, devi disporre di AGP 9.0 o versioni successive. AGP 9.0 abilita già Kotlin integrato per tutti i moduli in cui applichi AGP, quindi non devi fare nulla per abilitarlo. Tuttavia, se in precedenza hai disattivato Kotlin integrato impostando android.builtInKotlin=false nel file gradle.properties, devi rimuovere questa impostazione o impostarla su true.

Nota: puoi anche attivare Kotlin integrato per un modulo alla volta.

Kotlin integrato richiede alcune modifiche al progetto, quindi dopo averlo abilitato, segui i passaggi successivi per eseguire la migrazione del progetto.

Passaggi per la migrazione

Dopo aver eseguito l'upgrade del progetto da una versione precedente di AGP ad AGP 9.0 o versioni successive o dopo aver attivato manualmente Kotlin integrato, potresti visualizzare il seguente messaggio di errore:

Failed to apply plugin 'org.jetbrains.kotlin.android'.
> Cannot add extension with name 'kotlin', as there is an extension already registered with that name.

…o

Failed to apply plugin 'com.jetbrains.kotlin.android'
> The 'org.jetbrains.kotlin.android' plugin is no longer required for Kotlin support since AGP 9.0.

Questo errore si verifica perché Kotlin integrato richiede alcune modifiche al progetto. Per risolvere questo errore:

Nota: se non sei ancora pronto per eseguire la migrazione del progetto, puoi anche disattivare Kotlin integrato.

1. Rimuovere il plug-in kotlin-android
2. Esegui la migrazione del plug-in kotlin-kapt, se necessario
3. Esegui la migrazione del DSL android.kotlinOptions{}, se necessario
4. Esegui la migrazione del DSL kotlin.sourceSets{}, se necessario

1. Rimuovere il plug-in kotlin-android

Rimuovi il plug-in org.jetbrains.kotlin.android (o kotlin-android) dai file di build a livello di modulo in cui lo applichi. Il codice esatto da rimuovere dipende dal fatto che utilizzi i cataloghi delle versioni per dichiarare i plug-in.

Con i cataloghi delle versioni

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Nessun catalogo delle versioni

Kotlin

// Module-level build file
plugins {
    id("org.jetbrains.kotlin.android")
}

Groovy

// Module-level build file
plugins {
    id 'org.jetbrains.kotlin.android'
}

Poi, rimuovi il plug-in dal file di build di primo livello:

Con i cataloghi delle versioni

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Nessun catalogo delle versioni

Kotlin

// Top-level build file
plugins {
    id("org.jetbrains.kotlin.android") version "KOTLIN_VERSION" apply false
}

Groovy

// Top-level build file
plugins {
    id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false
}

Se utilizzi i cataloghi delle versioni, rimuovi anche la definizione del plug-in dal file TOML del catalogo delle versioni (in genere gradle/libs.versions.toml):

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "KOTLIN_VERSION" }

2. Esegui la migrazione del plug-in kotlin-kapt, se necessario

Il plug-in org.jetbrains.kotlin.kapt (o kotlin-kapt) non è compatibile con Kotlin integrato. Se utilizzi kapt, ti consigliamo di eseguire la migrazione del progetto a KSP.

Se non puoi ancora eseguire la migrazione a KSP, sostituisci il plug-in kotlin-kapt con il plug-in com.android.legacy-kapt, utilizzando la stessa versione del plug-in Android Gradle.

Ad esempio, con i cataloghi delle versioni, aggiorna il file TOML del catalogo delle versioni come segue:

[plugins]
android-application = { id = "com.android.application", version.ref = "AGP_VERSION" }

# Add the following plugin definition
legacy-kapt = { id = "com.android.legacy-kapt", version.ref = "AGP_VERSION" }

# Remove the following plugin definition
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "KOTLIN_VERSION" }

Quindi, aggiorna i file di build:

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Nota: se dichiari il plug-in kotlin-kapt nel blocco plugins{} come kotlin("kapt") version "<KOTLIN_VERSION>", rimuovi invece questa riga.

3. Migra il DSL android.kotlinOptions{} se necessario

Se utilizzi il DSL android.kotlinOptions{}, devi eseguire la migrazione al DSL kotlin.compilerOptions{}.

Ad esempio, aggiorna questo codice:

Kotlin

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

Groovy

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

...alla nuova DSL:

Kotlin

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Groovy

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Nota: con Kotlin integrato, non è necessario impostare kotlin.compilerOptions.jvmTarget perché il suo valore predefinito è android.compileOptions.targetCompatibility.

4. Migra il DSL kotlin.sourceSets{} se necessario

Quando utilizzi il plug-in kotlin-android, AGP ti consente di aggiungere directory di origine Kotlin aggiuntive utilizzando la DSL android.sourceSets{} o la DSL kotlin.sourceSets{}. Con il android.sourceSets{} DSL, puoi aggiungere le directory al set AndroidSourceSet.kotlin o al set AndroidSourceSet.java.

Con Kotlin integrato, l'unica opzione supportata è aggiungere le directory al set AndroidSourceSet.kotlin utilizzando il DSL android.sourceSets{}. Se utilizzi opzioni non supportate, esegui la migrazione nel seguente modo:

Kotlin

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories += "additionalSourceDirectory/kotlin"
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

Groovy

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories.add("additionalSourceDirectory/kotlin")
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories.add("additionalSourceDirectory/kotlin")
}

Se vuoi aggiungere una directory di origine Kotlin a una variante specifica o se la directory viene generata da un'attività, puoi utilizzare i metodi addStaticSourceDirectory o addGeneratedSourceDirectory nell'API Variant:

Kotlin

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Groovy

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Segnala problemi

Se riscontri problemi dopo aver completato i passaggi precedenti, controlla i problemi noti nel problema n. 438678642 e, se necessario, inviaci un feedback.

Disattivare Kotlin integrato

Se non riesci a eseguire la migrazione del progetto per utilizzare Kotlin integrato, imposta android.builtInKotlin=false nel file gradle.properties per disattivarlo temporaneamente. In questo modo, la build mostra un avviso che ti ricorda di eseguire la migrazione a Kotlin integrato, in quanto non potrai disattivare Kotlin integrato in una versione futura di AGP 9.x prima di AGP 10.0.

Nota :devi anche impostare android.newDsl=false per disattivare il nuovo DSL perché il plug-in kotlin-android non è compatibile.

Quando è tutto pronto per la migrazione del progetto, attiva Kotlin integrato e segui i passaggi di migrazione.

Migrazione modulo per modulo

La proprietà Gradle android.builtInKotlin ti consente di attivare o disattivare Kotlin integrato per tutti i moduli in cui applichi AGP.

Se la migrazione di tutti i moduli contemporaneamente è difficile, puoi eseguire la migrazione di un modulo alla volta:

1. Imposta android.builtInKotlin=false nel file gradle.properties per disattivare Kotlin integrato per tutti i moduli.

2. Applica il plug-in com.android.built-in-kotlin al modulo in cui vuoi attivare Kotlin integrato, utilizzando la stessa versione del plug-in Android Gradle.

3. Segui i passaggi di migrazione precedenti per eseguire la migrazione di questo modulo a Kotlin integrato.

4. Dopo aver eseguito la migrazione di tutti i moduli, rimuovi l'impostazione android.builtInKotlin=false in gradle.properties e il plug-in com.android.built-in-kotlin nei file di build.

Opzione per disattivare selettivamente Kotlin integrato

Il plug-in Android per Gradle 9.0 attiva Kotlin integrato per tutti i moduli in cui è applicato. Consigliamo di disattivare Kotlin integrato in modo selettivo per i moduli che non hanno origini Kotlin in progetti di grandi dimensioni. In questo modo vengono rimosse sia l'attività di compilazione Kotlin, che ha un piccolo costo in termini di prestazioni di build, sia la dipendenza automatica dalla libreria standard Kotlin.

Per disattivare Kotlin integrato per un modulo, imposta enableKotlin = false nel file di build del modulo:

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}