כיוצרי ספרייה, אתם צריכים לוודא שמפתחי אפליקציות יכולים לשלב בקלות את הספרייה שלכם באפליקציה שלהם, תוך שמירה על חוויית משתמש קצה איכותית. כלומר, הספרייה צריכה להיות תואמת לאופטימיזציה של Android (R8) בלי לדרוש הגדרה נוספת מהמפתח, או לתעד שהספרייה לא מתאימה לשימוש ב-Android. חשוב מאוד שספריות שמיועדות לשימוש ב-Android לא ימנעו אופטימיזציות חשובות של האפליקציה, ויעמדו בדרישות אופטימיזציה נוספות.
המסמכים האלה מיועדים למפתחים של ספריות שפורסמו, אבל הם יכולים להיות שימושיים גם למפתחים של מודולים פנימיים של ספריות באפליקציה גדולה ומודולרית.
אם אתם מפתחי אפליקציות ורוצים לדעת איך לבצע אופטימיזציה של האפליקציה שלכם ל-Android, קראו את המאמר הפעלת אופטימיזציה של אפליקציות. במאמר בחירת ספריות בתבונה מוסבר באילו ספריות כדאי להשתמש.
הסבר על סוגי כללי השמירה
יש שני סוגים שונים של כללי שמירה שאפשר להגדיר בספריות:
- כללי שמירה על נתונים של צרכנים חייבים לציין כללים ששומרים את כל מה שהספרייה משקפת. אם ספרייה משתמשת ב-reflection או ב-JNI כדי לקרוא לקוד שלה, או לקוד שמוגדר על ידי אפליקציית לקוח, הכללים האלה צריכים לתאר איזה קוד צריך לשמור. ספריות צריכות לארוז כללי שמירה של צרכנים, שמשתמשים באותו פורמט כמו כללי שמירה של אפליקציות. הכללים האלה מקובצים לקובצי ארטיפקטים של ספריות (AAR או JAR) ונצרכים באופן אוטומטי במהלך האופטימיזציה של אפליקציית Android כשמשתמשים בספרייה. הכללים האלה מנוהלים בקובץ שצוין במאפיין
consumerProguardFilesבקובץbuild.gradle.kts(אוbuild.gradle). מידע נוסף זמין במאמר כתיבת כללי שמירה של צרכנים. - כללי שמירה של גרסת build של ספרייה מופעלים כשיוצרים את הספרייה. הם נדרשים רק אם מחליטים לבצע אופטימיזציה חלקית של הספרייה בזמן ה-build. הם צריכים למנוע את ההסרה של ה-API הציבורי של הספרייה, אחרת ה-API הציבורי לא יהיה קיים בהפצה של הספרייה, ומפתחי האפליקציות לא יוכלו להשתמש בספרייה. הכללים האלה מנוהלים בקובץ שצוין במאפיין
proguardFilesבקובץbuild.gradle.kts(אוbuild.gradle). מידע נוסף זמין במאמר אופטימיזציה של גרסת build של ספריית AAR.
דרישות והנחיות לאופטימיזציה
ההגדרות של R8 בספריות משפיעות באופן גלובלי על הגודל הסופי של הקובץ הבינארי ועל הביצועים של האפליקציה שמשתמשת בהן. בנוסף לשיטות המומלצות הכלליות לכללי שמירה, יוצרי ספריות צריכים לעמוד בדרישות ספציפיות ולהביא בחשבון הנחיות נוספות.
עמידה בדרישות האופטימיזציה
חוסר יעילות בספריות הוא גורם משמעותי לניפוח האפליקציה, לבזבוז זיכרון, להפעלה איטית ולשגיאות מסוג "האפליקציה לא מגיבה" (ANR). כדי לא לפגוע באופן משמעותי באיכות האפליקציה ובחוויית המשתמש, אסור להפר את הדרישות הבאות בספריות.
אל תשתמשו בכללי שמירה רחבים או כאלה שחלים על כל החבילה: הספרייה לא יכולה לכלול כללי שמירה רחבים ששומרים את רוב הקוד בספרייה שלכם או בספרייה אחרת. כללי שמירה רחבים יכולים לפתור קריסות בטווח הקצר, אבל הם מגדילים את הנפח של כל האפליקציות שמשתמשות בספרייה.
אל תכללו כללי שמירה שחלים על כל החבילה (כמו
-keep class com.mylibrary.** {*; }) לחבילות בספרייה שלכם או בספריות אחרות שאתם מפנים אליהן. כללים כאלה מגבילים את האופטימיזציה של החבילות האלה בכל האפליקציות שמשתמשות בספרייה שלכם.אל תכללו כללי שמירה רחבים ליחסי תלות של צד שלישי שהספרייה שלכם צורכת (לדוגמה,
-keep public class com.google.android.gms.** { *; }). ספריות חיצוניות רבות כבר כוללות כללי שמירה משלהן לצרכנים. הוספה של כלל שחל על כל החבילה מחליפה את הכללים האלה ומאלצת את R8 לשמור קוד של יחסי תלות ללא הפניה בכל האפליקציה.אין כללים גלובליים לא מתאימים: אף פעם אל תשתמשו באפשרויות גלובליות כמו
-dontobfuscateאו-allowaccessmodification.שימוש ביצירת קוד במקום ברפלקציה כשאפשר: כשאפשר, השתמשו ביצירת קוד (codegen) במקום ברפלקציה. יצירת קוד ורפלקציה הן שתי גישות נפוצות להימנעות מקוד שחוזר על עצמו (boilerplate) בזמן התכנות, אבל יצירת קוד מתאימה יותר לכלי אופטימיזציה של אפליקציות כמו R8.
בעזרת codegen, הקוד מנותח ומשתנה במהלך תהליך ה-build. מכיוון שאין שינויים משמעותיים אחרי זמן ההידור, כלי האופטימיזציה יודע איזה קוד נדרש בסופו של דבר ומה אפשר להסיר בבטחה.
באמצעות רפלקציה, הקוד מנותח ומעובד בזמן הריצה. הקוד לא באמת סופי עד שהוא מופעל, ולכן הכלי לאופטימיזציה לא יודע איזה קוד אפשר להסיר בלי לגרום לבעיות. סביר להניח שהוא יסיר קוד שנעשה בו שימוש באופן דינמי באמצעות רפלקציה בזמן הריצה, מה שיגרום לאפליקציה לקרוס אצל המשתמשים.
הרבה ספריות מודרניות משתמשות ב-codegen במקום ב-reflection. ב-KSP יש נקודת כניסה נפוצה שמשמשת את Room, את Hilt ועוד הרבה ספריות אחרות.
תמיכה במצב מלא של R8: הספרייה לא אמורה לקרוס כשהמצב המלא של R8 מופעל. מצב מלא של R8 הוא המצב המומלץ לשימוש ב-R8, והוא מוגדר כברירת מחדל מאז AGP 8.0, שהפך ליציב ב-2023. אם הספרייה קורסת ב-R8, הפתרון הוא לזהות את נקודת הכניסה הספציפית של ה-reflection או ה-JNI ולהוסיף כלל ממוקד, ולא לשמור את כל החבילה. כדי ליצור כללים ממוקדים מהערות בנקודות הכניסה האלה, משתמשים ב-Jetpack Keep.
המלצות נוספות
בנוסף לדרישות האופטימיזציה, ריכזנו כאן כמה המלצות נוספות.
אל תשתמשו ב-
-repackageclassesבקובץ כללי השמירה של הצרכנים בספרייה. כללי השמירה הספציפיים של הצרכן מוזגו לתוך הגדרות ה-R8 של כל אפליקציה שמשתמשת בספרייה שלכם, כך שהאפשרות הגלובלית הזו חלה על כל האפליקציה ומבטלת את הגדרות האריזה מחדש של מפתח האפליקציה. כברירת מחדל, החל מ-AGP 9.0, פרסום הספרייה נכשל אם כללי השמירה של הצרכן מכילים אפשרויות גלובליות. מידע נוסף זמין בנתוני הגרסה של AGP 9.0.כדי לבצע אופטימיזציה של גרסת ה-build של הספרייה, אפשר להשתמש ב-
-repackageclassesעם שם חבילה פנימי, כמו<your.library.package>.internal, בקובץ כללי השמירה של גרסת ה-build של הספרייה. הפעולה הזו יכולה לשפר את היעילות של הספרייה באפליקציות שלא עברו אופטימיזציה, אבל בדרך כלל היא לא נחוצה כי גם האפליקציות צריכות לעבור אופטימיזציה.הצהירו על כל המאפיינים שדרושים לפעולת הספרייה בקובצי כללי השמירה של הספרייה, גם אם יכולה להיות חפיפה עם המאפיינים שמוגדרים ב-
proguard-android-optimize.txt.אם אתם צריכים את המאפיינים הבאים בהפצה של הספרייה, שמרו אותם בקובץ כללי השמירה של ה-build של הספרייה, ולא בקובץ כללי השמירה של הצרכן של הספרייה:
AnnotationDefaultEnclosingMethodExceptionsInnerClassesRuntimeInvisibleAnnotationsRuntimeInvisibleParameterAnnotationsRuntimeInvisibleTypeAnnotationsRuntimeVisibleAnnotationsRuntimeVisibleParameterAnnotationsRuntimeVisibleTypeAnnotationsSignature
מפתחי ספריות צריכים לשמור את המאפיין
RuntimeVisibleAnnotationsבכללי השמירה לצרכנים אם משתמשים באנוטציות בזמן ריצה.יוצרי ספריות לא צריכים להשתמש באפשרויות הגלובליות הבאות בכללי השמירה של הצרכן. בדומה ל-
-repackageclasses, האפשרויות האלה מגדירות את כל ה-build של R8 באפליקציה, ולא רק את הקוד של הספרייה, אז תשאירו אותן למפתח האפליקציה:-include-basedirectory-injars-outjars-libraryjars-repackageclasses-flattenpackagehierarchy-allowaccessmodification-renamesourcefileattribute-ignorewarnings-addconfigurationdebugging-printconfiguration-printmapping-printusage-printseeds-applymapping-obfuscationdictionary-classobfuscationdictionary-packageobfuscationdictionary
מתי החזר האור תקין
אם אתם חייבים להשתמש ב-reflection, אתם צריכים להשתמש ב-reflection רק באחת מהאפשרויות הבאות:
- סוגי טירגוט ספציפיים (ממשקים ספציפיים או מחלקות משנה)
- קוד שמשתמש בהערת זמן ריצה ספציפית
שימוש ב-reflection בדרך הזו מגביל את עלות זמן הריצה, ומאפשר לכתוב כללי שמירה ממוקדים על נתונים של צרכנים.
הצורה הספציפית והממוקדת הזו של רפלקציה היא דפוס שאפשר לראות גם ב-Android framework (לדוגמה, כשמנפחים פעילויות, תצוגות ורכיבים שניתנים לשרטוט) וגם בספריות AndroidX (לדוגמה, כשיוצרים את WorkManager
ListenableWorkers או את RoomDatabases). לעומת זאת, הרפלקציה הפתוחה של Gson לא מתאימה לשימוש באפליקציות ל-Android.
תפיסות מוטעות נפוצות
יש כמה תפיסות מוטעות נפוצות שעלולות להוביל להגדרה שגויה של R8. למשל:
הבנה שגויה של האופטימיזציות של R8: בניגוד לתפיסה הרווחת, האופטימיזציות של R8 לא מוגבלות רק לערפול קוד, אלא כוללות גם כיווץ קוד ואופטימיזציות לוגיות באמצעות שיטות של הטמעת שיטות ומיזוג כיתות. מידע נוסף זמין בסקירה הכללית על אופטימיזציה של R8.
מעקף של אופטימיזציה של ספריות מעורפלות: שגיאה נפוצה היא להשמיט ספרייה מהאופטימיזציה, כי הספרייה עברה אופטימיזציה או ערפול כשהיא קומפלה ל-AAR (ארכיון Android) או ל-JAR (ארכיון Java). האופטימיזציות במהלך יצירת הספרייה מוגבלות, והאפליקציה לא אמורה להשבית את האופטימיזציה של הספרייה על ידי הכללה שלה בכלל שמירה. מידע נוסף זמין במאמר אופטימיזציה של גרסת build של ספריית AAR.
הבנה שגויה של האפשרות
-keepהכלל-keepמונע מ-R8 להריץ את סבבי האופטימיזציה שלו. מידע נוסף זמין במאמר בחירת אפשרות השמירה המתאימה.
אימות האיכות של כלל השמירה של הצרכן
כדי לוודא שהספרייה לא מונעת יותר מדי אופטימיזציה של הקוד כשהיא מוטמעת באפליקציה, אתם יכולים להשתמש בדוגמה לספרייה או באפליקציה לבדיקת השילוב. מפעילים את R8 ובודקים את איכות ההגדרה הכוללת של R8 באפליקציה באמצעות R8 Configuration Analyzer.
אם כללי הצרכן מגבילים את האופטימיזציה בחלקים גדולים מהקוד של הספרייה, זה סימן שצריך לשפר את כללי הצרכן. צמצמו את כללי הצרכן ובדקו את כל ההיבטים המושפעים של הספרייה באפליקציה שבה R8 מופעל.
הגדרת חבילת הכללים
כדי לוודא שכללי השמירה של הצרכן מיושמים בצורה נכונה, צריך לארוז אותם בהתאם לפורמט של הספרייה.
אם אתם משתמשים ב-Jetpack Keep כדי להצהיר על השימוש של הספרייה ב-Reflection וב-JNI, הפלאגין של Gradle יכול לארוז את הכללים שנוצרו ככללי שמירה של הצרכן.
ספריות AAR
כדי להוסיף כללי צרכן לספריית AAR, משתמשים באפשרות consumerProguardFiles בסקריפט ה-build של מודול הספרייה של Android. מידע נוסף זמין בהנחיות ליצירת מודולים של ספרייה.
Kotlin
android {
defaultConfig {
consumerProguardFiles("consumer-proguard-rules.pro")
}
...
}
מגניב
android {
defaultConfig {
consumerProguardFiles 'consumer-proguard-rules.pro'
}
...
}
ספריות JAR
כדי לכלול כללים בספריית Kotlin או Java שנשלחת כקובץ JAR, צריך להוסיף את קובץ הכללים לספרייה META-INF/proguard/ של קובץ ה-JAR הסופי, עם שם קובץ כלשהו.
לדוגמה, אם הקוד נמצא ב-<libraryroot>/src/main/kotlin, צריך להוסיף קובץ כללים של צרכן ב-<libraryroot>/src/main/resources/META-INF/proguard/consumer-proguard-rules.pro והכללים יקובצו במיקום הנכון בקובץ ה-JAR של הפלט.
מוודאים שקובץ ה-JAR הסופי כולל את הכללים בצורה נכונה, על ידי בדיקה שהכללים נמצאים בספרייה META-INF/proguard.
אופטימיזציה של גרסת ה-build של ספריית ה-AAR (מתקדם)
בדרך כלל אין צורך לבצע אופטימיזציה של גרסת build של ספרייה באופן ישיר, כי האופטימיזציות האפשריות בזמן ה-build של הספרייה מוגבלות מאוד. כמפתחי ספריות, אתם צריכים להביא בחשבון כמה שלבים של אופטימיזציה ולשמור על ההתנהגות בזמן פיתוח הספרייה והאפליקציה, לפני שאתם מבצעים אופטימיזציה של הספרייה.
אם אתם עדיין רוצים לבצע אופטימיזציה של הספרייה בזמן ה-build, הפלאגין של Android Gradle תומך בכך.
Kotlin
android {
buildTypes {
release {
isMinifyEnabled = true
proguardFiles(
getDefaultProguardFile("proguard-android-optimize.txt"),
"proguard-rules.pro"
)
}
configureEach {
consumerProguardFiles("consumer-rules.pro")
}
}
}
מגניב
android {
buildTypes {
release {
minifyEnabled true
proguardFiles
getDefaultProguardFile('proguard-android-optimize.txt'),
'proguard-rules.pro'
}
configureEach {
consumerProguardFiles "consumer-rules.pro"
}
}
}
שימו לב שההתנהגות של proguardFiles שונה מאוד מזו של consumerProguardFiles:
proguardFilesמשמשים בזמן ה-build, לעיתים קרובות יחד עםgetDefaultProguardFile("proguard-android-optimize.txt"), כדי להגדיר איזה חלק מהספרייה צריך להישמר במהלך ה-build של הספרייה. לכל הפחות, זהו ה-API הציבורי שלכם.- לעומת זאת, קובצי
consumerProguardFilesנארזים בספרייה כדי להשפיע על האופטימיזציות שמתרחשות מאוחר יותר, במהלך ה-build של אפליקציה שמשתמשת בספרייה.
לדוגמה, אם הספרייה משתמשת ברפלקציה כדי ליצור מחלקות פנימיות, יכול להיות שתצטרכו להגדיר את כללי השמירה גם ב-proguardFiles וגם ב-consumerProguardFiles.
אם אתם משתמשים ב--repackageclasses בגרסת ה-build של הספרייה, צריך לארוז מחדש את המחלקות לחבילת משנה בתוך החבילה של הספרייה. לדוגמה, צריך להשתמש ב--repackageclasses
'com.example.mylibrary.internal' במקום ב--repackageclasses 'internal'.
תמיכה בגרסאות שונות של R8 (מתקדם)
אתם יכולים להתאים אישית את הכללים כדי לטרגט גרסאות ספציפיות של R8. כך הספרייה שלכם תוכל לפעול בצורה אופטימלית בפרויקטים שמשתמשים בגרסאות חדשות יותר של R8, ועדיין יהיה אפשר להשתמש בכללים הקיימים בפרויקטים עם גרסאות ישנות יותר של R8.
כדי לציין כללי R8 מטורגטים, צריך לכלול אותם בספרייה META-INF/com.android.tools בתוך classes.jar של קובץ AAR או בספרייה META-INF/com.android.tools של קובץ JAR.
In an AAR library:
proguard.txt (legacy location, the file name must be "proguard.txt")
classes.jar
└── META-INF
└── com.android.tools (location of targeted R8 rules)
├── r8-from-<X>-upto-<Y>/<R8-rule-files>
└── ... (more directories with the same name format)
In a JAR library:
META-INF
├── proguard/<ProGuard-rule-files> (legacy location)
└── com.android.tools (location of targeted R8 rules)
├── r8-from-<X>-upto-<Y>/<R8-rule-files>
└── ... (more directories with the same name format)
בספרייה META-INF/com.android.tools יכולות להיות כמה ספריות משנה עם שמות בפורמט r8-from-<X>-upto-<Y>, כדי לציין לאילו גרסאות של R8 הכללים נכתבו. כל תת-ספרייה יכולה להכיל קובץ אחד או יותר עם כללי R8, עם שמות קבצים וסיומות כלשהם.
שימו לב שהחלקים -from-<X> ו--upto-<Y> הם אופציונליים, הגרסה <Y> היא בלעדית, וטווחי הגרסאות הם בדרך כלל רציפים אבל יכולים גם לחפוף.
לדוגמה, r8, r8-upto-8.0.0, r8-from-8.0.0-upto-8.2.0 ו-r8-from-8.2.0 הם שמות של ספריות שמייצגות קבוצה של כללי R8 מטורגטים. כל גרסאות R8 יכולות להשתמש בכללים שבספרייה r8. הכללים בספרייה r8-from-8.0.0-upto-8.2.0 יכולים לשמש את R8 מגרסה 8.0.0 עד גרסה 8.2.0, לא כולל.
הפלאגין של Android Gradle משתמש במידע הזה כדי לבחור את כל הכללים שבהם אפשר להשתמש בגרסת R8 הנוכחית. אם בספרייה לא צוינו כללי R8 מטורגטים, הפלאגין של Android Gradle יבחר את הכללים מהמיקומים הקודמים (proguard.txt ל-AAR או META-INF/proguard/<ProGuard-rule-files> ל-JAR).