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 org.jetbrains.kotlin.android-Plug-in (oder kotlin-android-Plug-in) 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.

Hinweis :Das integrierte Kotlin ersetzt nur das kotlin-android-Plug-in. Wenn Sie ein KMP-Bibliotheksmodul (Kotlin Multiplatform) schreiben, müssen Sie weiterhin das org.jetbrains.kotlin.multiplatform-Plug-in und das com.android.kotlin.multiplatform.library-Plug-in anwenden. Außerdem ist die Verwendung des org.jetbrains.kotlin.multiplatform-Plug-ins zusammen mit dem com.android.library- oder com.android.application-Plug-in nicht mehr zulässig, wenn das integrierte Kotlin aktiviert ist.

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 entfernen oder auf true setzen.

Hinweis: Sie können integriertes Kotlin auch für jeweils ein Modul aktivieren.

Für integriertes Kotlin sind einige Änderungen an Ihrem Projekt erforderlich. Nachdem Sie integriertes Kotlin 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:

Hinweis :Wenn Sie Ihr Projekt noch nicht migrieren möchten, können Sie auch die integrierte Kotlin-Unterstützung deaktivieren.

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

1. kotlin-android-Plug-in 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.

Mit Versionskatalogen

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Keine Versionskataloge

Kotlin

// Module-level build file
plugins {
    id("org.jetbrains.kotlin.android")
}

Groovy

// Module-level build file
plugins {
    id 'org.jetbrains.kotlin.android'
}

Entfernen Sie das Plug-in dann aus Ihrer Build-Datei auf oberster Ebene:

Mit Versionskatalogen

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Keine Versionskataloge

Kotlin

// Top-level build file
plugins {
    id("org.jetbrains.kotlin.android") version "KOTLIN_VERSION" apply false
}

Groovy

// 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. kotlin-kapt-Plug-in bei Bedarf migrieren

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 kotlin-kapt-Plug-in durch das com.android.legacy-kapt-Plug-in und verwenden Sie dieselbe Version wie Ihr Android-Gradle-Plug-in.

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:

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Hinweis :Wenn Sie das kotlin-kapt-Plug-in im plugins{}-Block als kotlin("kapt") version "<KOTLIN_VERSION>" deklarieren, entfernen Sie stattdessen diese Zeile.

3. android.kotlinOptions{}-DSL bei Bedarf migrieren

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

Aktualisieren Sie beispielsweise diesen Code:

Kotlin

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

Groovy

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

…in die neue DSL:

Kotlin

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Groovy

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Hinweis: Bei integriertem Kotlin müssen Sie kotlin.compilerOptions.jvmTarget nicht festlegen, da der Standardwert android.compileOptions.targetCompatibility ist.

4. kotlin.sourceSets{}-DSL bei Bedarf migrieren

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

Bei integriertem Kotlin ist die einzige unterstützte Option, die Verzeichnisse mit dem android.sourceSets{}-DSL der AndroidSourceSet.kotlin-Menge hinzuzufügen. Wenn Sie nicht unterstützte Optionen verwenden, migrieren Sie sie so:

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 += "additionalSourceDirectory/kotlin"
}

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

Groovy

# 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 einer bestimmten Variante ein Kotlin-Quellverzeichnis hinzufügen möchten oder wenn das Verzeichnis von einer Aufgabe generiert wird, können Sie die Methoden addStaticSourceDirectory oder addGeneratedSourceDirectory in der Variant API verwenden:

Kotlin

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

Groovy

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 bei Bedarf Feedback.

Integrierte Kotlin-Unterstützung deaktivieren

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

Hinweis :Sie müssen auch android.newDsl=false festlegen, um die neue DSL zu deaktivieren, da das kotlin-android-Plug-in nicht damit kompatibel ist.

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 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 haben. Dadurch werden sowohl die Kotlin-Kompilierungsaufgabe, die sich geringfügig auf die Build-Leistung auswirkt, als auch die automatische Abhängigkeit von der Kotlin-Standardbibliothek entfernt.

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

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}