Zu integriertem Kotlin migrieren

Android-Gradle-Plug-in 9.0 führt die integrierte Kotlin-Unterstützung ein und aktiviert sie standardmäßig. 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. Mit dem integrierten Kotlin sind Ihre Build-Dateien einfacher und Sie können Kompatibilitätsprobleme zwischen AGP und dem Plug-in kotlin-android vermeiden.

Integriertes Kotlin aktivieren

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

Für das integrierte Kotlin sind einige Änderungen an Ihrem Projekt erforderlich. Nachdem Sie das integrierte 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 Sie manuell das integrierte Kotlin 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 das integrierte Kotlin einige Änderungen an Ihrem Projekt erforderlich sind. So beheben Sie diesen Fehler:

1. Plug-in kotlin-android entfernen
2. Plug-in kotlin-kapt migrieren (falls erforderlich)
3. DSL android.kotlinOptions{} migrieren (falls erforderlich)
4. DSL kotlin.sourceSets{} migrieren (falls erforderlich)

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 dann das Plug-in 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 (in der Regel gradle/libs.versions.toml):

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

2. Plug-in kotlin-kapt migrieren (falls erforderlich)

Das Plug-in org.jetbrains.kotlin.kapt (oder kotlin-kapt) ist nicht mit dem integrierten Kotlin kompatibel. Wenn Sie kapt verwenden, empfehlen wir, Ihr Projekt zu KSP zu migrieren.

Wenn Sie noch nicht zu KSP migrieren können, ersetzen Sie das Plug-in kotlin-kapt durch das Plug-in com.android.legacy-kapt und verwenden Sie dieselbe Version wie für Ihr Android-Gradle-Plug-in.

Aktualisieren Sie beispielsweise mit Versionskatalogen die TOML-Datei des 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. DSL android.kotlinOptions{} migrieren (falls erforderlich)

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

...zur neuen 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
    }
}

4. DSL kotlin.sourceSets{} migrieren (falls erforderlich)

Wenn Sie das Plug-in kotlin-android verwenden, können Sie mit AGP zusätzliche Kotlin Quellverzeichnisse hinzufügen. Dazu verwenden Sie entweder die DSL android.sourceSets{} oder die kotlin.sourceSets{} DSL. Mit der DSL android.sourceSets{} können Sie die Verzeichnisse entweder dem Satz AndroidSourceSet.kotlin oder dem Satz AndroidSourceSet.java hinzufügen.

Mit dem integrierten Kotlin ist es nur möglich, die Verzeichnisse mit der DSL android.sourceSets{} dem Satz AndroidSourceSet.kotlin hinzuzufügen. Wenn Sie nicht unterstützte Optionen verwenden, migrieren Sie sie so:

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories += "additionalSourceDirectory/kotlin"
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories.add("additionalSourceDirectory/kotlin")
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories.add("additionalSourceDirectory/kotlin")
}

Wenn Sie ein Kotlin-Quellverzeichnis zu einer bestimmten Variante hinzufügen möchten oder wenn das Verzeichnis von einer Aufgabe generiert wird, können Sie die addStaticSourceDirectory oder addGeneratedSourceDirectory Methoden in der Variant API verwenden:

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Probleme melden

Wenn nach Abschluss der vorherigen Schritte Probleme auftreten, sehen Sie sich die bekannten Probleme in Problem #438678642 an und geben Sie uns Feedback, falls erforderlich.

Integriertes Kotlin deaktivieren

Wenn Sie Ihr Projekt nicht migrieren können, um das integrierte Kotlin zu verwenden, legen Sie in der Datei gradle.properties die Einstellung android.builtInKotlin=false fest, um es vorübergehend zu deaktivieren. In diesem Fall wird beim Build eine Warnung angezeigt, die Sie daran erinnert, zu integriertem Kotlin zu migrieren, da Sie das integrierte Kotlin in 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.

Migration von Modul zu Modul

Mit der Gradle-Eigenschaft android.builtInKotlin können Sie das integrierte Kotlin für alle 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 in der Datei gradle.properties die Einstellung android.builtInKotlin=false fest, um das integrierte Kotlin für alle Module zu deaktivieren.

2. Wenden Sie das Plug-in com.android.built-in-kotlin auf das Modul an, für das Sie das integrierte Kotlin aktivieren möchten, und verwenden Sie dieselbe Version wie für Ihr Android-Gradle-Plug-in.

3. Folgen Sie der Anleitung zur Migration oben, 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 Plug-in com.android.built-in-kotlin in Ihren Build-Dateien.

Option zum selektiven Deaktivieren des integrierten Kotlin

In Android-Gradle-Plug-in 9.0 ist das integrierte Kotlin für alle Module aktiviert, in denen es angewendet wird. Wir empfehlen, das integrierte Kotlin in großen Projekten selektiv für Module zu deaktivieren, die keine Kotlin-Quellen haben. Dadurch werden sowohl die Kotlin-Kompilierungsaufgabe, die geringe Auswirkungen auf die Build-Leistung hat, als auch die automatische Abhängigkeit von der Kotlin-Standardbibliothek entfernt.

Wenn Sie das integrierte Kotlin für ein Modul deaktivieren möchten, legen Sie in der Build-Datei dieses Moduls enableKotlin = false fest:

android {
    enableKotlin = false
}

android {
    enableKotlin = false
}