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 aufnehmen. 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 spezifisch für das Android Gradle-Plug-in (AGP) sind. Einen detaillierten Konzeptleitfaden zu Gradle-Abhängigkeiten finden Sie im Gradle-Leitfaden zum Abhängigkeitsmanagement. Denken Sie aber daran, dass in Ihrem Android-Projekt nur die auf dieser Seite definierten Abhängigkeitskonfigurationen verwendet werden dürfen.

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

Die beste Möglichkeit, Buildabhängigkeiten hinzuzufügen und zu verwalten, sind Versionskataloge. Diese Methode wird bei neuen Projekten standardmäßig verwendet. 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 unserem Projekt eine remote binäre Abhängigkeit (die Jetpack Macrobenchmark-Bibliothek), eine lokale Bibliotheksmodulabhängigkeit (myLibrary) und eine Plug-in-Abhängigkeit (das Android Gradle-Plug-in) hinzu. So fügen Sie Ihrem Projekt diese Abhängigkeiten hinzu:

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-Scripts 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 in der Datei libs.versions.toml im Abschnitt [libraries] (für Remote-Binärdateien oder lokale Bibliotheksmodule) oder [plugins] (für Plug-ins) einen Alias für die Abhängigkeit 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, BOM) verfügbar, in der Bibliotheksfamilien und ihre Versionen gruppiert 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-Script 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
   }

   Pluginverweise enthalten nach dem Katalognamen plugins und Versionsverweise versions. Versionsverweise sind selten. Beispiele für Versionsverweise finden Sie unter Abhängigkeiten mit denselben Versionsnummern. Bibliotheksreferenzen enthalten keinen libraries-Qualifikator. Sie können also weder versions noch plugins 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.

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

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

Bei allen vorherigen Konfigurationen werden Abhängigkeiten auf alle Buildvarianten angewendet. Wenn Sie stattdessen eine Abhängigkeit nur für eine bestimmte Buildvariante oder für ein Testquellen-Set angeben möchten, müssen Sie den Konfigurationsnamen großschreiben und mit dem Namen der Buildvariante oder des Testquellen-Sets voranstellen.

Wenn Sie beispielsweise eine Remote-Binärabhängigkeit nur der „kostenlosen“ Produktvariante mithilfe der implementation-Konfiguration hinzufügen möchten, verwenden Sie Folgendes:

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

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:

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

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

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:

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

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 beispielsweise nicht von androidTest abhängig sein können, wird bei Verwendung der androidTestApi-Konfiguration die folgende Warnung angezeigt:

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 aus den Bibliotheken in Ihre App zusammengeführt oder Manifestelemente aus den Bibliotheken in Ihre App zusammengeführt werden.

Beispiel: In Ihrem Projekt wird Folgendes deklariert:

• Abhängigkeit von LIB_A und LIB_B (in dieser Reihenfolge)
• Und 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

So können sowohl LIB_A als auch LIB_B LIB_C überschreiben. LIB_D hat weiterhin eine höhere Priorität als LIB_B, da LIB_A (von dem es 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.

Informationen zu Abhängigkeiten für die Play Console

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

Die Daten werden komprimiert, mit einem Google Play-Signaturschlüssel verschlüsselt und im Signaturblock Ihrer Release-App gespeichert. Wir empfehlen, diese Abhängigkeitsdatei beizubehalten, um eine sichere und positive Nutzererfahrung zu ermöglichen. Sie können die Funktion deaktivieren, indem Sie den folgenden Block dependenciesInfo 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 potenziellen Problemen mit Abhängigkeiten finden Sie auf unserer Supportseite Drittanbieter-SDKs in Ihrer App verwenden.

SDK-Statistiken

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

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

Die Warnungen sind ein Signal, dass Sie diese Abhängigkeiten aktualisieren sollten, da die Verwendung veralteter Versionen die Veröffentlichung in der Google Play Console in Zukunft verhindern könnte.

Build-Abhängigkeiten ohne Versionskataloge hinzufügen

Wir empfehlen, Versionskataloge zum Hinzufügen und Verwalten von Abhängigkeiten zu verwenden. Bei einfachen Projekten sind sie jedoch möglicherweise nicht erforderlich. Hier ist ein Beispiel für eine Builddatei, die keine Versionskataloge verwendet:

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

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:

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

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 App erstellen, kompiliert das Build-System das Bibliotheksmodul und verpackt den resultierenden kompilierten Inhalt in der App.

In der Build-Datei wird auch eine Abhängigkeit vom Android Gradle-Plug-in (com.application.android) deklariert. Wenn Sie mehrere Module haben, die dasselbe Plug-in verwenden, kann es nur eine einzige Version des Plug-ins im Build-Classpath für alle Module geben. 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.

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

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:

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

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