הגדרה של Android Gradle Library Plugin ל-KMP

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

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

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

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

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

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

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

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

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

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

היתרונות של תוסף הספרייה Android-KMP

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

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

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

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

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

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

• ‫Android Gradle Plugin (AGP): ‏ 8.10.0
• ‫Kotlin Gradle Plugin (KGP): ‏ 2.0.0

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

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

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

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "8.13.2"
   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
   }

   Groovy

   // 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)
   }

   Groovy

   // 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 באמצעות androidLibrary:

   Kotlin

   kotlin {
      androidLibrary {
          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.) ...
   }

   Groovy

   kotlin {
      androidLibrary {
          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. הצהרה על יחסי תלות

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

// build.gradle.kts

kotlin {
    androidLibrary {}
    //... 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")
        }
    }
}

// build.gradle.kts

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

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

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

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

// build.gradle.kts

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

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.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

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

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

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

// build.gradle.kts

kotlin {
  androidLibrary {
    // ...

    // 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 = "ANDROIDX_TEST_ORCHESTRATOR"
    }
  }
}

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

// 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 = "ANDROIDX_TEST_ORCHESTRATOR"
  }
}

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

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

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

// build.gradle.kts

kotlin {
  androidLibrary {
    //  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

// build.gradle.kts

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

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

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

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

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

// build.gradle.kts

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

// build.gradle.kts

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

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

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

// build.gradle.kts
kotlin {
  androidLibrary {
    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"))
      }
    }
  }
}

7. תלות ביצירת התצוגה המקדימה

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

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

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

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

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

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

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

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

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

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

    kotlinOptions {
        jvmTarget = "11"
    }
}

Plugin API reference

לפלאגין החדש יש ממשק 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

• תמיכה ב-instrumented sourceSetTree עבור יעד androidLibrary

  • תוקן ב-Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 וב-Android Gradle Plugin 9.0.0-alpha13

תכונות שאינן נתמכות

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

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

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

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

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

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

• BuildConfig class

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