פלאגין 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++ לפרויקט.BuildConfigclassהתכונה
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, צריך לבצע את השלבים הבאים:
מצהירים על הפלאגינים בקטלוג הגרסאות. פותחים את קובץ ה-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" }מחילים את הצהרת הפלאגין בקובץ הבנייה ברמה הבסיסית. פותחים את הקובץ
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 }
מחילים את הפלאגין בקובץ 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) }
מגדירים יעד 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.) ... }
החלת השינויים. אחרי שמחילים את הפלאגין ומגדירים את
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:
KotlinMultiplatformAndroidLibraryExtensionKotlinMultiplatformAndroidLibraryTargetKotlinMultiplatformAndroidDeviceTestKotlinMultiplatformAndroidHostTestKotlinMultiplatformAndroidVariant
בעיות מוכרות בפלאגין של ספריית 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
- תוקן ב-
-
- תוקן ב-
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
- תוקן ב
תמיכה ב-instrumented sourceSetTree עבור יעד androidLibrary
- תוקן ב-
Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3וב-Android Gradle Plugin 9.0.0-alpha13
- תוקן ב-
מומלץ בשבילכם
- הערה: טקסט הקישור מוצג כש-JavaScript מושבת
- הגדרת הסביבה
- הוספת מודול KMP לפרויקט