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

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

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

הערה: אין תחליף ישיר להגדרת מודול Kotlin Multiplatform באמצעות הפלאגין com.android.application. כדי להעביר, צריך לחלץ את האפליקציה ל-Android למודול Gradle נפרד.

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

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

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

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

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

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

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

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

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

• tubingData binding ו-View binding

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

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

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

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

• כיתה BuildConfig

  התכונה 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 ברמה הבסיסית (root). פותחים את הקובץ 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. מגדירים את היעד של Android KMP. מגדירים את הבלוק של 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.

הערה: בגרסאות של הפלאגין של Android Gradle שקודמות ל-8.12.0, בלוק ההגדרות של יעד Android הוא androidLibrary{}. החל מגרסה 8.12.0 של AGP, נוסף בלוק android{} חדש שמחליף את androidLibrary{}. המאפיין androidLibrary{} הוצא משימוש החל מגרסה AGP 9.1.0-alpha09 ויוסר בגרסה עתידית. אם אתם משתמשים ב-AGP בגרסה 8.12.0 ואילך, השתמשו ב-android{}, אחרת השתמשו ב-androidLibrary{}.

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

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

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

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

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

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

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

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.

// build.gradle.kts

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

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

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

// build.gradle.kts

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

8. בחירת וריאנטים של תלויות בספריית Android

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

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 preview

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

Android-KMP

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

גרסת טרום-השקה (Preview): הפתרון החלופי הזה זמין רק בפלאגין של Android Gradle מגרסה 9.0.0-beta01 ואילך.

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

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

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

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

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

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

Android-KMP

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

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

שימוש ב-toolchain של Kotlin (העדיפות הנמוכה ביותר)

הדרך הכללית ביותר להגדיר את יעד ה-JVM היא לציין את ה-toolchain בבלוק kotlin של הקובץ build.gradle.kts. הגישה הזו מגדירה את היעד למשימות הידור (compilation) גם ב-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 אחרת. ההגדרה הזו מבטלת את ה-toolchain של Kotlin ואת האפשרויות ברמת היעד של Android.

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

ההגדרה הזו עוזרת לוודא שכל ההידורים ב-Android target משתמשים ב-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

אם אתם לא משתמשים ב-toolchain של 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 כדי להכין ולפרסם את פריט המידע שנוצר בתהליך הפיתוח (Artifact) הספציפי ל-Android‏ (.aar).

הוראות מפורטות זמינות במאמר הכנת הספרייה להפצה.

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

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

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

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

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

• התצוגה המקדימה של Compose נכשלת כשמשתמשים בפלאגין החדש של android-KMP

  • הבעיה תוקנה בגרסאות Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 ו-Android Gradle Plugin 9.0.0-alpha13

• ‫NullPointerException בתצוגות מקדימות של Compose Multiplatform עם הפלאגין com.android.kotlin.multiplatform.library

  • הבעיה תוקנה בגרסאות Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 ו-Android Gradle Plugin 9.0.0-alpha13

• ‫KMP שומר את פתרון התלות הנפוץ של הידור במטמון של ההגדרות האישיות, מה שמוביל לשגיאה בזמן ביטול ההמשכה (Android בלבד)

  • תוקן ב-Kotlin Gradle Plugin 2.3.0-Beta2

• תמיכה ב-sourceSetTree עם אינסטרומנטציה ליעד androidLibrary

  • הבעיה תוקנה בגרסאות Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 ו-Android Gradle Plugin 9.0.0-alpha13