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.

Uwaga: wbudowany Kotlin zastępuje tylko wtyczkę kotlin-android. Jeśli piszesz moduł biblioteki Kotlin Multiplatform (KMP), nadal musisz zastosować wtyczkę org.jetbrains.kotlin.multiplatform i wtyczkę com.android.kotlin.multiplatform.library. Gdy wbudowany Kotlin jest włączony, nie można już używać wtyczki org.jetbrains.kotlin.multiplatform razem z wtyczką com.android.library lub com.android.application.

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ć true.

Uwaga: wbudowany język Kotlin możesz też włączyć w jednym module naraz.

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 Kotlin wymaga wprowadzenia pewnych zmian w projekcie. Aby rozwiązać ten problem, wykonaj te czynności:

Uwaga: jeśli nie chcesz jeszcze migrować projektu, możesz też zrezygnować z wbudowanego języka Kotlin.

1. Usuwanie wtyczki kotlin-android
2. W razie potrzeby wykonaj migrację wtyczki kotlin-kapt
3. W razie potrzeby wykonaj migrację DSL android.kotlinOptions{}
4. W razie potrzeby wykonaj 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 jest ona stosowana. Dokładny kod do usunięcia zależy od tego, czy do deklarowania wtyczek używasz katalogów wersji.

Z katalogami wersji

Kotlin

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

Groovy

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

Bez katalogów wersji

Kotlin

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

Groovy

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

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

Z katalogami wersji

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
}

Bez katalogów wersji

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
}

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

Wtyczka org.jetbrains.kotlin.kapt (lub kotlin-kapt) jest niezgodna z wbudowanym Kotlinem. Jeśli używasz kapt, zalecamy migrację projektu do KSP.

Jeśli nie możesz jeszcze przejść na 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:

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

Uwaga: jeśli zadeklarujesz wtyczkę kotlin-kapt w bloku plugins{} jako kotlin("kapt") version "<KOTLIN_VERSION>", usuń tę linię.

3. W razie potrzeby wykonaj migrację DSL android.kotlinOptions{}.

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

Na przykład zaktualizuj ten kod:

Kotlin

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

Groovy

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

…do nowego 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
    }
}

Uwaga: w przypadku wbudowanego języka Kotlin nie musisz ustawiać wartości kotlin.compilerOptions.jvmTarget, ponieważ domyślnie jest ona równa android.compileOptions.targetCompatibility.

4. W razie potrzeby wykonaj 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ą android.sourceSets{} DSL możesz dodać katalogi do AndroidSourceSet.kotlin lub AndroidSourceSet.java.

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

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

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:

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

Zgłoś problemy

Jeśli po wykonaniu powyższych czynności napotkasz problemy, zapoznaj się ze znanymi problemami 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.

Uwaga: musisz też ustawić android.newDsl=false, aby zrezygnować z nowego DSL, ponieważ wtyczka kotlin-android nie jest z nim zgodna.

Gdy wszystko będzie gotowe do migracji 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. 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.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.

Możliwość selektywnego wyłączania wbudowanego języka Kotlin

Wtyczka Androida do obsługi Gradle w wersji 9.0 włącza wbudowaną obsługę języka 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ł w tym języku. Usuwa to zadanie kompilacji Kotlin, które wiąże się z niewielkim kosztem wydajności kompilacji, oraz automatyczną zależność od biblioteki standardowej Kotlin.

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

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}