פרסום כמה ספריות Android כספרייה אחת באמצעות Fused Library

בפרויקטים עם הרבה מודולים, יכול להיות קשה להפיץ ספריות Android למשתמשים תוך שמירה על מבנה פרויקט ברור. במקרים רבים, צריך לפרסם הרבה יותר ספריות ממה שהתכוונתם.

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

להפצה כספרייה אחת יכולים להיות היתרונות הבאים:

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

יצירת ספרייה משולבת

כדי ליצור ספרייה משולבת, צריך ליצור מודול חדש ל-Android, להוסיף יחסי תלות ואז לפרסם את הספרייה המשולבת.

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

כדי להשתמש בפלאגין Fused Library, צריך להשתמש ב-AGP מגרסה 9.0 ואילך. בגרסאות קודמות של הפלאגין Fused Library יש התנהגות שונה ובעיות שתוקנו ב-AGP 9.0.

הוספת מודול חדש של ספרייה משולבת

כדי להשתמש בפלאגין, צריך להוסיף לפרויקט מודול חדש של Android:

בדוגמה הזו, מודול הספרייה הממוזגת ייקרא myFusedLibrary.

  1. מוסיפים את include(":myFusedLibrary") לקובץ settings.gradle.kts.
  2. מוסיפים את android-fusedlibrary = { id = "com.android.fused-library", version.ref = "agp" } בקטע [plugins] בקובץ gradle/libs.versions.toml.
  3. מוסיפים את alias(libs.plugins.android.fusedlibrary) apply false בבלוק הפלאגינים בקובץ build.gradle.kts ברמה העליונה.
  4. כדי ליצור את המודול myFusedLibrary, יוצרים ספרייה חדשה בשם myFusedLibrary (לוחצים לחיצה ימנית על My Application‏ > New‏ > Directory).
  5. יוצרים קובץ build.gradle.kts במודול myFusedLibrary (לוחצים לחיצה ימנית על המודול myFusedLibrary > חדש > קובץ).
  6. מדביקים את הקוד הבא בקובץ myFusedLibrary/build.gradle.kts:

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

androidFusedLibrary {
    namespace = "com.example.myFusedLibrary"
    minSdk = 21
}

dependencies { }

מגניב

plugins {
    id 'com.android.fused-library'
}

androidFusedLibrary {
    namespace 'com.example.myFusedLibrary'
    minSdk 21
}

dependencies {

}

הוספת יחסי תלות

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

לדוגמה:

Kotlin

dependencies {
    include(project(":image-rendering"))
    include("mycoolfonts:font-wingdings:5.0")
}

מגניב

dependencies {
    include project(':image-rendering')
    include 'mycoolfonts:font-wingdings:5.0'
}

פרסום הספרייה הממוזגת

לפני שמפרסמים ספרייה משולבת, כדאי להכיר את התהליך של פרסום ספריית Android. פרסום של ספרייה משולבת דומה לפרסום של ספריית Android, אבל יש כמה הבדלים חשובים שצריך להביא בחשבון כדי לפרסם את הספרייה המשולבת בצורה נכונה:

  • צריך להחיל את הפלאגין Maven Publish גם על כל מודול שהוחל עליו הפלאגין Fused Library.
  • הפרסום חייב לרשת מה-fusedLibraryComponent כי הוא מספק את יחסי התלות הנדרשים כדי לקמפל את פריט המידע שנוצר מהספרייה הממוזגת.

דוגמה להגדרת אתרי חדשות:

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

androidFusedLibrary { … }

dependencies { … }

publishing {
    publications {
        register<MavenPublication>("release") {
             groupId = "my-company"
             artifactId = "my-fused-library"
             version = "1.0"
             from(components["fusedLibraryComponent"])
        }
    }
}

מגניב

plugins {
    id 'com.android.fused-library'
    id 'maven-publish'
}

androidFusedLibrary { … }

dependencies { … }

publishing {
    publications {
        release(MavenPublication) {
            groupId = "my-company"
            artifactId = "my-fused-library"
            version = "1.0"
            afterEvaluate {
            from components.fusedLibraryComponent
        }
    }
}

פרסום הספרייה המשולבת לבדיקה

כדאי לבדוק את התלות בספרייה משולבת שפורסמה מאפליקציה ל-Android או מספרייה ל-Android. השיטה המומלצת היא לפרסם את הספרייה הממוזגת ואת התלויות של הפרויקט שלה במאגר Maven מקומי.

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

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

repositories {
    maven {
        name = "myLocalRepo"
        url = uri(layout.buildDirectory.dir("myLocalRepo"))
    }
}

מגניב

plugins {
    id 'com.android.fused-library'
    id 'maven-publish'
}

repositories {
    maven {
        name 'myLocalRepo'
        url layout.buildDirectory.dir('myLocalRepo')
    }
}

העלאת הספרייה המשולבת

כדי להפיץ את הספרייה הממוזגת, עיינו בקטע העלאת הספרייה.

התנהגות ואמצעי הגנה

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

  • אפשר לפרסם ספריות משולבות רק כארטיפקט AAR של ספריית Android כדי להוסיף אותן כתלות.
  • אין תמיכה בשילוב ספריות שמשתמשות בקישור נתונים.
  • אי אפשר למזג כמה סוגי build וגרסאות מוצר בספרייה ממוזגת אחת. יוצרים ספריות נפרדות של נתונים משולבים לווריאציות שונות.

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

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

Kotlin

 androidFusedLibrary { aarMetadata { minCompileSdk = 21 minCompileSdkExtension = 1 } }
מקורות מידע על Java אסור להשתמש בקובצי משאבים של Java בכמה ספריות עם נתיבים זהים, כי זה יגרום לכשל ב-build.

בעיות מוכרות

‫Fused Library הוא פלאגין חדש, ויש בעיות מוכרות שאנחנו מטפלים בהן כדי לתת מענה לכל התרחישים לדוגמה. אם נתקלתם בבעיות, אתם יכולים לדווח על באגים.

  • בעיה מספר 454305444: ספריות שמכילות כללי ProGuard של צרכנים שלא נקראים proguard.txt גורמות לכשל ב-build. הבעיה תוקנה ב-AGP מגרסה 9.1 ואילך.
  • בעיה מספר 374982739: הוספת יחסי תלות של קבצים בקובצי ‎ .aar אחרים
  • בעיה מספר 231433225: אין תמיכה בשילוב של פריטי מידע שנוצרו בתהליך פיתוח (Artifact) של RenderScript ו-Prefab

הסבר על יחסי התלות של ספרייה משולבת

לספרייה הממוזגת אין מקורות, והיא משתמשת בספריות של Android כמקור היחיד שלה. לכן חשוב להבין מה מגיע מאיפה. כדי להציג את רשימת יחסי התלות שמוזגו לארטיפקט שנוצר ואת יחסי התלות שנדרשים כדי ליצור את הארטיפקט, מריצים את המשימה gradle :report בספרייה הממוזגת. המשימה יוצרת דוח JSON שנשמר בספרייה build/reports של הספרייה הממוזגת.

כדי לקבל מידע נוסף על יחסי תלות פנימיים של פלאגינים, מריצים את המשימה gradle :dependencies כדי לראות את המצב של הגדרות הפלאגינים.