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 menyetel android.builtInKotlin=false di file gradle.properties, Anda harus menghapus setelan tersebut atau menyetel android.builtInKotlin=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. Memigrasikan blok kotlinOptions{} 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 persis yang akan 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

Jika Anda menggunakan org.jetbrains.kotlin.kapt (atau kotlin-kapt) di file build, plugin ini tidak akan kompatibel dengan Kotlin bawaan. Sebaiknya migrasikan project Anda ke KSP.

Namun, jika Anda belum siap menggunakan KSP, Anda harus mengganti plugin kotlin-kapt dengan plugin com.android.legacy-kapt, menggunakan versi yang sama dengan plugin Android Gradle saat ini.

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 blok kotlinOptions{} jika perlu

Jika Anda menggunakan DSL android.kotlinOptions{}, Anda harus 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 nilainya sama dengan android.compilerOptions.targetCompatibility secara default.

Laporkan masalah

Setelah menyelesaikan langkah-langkah sebelumnya, jika Anda mengalami masalah, tinjau masalah yang diketahui dalam deskripsi masalah #438678642 dan berikan masukan kepada kami 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 harus memilih tidak menggunakan DSL baru karena plugin kotlin-android tidak kompatibel dengannya.

Setelah Anda siap memigrasikan project, aktifkan Kotlin bawaan (bersama dengan DSL baru) 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.experimental.built-in-kotlin ke modul yang ingin Anda aktifkan Kotlin bawaannya, menggunakan versi yang sama dengan plugin Android Gradle saat ini.

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.experimental.built-in-kotlin di file build Anda.