API-Updates für das Android Gradle-Plug-in

Auf dieser Seite werden die Einstellung und Entfernungen der API für das Android Gradle-Plug-in (AGP) sowie Informationen dazu aufgeführt, wie Sie Ihren Code entsprechend aktualisieren können.

Informationen zur Einstellung und Entfernung von APIs

In der folgenden Tabelle wird zusammengefasst, wann AGP-APIs eingestellt und entfernt werden, unter Angabe der AGP-Version.

8,8 AGP

Im Folgenden finden Sie wichtige API-Updates zu AGP 8.8.

Ressourcenkonfigurationen wurden verworfen

Ressourcenkonfigurationen werden ab AGP 8.8 nicht mehr unterstützt. Das liegt daran, dass AGP keine unterschiedlichen Ressourcendichten mehr unterstützt und Apps in der Google Play Console jetzt als App-Bundles veröffentlicht werden müssen. Für die Sprachkonfiguration können Sie mit der localeFilters-DSL die von Ihrer App unterstützten Sprachen angeben, um Sprachkonfigurationen den entsprechenden Ressourcen zuzuordnen.

AGP 8.0

Im Folgenden finden Sie wichtige API-Updates für AGP 8.0.

Transform API entfernt

Ab AGP 8.0 wird die Transform API entfernt. Das bedeutet, dass alle Klassen im Paket com.android.build.api.transform entfernt werden.

Die Transform API wird entfernt, um die Build-Leistung zu verbessern. Bei Projekten, in denen die Transform API verwendet wird, zwingt AGP dazu, einen weniger optimierten Ablauf für den Build zu verwenden, was zu großen Rückgängen bei den Buildzeiten führen kann. Außerdem ist es schwierig, die Transform API zu verwenden und mit anderen Gradle-Features zu kombinieren. Mit den Ersatz-APIs soll AGP einfacher erweitert werden, ohne dass die Leistung oder die Fehlerfreiheit beeinträchtigt werden.

Ersatz-APIs

Es gibt keinen einzelnen Ersatz für die Transform API. Stattdessen gibt es für jeden Anwendungsfall neue, spezifische APIs. Alle Ersatz-APIs befinden sich im Block androidComponents {}. Diese APIs sind ab AGP 7.2 verfügbar.

Unterstützung für die Transformation von Bytecode

Verwenden Sie zum Transformieren von Bytecode die Instrumentation API. Bei Bibliotheken können Sie eine Instrumentierung nur für lokale Projektklassen registrieren. Bei Apps und Tests können Sie eine Instrumentierung nur für lokale Klassen oder für alle Klassen registrieren, einschließlich lokaler und Remote-Abhängigkeiten. Wenn Sie diese API verwenden, wird die Instrumentierung unabhängig für jede Klasse ausgeführt, mit eingeschränktem Zugriff auf andere Klassen im Klassenpfad. Weitere Informationen finden Sie unter createClassVisitor(). Diese Einschränkung verbessert die Leistung sowohl von vollständigen als auch von inkrementellen Builds und sorgt für eine einfache API-Oberfläche. Jede Bibliothek wird parallel instrumentiert, sobald sie bereit ist, und nicht erst, wenn die gesamte Kompilierung abgeschlossen ist. Außerdem bedeutet eine Änderung an einer einzelnen Klasse, dass nur die betroffenen Klassen in einem inkrementellen Build neu instrumentiert werden müssen. Ein Beispiel für die Verwendung der Instrumentation API finden Sie im AGP-Rezept Klassen mit ASM transformieren.

Unterstützung für das Hinzufügen generierter Klassen zu Ihrer App

Wenn Sie der App zusätzliche generierte Klassen hinzufügen möchten, verwenden Sie die Artifacts API mit MultipleArtifact.ALL_CLASSES_DIRS. Verwenden Sie insbesondere:

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

mit MultipleArtifact.ALL_CLASSES_DIRS, um zusätzliche generierte Verzeichnisse an die Projektklassen anzuhängen. Die Artifacts API wählt automatisch einen eindeutigen Speicherort für die Ausgabe Ihrer benutzerdefinierten Aufgabe aus. Ein Beispiel für die Verwendung dieser API finden Sie im Rezept "addToAllClasses".

Unterstützung für Transformationen auf Grundlage einer Analyse des gesamten Programms

Um Transformationen auf der Grundlage einer Analyse des gesamten Programms zu implementieren, können alle Klassen in einer einzigen Aufgabe zusammen transformiert werden. Dieser Ansatz sollte mit Vorsicht verwendet werden, da er deutlich höhere Build-Leistungskosten verursacht als die Verwendung der Instrumentation API. Wenn Ihr Plug-in diese API verwendet, wird empfohlen, die Transformation pro Buildtyp zu aktivieren, damit der App-Entwickler sie für Entwicklungsbuilds deaktivieren kann.

Zum Registrieren einer Aufgabe, die alle Klassen zusammen transformiert, wird im Android-Gradle-Plug-in 7.4 die Artifacts.forScope API eingeführt. Wenn Sie alle Klassen im aktuellen Projekt transformieren möchten, verwenden Sie Artifacts.forScope.PROJECT. Wenn Sie alle Klassen im aktuellen Projekt, importierte Projekte und alle externen Abhängigkeiten transformieren möchten, verwenden Sie Artifacts.forScope.ALL. Der folgende Code zeigt, wie Sie mit Artifacts.forScope.ALL eine Aufgabe registrieren, die alle Klassen zusammen transformiert:

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

Im Rezept modifyProjectClasses finden Sie ein Beispiel für die Verwendung dieser API. Im Rezept customizeAgpDsl wird gezeigt, wie Sie benutzerdefinierte Erweiterungen für die Android-Buildtypen registrieren.

Wenn Ihr Anwendungsfall nicht durch eine der AndroidComponents-APIs abgedeckt ist, melden Sie bitte einen Fehler.

Mehrere häufig verwendete Plug-ins wurden bereits auf die Verwendung dieser neuen APIs umgestellt, darunter das Firebase-Plug-in für die Leistungsüberwachung (1.4.1 ist mit AGP 8.0 kompatibel) und das Hilt-Gradle-Plug-in (2.40.1 ist mit AGP 8.0 kompatibel). Der AGP-Upgrade-Assistent hilft Projektentwicklern auch dabei, häufig verwendete Plug-ins bei Bedarf zu aktualisieren.

Wenn Sie die Transform API über ein Drittanbieter-Plug-in verwenden, informieren Sie den Autor bitte darüber, dass sein Plug-in aktualisiert werden muss, damit es mit den neuen APIs für AGP 8.0 funktioniert.

AGP 7.2

Im Folgenden finden Sie wichtige API-Änderungen für AGP 7.2.

RenderScript wird eingestellt

Ab AGP 7.2 werden die RenderScript APIs eingestellt. Sie funktionieren weiterhin, lösen aber Warnungen aus und werden in zukünftigen Versionen von AGP vollständig entfernt. Eine Anleitung zur Umstellung von RenderScript finden Sie unter Von RenderScript migrieren.

Component.transformClassesWith und Component.setAsmFramesComputationMode werden nicht mehr unterstützt

Ab AGP 7.2 werden die APIs zur Bytecode-Instrumentierung von Klassen Component.transformClassesWith und Component.setAsmFramesComputationMode eingestellt. Sie wurden in den neuen Block Component.instrumentation verschoben, der alle APIs zur Konfiguration des Instrumentierungsprozesses enthält. Wenn Sie diese Instrumentierungsfunktionen weiterhin nutzen möchten, verwenden Sie stattdessen die entsprechenden APIs im neuen Block, wie im folgenden Code-Snippet gezeigt:

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