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

פלאגין Android Gradle מגרסה 9.0 כולל תמיכה מובנית ב-Kotlin, והתמיכה הזו מופעלת כברירת מחדל. כלומר, כבר לא צריך להחיל את הפלאגין org.jetbrains.kotlin.android (או kotlin-android) בקובצי ה-build כדי לקמפל קובצי מקור של Kotlin. עם Kotlin מובנה, קובצי ה-build שלכם פשוטים יותר ואתם יכולים להימנע מבעיות תאימות בין 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 מובנה

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

הערה: אפשר גם להפעיל את Kotlin המובנה במודול אחד בכל פעם.

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

עם קטלוגים של גרסאות

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

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

עם קטלוגים של גרסאות

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

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

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. העברת android.kotlinOptions{} DSL אם צריך

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

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

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. העברת 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. אם אתם משתמשים באפשרויות לא נתמכות, אתם יכולים להעביר אותן באופן הבא:

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

הערה: צריך גם להגדיר את android.newDsl=false כדי לבטל את ההסכמה לשימוש ב-DSL החדש, כי הפלאגין kotlin-android לא תואם לו.

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

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

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

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

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

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

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 של המודול:

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}