מעבר ל-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. מגדירים את 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 בקובצי ה-build.

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

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

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

android {
    enableKotlin = false
}

android {
    enableKotlin = false
}