Versionshinweise für Android-Gradle-Plug-in 8.3

Das Build-System von Android Studio basiert auf Gradle und das Android-Gradle-Plug-in bietet verschiedene Funktionen, die speziell zum Erstellen von Android-Apps entwickelt wurden. Obwohl das Android-Gradle-Plug-in (AGP) in der Regel mit Android Studio aktualisiert wird, können das Plug-in (und der Rest des Gradle-Systems) unabhängig von Android Studio ausgeführt und separat aktualisiert werden.

Auf dieser Seite wird erläutert, wie Sie Ihre Gradle-Tools auf dem neuesten Stand halten und die neuesten Updates veröffentlichen. Versionshinweise für frühere Versionen des Gradle-Plug-ins für Android finden Sie unter Frühere Versionshinweise.

Informationen zu den Fehlerkorrekturen in dieser Version des Android-Gradle-Plug-ins finden Sie unter Geschlossene Probleme.

Eine allgemeine Zusammenfassung der bevorstehenden funktionsgefährdenden Änderungen im Android-Gradle-Plug-in finden Sie in der Roadmap für das Android-Gradle-Plug-in.

Weitere Informationen zum Konfigurieren Ihrer Android-Builds mit Gradle finden Sie auf den folgenden Seiten:

• Build konfigurieren
• DSL-Referenz für das Android-Gradle-Plug-in
• Gradle DSL-Referenz
• Nutzerhandbuch zur Gradle-Leistung

Weitere Informationen zum Gradle-Build-System finden Sie im Gradle-Nutzerhandbuch.

Android-Gradle-Plug-in aktualisieren

Wenn Sie Android Studio aktualisieren, werden Sie möglicherweise aufgefordert, das Android-Gradle-Plug-in automatisch auf die neueste verfügbare Version zu aktualisieren. Sie können das Update akzeptieren oder manuell eine Version basierend auf den Build-Anforderungen Ihres Projekts angeben.

Sie können die Plug-in-Version in Android Studio über das Menü Datei > Projektstruktur > Projekt oder in der übergeordneten Datei build.gradle.kts angeben. Die Plug-in-Version gilt für alle Module, die in diesem Android Studio-Projekt erstellt sind. Im folgenden Beispiel wird das Plug-in von der Datei build.gradle.kts auf Version 8.3.0 festgelegt:

plugins {
    id("com.android.application") version "8.3.0" apply false
    id("com.android.library") version "8.3.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.23" apply false
}

plugins {
    id 'com.android.application' version '8.3.0' apply false
    id 'com.android.library' version '8.3.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.23' apply false
}

Achtung: Verwenden Sie in Versionsnummern keine dynamischen Abhängigkeiten wie 'com.android.tools.build:gradle:8.3.+'. Die Verwendung dieser Funktion kann zu unerwarteten Versionsupdates und Problemen beim Beheben von Versionsunterschieden führen.

Wenn die angegebene Plug-in-Version noch nicht heruntergeladen wurde, wird sie von Gradle heruntergeladen, wenn Sie das nächste Mal Ihr Projekt erstellen oder in der Menüleiste von Android Studio auf File > Sync Project with Gradle Files klicken.

Gradle aktualisieren

Wenn Sie Android Studio aktualisieren, werden Sie möglicherweise aufgefordert, auch Gradle auf die neueste verfügbare Version zu aktualisieren. Sie können das Update akzeptieren oder manuell eine Version basierend auf den Build-Anforderungen Ihres Projekts angeben.

In der folgenden Tabelle ist aufgeführt, welche Gradle-Version für die einzelnen Versionen des Android-Gradle-Plug-ins erforderlich ist. Für eine optimale Leistung sollten Sie die jeweils neueste Version von Gradle und des Plug-ins verwenden.

Du kannst die Gradle-Version in Android Studio im Menü Datei > Projektstruktur > Projekt angeben oder deine Gradle-Version über die Befehlszeile aktualisieren. In diesem Fall ist es am besten, das Befehlszeilentool Gradle Wrapper zu verwenden, mit dem die gradlew-Skripts aktualisiert werden. Im folgenden Beispiel wird die Gradle-Version mit dem Gradle Wrapper auf 8.3 gesetzt. Hinweis: Du musst diesen Befehl zweimal ausführen, um sowohl Gradle als auch den Gradle-Wrapper selbst zu aktualisieren. Weitere Informationen findest du unter Gradle-Wrapper aktualisieren.

gradle wrapper --gradle-version 8.3

Dies kann jedoch in einigen Fällen fehlschlagen, z. B. wenn Sie AGP gerade aktualisiert haben und es nicht mehr mit der aktuellen Gradle-Version kompatibel ist. In diesem Fall müssen Sie die Gradle-Distributionsreferenz in der Datei gradle/wrapper/gradle-wrapper.properties bearbeiten. Im folgenden Beispiel wird die Gradle-Version in der Datei gradle-wrapper.properties auf 8.3 festgelegt.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.3-bin.zip
...

Android-Gradle-Plug-in und Kompatibilität mit Android Studio

Das Build-System von Android Studio basiert auf Gradle. Das Android Gradle-Plug-in (AGP) bietet verschiedene Funktionen, die speziell für das Erstellen von Android-Apps entwickelt wurden. In der folgenden Tabelle ist aufgeführt, welche AGP-Version für die jeweilige Version von Android Studio erforderlich ist.

Informationen zu den Neuerungen im Android-Gradle-Plug-in finden Sie in den Versionshinweisen zum Android-Gradle-Plug-in.

Mindestversionen von Tools für Android API-Level

Es gibt Mindestversionen von Android Studio und AGP, die eine bestimmte API-Ebene unterstützen. Die Verwendung niedrigerer Versionen von Android Studio oder AGP als für targetSdk oder compileSdk Ihres Projekts erforderlich, kann zu unerwarteten Problemen führen. Wir empfehlen, für Projekte, die auf Vorschauversionen des Android-Betriebssystems ausgerichtet sind, die neueste Vorschauversion von Android Studio und AGP zu verwenden. Sie können Vorschauversionen von Android Studio zusammen mit einer stabilen Version installieren.

Für Android Studio und AGP gelten folgende Mindestversionen:

Versionsänderungen (November 2020)

Wir aktualisieren die Versionsnummer für das Android-Gradle-Plug-in (AGP), damit sie besser mit dem zugrunde liegenden Gradle-Build-Tool übereinstimmt.

Dies sind die wichtigsten Änderungen:

• AGP verwendet jetzt eine semantische Versionsverwaltung und es werden funktionsgefährdende Änderungen für Hauptversionen vorgenommen.

• Pro Jahr wird eine Hauptversion von AGP veröffentlicht, die auf die Gradle-Hauptversion abgestimmt ist.

• Der Release nach AGP 4.2 wird Version 7.0 und erfordert ein Upgrade auf Gradle Version 7.x. Für jeden AGP-Hauptrelease ist ein Upgrade der Hauptversion im zugrunde liegenden Gradle-Tool erforderlich.

• APIs werden etwa ein Jahr im Voraus eingestellt. Ersatzfunktionen sind gleichzeitig verfügbar. Verworfene APIs werden etwa ein Jahr später bei der nachfolgenden großen Aktualisierung entfernt.

Kompatibilität

Das maximale API-Level, das das Android-Gradle-Plug-in 8.3 unterstützt, ist API-Level 34. Weitere Informationen zur Kompatibilität:

Die folgenden neuen Funktionen werden im Android-Gradle-Plug-in 8.3 eingeführt.

Patch releases

Im Folgenden finden Sie eine Liste der Patch-Releases in Android Studio Iguana und dem Android Gradle-Plug-in 8.3.

Android Studio Iguana | 2023.2.1 Patch 2 und AGP 8.3.2 (April 2024)

Dieses kleinere Update umfasst diese Fehlerkorrekturen.

Android Studio Iguana | Patch 1 und AGP 8.3.1 (März 2024)

Dieses kleinere Update umfasst diese Fehlerkorrekturen.

Unterstützung für Gradle-Versionskataloge

Android Studio unterstützt TOML-basierte Gradle-Versionskataloge. Mit dieser Funktion können Sie Abhängigkeiten an einem zentralen Ort verwalten und Abhängigkeiten zwischen Modulen oder Projekten teilen. In Android Studio ist es jetzt einfacher, Versionskataloge durch Editorvorschläge und die Einbindung in das Dialogfeld Projektstruktur zu konfigurieren. Hier erfahren Sie, wie Sie Gradle-Versionskataloge einrichten und konfigurieren und Builds in Versionskataloge migrieren.

Codevervollständigung und Navigation

Android Studio bietet Codevervollständigung, wenn Sie einen Versionskatalog im TOML-Dateiformat bearbeiten oder einer Build-Datei eine Abhängigkeit von einem Versionskatalog hinzufügen. Drücken Sie Strg + Leertaste (Befehlstaste + Leertaste unter macOS), um die Codevervollständigung zu verwenden. Außerdem können Sie mit Strg + B (Befehlstaste + B unter macOS) schnell von einer Abhängigkeitsreferenz in der Datei build.gradle Ihrer App zu der Deklaration im Versionskatalog wechseln.

Einbindung in das Dialogfeld „Projektstruktur“

Wenn Ihr Projekt einen im TOML-Dateiformat definierten Versionskatalog verwendet, können Sie die dort definierten Variablen in Android Studio in der Ansicht Variablen (Datei > Projektstruktur > Variablen) im Dialogfeld Projektstruktur bearbeiten. Für jeden Versionskatalog gibt es ein Drop-down-Menü, in dem die Variablen aus diesem Katalog aufgeführt sind. Wenn Sie eine Variable bearbeiten möchten, klicken Sie auf ihren Wert und überschreiben Sie ihn. Wenn Sie diese Änderungen speichern, wird die TOML-Datei entsprechend aktualisiert.

Sie können Abhängigkeiten auch im Dialogfeld Projektstruktur in der Ansicht Abhängigkeiten aktualisieren (Datei > Projektstruktur > Abhängigkeiten). Um Versionen über das Dialogfeld Projektstruktur zu aktualisieren, gehen Sie zu dem Modul und der Abhängigkeit, die Sie bearbeiten möchten, und aktualisieren Sie dann das Feld Angeforderte Version. Wenn Sie diese Änderungen speichern, wird die TOML-Datei entsprechend aktualisiert. Wenn die Abhängigkeitsversion mit einer Variablen definiert wurde, wird beim Aktualisieren der Version die Variable auf diese Weise durch einen hartcodierten Wert ersetzt. Beachten Sie außerdem, dass das Entfernen einer Abhängigkeit aus einer Build-Datei die Abhängigkeit aus dem Versionskatalog nicht entfernt, unabhängig davon, ob Sie das Dialogfeld Projektstruktur verwenden oder nicht.

Bekannte Probleme und Einschränkungen

Im Folgenden sind bekannte Probleme oder Einschränkungen bei der Unterstützung von Gradle-Versionskatalogen in Android Studio aufgeführt.

• Fehler beim Hervorheben von Plug-in-Alias-Deklarationen in Kotlin-Scriptdateien: Wenn Sie eine Plug-in-Deklaration im Formular alias(libs.plugins.example) hinzufügen, wird der libs-Teil des Editors rot unterstrichen. Dies ist ein bekanntes Problem in den Gradle-Versionen 8.0 und niedriger und wird in einer zukünftigen Gradle-Version behoben.

• Android Studio-Unterstützung für Versionskataloge im TOML-Format ist derzeit nur für Versionskataloge im TOML-Dateiformat verfügbar: Die Codevervollständigung von Android Studio, die Navigation und das Dialogfeld „Projektstruktur“ sind derzeit nur für Versionskataloge verfügbar, die im TOML-Dateiformat definiert sind. Sie können aber trotzdem einen Versionskatalog direkt in die Datei settings.gradle einfügen und die zugehörigen Abhängigkeiten in Ihrem Projekt verwenden.

• Die Navigation für KTS-Build-Dateien wird nicht unterstützt: Das Aufrufen einer Abhängigkeitsdefinition in einem Versionskatalog mithilfe von Strg + Klick (Befehlstaste + Klick unter macOS) wird für Build-Dateien, die mit einem Kotlin-Skript geschrieben wurden, noch nicht unterstützt.

• Firebase Assistant fügt Abhängigkeiten direkt in Build-Skripts hinzu: Firebase Assistant fügt Abhängigkeiten direkt zu Ihren Build-Skripts hinzu, nicht über Versionskataloge.

• Die Funktion „Nutzungen suchen“ wird nicht unterstützt: Das Ermitteln von Nutzungen einer Versionskatalogvariable in anderen Build-Dateien wird noch nicht unterstützt, unabhängig davon, ob sich die Build-Datei in KTS oder Groovy befindet. Das heißt, das Drücken von Strg + Klick (Befehlstaste + Klick auf macOS) auf eine Variablendefinition in einem Versionskatalog führt nicht zu den Build-Dateien, in denen die Variable verwendet wird.

• Im Dialogfeld „Projektstruktur“ in Android Studio werden mehrere Katalogdateien angezeigt, wenn sie sich im Stammordner gradle befinden. Es werden jedoch keine Kataloge für einen zusammengesetzten Build angezeigt. Wenn Sie beispielsweise zwei Katalogdateien haben – eine für Ihre Anwendung und eine für einen zusammengesetzten Build – wird im Dialogfeld „Projektstruktur“ nur die Anwendungskatalogdatei angezeigt. Sie können einen zusammengesetzten Build verwenden, aber Sie müssen die zugehörige TOML-Datei direkt bearbeiten.

Zusätzliche SDK-Statistiken: Richtlinienverstöße

In Android Studio werden Lint-Warnungen in build.gradle.kts- und build.gradle-Dateien sowie im Dialogfeld „Projektstruktur“ für öffentliche SDKs angezeigt, die im Google Play SDK Index gegen Google Play-Richtlinien verstoßen. Du solltest alle Abhängigkeiten aktualisieren, die gegen die Google Play-Richtlinien verstoßen, da diese Verstöße dazu führen könnten, dass du in Zukunft keine Apps mehr in der Google Play Console veröffentlichen kannst. Die Warnungen zu Richtlinienverstößen ergänzen die Warnungen zu veralteten Versionen, die in Android Studio angezeigt werden.

Unterstützung von Android Studio-CompilierungSdk-Versionen

In Android Studio wird eine Warnung angezeigt, wenn dein Projekt eine compileSdk verwendet, die von der aktuellen Version von Android Studio nicht unterstützt wird. Falls verfügbar, wird auch empfohlen, zu einer Version von Android Studio zu wechseln, die das von deinem Projekt verwendete compileSdk unterstützt. Beachten Sie, dass für ein Upgrade von Android Studio möglicherweise auch ein Upgrade von AGP erforderlich ist. Außerdem zeigt AGP im Toolfenster Build eine Warnung an, wenn die von Ihrem Projekt verwendete compileSdk von der aktuellen AGP-Version nicht unterstützt wird.

Änderungen am Lint-Verhalten

Ab dem Android-Gradle-Plug-in 8.3.0-alpha02 werden beim Ausführen von Lint auf einem Modul separate Lint-Analyseaufgaben für die Haupt- und Testkomponenten des Moduls ausgeführt. Der Grund für diese Änderung ist eine Leistungssteigerung. Wenn Sie zum vorherigen Verhalten zurückkehren möchten, legen Sie android.experimental.lint.analysisPerComponent=false in der Datei gradle.properties fest.

Präzise Ressourcenverkleinerung standardmäßig aktiviert

Die präzise Ressourcenverkleinerung, bei der nicht verwendete Einträge aus der Datei resources.arsc und nicht verwendete Ressourcendateien entfernt werden, ist standardmäßig aktiviert. Wenn diese Verkleinerung aktiviert ist, wird die Ressourcentabelle reduziert und nur referenzierte res-Ordnereinträge werden in das APK aufgenommen.

Wenn Sie die präzise Ressourcenverkleinerung deaktivieren möchten, setzen Sie android.enableNewResourceShrinker.preciseShrinking in der Datei gradle.properties Ihres Projekts auf false.