Migrer vers Kotlin intégré

Le plug-in Android Gradle 9.0 introduit la prise en charge intégrée de Kotlin et l'active par défaut. Cela signifie que vous n'avez plus besoin d'appliquer le plug-in org.jetbrains.kotlin.android (ou kotlin-android) dans vos fichiers de compilation pour compiler les fichiers sources Kotlin. Grâce à Kotlin intégré, vos fichiers de compilation sont plus simples et vous pouvez éviter les problèmes de compatibilité entre AGP et le plug-in kotlin-android.

Activer Kotlin intégré

Vous devez disposer d'AGP 9.0 ou version ultérieure pour bénéficier de la compatibilité Kotlin intégrée. AGP 9.0 active déjà Kotlin intégré pour tous les modules auxquels vous appliquez AGP. Vous n'avez donc rien à faire pour l'activer. Toutefois, si vous avez désactivé Kotlin intégré en définissant android.builtInKotlin=false dans le fichier gradle.properties, vous devez supprimer ce paramètre ou définir android.builtInKotlin=true pour l'activer.

Kotlin intégré vous oblige à apporter des modifications à votre projet. Une fois que vous avez activé Kotlin intégré, suivez les étapes suivantes pour migrer votre projet.

Procédure de migration

Après avoir migré votre projet d'une ancienne version d'AGP vers AGP 9.0 ou une version ultérieure, ou après avoir activé manuellement Kotlin intégré, le message d'erreur suivant peut s'afficher :

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

...ou

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.

En effet, Kotlin intégré vous oblige à apporter des modifications à votre projet. Pour résoudre cette erreur, procédez comme suit.

1. Supprimer le plug-in kotlin-android
2. Migrer le plug-in kotlin-kapt si nécessaire
3. Migrer le bloc kotlinOptions{} si nécessaire

1. Supprimer le plug-in kotlin-android

Supprimez le plug-in org.jetbrains.kotlin.android (ou kotlin-android) des fichiers de compilation au niveau du module où vous l'appliquez. Le code exact à supprimer dépend de l'utilisation ou non de catalogues de versions pour déclarer les plug-ins.

// 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'
}

Ensuite, supprimez le plug-in de votre fichier de compilation de premier niveau :

// 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
}

Si vous utilisez des catalogues de versions, supprimez également la définition du plug-in du fichier TOML du catalogue de versions (généralement gradle/libs.versions.toml) :

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

2. Migrer le plug-in kotlin-kapt si nécessaire

Si vous utilisez org.jetbrains.kotlin.kapt (ou kotlin-kapt) dans vos fichiers de compilation, ce plug-in ne sera pas compatible avec Kotlin intégré. Vous devez remplacer ce plug-in par le plug-in com.android.legacy-kapt, en utilisant la même version que votre plug-in Android Gradle actuel.

Par exemple, avec les catalogues de versions, mettez à jour votre fichier TOML de catalogue de versions comme suit :

[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" }

Mettez ensuite à jour vos fichiers de compilation :

// 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. Migrer le bloc kotlinOptions{} si nécessaire

Si vous utilisez le DSL android.kotlinOptions{}, vous devez le migrer vers le DSL kotlin.compilerOptions{}.

Par exemple, mettez à jour ce code :

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

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

...au nouveau 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
    }
}

Signaler des problèmes

Après avoir suivi les étapes précédentes, si vous rencontrez des problèmes, consultez les problèmes connus dans la description de issue #438678642 et envoyez-nous vos commentaires si nécessaire.

Désactiver Kotlin intégré

Si vous ne parvenez pas à migrer votre projet pour utiliser Kotlin intégré, définissez android.builtInKotlin = false dans le fichier gradle.properties pour désactiver temporairement Kotlin intégré. Dans ce cas, la compilation affiche un avertissement vous rappelant de migrer vers Kotlin intégré, car vous ne pourrez pas désactiver Kotlin intégré dans une future version d'AGP 9.x avant AGP 10.0.

Migration module par module

La propriété Gradle android.builtInKotlin vous permet d'activer ou de désactiver Kotlin intégré pour tous les modules auxquels vous appliquez AGP.

Si vous avez du mal à migrer tous vos modules en même temps, vous pouvez le faire un par un :

1. Définissez android.builtInKotlin = false sur gradle.properties dans le fichier gradle.properties pour désactiver Kotlin intégré pour tous les modules.

2. Appliquez le plug-in com.android.experimental.built-in-kotlin au module pour lequel vous souhaitez activer Kotlin intégré, en utilisant la même version que votre plug-in Android Gradle actuel.

3. Effectuez les étapes de migration précédentes pour migrer ce module vers Kotlin intégré.

4. Une fois que vous avez migré tous vos modules, supprimez le paramètre android.builtInKotlin = false dans gradle.properties et le plug-in com.android.experimental.built-in-kotlin dans vos fichiers de compilation.