הערות מוצר של גרסת Preview של הפלאגין Android Gradle

בדף הזה מפורטות הערות על גרסאות טרום-השקה של Android Gradle Plugin‏ (AGP).

Android Gradle Plugin 9.0

‫Android Gradle plugin 9.0 היא גרסה מרכזית חדשה של AGP, והיא כוללת שינויים בממשקי ה-API ובהתנהגות.

כדי לעדכן ל-Android Gradle Plugin 9.0.0-beta01, צריך להשתמש בAndroid Gradle Plugin Upgrade Assistant ב-Android Studio Otter 3 Feature Drop | 2025.2.3.

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

תאימות

רמת ה-API המקסימלית של Android שנתמכת ב-Android Gradle Plugin 9.0.0-beta01 היא 36.

‫Android Gradle Plugin 9.0.0-beta01 דורש Gradle 9.0.0.

המחלקה android DSL מטמיעה עכשיו רק את הממשקים הציבוריים החדשים

במהלך השנים האחרונות השקנו ממשקים חדשים ל-DSL ול-API שלנו כדי לשפר את השליטה ב-API שזמינים לציבור. בגרסאות AGP‏ 7.x ו-8.x עדיין נעשה שימוש בסוגי ה-DSL הישנים (לדוגמה, BaseExtension), שגם יישמו את הממשקים הציבוריים החדשים, כדי לשמור על תאימות בזמן שהעבודה על הממשקים התקדמה.

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

כדי לעדכן ל-AGP 9.0, יכול להיות שתצטרכו לבצע את הפעולות הבאות:

• מוודאים שהפרויקט תואם ל-built-in Kotlin: הפלאגין org.jetbrains.kotlin.android לא תואם ל-DSL החדש.

• מעבירים פרויקטים של KMP אל Android Gradle Library Plugin for KMP: השימוש בפלאגין org.jetbrains.kotlin.multiplatform באותו פרויקט משנה של Gradle כמו הפלאגינים com.android.library ו-com.android.application לא תואם ל-DSL החדש.

• מעדכנים את קובצי ה-build: השינוי בממשקי המשתמש נועד לשמור על ה-DSL כמה שיותר דומה, אבל יכול להיות שיהיו שינויים קטנים.

• מעדכנים את הלוגיקה של הגרסה המותאמת אישית כדי להפנות ל-DSL ול-API החדשים: מחליפים את כל ההפניות ל-DSL הפנימי בממשקי ה-DSL הציבוריים. ברוב המקרים, מדובר בהחלפה של אחד באחד. צריך להחליף כל שימוש ב-applicationVariants ובממשקי API דומים ב-androidComponents API החדש. יכול להיות שהתהליך יהיה מורכב יותר, כי androidComponents API נועד להיות יציב יותר כדי שהתוספים יהיו תואמים למשך זמן ארוך יותר. כדאי לעיין בדוגמאות ל-Gradle.

• עדכון פלאגינים של צד שלישי: יכול להיות שחלק מהפלאגינים של צד שלישי עדיין מסתמכים על ממשקי משתמש או ממשקי API שכבר לא חשופים. מעבר לגרסאות של התוספים האלה שתואמות ל-AGP 9.0.

המעבר לממשקי ה-DSL החדשים מונע שימוש בתוספים ובסקריפטים של Gradle build ב-API שונים שהוצאו משימוש, כולל:

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

אם אתם מעדכנים ל-AGP 9.0 ורואים את הודעת השגיאה הבאה, המשמעות היא שהפרויקט שלכם עדיין מפנה לחלק מהסוגים הישנים:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

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

android.newDsl=false

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

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

אם גיליתם שהיכולות או התכונות של ה-DSL החדש או של Variant API חסרות, חשוב לשלוח דיווח על בעיה בהקדם האפשרי.

‫Kotlin מובנה

בפלאגין Android Gradle 9.0 נוספה תמיכה מובנית ב-Kotlin, והיא מופעלת כברירת מחדל. כלומר, כבר לא צריך להחיל את הפלאגין org.jetbrains.kotlin.android (או kotlin-android) בקובצי ה-build כדי לקמפל קובצי מקור של Kotlin. השינוי הזה מפשט את השילוב של Kotlin עם AGP, מונע את השימוש בממשקי API שיצאו משימוש ומשפר את הביצועים במקרים מסוימים.

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

אפשר להשבית באופן סלקטיבי את התמיכה המובנית ב-Kotlin בפרויקטים משניים של Gradle שאין להם מקורות Kotlin.

תלות בזמן ריצה בפלאגין Kotlin Gradle גרסה 2.2.10

ל-Android Gradle plugin 9.0 יש תלות בזמן ריצה ב-Kotlin Gradle plugin ‏ (KGP) 2.2.10, שהיא הגרסה המינימלית שנדרשת לתמיכה מובנית ב-Kotlin.

המשמעות היא שאם תפעילו את Kotlin המובנה ותשתמשו בגרסת KGP נמוכה מ-2.2.10, מערכת Gradle תשדרג אוטומטית את גרסת ה-KGP ל-2.2.10.

באופן דומה, אם אתם משתמשים בגרסה של KSP שקודמת לגרסה 2.2.10-2.0.2, ‏ AGP ישדרג את גרסת ה-KSP לגרסה 2.2.10-2.0.2 כדי להתאים לגרסת ה-KGP.

לכן, אם אתם מבטלים את ההסכמה לשימוש ב-Kotlin המובנה ורוצים להשתמש בגרסה ישנה יותר של KGP או KSP, אתם צריכים להוסיף את השורות הבאות לקובץ הבנייה ברמה העליונה:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

תמיכה ב-IDE עבור נתוני בדיקה

‫AGP 9.0 כולל תמיכה מלאה בסביבת הפיתוח המשולבת (IDE) של Android Studio בtest fixtures. כדי לקבל את התמיכה הזו, צריך להשתמש ב-AGP 9.0.0-alpha07 ומעלה.

שינויים בהתנהגות

ל-Android Gradle plugin 9.0 יש התנהגויות חדשות:

‫AGP 9.0 כולל עדכונים בערכי ברירת המחדל של מאפייני Gradle הבאים. כך תוכלו לבחור אם לשמור על ההתנהגות של AGP 8.13 כשמשדרגים:

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

תכונות שהוסרו

הפונקציונליות הבאה הוסרה מ-Android Gradle Plugin 9.0:

• התמיכה בהטמעת אפליקציות ל-Wear OS
  ב-AGP 9.0 הוסרה התמיכה בהטמעת אפליקציות ל-Wear OS, שלא נתמכת יותר ב-Play. זה כולל הסרה של הגדרות wearApp ושל AndroidSourceSet.wearAppConfigurationName DSL. במאמר הפצה ב-Wear OS מוסבר איך לפרסם את האפליקציה ב-Wear OS.
• androidDependencies וsourceSets דיווח על משימה
• תמיכה בחבילות APK מפוצלות לדחיסות
  ב-AGP 9.0 הוסרה התמיכה ביצירת חבילות APK מפוצלות על סמך צפיפות פיקסלים. הפונקציונליות וממשקי ה-API שקשורים אליה הוסרו. כדי לפצל קובצי APK על סמך צפיפות המסך באמצעות AGP 9.0 ואילך, צריך להשתמש בחבילות App Bundle.

שינוי ב-DSL

ב-Android Gradle plugin 9.0 בוצעו שינויים משמעותיים ב-DSL:

• הוסרה הפרמטריזציה של CommonExtension.

  השינוי הזה הוא שינוי שובר תאימות ברמת המקור, שמטרתו למנוע שינויים שוברי תאימות ברמת המקור בעתיד. אבל המשמעות שלו היא גם שצריך להעביר את שיטות החסימה מ-CommonExtension אל ApplicationExtension, ‏LibraryExension, ‏DynamicFeatureExtension ו-TestExtension.

  כשמשדרגים את הפרויקט ל-AGP 9.0, צריך לבצע רפקטורינג של קוד הפלאגין Gradle שמשתמש בפרמטרים האלה או בשיטות הבלוק. לדוגמה, התוסף הבא עודכן כדי להסיר את פרמטר הסוג ולא להסתמך על שיטות הבלוק שהוסרו:

  ‫AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  בתוספים שמטרגטים טווח של גרסאות AGP, שימוש בשיטת ה-getter ישירות תואם בינארית לגרסאות AGP נמוכות מ-9.0.

הסרת DSL

ב-Android Gradle Plugin 9.0 הוסרו:

• AndroidSourceSet.jni, כי הוא לא היה תקין.

• ‫AndroidSourceSet.wearAppConfigurationName, כי הוא קשור להסרת התמיכה באפליקציית Wear OS המוטמעת.

• BuildType.isRenderscriptDebuggable, כי הוא לא היה תקין.

• ‫DependencyVariantSelection. הוא הוחלף ב-DependencySelection, שמוצג כ-kotlin.android.localDependencySelection

• ‫Installation.installOptions(String). הוא מוחלף במאפיין הניתן לשינוי של Installation.installOptions.

• הבלוק PostProcessing, שהוא ניסיוני אבל אף פעם לא יציב.

• ‫ProductFlavor.setDimension, שמוחלף במאפיין dimension

• ‫LanguageSplitOptions, שהיה שימושי רק ל-Google Play ללא התקנה, שהוצא משימוש.

• DensitySplit, כי התכונה הזו כבר לא נתמכת. הפתרון הוא שימוש בקובצי App Bundle.

ממשקי API שהוסרו

ב-Android Gradle Plugin 9.0 הוסרו:

• ‫AndroidComponentsExtension.finalizeDSl. הוא הוחלף ב-finalizeDsl

• ‫Component.transformClassesWith. הוא הוחלף ב-Instrumentation.transformClassesWith

• ‫Component.setAsmFramesComputationMode. הוא הוחלף ב-Instrumentation.setAsmFramesComputationMode

• ‫ComponentBuilder.enabled. הוא הוחלף ב-ComponentBuilder.enable.

• ‫DependenciesInfoBuilder.includedInApk. הוא הוחלף ב-includeInApk

• ‫DependenciesInfoBuilder.includedInBundle. הוא הוחלף ב-includeInBundle

• ‫GeneratesApk.targetSdkVersion. הוא הוחלף ב-targetSdk

• ‫Variant.minSdkVersion. הוא הוחלף ב-minSdk

• ‫Variant.maxSdkVersion. הוא הוחלף ב-maxSdk

• ‫Variant.targetSdkVersion. הוא הוחלף ב-targetSdk

• Variant.unitTest, כי הוא לא רלוונטי לפלאגין com.android.test. המאפיין unitTest זמין בסוגי המשנה VariantBuilder של HasUnitTest.

• ‫VariantBuilder.targetSdk ו-targetSdkPreview, כי הן לא היו רלוונטיות בספריות. במקום זאת, אתם צריכים להשתמש ב-GeneratesApkBuilder.targetSdk או ב-GeneratesApkBuilder.targetSdkPreview.

• VariantBuilder.enableUnitTest, כי הוא לא רלוונטי לפלאגין com.android.test. המאפיין enableUnitTest זמין בסוגי המשנה VariantBuilder של HasUnitTestBuilder.

• הסוג VariantBuilder.unitTestEnabled הוסר לטובת הסוג enableUnitTest, ששמו עקבי יותר, בסוגי המשנה VariantBuilder שמרחיבים את HasUnitTestBuilder.

• ‫VariantOutput.enable. הוא הוחלף ב-enabled

• התכונות FeaturePlugin ו-FeatureExtension שהוצאו משימוש והושבתו.

• ממשקי ה-API שהוצאו משימוש והושבתו, BaseExtension.registerTransformשנותרו רק כדי לאפשר קומפילציה מול הגרסה העדכנית ביותר של AGP תוך טירגוט הפעלה ב-AGP 4.2 או בגרסאות קודמות.

הוסרו מאפייני Gradle

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

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

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

מאפייני Gradle שנאכפים

‫AGP 9.0 מציג שגיאה אם מגדירים את מאפייני Gradle הבאים.

הכלי Android Gradle Plugin Upgrade Assistant לא ישדרג פרויקטים ל-AGP 9.0 שמשתמשים במאפיינים האלה.

בעיות שתוקנו

Android Gradle plugin 9.0.0-alpha10

Android Gradle plugin 9.0.0-alpha09

Android Gradle plugin 9.0.0-alpha08

Android Gradle plugin 9.0.0-alpha07

Android Gradle plugin 9.0.0-alpha06

Android Gradle plugin 9.0.0-alpha05

Android Gradle plugin 9.0.0-alpha04

Android Gradle plugin 9.0.0-alpha03

‫Android Gradle Plugin 9.0.0-alpha02

Android Gradle plugin 9.0.0-alpha01