Zu integriertem Kotlin migrieren

Das Android-Gradle-Plug-in 9.0 bietet integrierte Kotlin-Unterstützung, die standardmäßig aktiviert ist. Das bedeutet, dass Sie das Plug-in org.jetbrains.kotlin.android (oder kotlin-android) nicht mehr in Ihren Build-Dateien anwenden müssen, um Kotlin-Quelldateien zu kompilieren. Da Kotlin integriert ist, sind Ihre Build-Dateien einfacher und Sie können Kompatibilitätsprobleme zwischen AGP und dem kotlin-android-Plug-in vermeiden.

Integrierte Kotlin-Unterstützung aktivieren

Für die integrierte Kotlin-Unterstützung benötigen Sie AGP 9.0 oder höher. In AGP 9.0 ist Kotlin bereits für alle Module aktiviert, in denen Sie AGP anwenden. Sie müssen also nichts tun, um es zu aktivieren. Wenn Sie jedoch zuvor integriertes Kotlin deaktiviert haben, indem Sie android.builtInKotlin=false in der Datei gradle.properties festgelegt haben, müssen Sie diese Einstellung entweder entfernen oder android.builtInKotlin=true festlegen, um sie zu aktivieren.

Für integriertes Kotlin müssen Sie einige Änderungen an Ihrem Projekt vornehmen. Nachdem Sie integriertes Kotlin aktiviert haben, folgen Sie der Anleitung unten, um Ihr Projekt zu migrieren.

Migrationsschritte

Nachdem Sie Ihr Projekt von einer älteren AGP-Version auf AGP 9.0 aktualisiert oder integriertes Kotlin manuell aktiviert haben, wird möglicherweise die folgende Fehlermeldung angezeigt:

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

…oder

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.

Das liegt daran, dass Sie bei der integrierten Kotlin-Unterstützung einige Änderungen an Ihrem Projekt vornehmen müssen. Führen Sie folgende Schritte aus, um diesen Fehler zu beheben.

1. kotlin-android-Plug-in entfernen
2. kotlin-kapt-Plug-in bei Bedarf migrieren
3. kotlinOptions{}-Block bei Bedarf migrieren

1. Plug-in „kotlin-android“ entfernen

Entfernen Sie das Plug-in org.jetbrains.kotlin.android (oder kotlin-android) aus den Build-Dateien auf Modulebene, in denen Sie es anwenden. Der genaue Code, der entfernt werden muss, hängt davon ab, ob Sie Versionskataloge zum Deklarieren von Plug-ins verwenden.

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

Entfernen Sie das Plug-in dann aus Ihrer Build-Datei der obersten Ebene:

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

Wenn Sie Versionskataloge verwenden, entfernen Sie die Plug-in-Definition auch aus der TOML-Datei des Versionskatalogs (normalerweise gradle/libs.versions.toml):

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

2. kotlin-kapt-Plug-in bei Bedarf migrieren

Wenn Sie org.jetbrains.kotlin.kapt (oder kotlin-kapt) in Ihren Build-Dateien verwenden, ist dieses Plug-in nicht mit dem integrierten Kotlin kompatibel. Sie müssen dieses Plug-in durch das com.android.legacy-kapt-Plug-in ersetzen und dabei dieselbe Version wie Ihr aktuelles Android Gradle-Plug-in verwenden.

Aktualisieren Sie beispielsweise mit Versionskatalogen die TOML-Datei Ihres Versionskatalogs so:

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

Aktualisieren Sie dann Ihre Build-Dateien:

// 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. kotlinOptions{}-Block bei Bedarf migrieren

Wenn Sie die android.kotlinOptions{}-DSL verwenden, müssen Sie sie zur kotlin.compilerOptions{}-DSL migrieren.

Aktualisieren Sie beispielsweise diesen Code:

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

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

…in die neue 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
    }
}

Probleme melden

Wenn nach Abschluss der vorherigen Schritte Probleme auftreten, sehen Sie sich die bekannten Probleme in der Beschreibung von Problem 438678642 an und geben Sie uns bei Bedarf Feedback.

Integrierte Kotlin-Unterstützung deaktivieren

Wenn Sie Ihr Projekt nicht auf die Verwendung von integriertem Kotlin migrieren können, legen Sie in der Datei gradle.properties android.builtInKotlin = false fest, um integriertes Kotlin vorübergehend zu deaktivieren. In diesem Fall wird im Build eine Warnung angezeigt, in der Sie daran erinnert werden, zu integriertem Kotlin zu migrieren, da Sie integriertes Kotlin in einer zukünftigen Version von AGP 9.x vor AGP 10.0 nicht deaktivieren können.

Modulweise Migration

Mit der Gradle-Eigenschaft android.builtInKotlin können Sie integriertes Kotlin für alle Ihre Module aktivieren oder deaktivieren, in denen Sie AGP anwenden.

Wenn es schwierig ist, alle Module gleichzeitig zu migrieren, können Sie sie einzeln migrieren:

1. Legen Sie android.builtInKotlin = false in der Datei gradle.properties fest, um das integrierte Kotlin für alle Module zu deaktivieren.

2. Wenden Sie das com.android.experimental.built-in-kotlin-Plug-in auf das Modul an, für das Sie integriertes Kotlin aktivieren möchten. Verwenden Sie dabei dieselbe Version wie für Ihr aktuelles Android-Gradle-Plug-in.

3. Führen Sie die vorherigen Migrationsschritte aus, um dieses Modul zu integriertem Kotlin zu migrieren.

4. Nachdem Sie alle Module migriert haben, entfernen Sie die Einstellung android.builtInKotlin = false in gradle.properties und das com.android.experimental.built-in-kotlin-Plug-in in Ihren Build-Dateien.