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.

Attiva Kotlin integrato

Per avere il supporto Kotlin integrato, devi avere 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 attivarlo. Tuttavia, se in precedenza hai disattivato Kotlin integrato impostando android.builtInKotlin=false nel file gradle.properties, devi rimuovere questa impostazione o impostare android.builtInKotlin=true.

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:

1. Rimuovere il plug-in kotlin-android
2. Esegui la migrazione del plug-in kotlin-kapt, se necessario
3. Esegui la migrazione del blocco kotlinOptions{}, 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 tu stia utilizzando i cataloghi delle versioni per dichiarare i plug-in.

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

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

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

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

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

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

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

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

// 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 (di solito 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

Se utilizzi org.jetbrains.kotlin.kapt (o kotlin-kapt) nei file di build, questo plug-in non sarà compatibile con Kotlin integrato. Ti consigliamo di eseguire la migrazione del progetto a KSP.

Tuttavia, se non sei ancora pronto per utilizzare KSP, devi sostituire il plug-in kotlin-kapt con il plug-in com.android.legacy-kapt, utilizzando la stessa versione del plug-in Android Gradle attuale.

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:

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

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

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

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

3. Migra il blocco kotlinOptions{}, se necessario

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

Ad esempio, aggiorna questo codice:

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

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

...alla nuova DSL:

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

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

Segnala problemi

Dopo aver completato i passaggi precedenti, se riscontri problemi, esamina i problemi noti nella descrizione del problema n. 438678642 e inviaci un feedback, se necessario.

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.

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 attuale.

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 in un modulo specifico, imposta enableKotlin = false nel file di build del modulo:

android {
    enableKotlin = false
}

android {
    enableKotlin = false
}