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

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

פלאגין Android Gradle‏ 9.0

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

כדי לעדכן לגרסה 9.0.0-beta04 של פלאגין Android Gradle, צריך להשתמש בכלי העזרה לשדרוג פלאגין Android Gradle ב-Android Studio Otter 3 Feature Drop | 2025.2.3.

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

תאימות

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

פלאגין Android Gradle‏ ‎9.0.0-beta04 דורש 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 ול-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

כדי לספק תמיכה מובנית ב-Kotlin, פלאגין Android Gradle בגרסה 9.0 כולל עכשיו תלות בזמן ריצה בפלאגין Kotlin Gradle‏ (KGP) בגרסה 2.2.10. כלומר, אתם לא צריכים יותר להצהיר על גרסת KGP, ואם אתם משתמשים בגרסת KGP נמוכה מ-2.2.10,‏ Gradle ישדרג אוטומטית את גרסת KGP ל-2.2.10. באופן דומה, אם אתם משתמשים בגרסת KSP נמוכה מ-2.2.10-2.0.2, ‏ AGP ישדרג אותה ל-2.2.10-2.0.2 כדי להתאים לגרסת KGP.

שדרוג לגרסה גבוהה יותר של KGP

כדי להשתמש בגרסה מתקדמת יותר של KGP או KSP, מוסיפים את השורה הבאה לקובץ build ברמה העליונה:

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

שדרוג לאחור לגרסה קודמת של KGP

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

כדי להשתמש בגרסה ישנה יותר של KGP או KSP, צריך להצהיר על הגרסה הזו בקובץ build ברמה העליונה באמצעות הצהרה על גרסה מדויקת:

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

הערה: הגרסה המינימלית של KGP שאפשר לשנמך אליה היא 2.0.0.

תמיכה ב-IDE עבור test fixtures

‫AGP 9.0 כולל תמיכה מלאה ב-IDE של Android Studio בtest fixtures.

תוסף Fused Library

התוסף Fused Library Plugin (גרסת Preview) מאפשר לכם לפרסם כמה ספריות כספריית Android אחת מסוג AAR. כך יהיה קל יותר למשתמשים להסתמך על הארטיפקטים שפרסמתם.

מידע על תחילת העבודה זמין במאמר פרסום של כמה ספריות Android כאחת באמצעות Fused Library.

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

פלאגין Android Gradle בגרסה 9.0 כולל את ההתנהגויות החדשות הבאות:

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

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

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

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

בפלאגין Android Gradle‏ 9.0 הוסרה הפונקציונליות הבאה:

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

שינוי ב-DSL

בפלאגין Android Gradle בגרסה 9.0 בוצעו שינויים הבאים ב-DSL שעלולים לגרום לכשלים:

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

  השינוי הזה הוא שינוי שובר תאימות ברמת המקור, שמטרתו למנוע שינויים שוברי תאימות ברמת המקור בעתיד. אבל המשמעות שלו היא גם שצריך להעביר את שיטות החסימה מ-CommonExtension אל ApplicationExtension, ‏LibraryExtension, ‏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‏ 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‏ 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 נוספו בהתחלה כדרכים להשבית באופן גלובלי תכונות שהופעלו כברירת מחדל.

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

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

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

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

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

בעיות שתוקנו

פלאגין Android Gradle‏ ‎9.0.0-beta04

פלאגין Android Gradle‏ ‎9.0.0-beta03

פלאגין Android Gradle‏ ‎9.0.0-beta02

פלאגין Android Gradle‏ ‎9.9.0-beta01

פלאגין Android Gradle‏ ‎9.0.0-alpha14

פלאגין Android Gradle‏ ‎9.0.0-alpha13

פלאגין Android Gradle‏ ‎9.0.0-alpha12

פלאגין Android Gradle‏ ‎9.9.0-alpha11

פלאגין Android Gradle‏ ‎9.0.0-alpha10

פלאגין Android Gradle‏ ‎9.0.0-alpha09

פלאגין Android Gradle‏ ‎9.0.0-alpha08

פלאגין Android Gradle‏ ‎9.0.0-alpha07

פלאגין Android Gradle‏ ‎9.0.0-alpha06

פלאגין Android Gradle‏ ‎9.0.0-alpha05

פלאגין Android Gradle‏ ‎9.0.0-alpha04

פלאגין Android Gradle‏ ‎9.0.0-alpha03

פלאגין Android Gradle‏ ‎9.0.0-alpha02

פלאגין Android Gradle‏ ‎9.0.0-alpha01