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

  • אין תוסף 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.

    אם אתם צריכים גרסאות 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 מתבצע ישירות על ידי יעדי ה-Native של 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.2.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, בנוסף ל-src/androidMain, ל-src/androidHostTest ול-src/androidDeviceTest. הפלאגין החדש משתמש רק בספריות המקור האחרונות, ולכן תצטרכו להעביר מקורות מ-src/main ל-src/androidMain, מ-src/test ל-src/androidHostTest ומ-src/androidTest ל-src/androidDeviceTest.

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

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

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

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 באופן הבא:

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

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

// 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 toolchain ואת האפשרויות ברמת היעד של 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 toolchain, אתם צריכים להגדיר את יעדי ה-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: