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

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

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

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

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

Groovy

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:

Groovy

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 ברמת המודול:

Groovy

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

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

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