מעבר לפלאגין Android-KMP

בעבר, הדרך היחידה לשלב Android בפרויקט KMP הייתה להשתמש בפלאגין ה-Gradle הרגיל של ספריית Android: com.android.library. עם זאת, הגישה הזו הוצאה משימוש לטובת הפלאגין הייעודי com.android.kotlin.multiplatform.library, שנקרא גם פלאגין Android-KMP. במדריך הזה נסביר איך להעביר את האתר ל-Plugin החדש.

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

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

  • ארכיטקטורה של וריאנט יחיד: הפלאגין פועל עם וריאנט יחיד, שמפשט את תהליך ה-build על ידי הסרת התמיכה בטעמי המוצר ובסוגי ה-build הנפוצים בפרויקטים רגילים של ספריות Android. כך אפשר לפשט את ההגדרה ולשפר את ביצועי ה-build בספריות KMP ל-Android.
  • אופטימיזציה ל-KMP: הפלאגין מיועד במיוחד לספריות Kotlin למספר פלטפורמות, עם דגש על קוד Kotlin משותף ועל יכולת פעולה הדדית. כתוצאה מכך, אין תמיכה ב-builds מקומיים ספציפיים ל-Android, ב-AIDL (Android Interface Definition Language) וב-RenderScript, שאינם רלוונטיים בדרך כלל בהקשר של קוד משותף ב-KMP.
  • הבדיקות מושבתות כברירת מחדל: כדי לשפר עוד יותר את מהירות ה-build בסביבה עם תמיכה בפלטפורמות מרובות, הבדיקות מושבתות כברירת מחדל. אם צריך לבצע בדיקות בפרויקט, אפשר להפעיל אותן במפורש. הכלל הזה חל גם על בדיקות במארח (בדיקות יחידה) וגם על בדיקות במכשיר (בדיקות של מכשירי מדידה).
  • אין תוסף Android ברמה העליונה: הפלאגין לא יוצר תוסף android ברמה העליונה בקובצי ה-build של Gradle. ההגדרות מטופלות באמצעות בלוק androidLibrary ב-DSL של Kotlin לפלטפורמות מרובות, תוך שמירה על מבנה עקבי של פרויקט KMP.
  • הפעלת הידור Java: הידור Java לא מופעל כברירת מחדל. אם ספריית ה-KMP צריכה לקמפל קוד מבוסס-Java, צריך להביע הסכמה מפורשת באמצעות ה-API של withJava() בתוך בלוק התצורה androidLibrary בבלוק kotlin. כך אפשר לשלוט בצורה טובה יותר בתהליך הידור, וזה יכול לשפר את זמני ה-build כשלא נדרש הידור של קוד מבוסס-Java.

היתרונות של ההעברה

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

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

החלת הפלאגין Android-KMP על פרויקט

יש שתי דרכים עיקריות להחיל את הפלאגין Android-KMP על הפרויקט:

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

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

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

    [plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform",
version.ref = "KOTLIN_PLUGIN_VERSION" }
android-kotlin-multiplatform-library = { id =
"com.android.kotlin.multiplatform.library", version.ref =
"ANDROID_KMP_PLUGIN_VERSION" }

    מחליפים את KOTLIN_PLUGIN_VERSION ו-ANDROID_KMP_PLUGIN_VERSION בגרסאות שבהן אתם משתמשים.

  2. החלת הצהרות על הפלאגין בקובץ ה-build ברמה הבסיסית (root). פותחים את הקובץ build.gradle.kts (Kotlin) או build.gradle (Groovy) שנמצא בספריית השורש של הפרויקט. מוסיפים את כתובות האימייל החלופיות של הפלאגין לבלוק plugins באמצעות apply false. כך כינויי הפלאגין יהיו זמינים לכל הפרויקטים המשניים, בלי להחיל את הלוגיקה של הפלאגין על פרויקט הבסיס עצמו.

    Kotlin

    plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

    Groovy

    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 (Kotlin) או build.gradle (Groovy) במודול הספרייה של KMP. מחילים את הפלאגין בחלק העליון של הקובץ, בתוך הבלוק plugins:

    Kotlin

    plugins {
   alias(libs.plugins.kotlin.multiplatform)

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library)
}

    Groovy

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

       compilations.configureEach {
           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"
       }

       compilations.configureEach {
           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 כדי להחיל את השינויים.

יצירת מודול חדש באמצעות הפלאגין

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

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