Migracja do wbudowanego języka Kotlin

Wtyczka Androida do obsługi Gradle w wersji 9.0 wprowadza wbudowaną obsługę języka Kotlin i domyślnie ją włącza. Oznacza to, że nie musisz już stosować wtyczki org.jetbrains.kotlin.android (ani kotlin-android) w plikach kompilacji, aby kompilować pliki źródłowe Kotlin. Dzięki wbudowanemu Kotlinowi pliki kompilacji są prostsze i możesz uniknąć problemów ze zgodnością między AGP a wtyczką kotlin-android.

Włączanie wbudowanego języka Kotlin

Aby skorzystać z wbudowanej obsługi języka Kotlin, musisz mieć AGP w wersji 9.0 lub nowszej. Wtyczka AGP 9.0 ma już wbudowaną obsługę języka Kotlin we wszystkich modułach, w których stosujesz AGP, więc nie musisz nic robić, aby ją włączyć. Jeśli jednak wcześniej zrezygnowano z wbudowanego języka Kotlin przez ustawienie android.builtInKotlin=false w pliku gradle.properties, musisz usunąć to ustawienie lub ustawić wartość true.

Wbudowany Kotlin wymaga wprowadzenia pewnych zmian w projekcie, więc po włączeniu go wykonaj kolejne czynności, aby przeprowadzić migrację projektu.

Kroki migracji

Po uaktualnieniu starszej wersji AGP w projekcie do AGP 9.0 lub nowszej albo po ręcznym włączeniu wbudowanego języka Kotlin może pojawić się ten komunikat o błędzie:

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

lub

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.

Ten błąd występuje, ponieważ wbudowany język Kotlin wymaga wprowadzenia pewnych zmian w projekcie. Aby rozwiązać ten problem, wykonaj te czynności:

1. Usuń wtyczkę kotlin-android.
2. W razie potrzeby przeprowadź migrację wtyczki kotlin-kapt.
3. W razie potrzeby przeprowadź migrację DSL android.kotlinOptions{}.
4. W razie potrzeby przeprowadź migrację DSL kotlin.sourceSets{}.

1. Usuń wtyczkę kotlin-android.

Usuń wtyczkę org.jetbrains.kotlin.android (lub kotlin-android) z plików kompilacji na poziomie modułu, w których ją stosujesz. Dokładny kod do usunięcia zależy od tego, czy do deklarowania wtyczek używasz katalogów wersji.

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

Następnie usuń wtyczkę z pliku kompilacji najwyższego poziomu:

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

Jeśli używasz katalogów wersji, usuń też definicję wtyczki z pliku TOML katalogu wersji (zwykle gradle/libs.versions.toml):

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

2. W razie potrzeby przeprowadź migrację wtyczki kotlin-kapt.

Wtyczka org.jetbrains.kotlin.kapt (lub kotlin-kapt) jest niezgodna z wbudowanym językiem Kotlin. Jeśli używasz kapt, zalecamy, abyś zmigrował swój projekt do KSP.

Jeśli nie możesz jeszcze przeprowadzić migracji do KSP, zastąp wtyczkę kotlin-kapt wtyczką com.android.legacy-kapt, używając tej samej wersji co wtyczka Androida do obsługi Gradle.

Na przykład w przypadku katalogów wersji zaktualizuj plik TOML katalogu wersji w ten sposób:

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

Następnie zaktualizuj pliki kompilacji:

// 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. W razie potrzeby przeprowadź migrację DSL android.kotlinOptions{}.

Jeśli używasz DSL android.kotlinOptions{}, musisz przeprowadzić jego migrację do DSL kotlin.compilerOptions{}.

Na przykład zaktualizuj ten kod:

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

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

...do nowego 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. W razie potrzeby przeprowadź migrację DSL kotlin.sourceSets{}.

Gdy używasz wtyczki kotlin-android, AGP umożliwia dodawanie dodatkowych katalogów źródłowych Kotlin za pomocą DSL android.sourceSets{} lub DSL kotlin.sourceSets{}. Za pomocą DSL android.sourceSets{} możesz dodawać katalogi do zbioru AndroidSourceSet.kotlin lub AndroidSourceSet.java.

W przypadku wbudowanego języka Kotlin jedyną obsługiwaną opcją jest dodawanie katalogów do zbioru AndroidSourceSet.kotlin za pomocą DSL android.sourceSets{}. Jeśli używasz nieobsługiwanych opcji, przeprowadź ich migrację w ten sposób:

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

Jeśli chcesz dodać katalog źródłowy Kotlin do konkretnego wariantu lub jeśli katalog jest generowany przez zadanie, możesz użyć metod addStaticSourceDirectory lub addGeneratedSourceDirectory w interfejsie API wariantu:

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

Zgłaszanie problemów

Jeśli po wykonaniu poprzednich czynności napotkasz problemy, zapoznaj się ze znanymi problemami w zgłoszeniu #438678642 i w razie potrzeby prześlij opinię.

Rezygnacja z wbudowanego języka Kotlin

Jeśli nie możesz wykonać migracji projektu, aby korzystać z wbudowanego języka Kotlin, ustaw w pliku gradle.properties wartość android.builtInKotlin=false, aby tymczasowo wyłączyć tę funkcję. Gdy to zrobisz, w kompilacji pojawi się ostrzeżenie przypominające o migracji na wbudowany język Kotlin, ponieważ w AGP 10.0 nie będzie można wyłączyć wbudowanego języka Kotlin.

Gdy zechcesz przeprowadzić migrację projektu, włącz wbudowany język Kotlin i wykonaj kroki migracji.

Migracja moduł po module

Właściwość Gradle android.builtInKotlin umożliwia włączanie i wyłączanie wbudowanego języka Kotlin we wszystkich modułach, w których stosujesz AGP.

Jeśli migracja wszystkich modułów naraz jest trudna, możesz wykonać ich migrację pojedynczo:

1. Ustaw w pliku gradle.properties wartość android.builtInKotlin=false, aby wyłączyć wbudowany język Kotlin we wszystkich modułach.

2. Zastosuj wtyczkę com.android.built-in-kotlin do modułu, w którym chcesz włączyć wbudowany język Kotlin, używając tej samej wersji co wtyczka Androida do obsługi Gradle.

3. Aby wykonać migrację modułu do wbudowanego języka Kotlin, wykonaj opisane wcześniej etapy migracji.

4. Po migracji wszystkich modułów usuń ustawienie android.builtInKotlin=false w pliku gradle.properties i wtyczkę com.android.built-in-kotlin w plikach kompilacji.

Opcja selektywnego wyłączania wbudowanego języka Kotlin

Wtyczka Androida do obsługi Gradle w wersji 9.0 włącza wbudowany język Kotlin we wszystkich modułach, w których jest stosowana. W przypadku dużych projektów zalecamy selektywne wyłączanie wbudowanego języka Kotlin w modułach, które nie zawierają źródeł Kotlin. Spowoduje to usunięcie zarówno zadania kompilacji Kotlin, które wiąże się z niewielkim kosztem wydajności kompilacji, jak i automatycznej zależności od biblioteki standardowej Kotlin.

Aby wyłączyć wbudowany język Kotlin w module, ustaw w jego pliku kompilacji wartość enableKotlin = false:

android {
    enableKotlin = false
}

android {
    enableKotlin = false
}