Versionshinweise für die Vorabversion des Android-Gradle-Plug-ins

Auf dieser Seite finden Sie Versionshinweise für Vorabversionen des Android Gradle-Plug-ins (AGP).

Android-Gradle-Plug-in 9.0

Das Android-Gradle-Plug-in 9.0 ist ein neuer wichtiger Release von AGP, der API- und Verhaltensänderungen mit sich bringt.

Wenn Sie auf das Android Gradle-Plug-in 9.0.0-alpha05 aktualisieren möchten, verwenden Sie den Android Gradle-Plug-in-Aktualisierungsassistenten in Android Studio Narwhal 4 Feature Drop | 2025.1.4.

Der AGP-Upgrade-Assistent hilft dabei, vorhandenes Verhalten beim Upgrade Ihres Projekts beizubehalten, sofern dies angemessen ist. So können Sie Ihr Projekt auf AGP 9.0 aktualisieren, auch wenn Sie noch nicht bereit sind, alle neuen Standardeinstellungen in AGP 9.0 zu übernehmen.

Kompatibilität

Das maximale Android-API-Level, das vom Android-Gradle-Plug-in 9.0.0-alpha05 unterstützt wird, ist API-Level 36.

Für das Android-Gradle-Plug-in 9.0.0-alpha05 ist Gradle 9.0.0 erforderlich.

Die android-DSL-Klassen implementieren jetzt nur noch die neuen öffentlichen Schnittstellen.

In den letzten Jahren haben wir neue Schnittstellen für unsere DSL und API eingeführt, um besser steuern zu können, welche APIs öffentlich sind. In AGP-Versionen 7.x und 8.x wurden weiterhin die alten DSL-Typen (z. B. BaseExtension) verwendet, in denen auch die neuen öffentlichen Schnittstellen implementiert wurden, um die Kompatibilität während der Entwicklung der Schnittstellen aufrechtzuerhalten.

AGP 9.0 verwendet ausschließlich unsere neuen DSL-Schnittstellen und die Implementierungen wurden in neue, vollständig verborgene Typen geändert. Durch diese Änderungen wird auch der Zugriff auf die alte, eingestellte Variant API entfernt.

Für das Update auf AGP 9.0 müssen Sie möglicherweise Folgendes tun:

• Zu integriertem Kotlin wechseln:Das org.jetbrains.kotlin.android-Plug-in ist nicht mit der neuen DSL kompatibel.

• KMP-Projekte auf das Android-Gradle-Bibliotheks-Plug-in für KMP umstellen:Die Verwendung des org.jetbrains.kotlin.multiplatform-Plug-ins im selben Gradle-Unterprojekt wie die com.android.library- und com.android.application-Plug-ins ist nicht mit der neuen DSL kompatibel.

• Build-Dateien aktualisieren:Die Änderung der Schnittstellen soll das DSL so ähnlich wie möglich halten. Es kann jedoch einige kleine Änderungen geben.

• Benutzerdefinierte Build-Logik aktualisieren, um auf die neue DSL und API zu verweisen:Ersetzen Sie alle Verweise auf die interne DSL durch die öffentlichen DSL-Schnittstellen. In den meisten Fällen handelt es sich um einen direkten Ersatz. Ersetzen Sie alle Verwendungen der applicationVariants- und ähnlicher APIs durch die neue androidComponents-API. Das kann komplexer sein, da die androidComponents API stabiler konzipiert ist, damit Plugins länger kompatibel bleiben. Beispiele finden Sie in unseren Gradle-Rezepten.

• Drittanbieter-Plug-ins aktualisieren:Einige Drittanbieter-Plug-ins sind möglicherweise weiterhin von Schnittstellen oder APIs abhängig, die nicht mehr verfügbar sind. Migrieren Sie zu Versionen dieser Plug-ins, die mit AGP 9.0 kompatibel sind.

Wenn Sie auf AGP 9.0 aktualisieren und die folgende Fehlermeldung angezeigt wird, bedeutet das, dass in Ihrem Projekt weiterhin auf einige der alten Typen verwiesen wird:

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

Wenn Sie durch inkompatible Drittanbieter-Plug-ins blockiert werden, können Sie die alten Implementierungen für die DSL sowie die alte Variant API wiederherstellen. Die neuen Schnittstellen sind dabei auch verfügbar und Sie können Ihre eigene Build-Logik weiterhin auf die neue API umstellen. Fügen Sie diese Zeile in Ihre gradle.properties-Datei ein, um die Speicherung zu verhindern:

android.newDsl=false

Sie können auch mit dem Upgrade auf die neuen APIs beginnen, bevor Sie auf AGP 9.0 upgraden. Die neuen Schnittstellen sind seit vielen AGP-Versionen verfügbar, sodass Sie eine Mischung aus neuen und alten Schnittstellen verwenden können. In der AGP API-Referenzdokumentation wird die API-Oberfläche für jede AGP-Version angezeigt und es wird angegeben, wann jede Klasse, Methode und jedes Feld hinzugefügt wurde.

Während der Alpha-Phase von 9.0 werden wir uns an Plugin-Autoren wenden, um ihnen bei der Anpassung und Veröffentlichung von Plugins zu helfen, die vollständig mit den neuen Modi kompatibel sind. Außerdem werden wir den AGP Upgrade Assistant in Android Studio verbessern, um Sie bei der Migration zu unterstützen.

Wenn Sie feststellen, dass in der neuen DSL- oder Variant-API Funktionen fehlen, melden Sie das Problem bitte so bald wie möglich.

Integriertes Kotlin

Das Android-Gradle-Plug-in 9.0 bietet integrierte Unterstützung für das Kompilieren von Kotlin und ersetzt das separat angewendete Kotlin-Plug-in. Dadurch wird die Integration mit AGP vereinfacht, die Verwendung der eingestellten APIs vermieden und die Leistung in einigen Fällen verbessert.

Das Android-Gradle-Plug-in 9.0 hat eine Laufzeitabhängigkeit vom Kotlin-Gradle-Plug-in 2.2.10. Dies ist die Mindestversion, die für die integrierte Kotlin-Unterstützung erforderlich ist.

Sie können die integrierte Kotlin-Unterstützung deaktivieren, indem Sie android.builtInKotlin=false festlegen.

Wenn Sie die integrierte Kotlin-Version deaktiviert haben und eine ältere Version des Kotlin-Gradle-Plug-ins verwenden müssen, können Sie das Downgrade erzwingen:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

Geändertes Verhalten

Das Android-Gradle-Plug-in 9.0 hat die folgenden neuen Verhaltensweisen:

AGP 9.0 enthält Aktualisierungen der Standardwerte der folgenden Gradle-Attribute. So haben Sie die Möglichkeit, das Verhalten von AGP 8.13 beim Upgrade beizubehalten:

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Entfernte Funktionen

Im Android-Gradle-Plug-in 9.0 wurden die folgenden Funktionen entfernt:

• Unterstützung für eingebettete Wear OS-Apps
  Mit AGP 9.0 wird die Unterstützung für das Einbetten von Wear OS-Apps entfernt, da dies in Play nicht mehr unterstützt wird. Dazu gehört das Entfernen der wearApp-Konfigurationen und der AndroidSourceSet.wearAppConfigurationName-DSL. Informationen zum Veröffentlichen Ihrer App für Wear OS finden Sie unter Über Wear OS verbreiten.
• androidDependencies- und sourceSets-Berichtsaufgabe

Geänderte DSL

Das Android-Gradle-Plug-in 9.0 enthält die folgenden wichtigen DSL-Änderungen:

• Die Parametrisierung von CommonExtension wurde entfernt.

  An sich ist dies nur eine Breaking Change auf Quellcodeebene, um zukünftige Breaking Changes auf Quellcodeebene zu vermeiden. Sie bedeutet aber auch, dass die Blockmethoden von CommonExtension zu ApplicationExtension, LibraryExension, DynamicFeatureExtension und TestExtension verschoben werden müssen.

  Wenn Sie Ihr Projekt auf AGP 9.0 aktualisieren, müssen Sie den Gradle-Plug-in-Code umgestalten, in dem diese Parameter oder Blockmethoden verwendet werden. Das folgende Beispiel zeigt, wie ein Plug-in aktualisiert wird, um den Typparameter zu entfernen und nicht auf die entfernten Blockmethoden zu verweisen:

  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)
          }
      }
  }
  

  Bei Plug-ins, die auf einen Bereich von AGP-Versionen ausgerichtet sind, ist die direkte Verwendung des Getters binärkompatibel mit AGP-Versionen unter 9.0.

Entfernte DSL

Im Android-Gradle-Plug-in 9.0 wurden folgende Elemente entfernt:

• AndroidComponentsExtension.finalizeDSl. Sie wird durch finalizeDsl ersetzt.

• AndroidSourceSet.jni, da sie nicht funktionsfähig war.

• AndroidSourceSet.wearAppConfigurationName, da die Unterstützung für eingebettete Wear OS-Apps entfernt wurde.

• BuildType.isRenderscriptDebuggable, da sie nicht funktionsfähig war.

• Component.transformClassesWith. Sie wird durch Instrumentation.transformClassesWith ersetzt.

• Component.setAsmFramesComputationMode. Sie wird durch Instrumentation.setAsmFramesComputationMode ersetzt.

• DependenciesInfoBuilder.includedInApk. Ersetzt durch includeInApk

• DependenciesInfoBuilder.includedInBundle. Ersetzt durch includeInBundle

• ComponentBuilder.enabled. Es wird durch ComponentBuilder.enable ersetzt.

• DependencyVariantSelection. Sie wird durch DependencySelection ersetzt, die als kotlin.android verfügbar ist.

• GeneratesApk.targetSdkVersion. Sie wird durch targetSdk ersetzt.

• Installation.installOptions(String). Es wird durch das veränderliche Attribut von Installation.installOptions ersetzt.

• Variant.minSdkVersion. Sie wird durch minSdk ersetzt.

• Variant.maxSdkVersion. Sie wird durch maxSdk ersetzt.

• Variant.targetSdkVersion. Sie wird durch targetSdk ersetzt.

• VariantBuilder.targetSdk und targetSdkPreview, da sie in Bibliotheken nicht sinnvoll waren. Verwenden Sie stattdessen GeneratesApkBuilder.targetSdk oder GeneratesApkBuilder.targetSdkPreview.

• VariantOutput.enable. Sie wird durch enabled ersetzt.

• Der experimentelle, aber nie stabilisierte PostProcessing-Block.

• ProductFlavor.setDimension, das durch das Attribut dimension ersetzt wird

• LanguageSplitOptions, das nur für Google Play Instant nützlich war, das eingestellt wurde.

• Variant.unitTest, da sie nicht für das com.android.test-Plug-in galt. unitTest ist für VariantBuilder-Untertypen verfügbar, die HasUnitTest erweitern.

• VariantBuilder.enableUnitTest, da sie nicht für das com.android.test-Plug-in galt. enableUnitTest ist für VariantBuilder-Untertypen verfügbar, die HasUnitTestBuilder erweitern.

• VariantBuilder.unitTestEnabled wird zugunsten von enableUnitTest entfernt, das in den Untertypen von VariantBuilder, die HasUnitTestBuilder erweitern, einheitlicher benannt ist.

Entfernte Gradle-Eigenschaften

Die folgenden Gradle-Properties wurden ursprünglich hinzugefügt, um Funktionen, die standardmäßig aktiviert waren, global zu deaktivieren.

Diese Funktionen sind seit AGP 8.0 oder niedriger standardmäßig deaktiviert. Aktivieren Sie diese Funktionen nur in den Unterprojekten, in denen sie verwendet werden, um einen effizienteren Build zu ermöglichen.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Entfernte APIs

Im Android-Gradle-Plug-in 9.0 wurden folgende Elemente entfernt:

• Die eingestellten und deaktivierten BaseExtension.registerTransform APIs, die nur noch vorhanden waren, um die Kompilierung mit der neuesten AGP-Version zu ermöglichen, während die Ausführung auf AGP 4.2 oder niedriger erfolgte.

• Die verworfenen und deaktivierten FeaturePlugin und FeatureExtension.

Erzwungene Gradle-Properties

In AGP 9.0 wird ein Fehler ausgegeben, wenn Sie die folgenden Gradle-Attribute festlegen.

Der Android Gradle-Plug-in-Upgrade-Assistent aktualisiert Projekte, in denen diese Attribute verwendet werden, nicht auf AGP 9.0.