Zu integriertem Kotlin migrieren

Das Android-Gradle-Plug-in 9.0 bietet integrierte Kotlin-Unterstützung und aktiviert diese standardmäßig. Das bedeutet, dass Sie das org.jetbrains.kotlin.android-Plug-in (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 die integrierte Kotlin-Unterstützung 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.

Für die integrierte Kotlin-Unterstützung sind einige Änderungen an Ihrem Projekt erforderlich. Nachdem Sie die integrierte Kotlin-Unterstützung aktiviert haben, folgen Sie den nächsten Schritten, 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.

Dieser Fehler tritt auf, weil für integriertes Kotlin einige Änderungen an Ihrem Projekt erforderlich sind. So beheben Sie diesen Fehler:

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 org.jetbrains.kotlin.android-Plug-in (oder kotlin-android-Plug-in) 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 auf oberster 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. Wir empfehlen, Ihr Projekt zu KSP zu migrieren.

Wenn Sie KSP noch nicht verwenden möchten, müssen Sie das kotlin-kapt-Plugin durch das com.android.legacy-kapt-Plugin ersetzen und dabei dieselbe Version wie Ihr aktuelles Android-Gradle-Plugin 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 migrieren können, um integriertes Kotlin zu verwenden, legen Sie in der Datei gradle.properties android.builtInKotlin = false fest, um es 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.

Wenn Sie bereit sind, Ihr Projekt zu migrieren, aktivieren Sie das integrierte Kotlin und folgen Sie der Anleitung zur Migration.

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.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. Folgen Sie den vorherigen Migrationsschritten, 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.built-in-kotlin-Plug-in in Ihren Build-Dateien.

Option zum selektiven Deaktivieren von integriertem Kotlin

Das Android-Gradle-Plug-in 9.0 ermöglicht integriertes Kotlin für alle Module, in denen es angewendet wird. Wir empfehlen, die integrierte Kotlin-Unterstützung in großen Projekten selektiv für Module zu deaktivieren, die keine Kotlin-Quellen enthalten. Dadurch wird sowohl die Kotlin-Kompilierungsaufgabe entfernt, die sich geringfügig auf die Build-Leistung auswirkt, als auch die automatische Abhängigkeit von der Kotlin-Standardbibliothek.

Wenn Sie integriertes Kotlin in einem bestimmten Modul deaktivieren möchten, legen Sie enableKotlin = false in der Build-Datei dieses Moduls fest:

android {
    enableKotlin = false
}

android {
    enableKotlin = false
}