לוח הזמנים להעברת ה-DSL/API של פלאגין Android Gradle

‫Android Gradle Plugin‏ (AGP) היא מערכת ה-build הנתמכת לאפליקציות Android, והיא כוללת תמיכה בהידור של סוגים רבים ושונים של מקורות וקישור שלהם לאפליקציה שאפשר להפעיל במכשיר Android פיזי או באמולטור.

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

לרישום מפורט יותר של הוצאות משימוש או הסרות של AGP API, אפשר לעיין בעדכונים של AGP API.

‫AGP 10.0 (סוף 2026)

שינויים בממשק ה-API ומודרניזציה בפלאגין Android Gradle 10.0

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

למה כדאי להשתמש במודל של בנייה עצלה?

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

אם עוברים למודל build עצלני מלא באמצעות ספקי עצלנות (Provider<T>) וממשק Variant API מודרני (androidComponents {}), המערכת מחשבת את המאפיינים ואת חיבור המשימות באופן עצלני לפי דרישה רק כשצריך אותם לגרף הביצוע הפעיל של ה-build.

ממשקי ה-API הקודמים שיוסרו בגרסה הזו לא היו תואמים באופן מהותי לארכיטקטורה המודרנית הזו. הסרת התוספים האלה מאפשרת ל-AGP לתמוך באופן מלא ב-Gradle Configuration Cache וב-Project Isolation, וכך לשפר באופן משמעותי את מהירויות ה-build ואת זמני הסנכרון ב-Android Studio.

ההבדל המרכזי בארכיטקטורה

ה-API הקודם BaseVariant (applicationVariants.all {}) היה מבוסס על משימות. היא העניקה למפתחים גישה ישירה למשימות Gradle ולהגדרות פנימיות במהלך שלב ההגדרה, מה שפוגע באופן מובנה בתכונות הביצועים המודרניות של Gradle.

ה-Variant API החדש (androidComponents {}) הוא עצלן ומתמקד בארטיפקטים. הוא משתמש באופן נרחב ב-Property API של Gradle ומסיר לחלוטין את כל ההפניות אל Task ו-TaskProvider, כך שצריך לבצע אינטראקציה נקייה עם קלט ופלט (Variant.artifacts) ולא עם המשימות הבסיסיות עצמן.

מה יוסר ומה יתווסף

כל הממשקים והמחלקות הקודמים ששימשו ב-DSL מדור קודם וב-Variant API הישן נמחקים. כדי להכין את סקריפטים הבנייה ותוספים בהתאמה אישית, צריך להפסיק להשתמש בממשקי ה-API ובדגלים הבאים שיצאו משימוש:

הסרנו API או תכונה נדרשת החלפה או פעולה
גישה ישירה למשימה:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 ‫Artifacts API: במקום לאחזר את המשימה כדי לשנות את ההתנהגות שלה, אפשר להשתמש ב-variant.artifacts כדי לצרף, לשנות או להחליף קבצים בפועל (Artifacts) שעוברים בין משימות.
רישום מקור מוקדם:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 ‫Sources API: אפשר להגדיר את ספריית הפלט של המשימה המותאמת אישית באמצעות variant.sources.java.addGeneratedSourceDirectory(...).
גישה ל-Classpath / configuration:
  • getCompileConfiguration()
  • getCompileClasspath()
 ‫Instrumentation API: כדי לשנות או לבדוק bytecode (תרחיש השימוש הנפוץ ביותר לגישה ל-classpath), משתמשים ב-variant.instrumentation.transformClassesWith(...) באמצעות AsmClassVisitorFactory.
שינוי מאפיין מיידי:
  • buildConfigField()
  • resValue()
 מופעים של Lazy ‏ `MapProperty`: משתמשים ב-variant.buildConfigFields.put(...) וב-variant.manifestPlaceholders.put(...).
דגלי ביטול הסכמה:
  • android.newDsl
  • android.builtInKotlin
 אין תחליף ישיר. להסיר את הסימונים האלה מ-gradle.properties. ה-DSL המודרני ו-Kotlin המובנה נאכפים באופן מחמיר.
תוספים של Legacy Variant API:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 החלפה ב-androidComponents.onVariants().
סינון וריאנטים (variantFilter חסימה) מחליפים ב-androidComponents.beforeVariants() באמצעות סלקטורים של וריאציות.
רכיבי SDK ו-NDK:
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 אפשר לגשת לרכיבי SDK באמצעות androidComponents.sdkComponents.
סביבות בדיקה:
  • deviceProvider
  • testServer
 העברה של רישום מכשיר בדיקה מותאם אישית למכשירים בניהול Gradle.
ממשקי API מיושנים לרישום:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 נמחקות בלי שמוחלף ישירות.
Transform API מחליפים את הטרנספורמציות ב-Artifacts API וב-AsmClassVisitorFactory.

כדי לגשת לכל הממשקים והמחלקות של שפת התחום הספציפית (DSL) החלופית ושל Variant API ‏(androidComponents {}), צריך תמיד להשתמש בארטיפקט gradle-api כשמפתחים פלאגינים מותאמים אישית של Gradle או לוגיקה של בנייה.

שלבים בהעברה

כדי שהשדרוג ל-AGP 10.0 יהיה חלק וצפוי, כדאי לפעול לפי השיטות המומלצות הבאות למעבר:

  1. מריצים את AGP Upgrade Assistant: לפני שמשדרגים ישירות לגרסה 10.0, מריצים את AGP Upgrade Assistant הרשמי ב-Android Studio‏ (Tools > AGP Upgrade Assistant). הוא מבצע אוטומטית כמה העברות נפוצות של DSL ושל סקריפטים של build, ועוזר לשמור על התנהגויות קיימות של build.
  2. שימוש במיומנויות של Agent Mode ב-Android Studio: אפשר להשתמש במיומנויות שדרוג מבוססות-AI (כמו מיומנויות השדרוג של AGP שזמינות במאגר המיומנויות של Android) כדי להפוך את ההעברה של לוגיקת build מורכבת ושל DSLs בתוך Android Studio לאוטומטית ופשוטה יותר.
  3. קודם צריך לפתור את אזהרות ההוצאה משימוש ב-AGP 9.x: משדרגים את הפרויקט לגרסה האחרונה של AGP 9.x ופותרים את כל אזהרות ההוצאה משימוש הקיימות. אחרי שהפרויקט שלכם יפעל עם גרסה 9.x ללא אזהרות וללא הסתמכות על android.newDsl=false או android.builtInKotlin=false, המעבר לגרסה 10.0 יהיה חלק.
  4. בודקים את הפלאגינים של Gradle של צד שלישי: מוודאים שהפלאגינים של צד שלישי שודרגו לגרסאות שתואמות ל-AGP 10.0. תוספים שמסתמכים עדיין על סוגי תוספים מדור קודם יגרמו לכשלי בנייה כמו ClassCastException: ... cannot be cast to class BaseExtension.
  5. שימוש במתכוני העברה רשמיים: דוגמאות מורכבות להעברה בעולם האמיתי והשוואות זו לצד זו זמינות במאגר הרשמי gradle-recipes ב-GitHub.

הנה השוואה בין המצב לפני לבין המצב אחרי, שמראה איך עוברים משליחת שאילתות של וריאציות מדור קודם באופן מיידי להגדרת וריאציות באופן עצלני באמצעות androidComponents {}:

לפני: Legacy Variant API (הוסר ב-AGP 10.0)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

אחרי: Modern Variant API‏ (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

איך בודקים את ההתנהגות של AGP 10.0 ב-AGP 9.x

לא צריך לחכות לגרסה AGP 10.0 כדי להתחיל לבדוק את התנהגויות הבנייה שלה ולאמת את התאימות. כשמריצים גרסה כלשהי של AGP 9.x אפשר לאכוף באופן מפורש את ההתנהגות של AGP 10.0. לשם כך, צריך לוודא ש-gradle.properties משבית את כל ההסרות מהרשימה ומגדיר את דגלי ההתנהגות המחמירים הבאים:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

האכיפה של android.newDsl=true ושל android.builtInKotlin=true מאפשרת לוודא שהלוגיקה של הגרסה המותאמת אישית והתוספים של צד שלישי תואמים באופן מלא לדרישות ה-API המחמירות של AGP 10.0.

ביטול הסכמה סלקטיבי להעברה של פרויקטים משניים

אם אתם רוצים להפעיל את android.newDsl=true באופן גלובלי בפרויקט כדי לבדוק התנהגויות מודרניות, אבל אתם צריכים יותר זמן כדי להעביר פרויקטים משניים ספציפיים, אתם יכולים לבטל את ההסכמה באופן סלקטיבי למודולים ספציפיים החל מ-AGP 9.4.0-alpha04. מוסיפים את android.newDsl.optOut ל-gradle.properties ומציינים את נתיבי הפרויקט:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

השבתה סלקטיבית של Kotlin מובנה לכל מודול

אם רוצים להפעיל את Kotlin המובנה באופן גלובלי בכל הפרויקט (android.builtInKotlin=true), אבל צריך יותר זמן כדי להעביר פרויקטים משניים ספציפיים מ-kotlin-android (או מודולים ללא קוד Kotlin), צריך להגדיר את המודולים האלה ברמת ה-DSL ולא ברמת הפרויקט. מגדירים את enableKotlin = false בקובץ ה-build של המודול:

android {
    enableKotlin = false
}

תהליך העבודה של שליחת משוב ודיווח על באגים

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

  1. בדיקת פריטים קיימים: קודם כל, בודקים את AGP 10.0 Variant API Global Tracking Bug כדי לראות אם חוסם ההעברה כבר מוכר, ומוסיפים +1 לבעיה.
  2. דיווח על ממשקי API חסרים: אם תרחיש השימוש שלכם ייחודי, אתם יכולים לשלוח בקשה לתכונה חדשה באמצעות תבנית Variant API הספציפית שלנו כדי שנוכל לבדוק ולעזור.

(טיוטה) הגישה לכיתות פרטיות פנימיות של AGP הוסרה

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

אי אפשר להוסיף תלות באופן ידני כדי לקבל גישה למחלקות פנימיות.

‫AGP 9.0 (ינואר 2026)

ממשקי API חדשים למוצרים עם וריאציות הם יציבים, וממשקי ה-API הישנים הוצאו משימוש

‫Variant APIs שהיו בשלב פיתוח בגרסאות 4.1 ו-4.2 יציבים ונמצאים ב-artifact‏ gradle-api. ממשקי ה-API והמחלקות הקודמים ששימשו ב-Variant API הישן הוצאו משימוש, ונדרש אישור מפורש כדי להשתמש בהם.

ממשקי DSL חדשים הם יציבים, ממשקי DSL ישנים הוצאו משימוש

ממשקי ה-DSL שהיו בשלב פיתוח בגרסאות 4.1, 4.2 ו-7.0, יציבים עכשיו ונמצאים בארטיפקט gradle-api. הממשקים והמחלקות הקודמים שבהם נעשה שימוש ב-DSL הוצאו משימוש, ונדרש אישור מפורש כדי להשתמש בהם.

שיעורים פרטיים פנימיים ב-AGP שעדיין אפשר לגשת אליהם

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