עדכונים לממשק ה-API של הפלאגין של Android Gradle

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

מעקב אחר הוצאות משימוש והסרות של ממשקי API

בטבלה הבאה מפורט מתי ממשקי ה-API של AGP הוצאו משימוש והוסרו, בהתאם לגרסה של AGP.

AGP 8.8

לפניכם עדכוני API חשובים ל-AGP 8.8.

הגדרות המשאבים הוצאו משימוש

הגדרות משאבים הוצאו משימוש החל מ-AGP 8.8. הסיבה לכך היא ש-AGP לא תומך יותר בצפיפות משאבים שונה, ושמעכשיו נדרש לפרסם אפליקציות כ-App Bundles ב-Google Play Console. כדי להגדיר את השפה, אפשר לציין את השפות המקומיות שהאפליקציה תומכת בהן באמצעות ה-DSL של localeFilters כדי למפות את הגדרות השפה המקומית למשאבים המתאימים.

AGP 8.0

לפניכם עדכוני API חשובים ל-AGP 8.0.

Transform API הוסר

החל מגרסה AGP 8.0, ממשק ה-API Transform הוסר. כלומר, כל הכיתות בחבילה com.android.build.api.transform יוסרו.

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

ממשקי API חלופיים

אין תחליף יחיד ל-Transform API – יש ממשקי API חדשים ומותאמים לכל תרחיש לדוגמה. כל ממשקי ה-API החלופיים נמצאים בבלוק androidComponents {}. כל ממשקי ה-API האלה זמינים ב-AGP 7.2 ואילך.

תמיכה בטרנספורמציה של קוד בייט

כדי לבצע טרנספורמציה של בייטקוד, צריך להשתמש ב-Instrumentation API. בספריות, אפשר לרשום מכשיר למדידה רק לכיתות מקומיות בפרויקט. באפליקציות ובבדיקות, אפשר לרשום מכשיר למדידה רק לכיתות מקומיות או לכל הכיתות, כולל יחסי תלות מקומיים ומרוחקים. כדי להשתמש ב-API הזה, האינסטרומנטציה פועל בנפרד בכל מחלקה, עם גישה מוגבלת למחלקות אחרות ב-classpath (מידע נוסף זמין ב-createClassVisitor()). ההגבלה הזו משפרת את הביצועים של גרסאות build מלאות ושל גרסאות build מצטברות, ומאפשרת לשמור על ממשק API פשוט. כל ספרייה מתבצעת במקביל ברגע שהיא מוכנה, ולא בסיום כל תהליך ה-compilation. בנוסף, שינוי בכיתה אחת אומר שצריך לבצע שוב הטמעה של המודולים רק בכיתות המושפעות ב-build מצטבר. דוגמה לשימוש ב-Instrumentation API מופיעה במתכון AGP Transforming classes with ASM.

תמיכה בהוספת כיתות שנוצרו לאפליקציה

כדי להוסיף לאפליקציה עוד כיתות שנוצרו, משתמשים ב-API של Artifacts עם MultipleArtifact.ALL_CLASSES_DIRS. ובאופן ספציפי, משתמשים

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

עם MultipleArtifact.ALL_CLASSES_DIRS כדי לצרף עוד ספריות שנוצרו למחלקות הפרויקט. ה-Artifacts API יבחר באופן אוטומטי מיקום ייחודי להפקת הפלט של המשימה בהתאמה אישית. במתכון addToAllClasses מוסבר איך משתמשים בממשק ה-API הזה.

תמיכה בטרנספורמציות שמבוססות על ניתוח של התוכנית כולה

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

כדי לרשום משימה שמשנה את כל המחלקות יחד, הפלאגין Android Gradle בגרסה 7.4 כולל את ה-API Artifacts.forScope. כדי להמיר את כל הכיתות בפרויקט הנוכחי, משתמשים ב-Artifacts.forScope.PROJECT. כדי להמיר את כל הכיתות בפרויקט הנוכחי, את הפרויקטים המיובאים ואת כל יחסי התלות החיצוניים, משתמשים ב-Artifacts.forScope.ALL. בקוד הבא מוסבר איך להשתמש ב-Artifacts.forScope.ALL כדי לרשום משימה שמבצעת טרנספורמציה של כל הכיתות יחד:

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

במתכון שלmodifyProjectClasses תוכלו לראות דוגמה לאופן השימוש ב-API הזה, ובמתכון של AdjustAgpDsl דוגמה לרישום תוספים מותאמים אישית לסוגי ה-build של Android.

אם התרחיש לדוגמה שלכם לא מכוסה באף אחד מממשקי ה-API של AndroidComponents, עליכם לדווח על באג.

כבר העברנו כמה יישומי פלאגין נפוצים לשימוש ב-API החדשים האלה, כולל הפלאגין למעקב אחר ביצועים של Firebase (גרסה 1.4.1 תואמת ל-AGP 8.0) והפלאגין Hilt Gradle (גרסה 2.40.1 תואמת ל-AGP 8.0). כלי Assistant Upgrade של AGP יעזור גם למפתחי פרויקטים לשדרג פלאגינים נפוצים לפי הצורך.

אם אתם משתמשים ב-Transform API דרך פלאגין של צד שלישי, צריך להודיע למחבר שצריך לעדכן את הפלאגין שלו כדי שיעבוד עם ממשקי ה-API החדשים ל-AGP 8.0.

AGP 7.2

בטבלה הבאה מפורטים עדכוני API חשובים ל-AGP 7.2.

RenderScript הוצא משימוש

החל מ-AGP 7.2, ממשקי ה-API של RenderScript הוצאו משימוש. הן ימשיכו לפעול, אבל יוצגו אזהרות לגביהן, והן יוסרו לגמרי בגרסאות עתידיות של AGP. במאמר מעבר מ-RenderScript מוסבר איך עוברים מ-RenderScript.

האפשרויות Component.transformClassesWith ו-Component.setAsmFramesComputationMode הוצאו משימוש

החל מגרסה AGP 7.2, ממשקי ה-API למדידה של קוד בייט של הכיתה Component.transformClassesWith ו-Component.setAsmFramesComputationMode הוצאו משימוש. הם הועברו לבלוק חדש, Component.instrumentation, שמכיל את כל ממשקי ה-API שקשורים להגדרת תהליך המדידה. כדי להמשיך להשתמש בתכונות המדידה האלה, צריך להשתמש ב-APIs המתאימים בבלוק החדש במקום זאת, כפי שמוצג בקטע הקוד הבא:

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }