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

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

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

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

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

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

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

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

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

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

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

  אין תמיכה בסוגי 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. שילוב קוד מקורי ב-Kotlin Multiplatform מתבצע ישירות על ידי יעדי הקוד המקורי של KMP (כמו androidNativeArm64 ו-androidNativeX86) ויכולות הפעולה ההדדית שלו עם C. אם אתם צריכים לכלול קוד 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 Plugin (AGP): ‏ 8.10.0
• ‫Kotlin Gradle Plugin (KGP): ‏ 2.0.0

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

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

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

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

   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. הגדרת בדיקות של מארחים ומכשירים

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

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

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

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

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

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

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

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

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

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

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

מאמרי עזרה על Plugin 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

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

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