הגדרת פלאגין של ספריית Android Gradle ל-KMP

פלאגין Gradle‏ com.android.kotlin.multiplatform.library הוא הכלי שנתמך באופן רשמי להוספת יעד Android למודול ספרייה של Kotlin Multiplatform‏ (KMP). הוא מפשט את הגדרת הפרויקט, משפר את ביצועי ה-build ומציע שילוב טוב יותר עם Android Studio.

השימוש בפלאגין com.android.library לפיתוח KMP תלוי בממשקי Android Gradle Plugin API שהוצאו משימוש ודורשים הסכמה ב-Android Gradle Plugin 9.0 ואילך (רבעון 4 של 2025). ה-API האלה צפויים להיות מוסרים בפלאגין של Android Gradle 10.0 (במחצית השנייה של 2026).

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

כדי לקבל עזרה בהעברה ל-AGP מגרסה 9.0 ואילך, אפשר להשתמש במיומנות הסוכן שנוצרה על ידי JetBrains לאפליקציות KMP. מידע נוסף על שימוש במיומנויות ב-Android Studio זמין במאמר הרחבת מצב הסוכן באמצעות מיומנויות. חשוב לזכור שתוצאות ה-AI לא תמיד צפויות.

תכונות עיקריות והבדלים

התוסף Android-KMP מותאם במיוחד לפרויקטים של KMP, ויש לו כמה הבדלים מהותיים מהתוסף הרגיל com.android.library:

  • ארכיטקטורה של וריאנט יחיד: הפלאגין משתמש בווריאנט יחיד, ומסיר את התמיכה בטעמי מוצר ובסוגי build. כך הוא מפשט את ההגדרה ומשפר את ביצועי ה-build.

  • אופטימיזציה ל-KMP: הפלאגין מיועד לספריות KMP, ומתמקד בקוד Kotlin משותף וביכולת פעולה הדדית. הוא לא כולל תמיכה ב-AIDL, ב-RenderScript ובקומפילציות מקוריות ספציפיות ל-Android.

  • בדיקות שמושבתות כברירת מחדל: גם בדיקות יחידה וגם בדיקות מכשיר (instrumentation) מושבתות כברירת מחדל כדי לשפר את מהירות ה-build. אפשר להפעיל אותם אם צריך.

  • אין תוסף Android ברמה העליונה: ההגדרה מתבצעת באמצעות בלוק android ב-Gradle KMP DSL, תוך שמירה על מבנה פרויקט KMP עקבי. אין חסימה של תוסף android ברמה העליונה.

  • הסכמה לשימוש בהידור Java: הידור Java מושבת כברירת מחדל. כדי להפעיל את האפשרות, משתמשים ב-withJava() בבלוק android. השיפור הזה מקצר את משך ה-build כשאין צורך בהידור של Java.

היתרונות של הפלאגין של ספריית Android-KMP

התוסף Android-KMP מספק את היתרונות הבאים לפרויקטים של KMP:

  • שיפור הביצועים והיציבות של ה-build: הוא מתוכנן למהירויות build אופטימליות וליציבות משופרת בפרויקטים של KMP. ההתמקדות שלו בתהליכי עבודה של KMP תורמת לתהליך build יעיל ואמין יותר.

  • שילוב משופר של IDE: הוא מספק השלמת קוד, ניווט, ניפוי באגים וחוויית פיתוח משופרים באופן כללי כשעובדים עם ספריות KMP Android.

  • הגדרת פרויקט פשוטה יותר: הפלאגין מפשט את ההגדרה של פרויקטים ב-KMP על ידי הסרת מורכבויות ספציפיות ל-Android, כמו וריאציות של build. כך מתקבלים קובצי build נקיים יותר שקל יותר לתחזק. בעבר, שימוש בפלאגין com.android.library בפרויקט KMP יכול היה ליצור שמות מבלבלים של קבוצות מקור, כמו androidAndroidTest. מוסכמת השמות הזו הייתה פחות אינטואיטיבית למפתחים שמכירים את מבני הפרויקטים הרגילים של KMP.

פתרונות עקיפים לתכונות שלא נתמכות

בהשוואה לשילוב של KMP עם הפלאגין com.android.library, חלק מהתכונות לא זמינות בפלאגין com.android.kotlin.multiplatform.library. ריכזנו כאן פתרונות אפשריים לתכונות שלא נתמכות:

  • יצירת וריאציות של גרסאות Build

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

    אם אתם צריכים גרסאות build, מומלץ ליצור מודול נפרד ועצמאי של ספריית Android באמצעות הפלאגין com.android.library, להגדיר סוגי build וגרסאות מוצר במודול הזה, ואז להשתמש בו כתלות רגילה בפרויקט מתוך קבוצת המקורות androidMain של ספריית Kotlin Multiplatform. פרטים נוספים זמינים במאמרים יצירת ספרייה ל-Android והגדרת וריאציות של build.

  • קישור נתונים וקישור תצוגות

    אלה תכונות של מסגרת ממשק המשתמש שספציפיות ל-Android ומקושרות באופן הדוק למערכת התצוגה של Android ולפריסות XML. עם הפלאגין החדש לספריית Android-KMP, מומלץ לטפל בממשק המשתמש באמצעות מסגרת מרובת פלטפורמות כמו Compose Multiplatform. ‫Data binding ו-View binding נחשבים לפרטי הטמעה של אפליקציית Android סופית, ולא לספרייה שאפשר לשתף.

  • תמיכה מובנית ב-build

    התוסף החדש מתמקד ביצירת קובץ AAR רגיל עבור יעד Android. השילוב של קוד Native ב-Kotlin Multiplatform מתבצע ישירות על ידי יעדי הנייטיב של KMP (כמו androidNativeArm64 ו-androidNativeX86) ויכולות ה-C-interop שלו. אם אתם צריכים לכלול קוד C/C++ מקורי, כדאי להגדיר אותו כחלק ממערך מקורות משותף או מקורי ולהגדיר את C-interop בתוך הבלוק kotlin, במקום להשתמש במנגנון externalNativeBuild הספציפי ל-Android.

    לחלופין, אם אתם צריכים תמיכה בבנייה מקורית דרך externalNativeBuild, אנחנו ממליצים ליצור מודול com.android.library נפרד ועצמאי שבו תוכלו לשלב קוד מקורי, ולהשתמש בספרייה העצמאית הזו מתוך קבוצת המקורות androidMain של פרויקט ספריית Kotlin Multiplatform. מידע נוסף זמין במאמרים יצירת ספריית Android והוספת קוד C ו-C++ לפרויקט.

  • BuildConfig class

    התכונה BuildConfig שימושית במיוחד בסביבות עם כמה וריאציות. מכיוון שהפלאגין החדש של ספריית Kotlin Multiplatform לא תלוי בווריאנטים ואין בו תמיכה בסוגי build ובטעמים של מוצרים, התכונה הזו לא מיושמת. לחלופין, מומלץ להשתמש בתוסף BuildKonfig או בפתרונות דומים של הקהילה כדי ליצור מטא-נתונים לכל היעדים.

דרישות מוקדמות

כדי להשתמש בפלאגין com.android.kotlin.multiplatform.library, הפרויקט צריך להיות מוגדר עם הגרסאות המינימליות הבאות או גרסאות מתקדמות יותר:

  • פלאגין של Android Gradle (AGP): ‏ 8.10.0
  • Kotlin Gradle Plugin (KGP): ‏ 2.0.0

החלת הפלאגין Android-KMP על מודול קיים

כדי להחיל את הפלאגין Android-KMP על מודול ספרייה קיים של KMP, צריך לבצע את השלבים הבאים:

  1. הצהרה על תוספים בקטלוג הגרסאות. פותחים את קובץ ה-TOML של קטלוג הגרסאות (בדרך כלל gradle/libs.versions.toml) ומוסיפים את הקטע של הגדרות הפלאגין:

    # To check the version number of the latest Kotlin release, go to
    # https://kotlinlang.org/docs/releases.html
    
    [versions]
    androidGradlePlugin = "9.4.0"
    kotlin = "KOTLIN_VERSION"
    
    [plugins]
    kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
    android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "androidGradlePlugin" }
    
  2. מחילים את הצהרת הפלאגין בקובץ הבנייה ברמה הבסיסית. פותחים את הקובץ build.gradle.kts שנמצא בספריית הבסיס של הפרויקט. מוסיפים את הכינויים של התוסף לבלוק plugins באמצעות apply false. כך, הכינויים של הפלאגין זמינים לכל תתי הפרויקטים בלי שהלוגיקה של הפלאגין תחול על פרויקט הבסיס עצמו.

    Kotlin

    // Root build.gradle.kts file
    
    plugins {
       alias(libs.plugins.kotlin.multiplatform) apply false
    
       // Add the following
       alias(libs.plugins.android.kotlin.multiplatform.library) apply false
    }

    מגניב

    // Root build.gradle file
    
    plugins {
       alias(libs.plugins.kotlin.multiplatform) apply false
    
       // Add the following
       alias(libs.plugins.android.kotlin.multiplatform.library) apply false
    }
  3. מחילים את הפלאגין בקובץ build של מודול ספרייה של KMP. פותחים את הקובץ build.gradle.kts במודול הספרייה של KMP ומחילים את הפלאגין בחלק העליון של הקובץ בתוך הבלוק plugins:

    Kotlin

    // Module-specific build.gradle.kts file
    
    plugins {
       alias(libs.plugins.kotlin.multiplatform)
    
       // Add the following
       alias(libs.plugins.android.kotlin.multiplatform.library)
    }

    מגניב

    // Module-specific build.gradle file
    
    plugins {
       alias(libs.plugins.kotlin.multiplatform)
    
       // Add the following
       alias(libs.plugins.android.kotlin.multiplatform.library)
    }
  4. הגדרת יעד KMP ל-Android. מגדירים את הבלוק Kotlin Multiplatform ‏(kotlin) כדי להגדיר את יעד Android. בבלוק kotlin, מציינים את יעד Android באמצעות android:

    Kotlin

    kotlin {
       android {
           namespace = "com.example.kmpfirstlib"
           compileSdk = 33
           minSdk = 24
    
           withJava() // enable java compilation support
           withHostTestBuilder {}.configure {}
           withDeviceTestBuilder {
               sourceSetTreeName = "test"
           }
    
           compilerOptions.configure {
               jvmTarget.set(
                   org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
               )
           }
       }
    
       sourceSets {
           androidMain {
               dependencies {
                   // Add Android-specific dependencies here
               }
           }
           getByName("androidHostTest") {
               dependencies {
               }
           }
    
           getByName("androidDeviceTest") {
               dependencies {
               }
           }
       }
       // ... other targets (JVM, iOS, etc.) ...
    }

    מגניב

    kotlin {
       android {
           namespace = "com.example.kmpfirstlib"
           compileSdk = 33
           minSdk = 24
    
           withJava() // enable java compilation support
           withHostTestBuilder {}.configure {}
           withDeviceTestBuilder {
               it.sourceSetTreeName = "test"
           }
    
           compilerOptions.options.jvmTarget.set(
               org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
           )
       }
    
       sourceSets {
           androidMain {
               dependencies {
               }
           }
           androidHostTest {
               dependencies {
               }
           }
           androidDeviceTest {
               dependencies {
               }
           }
       }
       // ... other targets (JVM, iOS, etc.) ...
    }
  5. שמירת השינויים. אחרי שמחילים את הפלאגין ומגדירים את הבלוק kotlin, מסנכרנים את פרויקט Gradle כדי להחיל את השינויים.

העברה מהפלאגין הקודם

במדריך הזה מוסבר איך לבצע מיגרציה מהתוסף com.android.library מדור קודם לתוסף com.android.kotlin.multiplatform.library.

1. העברת מקורות

התוסף מדור קודם אפשר לכם להשתמש ב-src/main, ב-src/test וב-src/androidTest sourcesets, בנוסף ל-src/androidMain, ל-src/androidHostTest ול-src/androidDeviceTest. הפלאגין החדש משתמש רק בספריות המקור האחרונות, ולכן תצטרכו להעביר מקורות מ-src/main ל-src/androidMain, מ-src/test ל-src/androidHostTest ומ-src/androidTest ל-src/androidDeviceTest.

2. הגדרת ספריות מותאמות אישית של מקורות ומשאבים

אם יש לכם מקורות או משאבים בספריות לא סטנדרטיות, בעבר הייתם מגדירים אותם באמצעות הבלוק sourceSets. בעזרת הפלאגין החדש, משתמשים בתוסף androidComponents כדי להוסיף לסוג הווריאציה ספריות סטטיות של מקורות.

שימו לב שעם הפלאגין החדש, השיטה addStaticSourceDirectory מוסיפה את הספרייה לרשימה הקיימת של ספריות המקור. בתוסף מדור קודם, ה-method‏ setSrcDirs מחליפה את הרשימה, ואילו ה-method‏ srcDir מוסיפה לרשימה.

Android-KMP

בעזרת הפלאגין החדש, אפשר להשתמש בבלוק onVariants כדי לבצע פעולות עם המקורות של הווריאציה.

// build.gradle.kts

androidComponents {
    onVariants { variant ->
        // Add a directory for Kotlin sources
        variant.sources.kotlin?.addStaticSourceDirectory("other/kotlin")

        // Add a directory for Android assets
        variant.sources.assets?.addStaticSourceDirectory("other/assets")
    }
}

פלאגין מדור קודם

בפלאגין com.android.library, הבלוק sourceSets שימש להגדרת ספריות מקור או להוספה שלהן.

// build.gradle.kts

android {
    sourceSets {
        getByName("main") {
            // Replaces the directory for Kotlin sources.
            kotlin.setSrcDirs(listOf("other/kotlin"))

            // Appends a directory for assets.
            assets.srcDir("other/assets")
        }
    }
}

3. הצהרה על יחסי תלות

משימה נפוצה היא הצהרה על יחסי תלות עבור קבוצות מקור ספציפיות ל-Android. בניגוד לבלוק הכללי dependencies ששימש בעבר, התוסף החדש מחייב להציב את הרכיבים האלה באופן מפורש בתוך הבלוק sourceSets.

Android-KMP

הפלאגין החדש מקדם מבנה נקי יותר על ידי קיבוץ התלויות של Android בתוך קבוצת המקור androidMain. בנוסף לקבוצת המקורות הראשית, יש שתי קבוצות של מקורות לבדיקה, שנוצרות לפי דרישה: androidDeviceTest ו-androidHostTest (מידע נוסף זמין במאמר בנושא הגדרת בדיקות של המארח והמכשיר).

// build.gradle.kts

kotlin {
    android {}
    //... other targets

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
        }

        // Dependencies are now scoped to the specific Android source set
        androidMain.dependencies {
            implementation("androidx.appcompat:appcompat:1.7.0")
            implementation("com.google.android.material:material:1.11.0")
        }
    }
}

למערכי המקור יש קומפילציות תואמות של Kotlin בשמות main, deviceTest ו-hostTest. אפשר להגדיר את קבוצות המקור ואת האוספים בסקריפט הבנייה באופן הבא:

// build.gradle.kts

kotlin {
    android {
        compilations.getByName("deviceTest") {
            kotlinOptions.languageVersion = "2.0"
        }
    }
}

פלאגין מדור קודם

בתוסף מדור קודם, אפשר להצהיר על תלויות ספציפיות ל-Android בבלוק התלויות ברמה העליונה, ולפעמים זה יכול להיות מבלבל במודול מרובה פלטפורמות.

// build.gradle.kts

kotlin {
  androidTarget()
  //... other targets
}

// Dependencies for all source sets were often mixed in one block
dependencies {
  // Common dependencies
  commonMainImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")

  // Android-specific dependencies
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("com.google.android.material:material:1.11.0")
}

4. הפעלת משאבים של Android

התמיכה במשאבי Android (תיקיות res) לא מופעלת כברירת מחדל באמצעות הפלאגין החדש לאופטימיזציה של ביצועי הבנייה. כדי להשתמש בהם, צריך להביע הסכמה. השינוי הזה עוזר לוודא שפרויקטים שלא דורשים משאבים ספציפיים ל-Android לא יושפעו מהתקורה של הבנייה.

Android-KMP

צריך להפעיל באופן מפורש את העיבוד של משאבי Android. צריך למקם את המשאבים ב-src/androidMain/res.

// build.gradle.kts

kotlin {
  android {
    // ...
    // Enable Android resource processing
    androidResources {
      enable = true
    }
  }
}

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

פלאגין מדור קודם

עיבוד המשאבים הופעל כברירת מחדל. אפשר להוסיף מייד ספרייה ב-ressrc/main ולהתחיל להוסיף קבצים מסוג XML drawables, ערכים וכו'.

// build.gradle.kts

android {
    namespace = "com.example.library"
    compileSdk = 34
    // No extra configuration was needed to enable resources.
}

// Project Structure
// └── src
//     └── main
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

5. הגדרת בדיקות של המארח והמכשיר

כברירת מחדל, הפלאגין החדש משבית בדיקות בצד המארח (יחידה) ובצד המכשיר (מכשיר מנוהל) ב-Android. צריך להביע הסכמה מפורשת כדי ליצור את קבוצות המקור ואת ההגדרות של הבדיקה, בעוד שהפלאגין הקודם יצר אותן באופן אוטומטי.

מודל ההסכמה הזה עוזר לוודא שהפרויקט שלכם נשאר יעיל וכולל רק את לוגיקת הבנייה ואת קבוצות המקור שבהן אתם משתמשים באופן פעיל.

Android-KMP

בעזרת הפלאגין החדש, אפשר להפעיל ולהגדיר בדיקות בתוך הבלוק kotlin.android. כך ההגדרה ברורה יותר ונמנעת יצירה של רכיבי בדיקה שלא נעשה בהם שימוש. קבוצת המקור androidUnitTest הופכת ל-androidHostTest (ספריית הבדיקה משתנה מ-src/androidUnitTest ל-src/androidHostTest), ו-androidInstrumentedTest הופך ל-androidDeviceTest (ספריית הבדיקה משתנה מ-src/androidInstrumentedTest ל-src/androidDeviceTest).

// build.gradle.kts

kotlin {
  android {
    // ...

    // Opt-in to enable and configure host-side (unit) tests
    withHostTest {
      isIncludeAndroidResources = true
    }

    // Opt-in to enable and configure device-side (instrumented) tests
    withDeviceTest {
      instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
      execution = "HOST"
    }
  }
}

// Project Structure (After Opt-in)
// └── src
//     ├── androidHostTest
//     └── androidDeviceTest

פלאגין מדור קודם

עם הפלאגין com.android.library, נוצרות כברירת מחדל קבוצות המקורות androidUnitTest ו-androidInstrumentedTest. אתם מגדירים את ההתנהגות שלהם בתוך הבלוק android, בדרך כלל באמצעות ה-DSL‏ testOptions.

// build.gradle.kts

android {
  defaultConfig {
    // Runner was configured in defaultConfig
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
  }

  testOptions {
    // Configure unit tests (for the 'test' source set)
    unitTests.isIncludeAndroidResources = true

    // Configure device tests (for the 'androidTest' source set)
    execution = "HOST"
  }
}

// Project Structure (Defaults)
// └── src
//     ├── test
//     └── androidTest

6. הפעלת קומפילציה של מקור Java

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

Android-KMP

כדי להפעיל את ההידור של Java, צריך להתקשר אל withJava(). יעד ה-JVM מוגדר עכשיו ישירות בתוך הבלוק kotlin { android {} }, כדי שההגדרה תהיה אחידה יותר. ההגדרה jvmTarget כאן חלה על קומפילציה של Kotlin ושל Java עבור יעד Android.

// build.gradle.kts

kotlin {
  android {
    //  Opt-in to enable Java source compilation
    withJava()
    // Configure the JVM target for both Kotlin and Java sources
    compilerOptions {
      jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
    }
  }
  // ...
}

// Project Structure:
// └── src
//     └── androidMain
//         ├── kotlin
//         │   └── com/example/MyKotlinClass.kt
//         └── java
//             └── com.example/MyJavaClass.java

פלאגין מדור קודם

הקומפילציה של Java הופעלה כברירת מחדל. יעד ה-JVM עבור מקורות Java ו-Kotlin הוגדר בבלוק android באמצעות compileOptions.

// build.gradle.kts

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

kotlin {
  androidTarget {
    compilations.all {
      kotlinOptions.jvmTarget = "1.8"
    }
  }
}

7. אינטראקציה עם וריאנטים של build באמצעות androidComponents

התוסף androidComponents עדיין זמין לאינטראקציה עם ארטיפקטים של בנייה באופן פרוגרמטי. רוב ממשק ה-API של Variant נשאר זהה, אבל הממשק החדש של AndroidKotlinMultiplatformVariant מוגבל יותר כי התוסף יוצר רק וריאציה אחת.

לכן, מאפיינים שקשורים לסוגי build ולטעמי מוצרים לא זמינים יותר באובייקט הווריאנט.

Android-KMP

הבלוק onVariants חוזר עכשיו על וריאציה אחת. עדיין אפשר לגשת למאפיינים נפוצים כמו name ו-artifacts, אבל לא למאפיינים ספציפיים לסוג הבנייה.

// build.gradle.kts

androidComponents {
  onVariants { variant ->
      val artifacts = variant.artifacts
  }
}

פלאגין מדור קודם

אם יש כמה וריאציות, אפשר לגשת למאפיינים ספציפיים לסוג הבנייה כדי להגדיר משימות.

// build.gradle.kts

androidComponents {
  onVariants(selector().withBuildType("release")) { variant ->
    // ...
  }
}

8. בחירת וריאציות של תלות בספריות Android

ספריית ה-KMP שלכם יוצרת וריאנט יחיד ל-Android. עם זאת, יכול להיות שתסתמכו על ספריית Android רגילה (com.android.library) שיש לה כמה וריאציות (למשל, free/paid product flavors). שליטה באופן שבו הפרויקט בוחר וריאנט מהתלות הזו היא דרישה נפוצה.

Android-KMP

התוסף החדש מרכז ומבהיר את הלוגיקה הזו בתוך הבלוק kotlin.android.localDependencySelection. כך קל יותר להבין אילו וריאציות של תלות חיצונית ייבחרו לספריית KMP עם וריאציה אחת.

// build.gradle.kts
kotlin {
  android {
    localDependencySelection {
      // For dependencies with multiple build types, select 'debug' first, and 'release' in case 'debug' is missing
      selectBuildTypeFrom.set(listOf("debug", "release"))

      // For dependencies with a 'type' flavor dimension...
      productFlavorDimension("type") {
        // ...select the 'typeone' flavor.
        selectFrom.set(listOf("typeone"))
      }
    }
  }
}

פלאגין מדור קודם

הגדרתם אסטרטגיות לבחירת תלות בתוך בלוקים של buildTypes and productFlavors. לרוב, זה כלל שימוש ב-missingDimensionStrategy כדי לספק טעם ברירת מחדל למאפיין שלא היה בספרייה, או ב-matchingFallbacks בתוך טעם ספציפי כדי להגדיר סדר חיפוש.

מידע נוסף על השימוש ב-API מופיע במאמר פתרון שגיאות התאמה.

9. הוספת יחסי תלות של התצוגה המקדימה של היצירה

בדרך כלל, אנחנו רוצים להגדיר את ההיקף של ספריות ספציפיות לסביבת הפיתוח המקומית שלנו כדי למנוע דליפה של כלים פנימיים אל הארטיפקט הסופי שפורסם. השינוי הזה יוצר בעיה עם הפלאגין החדש של KMP ל-Android, כי הוא מסיר את ארכיטקטורת סוגי ה-Build ששימשה להפרדה בין תלות בפיתוח לבין קוד הגרסה.

Android-KMP

כדי להוסיף תלות רק לפיתוח ולבדיקה מקומיים, מוסיפים את התלות ישירות להגדרת נתיב המחלקה של זמן הריצה (בבלוק dependencies ברמה העליונה) של הקומפילציה הראשית של Android. כך מוודאים שהתלות זמינה בזמן הריצה (לדוגמה, לכלים כמו Compose Preview), אבל היא לא חלק מנתיב המחלקה של ההידור או מ-API שפורסם של הספרייה.

// build.gradle.kts
dependencies {
  "androidRuntimeClasspath"(libs.androidx.compose.ui.tooling)
}

פלאגין מדור קודם

בפרויקטים של Kotlin Multiplatform שמשתמשים בתוסף com.android.library לטירגוט Android, צריך להשתמש בהגדרה debugImplementation, שמגדירה את התלות בסוג ה-build של ניפוי הבאגים ומונעת את הכללתה בווריאנט של הגרסה של הספרייה שמשמשת את הצרכנים.

// build.gradle.kts
dependencies {
  debugImplementation(libs.androidx.compose.ui.tooling)
}

10. הגדרת יעד JVM ליעד KMP Android

התוסף KMP Android מגדיר את יעד ה-JVM באמצעות android.compilerOptions.jvmTarget, שרלוונטי גם ל-Java וגם ל-Kotlin. כך התצורה פשוטה יותר בהשוואה לבלוקים הנפרדים compileOptions ו-kotlinOptions בפרויקטים של Android בלבד.

Android-KMP

כשעובדים עם פרויקט Kotlin Multiplatform ‏ (KMP) שכולל יעד Android, יש כמה דרכים להגדיר את גרסת היעד של JVM עבור מהדר Kotlin ומהדר Java. כדי לנהל את התאימות של קוד הבייט של הפרויקט, חשוב להבין את ההיקף וההיררכיה של ההגדרות האלה.

אלו שלוש הדרכים העיקריות להגדרת יעד ה-JVM, בסדר עולה של עדיפות. ערכי יעד של JVM עם עדיפות גבוהה יותר חלים על קבוצת משנה קטנה יותר של היעדים שהגדרתם, ומבטלים ערכים עם עדיפות נמוכה יותר. המשמעות היא שאתם יכולים להגדיר גרסאות שונות של JVM ליעדים שונים ולקומפילציות שונות בתוך היעדים בפרויקט.

באמצעות ערכת הכלים של Kotlin (העדיפות הכי נמוכה)

הדרך הכי כללית להגדיר את יעד ה-JVM היא לציין את ערכת הכלים בבלוק kotlin בקובץ build.gradle.kts. בגישה הזו מוגדר היעד למשימות ההידור של Kotlin ו-Java בכל היעדים שמבוססים על JVM בפרויקט, כולל Android.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

ההגדרה הזו גורמת לכך שגם kotlinc וגם javac יהיו מכוונים ל-JVM 21. זו דרך מצוינת לקבוע בסיס עקבי לכל הפרויקט.

שימוש באפשרויות של קומפיילר ברמת היעד של Android (עדיפות בינונית)

אפשר לציין את יעד ה-JVM באופן ספציפי ליעד Android KMP בתוך הבלוק android. ההגדרה הזו מחליפה את ההגדרה jvmToolchain ברמת הפרויקט כולו, והיא חלה על כל הקומפילציות של Android.

// build.gradle.kts
kotlin {
    android {
        compilerOptions {
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }
}

במקרה כזה, גם אם jvmToolchain מוגדר לגרסה אחרת, קוד Kotlin ו-Java של יעד Android יקומפל ל-JVM 11.

שימוש באפשרויות של קומפיילר ברמת הקומפילציה (העדיפות הגבוהה ביותר)

כדי לקבל את השליטה המפורטת ביותר, אפשר להגדיר אפשרויות של קומפיילר על בסיס כל קומפילציה (לדוגמה, רק ב-androidMain או ב-androidHostTest). האפשרות הזו שימושית אם קומפילציה ספציפית צריכה לטרגט גרסה אחרת של JVM. ההגדרה הזו מבטלת את ההגדרות של ערכת הכלים של Kotlin ואת האפשרויות ברמת היעד של Android.

// build.gradle.kts
kotlin {
    android {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
            }
        }
    }
}

ההגדרה הזו עוזרת להבטיח שכל הקומפילציות ב-Android יעד ישתמשו ב-JVM 11, וכך מספקת שליטה מדויקת.

פלאגין מדור קודם

בפרויקט KMP שמשתמש בתוסף הרגיל של ספריית Android ‏(com.android.library), ההגדרה שונה מעט מההגדרה כשמשתמשים בתוסף KMP Android (אבל דומה מבחינה רעיונית).

שימוש ב-kotlin toolchain

השיטה kotlin.jvmToolchain() פועלת באופן זהה, ומגדירה את sourceCompatibility ואת targetCompatibility ב-Java ואת jvmTarget ב-Kotlin. אנחנו ממליצים להשתמש בגישה הזו.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

compileOptions ו-kotlinOptions

אם אתם לא משתמשים בערכת הכלים של Kotlin, אתם צריכים להגדיר את יעדי ה-JVM באמצעות בלוקים נפרדים ל-Java ול-Kotlin.

// build.gradle.kts
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. פרסום כללי שמירה של צרכנים

אם ספריית ה-KMP שלכם צריכה לשלוח כללי שמירה על נתונים של צרכנים (כמו כללי ProGuard עבור R8) לצרכנים שלה, אתם צריכים להפעיל במפורש את הפרסום באמצעות הפלאגין החדש. בעבר, כללי שמירה של צרכנים פורסמו כברירת מחדל אם הם צוינו.

Android-KMP

בעזרת הפלאגין החדש, צריך להגדיר את optimization.consumerKeepRules.publish = true ולציין קובצי כללים בתוך הבלוק consumerKeepRules כדי לפרסם כללי שמירה לצרכנים.

// build.gradle.kts
kotlin {
  android {
    optimization {
      consumerKeepRules.apply {
        publish = true
        file("consumer-proguard-rules.pro")
      }
    }
  }
}

פלאגין מדור קודם

עם com.android.library, כל קובצי הכללים שצוינו באמצעות consumerProguardFiles ב-android.defaultConfig מתפרסמים כברירת מחדל בפריטי המידע של הספרייה.

// build.gradle.kts
android {
  defaultConfig {
    consumerProguardFiles("consumer-proguard-rules.pro")
  }
}

12. פרסום הספרייה ב-Maven

אם אתם מתכננים לפרסם את ספריית ה-KMP שלכם ב-Maven לשימוש בפרויקטים אחרים, התהליך משתנה בהתאם לשימוש בתוסף החדש של Android-KMP או בתוסף הקודם.

Android-KMP

הפלאגין com.android.kotlin.multiplatform.library משתלב עם מנגנוני הפרסום הרגילים של Kotlin Multiplatform. אין צורך לבצע שלבים ספציפיים ל-Android מעבר לתהליך הרגיל של פרסום ספריית KMP.

כדי לפרסם את הספרייה, פועלים לפי התיעוד הרשמי של JetBrains: הגדרת פרסום של ספרייה חוצת-פלטפורמות.

פלאגין מדור קודם

כשמשתמשים ב-com.android.library לטירגוט של Android בפרויקט KMP, צריך לפעול לפי המדריך הרגיל לפרסום ספריות של Android כדי להכין ולפרסם את הארטיפקט הספציפי ל-Android ‏ (.aar).

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

מאמרי העזרה של ה-API של הפלאגינים

לפלאגין החדש יש ממשק API שונה מ-com.android.library. למידע מפורט על ה-DSL והממשקים החדשים, אפשר לעיין בהפניות ל-API:

בעיות מוכרות בפלאגין של ספריית Android-KMP

אלה הבעיות הידועות שעלולות להתרחש כשמחילים את התוסף החדש com.android.kotlin.multiplatform.library: