Das Android-Build-System kompiliert App-Ressourcen und Quellcode und verpackt sie in APKs oder Android App Bundles, die Sie testen, bereitstellen, signieren und verteilen können.
In den Artikeln Gradle-Build – Übersicht und Android-Build-Struktur haben wir die Build-Konzepte und die Struktur einer Android-App besprochen. Jetzt ist es an der Zeit, den Build zu konfigurieren.
Glossar zu Android-Builds
Mit Gradle und dem Android-Gradle-Plug-in können Sie die folgenden Aspekte Ihres Builds konfigurieren:
Build-Typen
Buildtypen definieren bestimmte Eigenschaften, die Gradle beim Erstellen und Verpacken Ihrer App verwendet. Buildtypen werden in der Regel für verschiedene Phasen des Entwicklungszyklus konfiguriert.
Beim Debug-Buildtyp werden beispielsweise Debug-Optionen aktiviert und die App mit dem Debug-Schlüssel signiert. Beim Release-Buildtyp kann die App für den Vertrieb verkleinert, verschleiert und mit einem Release-Schlüssel signiert werden.
Sie müssen mindestens einen Build-Typ definieren, um Ihre App zu erstellen. In Android Studio werden standardmäßig die Build-Typen „Debug“ und „Release“ erstellt. Wenn Sie die Verpackungseinstellungen für Ihre App anpassen möchten, erfahren Sie hier, wie Sie Buildtypen konfigurieren.
Produktvarianten
Produktvarianten stellen verschiedene Versionen Ihrer App dar, die Sie Nutzern anbieten können, z. B. kostenlose und kostenpflichtige Versionen. Sie können Produktvarianten anpassen, um anderen Code und andere Ressourcen zu verwenden, während Sie die Teile, die für alle Versionen Ihrer App gemeinsam sind, teilen und wiederverwenden. Produktvarianten sind optional und müssen manuell erstellt werden. Wenn Sie verschiedene Versionen Ihrer App erstellen möchten, können Sie hier erfahren, wie Sie Produktvarianten konfigurieren.
Build-Varianten
Eine Buildvariante ist ein produktübergreifender Buildtyp und Produktvariante und die Konfiguration, die Gradle zum Erstellen Ihrer App verwendet. Mit Buildvarianten können Sie während der Entwicklung die Debugversion Ihrer Produktvarianten und signierte Releaseversionen Ihrer Produktvarianten für den Vertrieb erstellen.
Sie konfigurieren Build-Varianten zwar nicht direkt, aber die Build-Typen und Produktvarianten, aus denen sie bestehen. Wenn Sie zusätzliche Buildtypen oder Produktvarianten erstellen, werden auch zusätzliche Buildvarianten erstellt. Informationen zum Erstellen und Verwalten von Buildvarianten finden Sie in der Übersicht Buildvarianten konfigurieren.
Manifesteinträge
Sie können Werte für einige Eigenschaften der Manifestdatei in der Buildvariantenkonfiguration angeben. Diese Build-Werte überschreiben die vorhandenen Werte in der Manifestdatei. Das ist hilfreich, wenn Sie mehrere Varianten Ihrer App mit einem anderen Anwendungsnamen, einer anderen Mindest-SDK-Version oder einer anderen SDK-Zielversion generieren möchten. Wenn mehrere Manifeste vorhanden sind, werden die Manifesteinstellungen mit dem Tool zum Zusammenführen von Manifesten
zusammengeführt.
Abhängigkeiten
Das Build-System verwaltet Projektabhängigkeiten aus Ihrem lokalen Dateisystem und aus Remote-Repositories. Sie müssen also nicht manuell nach Binärpaketen Ihrer Abhängigkeiten suchen, sie herunterladen und in Ihr Projektverzeichnis kopieren. Weitere Informationen finden Sie unter Build-Abhängigkeiten hinzufügen.
Unterzeichnung
Mit dem Build-System können Sie Signatureinstellungen in der Build-Konfiguration angeben. Außerdem kann Ihre App während des Build-Prozesses automatisch signiert werden. Das Build-System signiert die Debugversion mit einem Standardschlüssel und einem Zertifikat mit bekannten Anmeldedaten, um eine Passwortaufforderung beim Build zu vermeiden. Das Build-System signiert die Release-Version nur, wenn Sie explizit eine Signaturkonfiguration für diesen Build definieren. Wenn Sie keinen Release-Schlüssel haben, können Sie einen generieren, wie unter App signieren beschrieben. Signierte Release-Builds sind für den Vertrieb von Apps über die meisten App-Shops erforderlich.
Code- und Ressourcenkomprimierung
Mit dem Build-System können Sie für jede Build-Variante eine andere ProGuard-Regelndatei angeben. Beim Erstellen Ihrer App wendet das Build-System die entsprechenden Regeln an, um mithilfe der integrierten Komprimierungstools wie R8 Ihren Code und Ihre Ressourcen zu komprimieren.
Wenn Sie Ihren Code und Ihre Ressourcen verkleinern, können Sie die Größe Ihres APK oder AAB verringern.
Unterstützung für mehrere APKs
Mit dem Build-System können Sie automatisch verschiedene APKs erstellen, die jeweils nur den Code und die Ressourcen enthalten, die für eine bestimmte Bildschirmdichte oder Application Binary Interface (ABI) erforderlich sind.
Weitere Informationen finden Sie unter
Mehrere APKs erstellen. Wir empfehlen jedoch, ein einzelnes AAB zu veröffentlichen, da es neben der Bildschirmdichte und dem ABI auch eine Aufteilung nach Sprache bietet und Sie nicht mehrere Artefakte bei Google Play hochladen müssen. Alle neuen Apps, die nach August 2021 eingereicht werden, müssen AABs verwenden.
Java-Versionen in Android-Builds
Unabhängig davon, ob Ihr Quellcode in Java, Kotlin oder in beiden Sprachen geschrieben ist, müssen Sie an mehreren Stellen eine JDK- oder Java-Sprachversion für Ihren Build auswählen. Weitere Informationen finden Sie unter Java-Versionen in Android-Builds.
Build-Konfigurationsdateien
Wenn Sie benutzerdefinierte Build-Konfigurationen erstellen möchten, müssen Sie Änderungen an einer oder mehreren Build-Konfigurationsdateien vornehmen. In diesen Textdateien wird mit einer domänenspezifischen Sprache (DSL) die Buildlogik mit Kotlin-Script, einer Variante der Kotlin-Programmiersprache, beschrieben und manipuliert. Sie können Ihre Builds auch mit Groovy konfigurieren, einer dynamischen Sprache für die Java Virtual Machine (JVM).
Sie müssen kein Kotlin-Script oder Groovy beherrschen, um mit der Konfiguration Ihres Builds zu beginnen, da das Android Gradle-Plug-in die meisten benötigten DSL-Elemente enthält. Weitere Informationen zur Android Gradle Plugin DSL finden Sie in der DSL-Referenzdokumentation. Kotlin-Scripts basieren auch auf der zugrunde liegenden Gradle Kotlin DSL.
Wenn Sie ein neues Projekt starten, erstellt Android Studio automatisch einige dieser Dateien für Sie und füllt sie mit sinnvollen Standardwerten aus. Eine Übersicht über die erstellten Dateien finden Sie unter Android-Build-Struktur.
Die Gradle-Wrapper-Datei
Der Gradle-Wrapper (gradlew) ist eine kleine Anwendung, die im Quellcode enthalten ist und Gradle selbst herunterlädt und startet.
Dadurch wird die Build-Ausführung einheitlicher. Entwickler laden die Anwendungsquelle herunter und führen gradlew aus. Dadurch wird die erforderliche Gradle-Distribution heruntergeladen und Gradle gestartet, um Ihre Anwendung zu erstellen.
Die Datei gradle/wrapper/gradle-wrapper.properties enthält die Property distributionUrl, die beschreibt, welche Version von Gradle zum Ausführen des Builds verwendet wird.
Die Datei settings.gradle.kts (für die Kotlin-DSL) oder settings.gradle (für die Groovy-DSL) befindet sich im Stammverzeichnis des Projekts. In dieser Datei werden Repository-Einstellungen auf Projektebene definiert und Gradle wird mitgeteilt, welche Module beim Erstellen Ihrer App eingeschlossen werden sollen. Bei Projekten mit mehreren Modulen muss jedes Modul angegeben werden, das in den endgültigen Build aufgenommen werden soll.
Bei den meisten Projekten sieht die Datei standardmäßig so aus:
Die Datei build.gradle.kts (für die Kotlin-DSL) oder build.gradle (für die Groovy-DSL) der obersten Ebene befindet sich im Stammverzeichnis des Projekts. Normalerweise werden hier die gängigen Versionen von Plug-ins definiert, die von den Modulen in Ihrem Projekt verwendet werden.
Im folgenden Codebeispiel werden die Standardeinstellungen und DSL-Elemente im übergeordneten Build-Script nach dem Erstellen eines neuen Projekts beschrieben:
Die Datei build.gradle.kts (für die Kotlin-DSL) oder build.gradle (für die Groovy-DSL) auf Modulebene befindet sich in jedem project/module/-Verzeichnis. Damit können Sie Build-Einstellungen für das jeweilige Modul konfigurieren. Wenn Sie diese Build-Einstellungen konfigurieren, können Sie benutzerdefinierte Verpackungsoptionen wie zusätzliche Buildtypen und Produktvarianten angeben und Einstellungen im main/-App-Manifest oder im Build-Script der obersten Ebene überschreiben.
Android SDK-Einstellungen
Die Build-Datei auf Modulebene für Ihre Anwendung enthält Einstellungen, die die beim Kompilieren verwendeten Android SDK-Versionen angeben, Plattformverhalten auswählen und die Mindestversion angeben, unter der Ihre Anwendung ausgeführt wird.
Abbildung 1. Android SDKs in einem Build
compileSdk
Mit der compileSdk wird festgelegt, welche Android- und Java-APIs beim Kompilieren des Quellcodes verfügbar sind. Wenn Sie die neuesten Android-Funktionen nutzen möchten, verwenden Sie beim Kompilieren das neueste Android SDK.
Jedes Android SDK bietet eine Teilmenge der Java APIs zur Verwendung in Ihrer Anwendung.
In der Tabelle unter
Welche Java APIs kann ich in meinem Java- oder Kotlin-Quellcode verwenden? sehen Sie, welche Java API-Ebene je nach Android SDK-Version verfügbar ist.
Die neueren Java-APIs werden in älteren Android-Versionen durch Desugaring unterstützt, das in Ihrem Build aktiviert sein muss.
In Android Studio werden Warnungen angezeigt, wenn Ihre compileSdk mit der aktuellen Version von Android Studio, AGP oder den Bibliotheksabhängigkeitsanforderungen Ihres Projekts in Konflikt stehen.
minSdk
Mit minSdk wird die niedrigste Android-Version angegeben, die Ihre App unterstützen soll. Mit der Einstellung minSdk können Sie einschränken, auf welchen Geräten Ihre App installiert werden kann.
Wenn Sie niedrigere Android-Versionen unterstützen möchten, sind möglicherweise mehr bedingte Prüfungen in Ihrem Code oder eine stärkere Nutzung von AndroidX-Kompatibilitätsbibliotheken erforderlich. Sie sollten die Wartungskosten für die Unterstützung niedrigerer Versionen mit dem Prozentsatz der Nutzer abwägen, die diese niedrigeren Versionen noch verwenden. Die aktuellen Prozentsätze für die Versionsnutzung finden Sie im Versionsdiagramm im Assistenten für neues Projekt von Android Studio.
Wenn Sie Ihren Code in Android Studio bearbeiten oder während des Builds Prüfungen ausführen, warnt lint vor APIs, die Sie verwenden und die nicht in der minSdk verfügbar sind. Sie sollten diese Fehler beheben, indem Sie
neuere Funktionen bedingt machen oder Appcompat für die Abwärtskompatibilität verwenden.
targetSdk
Die targetSdk dient zwei Zwecken:
Damit wird das Laufzeitverhalten Ihrer Anwendung festgelegt.
Sie bestätigt, mit welcher Android-Version Sie den Test durchgeführt haben.
Wenn Sie auf einem Gerät mit einer höheren Android-Version als Ihrer targetSdk laufen, wird Ihre App von Android in einem Kompatibilitätsmodus ausgeführt, der sich ähnlich wie die in Ihrer targetSdk angegebene niedrigere Version verhält. Als beispielsweise mit API 23 das Berechtigungsmodell für die Laufzeit eingeführt wurde, waren nicht alle Apps sofort bereit, es zu verwenden.
Wenn Sie targetSdk auf 22 festlegen, können diese Apps auf Geräten mit API 23 ohne Laufzeitberechtigungen ausgeführt werden und Funktionen verwenden, die in der neuesten compileSdk-Version enthalten sind. Die Google Play-Vertriebsrichtlinie erzwingt
zusätzliche Richtlinien auf Ziel-API-Ebene.
Der Wert von targetSdk muss kleiner oder gleich dem Wert von compileSdk sein.
Hinweis:Die Werte für compileSdk und targetSdk müssen nicht identisch sein. Beachten Sie dabei die folgenden Grundprinzipien:
compileSdk bietet Zugriff auf neue APIs
targetSdk legt das Laufzeitverhalten Ihrer App fest
targetSdk muss kleiner oder gleich compileSdk sein
Beispiel für ein Build-Script für App-Module
In diesem Beispiel-Build-Script für ein Android-App-Modul werden einige der grundlegenden DSL-Elemente und ‑Einstellungen beschrieben:
Gradle enthält außerdem zwei Properties-Dateien im Stammverzeichnis des Projekts, mit denen Sie Einstellungen für das Gradle-Build-Toolkit selbst festlegen können:
gradle.properties
Hier können Sie projektweite Gradle-Einstellungen konfigurieren, z. B. die maximale Heap-Größe des Gradle-Daemons. Weitere Informationen finden Sie unter Build-Umgebung.
local.properties
Konfiguriert lokale Umgebungseigenschaften für das Build-System, einschließlich der folgenden:
ndk.dir: Pfad zum NDK. Dieses Attribut wird nicht mehr unterstützt. Alle heruntergeladenen Versionen des NDK werden im Verzeichnis ndk im Android SDK-Verzeichnis installiert.
sdk.dir: Pfad zum Android SDK.
cmake.dir: Pfad zu CMake.
ndk.symlinkdir – In Android Studio 3.5 und höher wird ein Symlink zum NDK erstellt, der kürzer als der installierte NDK-Pfad sein kann.
NDK einem kürzeren Pfad zuordnen (nur Windows)
Unter Windows haben Tools im installierten NDK-Ordner, z. B. ld.exe, lange Pfade. Die Tools unterstützen lange Pfade nicht gut.
Wenn Sie einen kürzeren Pfad erstellen möchten, legen Sie in local.properties die Property ndk.symlinkdir fest, um das Android Gradle-Plug-in aufzufordern, einen Symlink zum NDK zu erstellen. Der Pfad dieses Symlinks kann kürzer als der vorhandene NDK-Ordner sein.
ndk.symlinkdir = C:\ führt beispielsweise zum folgenden Symlink:
C:\ndk\19.0.5232133
Projekt mit Gradle-Dateien synchronisieren
Wenn Sie Änderungen an den Build-Konfigurationsdateien in Ihrem Projekt vornehmen, müssen Sie Ihre Projektdateien in Android Studio synchronisieren, damit die Änderungen an der Build-Konfiguration importiert und einige Prüfungen durchgeführt werden können, um sicherzustellen, dass Ihre Konfiguration keine Buildfehler verursacht.
Wenn Sie Ihre Projektdateien synchronisieren möchten, klicken Sie in der Benachrichtigungsleiste, die nach einer Änderung angezeigt wird (siehe Abbildung 2), auf Jetzt synchronisieren oder in der Menüleiste auf Projekt synchronisieren. Wenn Android Studio Fehler in Ihrer Konfiguration findet, z. B. wenn Ihr Quellcode API-Funktionen verwendet, die nur auf einer API-Ebene verfügbar sind, die höher als Ihre compileSdkVersion ist, wird das Problem im Fenster Nachrichten beschrieben.
Abbildung 2. Synchronisieren Sie das Projekt mit den Build-Konfigurationsdateien in Android Studio.
Source-Sets
In Android Studio werden Quellcode und Ressourcen für jedes Modul logisch in Quellsets gruppiert. Wenn Sie ein neues Modul erstellen, erstellt Android Studio darin ein main/-Quellset. Das main/-Quellset eines Moduls enthält den Code und die Ressourcen, die von allen Buildvarianten verwendet werden.
Zusätzliche Verzeichnisse für Quellsätze sind optional. Sie werden in Android Studio nicht automatisch für Sie erstellt, wenn Sie neue Buildvarianten konfigurieren. Das Erstellen von Quellsätzen, ähnlich wie bei main/, hilft jedoch, Dateien und Ressourcen zu organisieren, die Gradle nur beim Erstellen bestimmter Versionen Ihrer App verwenden sollte:
src/main/
Dieses Quellset enthält Code und Ressourcen, die für alle Buildvarianten gemeinsam sind.
src/buildType/
Erstellen Sie dieses Quellset, um Code und Ressourcen nur für einen bestimmten Buildtyp einzuschließen.
src/productFlavor/
Erstellen Sie dieses Quellset, um Code und Ressourcen nur für eine bestimmte Produktvariante einzuschließen.
Hinweis: Wenn Sie Ihren Build so konfigurieren, dass mehrere Produktvarianten kombiniert werden, können Sie für jede Kombination von Produktvarianten zwischen den Variantendimensionen src/productFlavor1ProductFlavor2/ Verzeichnisse für Quellsätze erstellen.
src/productFlavorBuildType/
Erstellen Sie dieses Quellset, um Code und Ressourcen nur für eine bestimmte Buildvariante einzuschließen.
Wenn Sie beispielsweise die Version „fullDebug“ Ihrer App generieren möchten, werden im Build-System Code, Einstellungen und Ressourcen aus den folgenden Quellsätzen zusammengeführt:
src/fullDebug/ (die Quelldatei der Buildvariante)
src/debug/ (die Quellgruppe des Build-Typs)
src/full/ (die Quelle für die Produktvariante)
src/main/ (Hauptquellensatz)
Hinweis:Wenn Sie in Android Studio eine neue Datei oder ein neues Verzeichnis erstellen, verwenden Sie die Menüoptionen Datei > Neu, um sie für ein bestimmtes Quellset zu erstellen. Die Quellsätze, aus denen Sie auswählen können, basieren auf Ihren Buildkonfigurationen. Die erforderlichen Verzeichnisse werden in Android Studio automatisch erstellt, falls sie noch nicht vorhanden sind.
Wenn verschiedene Quellsätze unterschiedliche Versionen derselben Datei enthalten, verwendet Gradle die folgende Prioritätsreihenfolge, um zu entscheiden, welche Datei verwendet werden soll. Die Quellgruppen auf der linken Seite überschreiben die Dateien und Einstellungen der Quellgruppen auf der rechten Seite:
build variant > build type > product flavor > main source set >
library dependencies
So kann Gradle Dateien verwenden, die für die Buildvariante spezifisch sind, die Sie erstellen möchten, und gleichzeitig Aktivitäten, Anwendungslogik und Ressourcen wiederverwenden, die für andere Versionen Ihrer App gemeinsam sind.
Wenn Ihr Build mehrere Module mit gemeinsamen Abhängigkeiten enthält oder Sie mehrere unabhängige Projekte mit gemeinsamen Abhängigkeiten haben, empfehlen wir Ihnen, einen Versionskatalog oder eine Stückliste (Bill of Materials, BOM) zu verwenden, um die gemeinsamen Versionen anzugeben.
Andere Build-Systeme
Das Erstellen von Android-Apps mit Bazel ist möglich, wird aber nicht offiziell unterstützt. Bazel-Projekte werden von Android Studio nicht offiziell unterstützt.
Weitere Informationen zu den aktuellen Einschränkungen beim Erstellen mit Bazel finden Sie unter Bekannte Probleme.
Alle Inhalte und Codebeispiele auf dieser Seite unterliegen den Lizenzen wie im Abschnitt Inhaltslizenz beschrieben. Java und OpenJDK sind Marken oder eingetragene Marken von Oracle und/oder seinen Tochtergesellschaften.