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 abilitarlo. 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 (insieme al nuovo DSL) e segui i passaggi per la 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.experimental.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.experimental.built-in-kotlin nei file di build.