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

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

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

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

API	הוצאה משימוש בגרסת AGP	הוסר מגרסת AGP
Component.setAsmFramesComputationMode	7.2
Component.transformClassesWith	7.2
RenderScript	7.2
Transform	7.2	8.0

AGP 8.12

פלאגין של Android Gradle בגרסה 8.12.0 כולל את השינויים הבאים ב-API.

שינוי בהתנהגות: האפשרות includeAndroidResources ממזגת את המניפסט מספריית הבדיקה

עכשיו אתם יכולים ליצור קובץ AndroidManifest.xml בספריית קובצי המקור לבדיקה כדי להתאים אישית את המניפסט לבדיקות יחידה באמצעות האפשרות android.testOptions.unitTests.includeAndroidResources. קובץ המניפסט של הבדיקה יתמזג עם המניפסט הראשי של האפליקציה. בעיה מספר 127986458

AGP 8.10

פלאגין של Android Gradle 8.10.0 כולל את השינויים הבאים ב-API.

שינוי תוכנה שעלול לגרום לכשל ברמת המקור: עכשיו צריך להשתמש בסוגים עם פרמטרים ב-finalizeDsl

כדי לאפשר שימוש ב-AndroidComponentsExtension ישירות עם הפלאגין com.android.kotlin.multiplatform.library, הוגמש סוג הקישור ב-finalizeDsl.

לדוגמה, אם השתמשתם בסוגים גולמיים של AndroidComponentsExtension כדי לטפל באפליקציות ובספריות:

extensions.getByType(AndroidComponentsExtension::class).finalizeDsl { androidExtension ->
  androidExtension.experimentalProperties["android.example"] = true
}

לפני השדרוג או במהלכו, תצטרכו לשנות את קוד המקור למשהו כמו:

extensions.getByType<AndroidComponentsExtension<CommonExtension<*, *, *, *, *, *>, *, *>>().finalizeDsl { androidExtension ->
  androidExtension.experimentalProperties["android.example"] = true
}

שימו לב: אם אתם רוצים לכתוב קוד finalizeDsl שפועל גם עם הפלאגינים הנוכחיים של com.android.library ו-com.android.application וגם עם הפלאגין החדש של com.android.kotlin.multiplatform.library, יכול להיות שתצטרכו לבדוק את הסוגים בזמן הריצה:

extensions.getByType<AndroidComponentsExtension<*, *, *>>().finalizeDsl { androidExtension ->
  when(androidExtension) {
    is CommonExtension<*, *, *, *, *, *> -> androidExtension.experimentalProperties["android.example"] = true
    is KotlinMultiplatformAndroidLibraryExtension -> androidExtension.experimentalProperties["android.example"] = true
  }
}

זהו שינוי תוכנה שעלול לגרום לכשל ברמת המקור בלבד, והוא לא ישפיע על פלאגינים בינאריים.

AGP 8.8

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

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

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

AGP 8.0

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

הסרנו את Transform API

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

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

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

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

תמיכה בהמרת קוד בייט (bytecode)

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

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

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

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

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

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

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

כדי לרשום משימה שמשנה את כל המחלקות ביחד, בפלאגין של 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 הזה, ובמתכון customizeAgpDsl יש דוגמה לרישום של תוספים בהתאמה אישית לסוגי ה-build של Android.

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

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

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

AGP 7.2

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

‫RenderScript הוצא משימוש

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

המאפיינים Component.transformClassesWith ו-Component.setAsmFramesComputationMode הוצאו משימוש

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

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