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

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

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

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

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

Groovy

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 בספרייה כדי לציין למפעילים שלה שהם צריכים לבצע בדיקות בסביבת זמן הריצה. מערכת AndroidLint משתמשת במידע של 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 ברמת המודול:

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

1. buildTypes{}

2. productFlavors{}

3. defaultConfig{}

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

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

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

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

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

Groovy

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

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

למידע נוסף, אפשר לעיין במסמכי העזרה של Gradle בנושא שימוש ב-fixtures לבדיקה.