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

בדף הזה מוסבר על המאפיינים והאפשרויות שצריך כדי להכין את הפרויקט של ספריית Android לפרסום באמצעות פלאגין Android ל-Gradle‏ (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 עם קבוצות של קוד מקור.

הפעלת בדיקות

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

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

Groovy

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

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

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