Build-Abhängigkeiten hinzufügen

Mit dem Gradle-Build-System in Android Studio können Sie externe Binärdateien oder andere Bibliotheksmodule als Abhängigkeiten in Ihren Build einbinden. Die Abhängigkeiten können sich auf Ihrem Computer oder in einem Remote-Repository befinden. Alle darin deklarierten transitiven Abhängigkeiten werden ebenfalls automatisch eingeschlossen. Auf dieser Seite wird beschrieben, wie Sie Abhängigkeiten in Ihrem Android-Projekt verwenden. Außerdem finden Sie hier Details zu Verhaltensweisen und Konfigurationen, die speziell für das Android Gradle-Plug-in (AGP) gelten. Einen ausführlicheren konzeptionellen Leitfaden zu Gradle-Abhängigkeiten finden Sie im Gradle-Leitfaden für die Abhängigkeitsverwaltung. Beachten Sie jedoch, dass in Ihrem Android-Projekt nur die auf dieser Seite definierten Abhängigkeitskonfigurationen verwendet werden dürfen.

Achtung: Geben Sie bei Abhängigkeiten keine dynamischen Versionsnummern wie 'com.android.tools.build:gradle:3.+' an. Die Verwendung dieser Funktion kann zu unerwarteten Versionsupdates, Schwierigkeiten bei der Behebung von Versionsunterschieden und einer schlechten Leistung führen.

Bibliotheks- oder Plug-in-Abhängigkeit hinzufügen

Die beste Möglichkeit zum Hinzufügen und Verwalten von Build-Abhängigkeiten besteht in der Verwendung von Versionskatalogen, der Methode, die bei neuen Projekten standardmäßig verwendet wird. In diesem Abschnitt werden die gängigsten Konfigurationstypen für Android-Projekte behandelt. Weitere Optionen finden Sie in der Gradle-Dokumentation. Ein Beispiel für eine App, die Versionskataloge verwendet, finden Sie unter Jetzt bei Android. Wenn Sie bereits Buildabhängigkeiten ohne Versionskataloge eingerichtet haben und ein mehrmoduliges Projekt haben, empfehlen wir Ihnen, zu migrieren.

Informationen zum Hinzufügen und Verwalten nativer Abhängigkeiten (nicht häufig) finden Sie unter Native Abhängigkeiten.

Im folgenden Beispiel fügen wir dem Projekt eine Remote-Binärabhängigkeit (die Jetpack MacroBenchmark-Bibliothek), die Modulabhängigkeit des lokalen Bibliotheksmoduls (myLibrary) und eine Plug-in-Abhängigkeit (das Android-Gradle-Plug-in) hinzu. So fügen Sie Ihrem Projekt diese Abhängigkeiten hinzu:

Hinweis :Es ist möglich, Versionskataloge in der Einstellungsdatei zu deklarieren. Wir empfehlen jedoch, eine separate toml-Datei zu verwenden, um mehr Unterstützung für Codevorschläge und Markierungen von Android Studio zu erhalten.

1. Fügen Sie im Abschnitt [versions] der Versionskatalogdatei einen Alias für die gewünschte Version der Abhängigkeit namens libs.versions.toml hinzu (im Verzeichnis gradle in der Ansicht Projekt oder Gradle-Scripts in der Ansicht Android):

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Aliasse können Bindestriche oder Unterstriche enthalten. Diese Aliasse generieren verschachtelte Werte, auf die Sie in Build-Skripts verweisen können. Die Verweise beginnen mit dem Namen des Katalogs, dem libs-Teil von libs.versions.toml. Wenn Sie einen Katalog mit einer einzelnen Version verwenden, empfehlen wir, den Standardwert „libs“ beizubehalten.

2. Fügen Sie einen Alias für die Abhängigkeit im Abschnitt [libraries] (für Remote-Binärdateien oder lokale Bibliotheksmodule) oder [plugins] (für Plug-ins) der Datei libs.versions.toml hinzu.

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   Einige Bibliotheken sind in einer veröffentlichten Stückliste (Bill of Materials, Stückliste) verfügbar, in der Bibliotheken und ihre Versionen zusammengefasst sind. Sie können eine BOM in Ihren Versionskatalog und Ihre Builddateien aufnehmen und diese Versionen von ihr verwalten lassen. Weitere Informationen finden Sie unter Materialliste verwenden.

3. Fügen Sie dem Build-Script der Module, für die die Abhängigkeit erforderlich ist, eine Referenz auf den Abhängigkeitsalias hinzu. Wandeln Sie die Unterstriche und Bindestriche des Alias in Punkte um, wenn Sie darauf über ein Build-Script verweisen. Unser Build-Skript auf Modulebene würde so aussehen:

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   Groovy

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   Plug-in-Referenzen enthalten plugins nach dem Katalognamen und Versionsverweise enthalten versions nach dem Katalognamen. Versionsverweise sind selten. Beispiele für Versionsverweise finden Sie unter Abhängigkeiten mit denselben Versionsnummern. Bibliotheksverweise enthalten keinen libraries-Qualifier. Daher können Sie versions oder plugins nicht am Anfang eines Bibliotheksalias verwenden.

Abhängigkeiten konfigurieren

Innerhalb des dependencies-Blocks können Sie eine Bibliothekabhängigkeit mit einer der verschiedenen Abhängigkeitskonfigurationen deklarieren, z. B. implementation, wie oben gezeigt. Jede Abhängigkeitskonfiguration enthält unterschiedliche Anweisungen für Gradle zur Verwendung der Abhängigkeit. In der folgenden Tabelle werden die Konfigurationen beschrieben, die Sie für eine Abhängigkeit in Ihrem Android-Projekt verwenden können.

Konfiguration	Verhalten
implementation	Gradle fügt die Abhängigkeit dem Compile-Classpath hinzu und verpackt sie in der Build-Ausgabe. Wenn das Modul eine implementation-Abhängigkeit konfiguriert, teilt es Gradle mit, dass das Modul die Abhängigkeit nicht bei der Kompilierung an andere Module weitergeben soll. Das heißt, die Abhängigkeit wird nicht für andere Module verfügbar gemacht, die vom aktuellen Modul abhängen. Die Verwendung dieser Abhängigkeitskonfiguration anstelle von api kann zu erheblichen Verbesserungen bei der Buildzeit führen, da die Anzahl der Module reduziert wird, die vom Buildsystem neu kompiliert werden müssen. Wenn sich beispielsweise die API einer implementation-Abhängigkeit ändert, kompiliert Gradle nur diese Abhängigkeit und die Module, die direkt davon abhängen. Diese Konfiguration sollte für die meisten App- und Testmodule verwendet werden.
api	Gradle fügt die Abhängigkeit dem Compile-Classpath und der Build-Ausgabe hinzu. Wenn ein Modul eine api-Abhängigkeit enthält, wird Gradle mitgeteilt, dass das Modul diese Abhängigkeit transitiv in andere Module exportieren möchte, damit sie sowohl zur Laufzeit als auch zur Kompilierzeit verfügbar ist. Verwenden Sie diese Konfiguration mit Vorsicht und nur mit Abhängigkeiten, die Sie vorübergehend in andere vorgelagerte Nutzer exportieren müssen. Wenn sich die externe API einer api-Abhängigkeit ändert, kompiliert Gradle alle Module neu, die zum Kompilierungszeitpunkt Zugriff auf diese Abhängigkeit haben. Eine große Anzahl von api-Abhängigkeiten kann die Build-Dauer erheblich verlängern. Sofern Sie die API einer Abhängigkeit nicht für ein separates Modul freigeben möchten, sollten Bibliotheksmodule stattdessen implementation-Abhängigkeiten verwenden.
compileOnly	Gradle fügt die Abhängigkeit nur dem Compile-Classpath hinzu, d. h., sie wird nicht der Build-Ausgabe hinzugefügt. Dies ist nützlich, wenn Sie ein Android-Modul erstellen und die Abhängigkeit während der Kompilierung benötigen. Es ist jedoch optional, dass sie zur Laufzeit vorhanden ist. Wenn Sie beispielsweise von einer Bibliothek abhängig sind, die nur Anmerkungen zur Kompilierungszeit enthält, die normalerweise zum Generieren von Code verwendet werden, aber oft nicht in der Build-Ausgabe enthalten sind, können Sie diese Bibliothek als compileOnly kennzeichnen. Wenn Sie diese Konfiguration verwenden, muss Ihr Bibliotheksmodul eine Laufzeitbedingung enthalten, um zu prüfen, ob die Abhängigkeit verfügbar ist, und dann sein Verhalten ordnungsgemäß ändern, sodass es auch ohne Angabe weiter funktionieren kann. So lässt sich die Größe der finalen App reduzieren, da keine nicht kritischen vorübergehenden Abhängigkeiten hinzugefügt werden. Hinweis: Sie können die compileOnly-Konfiguration nicht mit Android Archive-Abhängigkeiten (AAR) verwenden.
runtimeOnly	Gradle fügt die Abhängigkeit nur der Build-Ausgabe hinzu, um sie während der Laufzeit zu verwenden. Das heißt, es wird nicht dem Compile-Classpath hinzugefügt. Diese Methode wird unter Android selten, aber häufig in Serveranwendungen verwendet, um Logging-Implementierungen bereitzustellen. Eine Bibliothek könnte beispielsweise eine Logging-API verwenden, die keine Implementierung enthält. Nutzer dieser Bibliothek könnten sie als implementation-Abhängigkeit hinzufügen und eine runtimeOnly-Abhängigkeit für die eigentliche zu verwendende Logging-Implementierung einschließen.
ksp kapt annotationProcessor	Diese Konfigurationen stellen Bibliotheken bereit, die Annotationen und andere Symbole in Ihrem Code verarbeiten, bevor er kompiliert wird. Sie validieren in der Regel Ihren Code oder generieren zusätzlichen Code, wodurch Sie weniger Code schreiben müssen. Wenn Sie eine solche Abhängigkeit hinzufügen möchten, müssen Sie sie dem Klassenpfad des Anmerkungs-Prozessors mithilfe der Konfigurationen ksp, kapt oder annotationProcessor hinzufügen. Durch die Verwendung dieser Konfigurationen wird die Build-Leistung verbessert, da der Compile-Classpath vom Annotation-Prozessor-Classpath getrennt wird. Wenn Gradle Anmerkungs-Prozessoren im Compile-Classpath findet, deaktiviert es die Kompilierungsvermeidung, was sich negativ auf die Buildzeit auswirkt. In Gradle 5.0 und höher werden Anmerkungs-Prozessoren im Compile-Classpath ignoriert. Das Android-Gradle-Plug-in geht davon aus, dass eine Abhängigkeit ein Annotationsprozessor ist, wenn seine JAR-Datei die folgende Datei enthält: META-INF/services/javax.annotation.processing.Processor Wenn das Plug-in einen Annotationsprozessor erkennt, der sich im Kompilierungsklassenpfad befindet, wird ein Build-Fehler ausgegeben. ksp ist ein Kotlin-Symbolprozessor und wird vom Kotlin-Compiler ausgeführt. kapt und apt sind separate Tools, die Annotationen verarbeiten, bevor Kotlin- oder Java-Compiler ausgeführt werden. Berücksichtigen Sie bei der Entscheidung, welche Konfiguration Sie verwenden möchten, Folgendes: Wenn ein Prozessor als Kotlin-Symbolprozessor verfügbar ist, verwenden Sie ihn als ksp-Abhängigkeit. Weitere Informationen zur Verwendung von Kotlin-Symbolprozessoren finden Sie unter Von kapt zu ksp migrieren. Wenn der Prozessor nicht als Kotlin-Symbolprozessor verfügbar ist: Wenn Ihr Projekt Kotlin-Quellcode (aber auch Java-Quellcode) enthält, verwenden Sie kapt, um ihn einzubinden. Wenn Ihr Projekt nur Java-Quelle verwendet, fügen Sie sie mit annotationProcessor ein. Weitere Informationen zur Verwendung von Annotationsprozessoren finden Sie unter Annotationsprozessoren hinzufügen.
lintChecks	Verwenden Sie diese Konfiguration, um eine Bibliothek mit Lint-Prüfungen hinzuzufügen, die Gradle beim Erstellen Ihres Android-App-Projekts ausführen soll. Bei AARs, die eine lint.jar-Datei enthalten, werden automatisch die in dieser lint.jar-Datei definierten Prüfungen ausgeführt. Sie müssen keine explizite lintChecks-Abhängigkeit hinzufügen. So können Sie Bibliotheken und zugehörige Lint-Prüfungen in einer einzigen Abhängigkeit definieren und so dafür sorgen, dass Ihre Prüfungen ausgeführt werden, wenn Nutzer Ihre Bibliothek verwenden.
lintPublish	Verwenden Sie diese Konfiguration in Android-Bibliotheksprojekten, um Lint-Prüfungen anzugeben, die Gradle in eine lint.jar-Datei kompilieren und in Ihre AAR-Datei verpacken soll. Dadurch werden diese Lint-Prüfungen auch bei Projekten angewendet, die Ihre AAE nutzen. Wenn Sie zuvor die lintChecks-Abhängigkeitskonfiguration verwendet haben, um Lint-Prüfungen in die veröffentlichte AAR aufzunehmen, müssen Sie diese Abhängigkeiten migrieren, um stattdessen die lintPublish-Konfiguration zu verwenden. Kotlin dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Groovy dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

Abhängigkeiten für eine bestimmte Buildvariante konfigurieren

Alle vorherigen Konfigurationen wenden Abhängigkeiten auf alle Build-Varianten an. Wenn Sie stattdessen eine Abhängigkeit nur für einen bestimmten Build-Varianten-Quellsatz oder für einen Testquellsatz deklarieren möchten, müssen Sie den Konfigurationsnamen großschreiben und ihm den Namen der Build-Variante oder des Testquellsatzes voranstellen.

Wenn Sie beispielsweise eine binäre Remote-Abhängigkeit nur zu Ihrem "kostenlosen" Produkt-Flavor mit der implementation-Konfiguration hinzufügen möchten, verwenden Sie Folgendes:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Wenn Sie jedoch eine Abhängigkeit für eine Variante hinzufügen möchten, die eine Produktvariante und einen Buildtyp kombiniert, müssen Sie den Konfigurationsnamen initialisieren:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

So fügen Sie implementation-Abhängigkeiten für Ihre lokalen und instrumentierten Tests hinzu:

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

Bestimmte Konfigurationen sind in dieser Situation jedoch nicht sinnvoll. Da andere Module nicht von androidTest abhängen können, wird die folgende Warnung ausgegeben, wenn Sie die androidTestApi-Konfiguration verwenden:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Abhängigkeitsreihenfolge

Die Reihenfolge, in der Sie Ihre Abhängigkeiten auflisten, gibt die Priorität für jede an: Die erste Bibliothek hat eine höhere Priorität als die zweite, die zweite eine höhere Priorität als die dritte usw. Diese Reihenfolge ist wichtig, wenn Ressourcen oder Manifestelemente aus den Bibliotheken in Ihre App zusammengeführt werden.

Angenommen, in Ihrem Projekt wird Folgendes deklariert:

• Abhängigkeit von LIB_A und LIB_B (in dieser Reihenfolge)
• LIB_A hängt von LIB_C und LIB_D ab (in dieser Reihenfolge).
• Und LIB_B hängt auch von LIB_C ab.

Die flache Abhängigkeitsreihenfolge sieht dann so aus:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Dadurch wird sichergestellt, dass sowohl LIB_A als auch LIB_B LIB_C überschreiben können und LIB_D immer noch eine höhere Priorität als LIB_B hat, da LIB_A (das davon abhängt) eine höhere Priorität als LIB_B hat.

Weitere Informationen zum Zusammenführen von Manifesten aus verschiedenen Projektquellen/-abhängigkeiten finden Sie unter Mehrere Manifestdateien zusammenführen.

Abhängigkeitsinformationen für die Play Console

Beim Erstellen Ihrer App fügt AGP Metadaten hinzu, die die Bibliotheksabhängigkeiten beschreiben, die in Ihrer App kompiliert werden. Beim Hochladen Ihrer App prüft die Play Console diese Metadaten, um Benachrichtigungen zu bekannten Problemen mit SDKs und Abhängigkeiten Ihrer App bereitzustellen und in einigen Fällen umsetzbares Feedback zur Behebung dieser Probleme zu geben.

Die Daten werden komprimiert, mit einem Google Play-Signaturschlüssel verschlüsselt und im Signaturblock der Release-App gespeichert. Wir empfehlen, diese Abhängigkeitendatei für eine sichere und positive Nutzererfahrung aufzubewahren. Zum Deaktivieren können Sie den folgenden dependenciesInfo-Block in die build.gradle.kts-Datei Ihres Moduls einfügen.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Weitere Informationen zu unseren Richtlinien und möglichen Problemen mit Abhängigkeiten finden Sie auf unserer Supportseite zur Verwendung von Drittanbieter-SDKs in Ihrer App.

SDK-Statistiken

Android Studio zeigt Lint-Warnungen in der Versionskatalogdatei und im Dialogfeld „Projektstruktur“ für öffentliche SDKs im Google Play SDK Index an, wenn die folgenden Probleme auftreten:

• Die SDKs wurden von ihren Autoren als veraltet gekennzeichnet.
• Die SDKs verstoßen gegen die Google Play-Richtlinien.

Die Warnungen sind ein Signal, dass Sie diese Abhängigkeiten aktualisieren sollten. Wenn Sie veraltete Versionen verwenden, können Sie in Zukunft möglicherweise nicht mehr in der Google Play Console veröffentlichen.

Build-Abhängigkeiten ohne Versionskataloge hinzufügen

Wir empfehlen die Verwendung von Versionskatalogen, um Abhängigkeiten hinzuzufügen und zu verwalten. Für einfache Projekte werden sie jedoch möglicherweise nicht benötigt. Hier ist ein Beispiel für eine Build-Datei, die keine Versionskataloge verwendet:

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Cool

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

In dieser Build-Datei wird eine Abhängigkeit von Version 12.3 der Bibliothek „app-magic“ innerhalb der Namespacegruppe „com.example.android“ deklariert. Die Erklärung für die Remote-Binärabhängigkeit ist eine Kurzschreibweise für Folgendes:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Cool

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

Die Build-Datei deklariert auch eine Abhängigkeit von einem Android-Bibliotheksmodul namens „mylibrary“. Dieser Name muss mit dem Namen der Bibliothek übereinstimmen, der in Ihrer settings.gradle.kts-Datei mit einer include: definiert ist. Wenn Sie Ihre Anwendung erstellen, kompiliert das Build-System das Bibliotheksmodul und verpackt die resultierenden kompilierten Inhalte in der Anwendung.

Die Build-Datei deklariert auch eine Abhängigkeit vom Android-Gradle-Plug-in (com.application.android). Wenn mehrere Module dasselbe Plug-in verwenden, kann für alle Module nur eine einzige Version des Plug-ins im Build-Klassenpfad verwendet werden. Anstatt die Version in jedem der Modul-Build-Scripts anzugeben, sollten Sie die Plug-in-Abhängigkeit mit der Version in das Stamm-Build-Script aufnehmen und angeben, dass sie nicht angewendet werden soll. Wenn Sie apply false hinzufügen, wird Gradle angewiesen, die Version des Plug-ins zu notieren, sie aber nicht im Stamm-Build zu verwenden. Normalerweise ist das Stamm-Build-Script mit Ausnahme dieses plugins-Blocks leer.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Cool

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Wenn Sie ein Projekt mit nur einem Modul haben, können Sie die Version explizit im Build-Script auf Modulebene angeben und das Build-Script auf Projektebene leer lassen:

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}