ย้ายข้อมูลไปยัง Kotlin ในตัว

ปลั๊กอิน Android Gradle 9.0 เปิดตัวการรองรับ Kotlin ในตัวและเปิดใช้โดยค่าเริ่มต้น ซึ่งหมายความว่าคุณไม่จำเป็นต้องใช้ปลั๊กอิน org.jetbrains.kotlin.android (หรือ kotlin-android) ในไฟล์บิลด์อีกต่อไป เพื่อคอมไพล์ไฟล์ต้นฉบับ Kotlin เมื่อใช้ Kotlin ในตัว ไฟล์บิลด์จะเรียบง่ายขึ้นและคุณจะหลีกเลี่ยงปัญหาความเข้ากันได้ระหว่าง AGP กับปลั๊กอิน kotlin-android ได้

หมายเหตุ: Kotlin ในตัวจะแทนที่เฉพาะปลั๊กอิน kotlin-android เท่านั้น หากคุณกำลังเขียนโมดูลไลบรารี Kotlin Multiplatform (KMP) คุณยังคงต้องใช้ปลั๊กอิน org.jetbrains.kotlin.multiplatform และปลั๊กอิน com.android.kotlin.multiplatform.library นอกจากนี้ ระบบไม่อนุญาตให้ใช้ปลั๊กอิน org.jetbrains.kotlin.multiplatform ร่วมกับปลั๊กอิน com.android.library หรือ com.android.application อีกต่อไป เมื่อเปิดใช้ Kotlin ในตัว

เปิดใช้ Kotlin ในตัว

คุณต้องใช้ AGP 9.0 ขึ้นไปจึงจะได้รับการรองรับ Kotlin ในตัว AGP 9.0 เปิดใช้ Kotlin ในตัวสำหรับโมดูลทั้งหมดที่คุณใช้ AGP อยู่แล้ว คุณจึงไม่จำเป็นต้องดำเนินการใดๆ เพื่อเปิดใช้ อย่างไรก็ตาม หากก่อนหน้านี้คุณเลือกไม่ใช้ Kotlin ในตัวโดยตั้งค่า android.builtInKotlin=false ในไฟล์ gradle.properties คุณจะต้องนำการตั้งค่านั้นออกหรือตั้งค่าเป็น true

หมายเหตุ: คุณยังเปิดใช้ Kotlin ในตัวสำหรับโมดูลครั้งละ 1 โมดูลได้ด้วย

Kotlin ในตัวกำหนดให้คุณต้องทำการเปลี่ยนแปลงบางอย่างในโปรเจ็กต์ ดังนั้นหลังจากเปิดใช้ Kotlin ในตัวแล้ว ให้ทำตามขั้นตอนถัดไปเพื่อย้ายโปรเจ็กต์

ขั้นตอนการย้ายโปรเจ็กต์

หลังจากอัปเกรดโปรเจ็กต์จาก AGP เวอร์ชันเก่าเป็น AGP 9.0 หรือหลังจากเปิดใช้ Kotlin ในตัวด้วยตนเอง คุณอาจเห็นข้อความแสดงข้อผิดพลาดต่อไปนี้

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

...หรือ

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.

ข้อผิดพลาดนี้เกิดขึ้นเนื่องจาก Kotlin ในตัวต้องมีการเปลี่ยนแปลงบางอย่างในโปรเจ็กต์ หากต้องการแก้ไขข้อผิดพลาดนี้ ให้ทำตามขั้นตอนต่อไปนี้

หมายเหตุ: หากยังไม่พร้อมที่จะย้ายโปรเจ็กต์ คุณก็เลือกไม่ใช้ Kotlin ในตัวได้เช่นกัน

1. นำปลั๊กอิน kotlin-android ออก
2. ย้ายปลั๊กอิน kotlin-kapt หากจำเป็น
3. ย้ายข้อมูล DSL android.kotlinOptions{} หากจำเป็น
4. ย้ายข้อมูล DSL kotlin.sourceSets{} หากจำเป็น

1. นำปลั๊กอิน kotlin-android ออก

นำปลั๊กอิน org.jetbrains.kotlin.android (หรือ kotlin-android) ออกจาก ไฟล์บิลด์ระดับโมดูลที่คุณใช้ โค้ดที่แน่นอนที่จะนำออกจะขึ้นอยู่กับ ว่าคุณใช้แคตตาล็อกเวอร์ชันเพื่อประกาศปลั๊กอินหรือไม่

มีแคตตาล็อกเวอร์ชัน

Kotlin

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

Groovy

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

ไม่มีแคตตาล็อกเวอร์ชัน

Kotlin

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

Groovy

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

จากนั้นให้นำปลั๊กอินออกจากไฟล์บิลด์ระดับบนสุดโดยทำดังนี้

มีแคตตาล็อกเวอร์ชัน

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
}

ไม่มีแคตตาล็อกเวอร์ชัน

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
}

หากใช้แคตตาล็อกเวอร์ชัน ให้นำคำจำกัดความของปลั๊กอินออกจาก ไฟล์ TOML ของแคตตาล็อกเวอร์ชันด้วย (โดยปกติคือ gradle/libs.versions.toml)

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

2. ย้ายปลั๊กอิน kotlin-kapt หากจำเป็น

ปลั๊กอิน org.jetbrains.kotlin.kapt (หรือ kotlin-kapt) เข้ากันไม่ได้กับ Kotlin ในตัว หากคุณใช้ kapt เราขอแนะนำให้คุณย้ายข้อมูลโปรเจ็กต์ไปยัง KSP

หากยังย้ายข้อมูลไปยัง KSP ไม่ได้ ให้แทนที่ปลั๊กอิน kotlin-kapt ด้วยปลั๊กอิน com.android.legacy-kapt โดยใช้เวอร์ชันเดียวกับปลั๊กอิน Android Gradle

ตัวอย่างเช่น หากใช้แคตตาล็อกเวอร์ชัน ให้อัปเดตไฟล์ TOML ของแคตตาล็อกเวอร์ชันดังนี้

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

จากนั้นอัปเดตไฟล์บิลด์ดังนี้

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

หมายเหตุ: หากคุณประกาศปลั๊กอิน kotlin-kapt ในบล็อก plugins{} เป็น kotlin("kapt") version "<KOTLIN_VERSION>" ให้นำบรรทัดนั้นออกแทน

3. ย้าย DSL android.kotlinOptions{} หากจำเป็น

หากใช้ DSL android.kotlinOptions{} คุณต้องย้ายไปยัง DSL kotlin.compilerOptions{}

เช่น อัปเดตโค้ดนี้

Kotlin

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

Groovy

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

...เป็น 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
    }
}

หมายเหตุ: เมื่อใช้ Kotlin ในตัว คุณไม่จำเป็นต้องตั้งค่า kotlin.compilerOptions.jvmTarget เนื่องจากค่าเริ่มต้นจะเป็น android.compileOptions.targetCompatibility

4. ย้าย DSL kotlin.sourceSets{} หากจำเป็น

เมื่อใช้ปลั๊กอิน kotlin-android AGP จะช่วยให้คุณเพิ่มไดเรกทอรีแหล่งที่มาของ Kotlin เพิ่มเติมได้โดยใช้ DSL android.sourceSets{} หรือ DSL kotlin.sourceSets{} android.sourceSets{} DSL ช่วยให้คุณเพิ่มไดเรกทอรีลงในชุด AndroidSourceSet.kotlin หรือชุด AndroidSourceSet.java ได้

เมื่อใช้ Kotlin ในตัว ตัวเลือกที่รองรับเพียงอย่างเดียวคือการเพิ่มไดเรกทอรีลงใน AndroidSourceSet.kotlin ชุดโดยใช้ android.sourceSets{} DSL หากใช้ตัวเลือกที่ไม่รองรับ ให้ย้ายข้อมูลตัวเลือกเหล่านั้นดังนี้

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

หากต้องการเพิ่มไดเรกทอรีแหล่งที่มาของ Kotlin ลงในตัวแปรเฉพาะ หรือหากไดเรกทอรีสร้างขึ้นโดยงาน คุณสามารถใช้วิธี addStaticSourceDirectory หรือ addGeneratedSourceDirectory ใน Variant API ได้

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

รายงานปัญหา

หากพบปัญหาหลังจากทำตามขั้นตอนก่อนหน้า โปรดตรวจสอบปัญหาที่ทราบในปัญหา #438678642 และส่งความคิดเห็นให้เราหากจำเป็น

เลือกไม่ใช้ Kotlin ในตัว

หากย้ายโปรเจ็กต์ไปใช้ Kotlin ในตัวไม่ได้ ให้ตั้งค่า android.builtInKotlin=false ในไฟล์ gradle.properties เพื่อปิดใช้ชั่วคราว เมื่อทำเช่นนั้น บิลด์จะแสดงคำเตือนที่แจ้งให้คุณย้ายไปใช้ Kotlin ในตัว เนื่องจากคุณจะปิดใช้ Kotlin ในตัวใน AGP 9.x เวอร์ชันในอนาคตก่อน AGP 10.0 ไม่ได้

หมายเหตุ: คุณต้องตั้งค่า android.newDsl=false เพื่อเลือกไม่ใช้DSL ใหม่ด้วย เนื่องจากปลั๊กอิน kotlin-android ไม่สามารถใช้งานร่วมกับ DSL ใหม่ได้

เมื่อพร้อมที่จะย้ายข้อมูลโปรเจ็กต์แล้ว ให้เปิดใช้ Kotlin ในตัว และทำตามขั้นตอนการย้ายข้อมูล

การย้ายทีละโมดูล

พร็อพเพอร์ตี้ android.builtInKotlin Gradle ช่วยให้คุณเปิดหรือปิดใช้ Kotlin ในตัวสำหรับโมดูลทั้งหมดที่ใช้ AGP ได้

หากการย้ายทุกโมดูลพร้อมกันเป็นเรื่องยาก คุณสามารถย้ายทีละโมดูลได้โดยทำดังนี้

1. ตั้งค่า android.builtInKotlin=false ในไฟล์ gradle.properties เพื่อปิดใช้ Kotlin ในตัวสำหรับโมดูลทั้งหมด

2. ใช้ปลั๊กอิน com.android.built-in-kotlin กับโมดูล ที่คุณต้องการเปิดใช้ Kotlin ในตัว โดยใช้เวอร์ชันเดียวกับ ปลั๊กอิน Android Gradle

3. ทำตามขั้นตอนการย้ายข้อมูลก่อนหน้าเพื่อย้ายโมดูลนี้ไปใช้ Kotlin ในตัว

4. เมื่อย้ายโมดูลทั้งหมดแล้ว ให้นำการตั้งค่า android.builtInKotlin=false ใน gradle.properties และปลั๊กอิน com.android.built-in-kotlin ในไฟล์บิลด์ออก

ตัวเลือกในการปิดใช้ Kotlin ในตัวบางส่วน

ปลั๊กอิน Android Gradle 9.0 จะเปิดใช้ Kotlin ในตัวสำหรับโมดูลทั้งหมดที่มีการ ใช้ เราขอแนะนำให้ปิดใช้ Kotlin ในตัวแบบเลือกสำหรับโมดูลที่ไม่มีแหล่งที่มาของ Kotlin ในโปรเจ็กต์ขนาดใหญ่ ซึ่งจะนำทั้งงานการคอมไพล์ Kotlin ซึ่งมีต้นทุนด้านประสิทธิภาพการบิลด์เล็กน้อย และการขึ้นต่อกันโดยอัตโนมัติในไลบรารีมาตรฐานของ Kotlin ออก

หากต้องการปิดใช้ Kotlin ในตัวสำหรับโมดูล ให้ตั้งค่า enableKotlin = false ในไฟล์บิลด์ของโมดูลนั้น

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}