יצירת ספרייה ל-Android

מבחינה מבנית, ספריית Android זהה למודול של אפליקציית Android. הוא כולל את כל מה שדרוש כדי ליצור אפליקציה, כולל קוד מקור, קובצי משאבים ומניפסט של Android.

עם זאת, במקום להפעיל קומפילציה לקובץ APK שפועל במכשיר, ספריית Android עוברת קומפילציה לקובץ Android Archive ‏ (AAR) שאפשר להשתמש בו כיחס תלות למודול של אפליקציית Android. בניגוד לקובצי JAR, קובצי AAR מציעים את הפונקציונליות הבאה לאפליקציות ל-Android:

  • קובצי AAR יכולים להכיל משאבי Android וקובץ מניפסט, שמאפשרים לארוז משאבים משותפים כמו פריסות ורכיבי drawable, בנוסף לשיעורים ולשיטות של Kotlin או Java.
  • קובצי AAR יכולים להכיל ספריות C/C++ לשימוש בקוד C/C++ של מודול האפליקציה.

מודול ספרייה שימושי במצבים הבאים:

  • כשמפתחים כמה אפליקציות שמשתמשות בחלק מהרכיבים, כמו פעילויות, שירותים או פריסות של ממשק משתמש
  • כשיוצרים אפליקציה שקיימת בכמה וריאציות של APK, כמו גרסה בחינם וגרסה בתשלום, שיש להן רכיבי ליבה משותפים

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

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

יצירת מודול ספרייה

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

  1. לוחצים על קובץ > חדש > מודול חדש.
  2. בתיבת הדו-שיח Create New Module, לוחצים על Android Library ואז על Next.

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

  3. נותנים שם לספרייה ובוחרים גרסה מינימלית של SDK לקוד בספרייה, ואז לוחצים על סיום.

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

המרת מודול של אפליקציה למודול של ספרייה

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

  1. פותחים את הקובץ build.gradle ברמת המודול, אם משתמשים ב-Groovy, או את הקובץ build.gradle.kts, אם משתמשים בסקריפט של Kotlin.
  2. מוחקים את השורה של applicationId. רק מודול של אפליקציית Android יכול להגדיר את זה.
  3. מחפשים את הבלוק 'plugins' בחלק העליון של הקובץ. הוא נראה כך:

    Groovy

      plugins {
      id 'com.android.application'
  }

    Kotlin

      plugins {
      id("com.android.application")
  }

    משנים אותו כך:

    Groovy

      plugins {
      id 'com.android.library'
  }

    Kotlin

      plugins {
      id("com.android.library")
  }
  4. שומרים את הקובץ ולוחצים על קובץ > סנכרון הפרויקט עם קובצי Gradle.

המבנה של המודול לא השתנה, אבל הוא פועל עכשיו כספריית Android. ה-build יוצר קובץ AAR במקום קובץ APK.

כדי ליצור את קובץ ה-AAR, בוחרים את מודול הספרייה בחלון Project ולוחצים על Build > Build APK.

הוספת יחסי תלות באמצעות תיבת הדו-שיח Project Structure (מבנה הפרויקט)

אפשר להשתמש בתיבת הדו-שיח Project Structure כדי להוסיף יחסי תלות לפרויקט. בקטעים הבאים מוסבר איך להשתמש בתיבת הדו-שיח כדי להוסיף יחסי תלות.

שימוש בספרייה מתוך אותו פרויקט

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

  1. עוברים אל קובץ > מבנה הפרויקט > יחסי תלות.
  2. בוחרים את המודול שרוצים להוסיף לו את הספרייה.
  3. בכרטיסייה Declared Dependencies, לוחצים על ובוחרים באפשרות Module Dependency בתפריט.

  4. בתיבת הדו-שיח Add Module Dependency בוחרים את מודול הספרייה.

    הוספת יחסי תלות בין מודולים בתיבת הדו-שיח Project Structure (מבנה הפרויקט)

  5. בוחרים את ההגדרה שדורשת את התלות הזו, או בוחרים באפשרות הטמעה אם היא רלוונטית לכל ההגדרות, ולוחצים על אישור.

Android Studio עורכת את הקובץ build.gradle או build.gradle.kts של המודול כדי להוסיף את התלות, בצורה הבאה:

Groovy

  implementation project(path: ":example-library")

Kotlin

  implementation(project(":example-library"))

שימוש בספרייה בפרויקטים אחרים

הדרך המומלצת לשתף יחסי תלות (קובצי JAR ו-AAR) היא באמצעות מאגר Maven, שמתארח בשירות כמו Maven Central או באמצעות מבנה ספריות בדיסק המקומי. למידע נוסף על שימוש במאגרי Maven, ראו מאגרים מרוחקים.

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

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

  1. עוברים אל קובץ > מבנה הפרויקט > יחסי תלות.
  2. בכרטיסייה Declared Dependencies, לוחצים על ובוחרים באפשרות Library Dependency בתפריט.

  3. בתיבת הדו-שיח Add Library Dependency, משתמשים בתיבת החיפוש כדי למצוא את הספרייה שרוצים להוסיף. בטופס הזה אפשר לחפש במאגרים שצוינו בבלוק dependencyResolutionManagement { repositories {...}} בקובץ settings.gradle או settings.gradle.kts.

    הוספת תלות בספרייה בתיבת הדו-שיח Project Structure (מבנה הפרויקט)

  4. בוחרים את ההגדרה שדורשת את התלות הזאת או בוחרים באפשרות Embed (הטמעה) אם היא רלוונטית לכל ההגדרות, ולוחצים על OK (אישור).

צריך לבדוק את הקובץ build.gradle או build.gradle.kts של האפליקציה כדי לוודא שמופיעה הצהרה שדומה לזו (בהתאם להגדרת ה-build שבחרת):

Groovy

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

  implementation("com.example:examplelibrary:1.0.0")

הוספת קובץ ה-AAR או ה-JAR כיחס תלות

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

  1. עוברים אל קובץ > מבנה הפרויקט > יחסי תלות.
  2. בכרטיסייה Declared Dependencies, לוחצים על ובוחרים Jar Dependency בתפריט.

  3. בתיבת הדו-שיח Add Jar/Aar Dependency, מזינים את הנתיב לקובץ ה-AAR או ה-JAR ובוחרים את ההגדרה שאליה רלוונטית התלות. אם רוצים שהספרייה תהיה זמינה לכל ההגדרות, בוחרים את ההגדרה implementation.

    הוספת תלות ב-AAR בתיבת הדו-שיח Project Structure (מבנה הפרויקט)

    בודקים את הקובץ build.gradle או build.gradle.kts של האפליקציה כדי לוודא שמופיעה הצהרה דומה לזו (בהתאם להגדרת ה-build שבחרתם):

    Groovy

      implementation files('my_path/my_lib.aar')

    Kotlin

      implementation(files("my_path/my_lib.aar"))

כדי לייבא תלות ב-build של Gradle שפועל מחוץ ל-Android Studio, צריך להוסיף נתיב לתלות בקובץ build.gradle או build.gradle.kts של האפליקציה. לדוגמה:

Groovy

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}

Kotlin

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

מידע נוסף על הוספת יחסי תלות ב-Gradle זמין במאמר הוספת יחסי תלות ל-build.

הצהרה על משאב ציבורי

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

כדי להצהיר על משאב ציבורי, צריך להוסיף הצהרת <public> לקובץ public.xml של הספרייה. אם עדיין לא הוספתם משאבים ציבוריים, תצטרכו ליצור את הקובץ public.xml בתיקייה res/values/ בספרייה.

הקוד לדוגמה הבא יוצר שני משאבי מחרוזת ציבוריים בשמות mylib_app_name ו-mylib_public_string:

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

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

כל המשאבים שרוצים שימשיכו להיות גלויים למפתחים שמשתמשים בספרייה צריכים להיות גלויים לכולם.

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

כשיוצרים ספרייה, הפלאגין של Android Gradle מקבל את הגדרות המשאבים הציבוריים ומחלץ אותן לקובץ public.txt, שמארז לאחר מכן בתוך קובץ ה-AAR.

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

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

  • הספריות מוזגו לפי סדר העדיפות.

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

  • מניעת התנגשויות במיזוג משאבים

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

    אם יש סתירות בין כמה ספריות AAR, המערכת תשתמש במשאב מהספרייה שמופיעה ראשונה ברשימת יחסי התלות (הכי קרובה לחלק העליון של הבלוק dependencies).

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

  • ב-builds עם כמה מודולים, יחסי תלות ב-JAR נחשבים ליחסי תלות טרנזיטיביים.

    כשמוסיפים יחסי תלות של JAR לפרויקט ספרייה שמפיק קובץ AAR, יחסי התלות של ה-JAR עוברים עיבוד על ידי מודול הספרייה ומארזים אותם עם קובץ ה-AAR שלו.

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

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

  • מודול ספרייה יכול להיות תלוי בספריית JAR חיצונית.

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

    חשוב לזכור שגם מודול הספרייה וגם האפליקציה התלויה צריכים להצהיר על הספרייה החיצונית בקובצי המניפסט שלהם באמצעות רכיב <uses-library>.

  • הערך של minSdkVersion במודול האפליקציה חייב להיות שווה או גדול מהגרסה שמוגדרת בספרייה.

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

  • כל מודול בספרייה יוצר כיתה R משלו.

    כשמפתחים את המודולים של האפליקציות התלויות, המודולים של הספרייה עוברים הידור לקובץ AAR ולאחר מכן נוספים למודול של האפליקציה. לכן, לכל ספרייה יש סוג R משלה, שנקרא לפי שם החבילה של הספרייה.

    הכיתה R שנוצרת מהמודול הראשי ומהמודול של הספרייה נוצרת בכל החבילות הנדרשות, כולל החבילה של המודול הראשי והחבילות של הספריות.

  • מודול ספרייה עשוי לכלול קובץ תצורה משלו ב-ProGuard.

    אם יש לכם פרויקט ספרייה שבו אתם משתמשים כדי ליצור ולפרסם קובץ AAR, תוכלו להוסיף קובץ תצורה של ProGuard להגדרות ה-build של הספרייה. אם תעשו זאת, הפלאגין של Android Gradle יחיל את כללי ProGuard שציינתם. כלי ה-build מטמיעים את הקובץ הזה בקובץ ה-AAR שנוצר בשביל מודול הספרייה. כשמוסיפים את הספרייה למודול של אפליקציה, קובץ ProGuard של הספרייה מצורף לקובץ התצורה של ProGuard (proguard.txt) של מודול האפליקציה.

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

    כדי להוסיף את כללי ProGuard לפרויקט הספרייה, מציינים את שם הקובץ באמצעות המאפיין consumerProguardFiles בתוך הבלוק defaultConfig בקובץ build.gradle או בקובץ build.gradle.kts של הספרייה.

    לדוגמה, קטע הקוד הבא מגדיר את lib-proguard-rules.txt כקובץ התצורה של הספרייה ב-ProGuard:

    Groovy

    android {
    defaultConfig {
        consumerProguardFiles 'lib-proguard-rules.txt'
    }
    ...
}

    Kotlin

    android {
    defaultConfig {
        consumerProguardFiles("lib-proguard-rules.txt")
    }
    ...
}

    עם זאת, אם מודול הספרייה הוא חלק מ-build עם כמה מודולים שמתבצע לו הידור ל-APK ולא נוצר AAR, צריך להריץ צמצום קוד רק במודול האפליקציה שמשתמש בספרייה. לקבלת מידע נוסף על כללי ProGuard ועל השימוש בהם, אפשר לקרוא את המאמר כיווץ, ערפול קוד (obfuscation) ואופטימיזציה של האפליקציה.

  • בדיקת מודול בספרייה דומה כמעט לבדיקת אפליקציה.

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

    כשממזגים כמה קובצי מניפסט, Gradle פועל לפי סדר העדיפויות שמוגדר כברירת מחדל וממזג את המניפסט של הספרייה עם המניפסט הראשי של קובץ ה-APK לבדיקה.

המבנה של קובץ AAR

סיומת הקובץ של קובץ AAR היא .aar, וסוג הפריט שנוצר בתהליך פיתוח (artifact) ב-Maven הוא גם aar. הקובץ עצמו הוא קובץ ZIP. הערך היחיד שחובה להזין הוא /AndroidManifest.xml.

קובץ AAR יכול לכלול גם אחת או יותר מהרשומות האופציונליות הבאות: