מעבר ל-Kotlin מובנה

בפלאגין Android Gradle מגרסה 9.0 נוספה תמיכה מובנית ב-Kotlin, והיא מופעלת כברירת מחדל. כלומר, כבר לא צריך להחיל את הפלאגין org.jetbrains.kotlin.android (או kotlin-android) בקובצי ה-build כדי לקמפל קובצי מקור של Kotlin. עם Kotlin מובנה, קובצי ה-build פשוטים יותר ואפשר להימנע מבעיות תאימות בין AGP לבין התוסף kotlin-android.

הפעלת Kotlin מובנה

כדי לקבל תמיכה מובנית ב-Kotlin, צריך AGP בגרסה 9.0 ואילך. ב-AGP 9.0,‏ Kotlin מובנית כבר מופעלת בכל המודולים שבהם אתם משתמשים ב-AGP, כך שלא צריך לעשות שום דבר כדי להפעיל אותה. עם זאת, אם בעבר ביטלתם את ההסכמה לשימוש ב-Kotlin המובנה על ידי הגדרת android.builtInKotlin=false בקובץ gradle.properties, אתם צריכים להסיר את ההגדרה הזו או להגדיר android.builtInKotlin=true.

כדי להשתמש ב-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 המובנה צריך לבצע שינויים מסוימים בפרויקט. כדי לפתור את השגיאה, מבצעים את השלבים הבאים:

1. הסרת הפלאגין kotlin-android
2. העברת הפלאגין kotlin-kapt אם צריך
3. העברת הבלוק kotlinOptions{} אם צריך

1. הסרת הפלאגין kotlin-android

מסירים את התוסף org.jetbrains.kotlin.android (או kotlin-android) מקובצי ה-build ברמת המודול שבהם הוא מוחל. הקוד המדויק שצריך להסיר תלוי בשאלה אם אתם משתמשים בקטלוגים של גרסאות כדי להצהיר על תוספים.

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

לאחר מכן, מסירים את הפלאגין מקובץ ה-build ברמה העליונה:

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

אם אתם משתמשים בקטלוגים של גרסאות, צריך גם להסיר את הגדרת הפלאגין מקובץ ה-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) בקובצי ה-build, הפלאגין הזה לא יהיה תואם ל-Kotlin המובנה. מומלץ להעביר את הפרויקט ל-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" }

לאחר מכן, מעדכנים את קובצי ה-build:

// 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. העברת הבלוק kotlinOptions{} אם צריך

אם אתם משתמשים ב-android.kotlinOptions{} DSL, אתם צריכים להעביר אותו ל-kotlin.compilerOptions{} DSL.

לדוגמה, מעדכנים את הקוד הזה:

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

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

…ל-DSL החדש:

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

דיווח על בעיות

אחרי שתשלימו את השלבים הקודמים, אם תיתקלו בבעיות, תוכלו לעיין בבעיות הידועות שמתוארות בבעיה מספר 438678642 ולשלוח לנו משוב אם צריך.

ביטול ההסכמה לשימוש ב-Kotlin המובנה

אם אתם לא מצליחים להעביר את הפרויקט לשימוש ב-Kotlin מובנה, אתם יכולים להגדיר את הערך android.builtInKotlin = false בקובץ gradle.properties כדי להשבית אותו באופן זמני. כשעושים את זה, ב-build מוצגת אזהרה שמזכירה לכם לעבור ל-Kotlin מובנה, כי לא תוכלו להשבית את ה-Kotlin המובנה בגרסה עתידית של AGP 9.x לפני AGP 10.0.

כשמוכנים להעביר את הפרויקט, מפעילים את Kotlin המובנה (יחד עם ה-DSL החדש) ופועלים לפי שלבי ההעברה.

העברה של מודול אחרי מודול

המאפיין android.builtInKotlin Gradle מאפשר להפעיל או להשבית את Kotlin המובנה בכל המודולים שבהם אתם משתמשים ב-AGP.

אם קשה לכם להעביר את כל המודולים בבת אחת, אתם יכולים להעביר מודול אחד בכל פעם:

1. כדי להשבית את Kotlin המובנה בכל המודולים, מגדירים את android.builtInKotlin = false בקובץ gradle.properties.

2. מחילים את התוסף com.android.experimental.built-in-kotlin על המודול שרוצים להפעיל בו את Kotlin המובנה, באמצעות אותה גרסה של תוסף Android Gradle הנוכחי.

3. כדי להעביר את המודול הזה ל-Kotlin מובנה, צריך לפעול לפי שלבי ההעברה שצוינו למעלה.

4. אחרי שמעבירים את כל המודולים, מסירים את ההגדרה android.builtInKotlin = false ב-gradle.properties ואת התוסף com.android.experimental.built-in-kotlin בקובצי ה-build.