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 einbeziehen. Die Abhängigkeiten können sich auf Ihrem Computer oder in einem Remote-Repository befinden. Alle transitiven Abhängigkeiten, die sie deklarieren, werden automatisch mit einbezogen. Auf dieser Seite wird beschrieben, wie Sie Abhängigkeiten in Ihrem Android-Projekt verwenden. Außerdem finden Sie Details zu Verhaltensweisen und Konfigurationen, die für das Android-Gradle-Plugin (AGP) spezifisch sind. Einen ausführlicheren konzeptionellen Leitfaden zu Gradle-Abhängigkeiten finden Sie im Gradle-Leitfaden zur Abhängigkeitsverwaltung. Ihr Android-Projekt darf jedoch nur die auf dieser Seite definierten Abhängigkeitskonfigurationen verwenden.

Bibliotheks- oder Plugin-Abhängigkeit hinzufügen

Die beste Möglichkeit, Build-Abhängigkeiten hinzuzufügen und zu verwalten, ist die Verwendung von Versionskatalogen. Diese Methode wird standardmäßig für neue Projekte 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 Now in Android. Wenn Sie bereits Build-Abhängigkeiten ohne Versionskataloge eingerichtet haben und ein Projekt mit mehreren Modulen verwenden, empfehlen wir eine Migration.

Eine Anleitung zum Hinzufügen und Verwalten nativer Abhängigkeiten (nicht üblich) finden Sie unter Native Abhängigkeiten.

Im folgenden Beispiel fügen wir unserem Projekt eine Remote-Binärdatei-Abhängigkeit (die Jetpack Macrobenchmark-Bibliothek), eine lokale Bibliotheksmodul-Abhä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 (unter dem Verzeichnis gradle in der Ansicht Projekt oder Gradle-Skripts in der Ansicht Android) einen Alias für die gewünschte Version der Abhängigkeit hinzu:libs.versions.toml

   [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 Referenzen beginnen mit dem Namen des Katalogs, dem libs-Teil von libs.versions.toml. Wenn Sie einen Katalog mit einer einzigen Version verwenden, empfehlen wir, den Standardwert „libs.“ beizubehalten.

2. Fügen Sie einen Alias für die Abhängigkeit in den Abschnitten [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, BOM) verfügbar, in der Bibliotheksfamilien und ihre Versionen gruppiert sind. Sie können eine BOM in Ihren Versionskatalog und Ihre Build-Dateien einfügen und die Versionsverwaltung der BOM überlassen. Weitere Informationen finden Sie unter Stückliste verwenden.

3. Fügen Sie dem Build-Skript des Moduls bzw. der Module, für die die Abhängigkeit erforderlich ist, einen Verweis auf den Abhängigkeitsalias hinzu. Wenn Sie in einem Build-Script auf den Alias verweisen, müssen Sie die Unterstriche und Bindestriche in Punkte umwandeln. Das 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
   }

   Plugin-Referenzen enthalten plugins nach dem Katalognamen und Versionsreferenzen enthalten versions nach dem Katalognamen. Versionsreferenzen sind ungewöhnlich. Beispiele für Versionsreferenzen finden Sie unter Abhängigkeiten mit derselben Versionsnummer. Bibliotheksreferenzen enthalten keinen libraries-Qualifizierer. Daher können Sie versions oder plugins nicht am Anfang eines Bibliotheksalias verwenden.

Abhängigkeiten konfigurieren

Im dependencies-Block können Sie eine Bibliotheksabhängigkeit mit einer von mehreren 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 einzelnen 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 Build-Variante konfigurieren

Bei allen oben genannten Konfigurationen werden Abhängigkeiten auf alle Build-Varianten angewendet. Wenn Sie stattdessen eine Abhängigkeit nur für ein bestimmtes Build-Varianten-Quellset oder ein Testquellset deklarieren möchten, müssen Sie den Konfigurationsnamen in Großbuchstaben schreiben und mit dem Namen der Build-Variante oder des Testquellsets präfixieren.

Wenn Sie beispielsweise dem Produkt-Flavor „free“ mit der Konfiguration implementation eine Remote-Binärabhängigkeit 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 Build-Typ 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 Tests 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ängen können, wird die folgende Warnung angezeigt, wenn Sie die androidTestApi-Konfiguration verwenden:

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

Reihenfolge der Abhängigkeiten

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

Wenn in Ihrem Projekt beispielsweise Folgendes deklariert wird:

• 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).
• 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.

Abhängigkeitsinformationen für die Play Console

Beim Erstellen Ihrer App fügt das AGP Metadaten hinzu, die die Bibliotheksabhängigkeiten beschreiben, die in Ihre App kompiliert werden. Beim Hochladen Ihrer App prüft die Play Console diese Metadaten, um Sie über bekannte Probleme mit SDKs und Abhängigkeiten zu informieren, die Ihre App verwendet. In einigen Fällen erhalten Sie auch umsetzbares Feedback, um diese Probleme zu beheben.

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 Nutzern eine sichere und positive Nutzung zu ermöglichen. Sie können die Funktion deaktivieren, indem 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 potenziellen Problemen mit Abhängigkeiten finden Sie auf unserer Supportseite Drittanbieter-SDKs in Ihrer App verwenden.

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 vorliegen:

• Die SDKs werden von ihren Autoren als veraltet gekennzeichnet.
• Die SDKs verstoßen gegen die Play-Richtlinien.
• Die SDKs haben bekannte Sicherheitslücken.
• Die SDKs wurden von ihren Autoren eingestellt.

Die Warnungen sind ein Signal dafür, dass Sie diese Abhängigkeiten aktualisieren sollten, da Sie bei Verwendung veralteter Versionen in Zukunft möglicherweise nicht mehr in der Google Play Console veröffentlichen können.

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 sehen Sie ein Beispiel für eine Build-Datei, in der keine Versionskataloge verwendet werden:

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“ in der Namespace-Gruppe „com.example.android“ deklariert. Die Deklaration für die binäre Remote-Abhängigkeit ist eine Kurzform 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'

In der Build-Datei wird auch eine Abhängigkeit von einem Android-Bibliotheksmodul mit dem Namen „mylibrary“ deklariert. Dieser Name muss mit dem Bibliotheksnamen übereinstimmen, der mit einem include: in Ihrer settings.gradle.kts-Datei definiert ist. Wenn Sie Ihre App erstellen, kompiliert das Build-System das Bibliotheksmodul und packt die kompilierten Inhalte in die 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 im Build-Klassenpfad nur eine Version des Plug-ins für alle Module vorhanden sein. Anstatt die Version in jedem der Modul-Build-Skripts anzugeben, sollten Sie die Plugin-Abhängigkeit mit der Version in das Root-Build-Skript aufnehmen und angeben, dass sie nicht angewendet werden soll. Durch das Hinzufügen von apply false wird Gradle angewiesen, die Version des Plug-ins zu notieren, sie aber nicht im Root-Build zu verwenden. Normalerweise ist das Stamm-Build-Skript leer, mit Ausnahme dieses plugins-Blocks.

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 einem einzelnen Modul haben, können Sie die Version explizit im Build-Skript auf Modulebene angeben und das Build-Skript auf Projektebene leer lassen:

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

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