הכנת הספרייה לגרסה

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

בחירת מרחב שמות

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

החל מ-AGP 7.0, אפשר להגדיר את מרחב השמות בקובץ build.gradle של האפליקציה, כמו בדוגמת הקוד הבאה:

מגניב

android {
  namespace = 'com.example.library'
}

Kotlin

android {
  namespace = "com.example.library"
}

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

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

בחירת ערך minSdkVersion

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

כשבוחרים minSdkVersion, חשוב לשים לב לשיקולים הבאים:

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

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

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

    תהליך מיזוג המניפסטים, שהוא שלב ב-AGP, ממזג קובצי מניפסטים מהאפליקציה ומהתלויות שלה, ומוודא שאף תלות לא כוללת minSdkVersion גבוה יותר מהאפליקציה.

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

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

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

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

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

הגדרת מטא-נתונים של AAR

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

בחירת ערך ל-minCompileSdk

החל מגרסה 4.1, ‏ AGP תומך ב-minCompileSdk. המאפיין הזה מציין את המינימום של compileSdk שפרויקטים צורכים יכולים להשתמש בו. אם הספרייה מכילה רשומות של מניפסט או משאבים שנעשה בהם שימוש במאפייני פלטפורמה חדשים יותר, צריך להגדיר את הערך הזה.

אפשר להגדיר את הערך minCompileSdk בבלוקים defaultConfig{},‏ productFlavors{} ו-buildTypes{} בקובץ build.gradle ברמת המודול:

מגניב

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    foo {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

Kotlin

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    register("foo") {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

אם מגדירים את minCompileSdk בכמה מקומות, Gradle נותן עדיפות למיקומי ההגדרות לפי הסדר הבא במהלך תהליך הבנייה:

  1. buildTypes{}

  2. productFlavors{}

  3. defaultConfig{}

בדוגמה הקודמת, שבה minCompileSdk מוגדר גם ב-defaultConfig{} וגם ב-productFlavors{}, העדיפות היא ל-productFlavors{} והערך של minCompileSdk מוגדר ל-30.

מידע נוסף על האופן שבו Gradle נותן עדיפות להגדרות כשמשלבים קוד ומשאבים זמין במאמר Build with source sets.

הפעלת בדיקות קבועות

Test fixtures משמשים בדרך כלל להגדרת הקוד שנבדק או להקלת הבדיקות של רכיב. החל מגרסה 7.1,‏ AGP יכול ליצור מתקני בדיקה לפרויקטים של ספריות, בנוסף לפרויקטים של אפליקציות ותכונות דינמיות.

כשמפרסמים ספרייה לשימוש של אחרים, כדאי ליצור מתקני בדיקה ל-API. אפשר להפעיל את ה-fixtures של הבדיקה בקובץ build.gradle ברמת המודול:

מגניב

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

כשמפעילים את התוסף test fixtures, ‏ Gradle יוצר באופן אוטומטי src/testFixtures קבוצת מקורות שבה אפשר לכתוב test fixtures.

מידע נוסף זמין במסמכי התיעוד של Gradle בנושא שימוש בנתוני בדיקה.