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

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

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

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

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

מגניב

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

Kotlin

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

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

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

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

בחירת ערך של minSdkVersion

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

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

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

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

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

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

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

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

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

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

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

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

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

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

בחירת ערך ל-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 נותן עדיפות למיקומי ההגדרות באופן הבא במהלך תהליך ה-build:

1. buildTypes{}

2. productFlavors{}

3. defaultConfig{}

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

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

הפעלת מתקני בדיקה

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

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

מגניב

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

כשמפעילים את מתקני הבדיקה, Gradle יוצר באופן אוטומטי קבוצת מקורות src/testFixtures שבה אפשר לכתוב מתקני בדיקה.

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