Di chuyển sang Kotlin tích hợp

Trình bổ trợ Android cho Gradle 9.0 giới thiệu tính năng hỗ trợ Kotlin tích hợp và bật tính năng này theo mặc định. Điều đó có nghĩa là bạn không cần áp dụng trình bổ trợ org.jetbrains.kotlin.android (hoặc kotlin-android) trong các tệp bản dựng để biên dịch tệp nguồn Kotlin nữa. Với Kotlin tích hợp, các tệp bản dựng của bạn sẽ đơn giản hơn và bạn có thể tránh được các vấn đề về khả năng tương thích giữa AGP và trình bổ trợ kotlin-android.

Bật Kotlin tích hợp

Bạn cần AGP 9.0 trở lên để có chế độ hỗ trợ Kotlin tích hợp. AGP 9.0 đã bật Kotlin tích hợp cho tất cả các mô-đun mà bạn áp dụng AGP, vì vậy, bạn không cần làm gì để bật Kotlin. Tuy nhiên, nếu trước đây bạn đã chọn không sử dụng Kotlin tích hợp bằng cách đặt android.builtInKotlin=false trong tệp gradle.properties, thì bạn cần xoá chế độ cài đặt đó hoặc đặt android.builtInKotlin=true để bật chế độ này.

Kotlin tích hợp yêu cầu bạn thực hiện một số thay đổi đối với dự án của mình. Vì vậy, sau khi bật Kotlin tích hợp, hãy làm theo các bước tiếp theo để di chuyển dự án.

Các bước di chuyển

Sau khi nâng cấp dự án từ phiên bản AGP cũ lên AGP 9.0 hoặc sau khi bạn tự bật Kotlin tích hợp, bạn có thể thấy thông báo lỗi sau:

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

...hoặc

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.

Đó là do Kotlin tích hợp sẵn yêu cầu bạn thực hiện một số thay đổi đối với dự án của mình. Để giải quyết lỗi này, hãy thực hiện các bước sau.

1. Xoá trình bổ trợ kotlin-android
2. Di chuyển trình bổ trợ kotlin-kapt nếu cần
3. Di chuyển khối kotlinOptions{} nếu cần

1. Xoá trình bổ trợ kotlin-android

Xoá trình bổ trợ org.jetbrains.kotlin.android (hoặc kotlin-android) khỏi các tệp bản dựng cấp mô-đun mà bạn áp dụng. Đoạn mã chính xác cần xoá phụ thuộc vào việc bạn có đang sử dụng danh mục phiên bản để khai báo trình bổ trợ hay không.

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

Sau đó, hãy xoá trình bổ trợ khỏi tệp bản dựng cấp cao nhất:

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

Nếu bạn đang sử dụng danh mục phiên bản, hãy xoá định nghĩa trình bổ trợ khỏi tệp TOML của danh mục phiên bản (thường là gradle/libs.versions.toml):

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

2. Di chuyển trình bổ trợ kotlin-kapt nếu cần

Nếu bạn đang sử dụng org.jetbrains.kotlin.kapt (hoặc kotlin-kapt) trong các tệp bản dựng, thì trình bổ trợ này sẽ không tương thích với Kotlin tích hợp. Bạn cần thay thế trình bổ trợ này bằng trình bổ trợ com.android.legacy-kapt, sử dụng cùng phiên bản với trình bổ trợ Android Gradle hiện tại.

Ví dụ: với danh mục phiên bản, hãy cập nhật tệp TOML danh mục phiên bản như sau:

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

Sau đó, hãy cập nhật tệp bản dựng:

// 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. Di chuyển khối kotlinOptions{} nếu cần

Nếu đang sử dụng DSL android.kotlinOptions{}, bạn cần di chuyển DSL này sang DSL kotlin.compilerOptions{}.

Ví dụ: hãy cập nhật mã này:

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

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

...sang DSL mới:

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

Báo cáo vấn đề

Sau khi hoàn tất các bước trước đó, nếu bạn gặp vấn đề, hãy xem các vấn đề đã biết trong phần mô tả của vấn đề #438678642 và gửi ý kiến phản hồi cho chúng tôi nếu cần.

Chọn không sử dụng Kotlin tích hợp

Nếu không thể di chuyển dự án để sử dụng Kotlin tích hợp, hãy đặt android.builtInKotlin = false trong tệp gradle.properties để tạm thời tắt Kotlin tích hợp. Khi đó, bản dựng sẽ cho thấy một cảnh báo nhắc bạn di chuyển sang Kotlin tích hợp vì bạn sẽ không thể tắt Kotlin tích hợp trong phiên bản AGP 9.x trong tương lai trước AGP 10.0.

Di chuyển theo từng mô-đun

Thuộc tính android.builtInKotlin của Gradle cho phép bạn bật hoặc tắt Kotlin tích hợp cho tất cả các mô-đun mà bạn áp dụng AGP.

Nếu gặp khó khăn khi di chuyển tất cả các mô-đun cùng một lúc, bạn có thể di chuyển từng mô-đun một:

1. Đặt android.builtInKotlin = false trong tệp gradle.properties để tắt Kotlin tích hợp cho tất cả các mô-đun.

2. Áp dụng trình bổ trợ com.android.experimental.built-in-kotlin cho mô-đun mà bạn muốn bật Kotlin tích hợp, sử dụng cùng phiên bản với trình bổ trợ Android cho Gradle hiện tại.

3. Thực hiện các bước di chuyển trước đó để di chuyển mô-đun này sang Kotlin tích hợp.

4. Sau khi bạn di chuyển tất cả các mô-đun, hãy xoá chế độ cài đặt android.builtInKotlin = false trong gradle.properties và trình bổ trợ com.android.experimental.built-in-kotlin trong các tệp bản dựng.