Bermigrasi ke Kotlin bawaan

Plugin Android Gradle 9.0 memperkenalkan dukungan Kotlin bawaan dan mengaktifkannya secara default. Artinya, Anda tidak perlu lagi menerapkan plugin org.jetbrains.kotlin.android (atau kotlin-android) dalam file build untuk mengompilasi file sumber Kotlin. Dengan Kotlin bawaan, file build Anda lebih sederhana dan Anda dapat menghindari masalah kompatibilitas antara AGP dan plugin kotlin-android.

Catatan: Kotlin bawaan hanya menggantikan plugin kotlin-android. Jika Anda menulis modul library Multiplatform Kotlin (KMP), Anda tetap perlu menerapkan plugin org.jetbrains.kotlin.multiplatform dan plugin com.android.kotlin.multiplatform.library. Selain itu, penggunaan plugin org.jetbrains.kotlin.multiplatform bersama dengan plugin com.android.library atau com.android.application tidak lagi diizinkan jika Kotlin bawaan diaktifkan.

Mengaktifkan Kotlin bawaan

Anda memerlukan AGP 9.0 atau yang lebih tinggi untuk memiliki dukungan Kotlin bawaan. AGP 9.0 sudah mengaktifkan Kotlin bawaan untuk semua modul tempat Anda menerapkan AGP, jadi Anda tidak perlu melakukan apa pun untuk mengaktifkannya. Namun, jika sebelumnya Anda memilih tidak menggunakan Kotlin bawaan dengan menetapkan android.builtInKotlin=false dalam file gradle.properties, Anda harus menghapus setelan tersebut atau menetapkannya ke true.

Catatan: Anda juga dapat mengaktifkan Kotlin bawaan untuk satu modul dalam satu waktu.

Kotlin bawaan memerlukan beberapa perubahan pada project Anda, jadi setelah Anda mengaktifkan Kotlin bawaan, ikuti langkah-langkah berikutnya untuk memigrasikan project Anda.

Langkah migrasi

Setelah mengupgrade project dari versi AGP yang lebih lama ke AGP 9.0 atau setelah Anda mengaktifkan Kotlin bawaan secara manual, Anda mungkin melihat pesan error berikut:

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

...atau

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.

Error ini terjadi karena Kotlin bawaan memerlukan beberapa perubahan pada project Anda. Untuk mengatasi error ini, ikuti langkah-langkah berikut:

Catatan: Jika belum siap memigrasikan project, Anda juga dapat memilih tidak menggunakan Kotlin bawaan.

1. Menghapus plugin kotlin-android
2. Migrasikan plugin kotlin-kapt jika perlu
3. Migrasikan DSL android.kotlinOptions{} jika perlu
4. Migrasikan DSL kotlin.sourceSets{} jika perlu

1. Hapus plugin kotlin-android

Hapus plugin org.jetbrains.kotlin.android (atau kotlin-android) dari file build level modul tempat Anda menerapkannya. Kode yang tepat untuk dihapus bergantung pada apakah Anda menggunakan katalog versi untuk mendeklarasikan plugin.

Dengan katalog versi

Kotlin

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

Groovy

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

Tidak ada katalog versi

Kotlin

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

Groovy

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

Kemudian, hapus plugin dari file build level teratas Anda:

Dengan katalog versi

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
}

Tidak ada katalog versi

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
}

Jika Anda menggunakan katalog versi, hapus juga definisi plugin dari file TOML katalog versi (biasanya gradle/libs.versions.toml):

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

2. Migrasikan plugin kotlin-kapt jika perlu

Plugin org.jetbrains.kotlin.kapt (atau kotlin-kapt) tidak kompatibel dengan Kotlin bawaan. Jika Anda menggunakan kapt, sebaiknya migrasikan project Anda ke KSP.

Jika Anda belum dapat bermigrasi ke KSP, ganti plugin kotlin-kapt dengan plugin com.android.legacy-kapt, menggunakan versi yang sama dengan plugin Android Gradle Anda.

Misalnya, dengan katalog versi, perbarui file TOML katalog versi Anda sebagai berikut:

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

Kemudian, perbarui file build Anda:

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

Catatan: Jika Anda mendeklarasikan plugin kotlin-kapt di blok plugins{} sebagai kotlin("kapt") version "<KOTLIN_VERSION>", hapus baris tersebut.

3. Migrasikan DSL android.kotlinOptions{} jika perlu

Jika Anda menggunakan DSL android.kotlinOptions{}, Anda perlu memigrasikannya ke DSL kotlin.compilerOptions{}.

Misalnya, perbarui kode ini:

Kotlin

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

Groovy

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

...ke DSL baru:

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

Catatan: Dengan Kotlin bawaan, Anda tidak perlu menetapkan kotlin.compilerOptions.jvmTarget karena nilai defaultnya adalah android.compileOptions.targetCompatibility.

4. Migrasikan DSL kotlin.sourceSets{} jika perlu

Saat Anda menggunakan plugin kotlin-android, AGP memungkinkan Anda menambahkan direktori sumber Kotlin tambahan menggunakan DSL android.sourceSets{} atau DSL kotlin.sourceSets{}. Dengan DSL android.sourceSets{}, Anda dapat menambahkan direktori ke set AndroidSourceSet.kotlin atau set AndroidSourceSet.java.

Dengan Kotlin bawaan, satu-satunya opsi yang didukung adalah menambahkan direktori ke set AndroidSourceSet.kotlin menggunakan DSL android.sourceSets{}. Jika Anda menggunakan opsi yang tidak didukung, migrasikan opsi tersebut sebagai berikut:

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

Jika Anda ingin menambahkan direktori sumber Kotlin ke varian tertentu atau jika direktori dibuat oleh tugas, Anda dapat menggunakan metode addStaticSourceDirectory atau addGeneratedSourceDirectory di API varian:

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

Laporkan masalah

Jika Anda mengalami masalah setelah menyelesaikan langkah-langkah sebelumnya, tinjau masalah umum di masalah #438678642 dan beri kami masukan jika diperlukan.

Memilih tidak menggunakan Kotlin bawaan

Jika Anda tidak dapat memigrasikan project untuk menggunakan Kotlin bawaan, tetapkan android.builtInKotlin=false dalam file gradle.properties untuk menonaktifkannya sementara. Saat Anda melakukannya, build akan menampilkan peringatan yang mengingatkan Anda untuk bermigrasi ke Kotlin bawaan karena Anda tidak akan dapat menonaktifkan Kotlin bawaan di versi AGP 9.x mendatang sebelum AGP 10.0.

Catatan: Anda juga perlu menyetel android.newDsl=false untuk memilih tidak menggunakan DSL baru karena plugin kotlin-android tidak kompatibel dengannya.

Setelah Anda siap memigrasikan project, aktifkan Kotlin bawaan dan ikuti langkah-langkah migrasi.

Migrasi modul demi modul

Properti Gradle android.builtInKotlin memungkinkan Anda mengaktifkan atau menonaktifkan Kotlin bawaan untuk semua modul tempat Anda menerapkan AGP.

Jika memigrasikan semua modul sekaligus terasa sulit, Anda dapat memigrasikan satu modul dalam satu waktu:

1. Tetapkan android.builtInKotlin=false di file gradle.properties untuk menonaktifkan Kotlin bawaan untuk semua modul.

2. Terapkan plugin com.android.built-in-kotlin ke modul yang ingin Anda aktifkan Kotlin bawaan, menggunakan versi yang sama dengan plugin Android Gradle Anda.

3. Ikuti langkah-langkah migrasi sebelumnya untuk memigrasikan modul ini ke Kotlin bawaan.

4. Setelah Anda memigrasikan semua modul, hapus setelan android.builtInKotlin=false di gradle.properties dan plugin com.android.built-in-kotlin di file build Anda.

Opsi untuk menonaktifkan Kotlin bawaan secara selektif

Plugin Android Gradle 9.0 mengaktifkan Kotlin bawaan untuk semua modul tempat plugin ini diterapkan. Sebaiknya nonaktifkan Kotlin bawaan secara selektif untuk modul yang tidak memiliki sumber Kotlin dalam project besar. Hal ini menghapus tugas kompilasi Kotlin, yang memiliki biaya performa build kecil, dan dependensi otomatis pada library standar Kotlin.

Untuk menonaktifkan Kotlin bawaan untuk modul, tetapkan enableKotlin = false dalam file build modul tersebut:

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}