מעבר ל-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, תצטרכו להסיר את ההגדרה הזו או להגדיר אותה ל-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. העברת ה-DSL של android.kotlinOptions{} אם יש צורך
4. העברת ה-DSL של kotlin.sourceSets{} אם צריך

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) לא תואם ל-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" }

לאחר מכן, מעדכנים את קובצי ה-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. העברת ה-android.kotlinOptions{} DSL, אם צריך

אם אתם משתמשים ב-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
    }
}

4. העברת ה-kotlin.sourceSets{} DSL, אם צריך

כשמשתמשים בתוסף kotlin-android, ‏ AGP מאפשר להוסיף ספריות מקור נוספות של Kotlin באמצעות android.sourceSets{} DSL או kotlin.sourceSets{} DSL. באמצעות android.sourceSets{} DSL, אפשר להוסיף את הספריות לערכה AndroidSourceSet.kotlin או לערכה AndroidSourceSet.java.

עם Kotlin המובנה, האפשרות הנתמכת היחידה היא להוסיף את הספריות לערכה AndroidSourceSet.kotlin באמצעות android.sourceSets{} DSL. אם אתם משתמשים באפשרויות לא נתמכות, אתם יכולים להעביר אותן באופן הבא:

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

# 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:

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

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 כדי להשבית אותו באופן זמני. במקרה כזה, ב-build תוצג אזהרה שמזכירה לכם לעבור ל-Kotlin מובנה, כי לא תוכלו להשבית את Kotlin מובנה ב-AGP 10.0.

כשמוכנים להעביר את הפרויקט, מפעילים את Kotlin המובנה ופועלים לפי שלבי ההעברה.

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

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

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

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

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

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

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

אפשרות להשבית באופן סלקטיבי את Kotlin המובנה

פלאגין של Android Gradle 9.0 מאפשר להשתמש ב-Kotlin מובנה בכל המודולים שבהם הוא מופעל. בפרויקטים גדולים, מומלץ להשבית את Kotlin המובנה באופן סלקטיבי למודולים שאין להם מקורות Kotlin. הפעולה הזו מסירה גם את משימת הקומפילציה של Kotlin, שגורמת לעלות קטנה בביצועי הבנייה, וגם את התלות האוטומטית בספרייה הרגילה של Kotlin.

כדי להשבית את Kotlin המובנה במודול, מגדירים את enableKotlin = false בקובץ ה-build של המודול:

android {
    enableKotlin = false
}

android {
    enableKotlin = false
}