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ć android.builtInKotlin=true.

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

Etapy 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 wykonaj migrację wtyczki kotlin-kapt
3. W razie potrzeby wykonaj migrację bloku kotlinOptions{}

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 wykonaj migrację wtyczki kotlin-kapt

Jeśli w plikach kompilacji używasz org.jetbrains.kotlin.kapt (lub kotlin-kapt), ta wtyczka nie będzie zgodna z wbudowanym Kotlinem. Zalecamy migrację projektu do KSP.

Jeśli jednak nie chcesz jeszcze używać KSP, musisz zastąpić wtyczkę kotlin-kapt wtyczką com.android.legacy-kapt, używając tej samej wersji co bieżąca 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 wykonaj migrację bloku kotlinOptions{}.

Jeśli używasz DSL android.kotlinOptions{}, musisz wykonać 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
    }
}

Zgłoś problemy

Jeśli po wykonaniu powyższych czynności napotkasz problemy, zapoznaj się z opisem znanych problemów w zgłoszeniu nr 438678642 i w razie potrzeby prześlij nam 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 przyszłej wersji AGP 9.x nie będzie można wyłączyć wbudowanego języka Kotlin przed AGP 10.0.

Gdy wszystko będzie gotowe do migracji projektu, włącz wbudowany język Kotlin (wraz z nowym DSL) 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. W pliku gradle.properties ustaw wartość android.builtInKotlin = false, aby wyłączyć wbudowany język Kotlin we wszystkich modułach.

2. Zastosuj wtyczkę com.android.experimental.built-in-kotlin do modułu, w którym chcesz włączyć wbudowany język Kotlin, używając tej samej wersji co bieżąca 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.experimental.built-in-kotlin w plikach kompilacji.