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 deklarierten transitiven Abhängigkeiten werden ebenfalls automatisch einbezogen. 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 für das Android Gradle-Plug-in (AGP) spezifisch sind. Eine ausführlichere konzeptionelle Anleitung zu Gradle-Abhängigkeiten finden Sie im Gradle-Leitfaden zur Abhängigkeitsverwaltung. Beachten Sie jedoch, dass Ihr Android-Projekt nur die auf dieser Seite definierten Abhängigkeitskonfigurationen verwenden darf.

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

Build-Abhängigkeiten lassen sich am besten mit Versionskatalogen hinzufügen und verwalten. 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 haben, empfehlen wir die Migration.

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

Im folgenden Beispiel werden dem Projekt eine Remote-Binärabhängigkeit (die Jetpack Macrobenchmark-Bibliothek), eine Abhängigkeit von einem lokalen Bibliotheksmodul (myLibrary) und eine Plug-in-Abhängigkeit (das Android-Gradle-Plug-in) hinzugefügt. So fügen Sie diese Abhängigkeiten Ihrem Projekt hinzu:

1. Fügen Sie im Abschnitt [versions] der Versionskatalogdatei mit dem Namen libs.versions.toml (im 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:

   [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 Aliase 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 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 Materialliste (BOM) verfügbar, in der Bibliotheksfamilien und ihre Versionen gruppiert sind. Sie können eine BOM in Ihren Versionskatalog und Ihre Build-Dateien aufnehmen und diese Versionen von ihr verwalten lassen. Weitere Informationen finden Sie unter Materialliste verwenden.

3. Fügen Sie dem Build-Script der Module, die die Abhängigkeit benötigen, einen Verweis auf den Abhängigkeitsalias hinzu. Konvertieren Sie die Unterstriche und Bindestriche des Alias in Punkte, wenn Sie in einem Build-Skript darauf verweisen. Das 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
   }

   Plug-in-Referenzen enthalten plugins nach dem Katalognamen und Versionsreferenzen enthalten versions nach dem Katalognamen. Versionsreferenzen sind selten. Beispiele für Versionsreferenzen finden Sie unter Abhängigkeiten mit denselben Versionsnummern. Bibliotheksreferenzen enthalten keinen libraries-Kennzeichner. Sie können also nicht versions oder plugins am Anfang eines Bibliotheks-Alias verwenden.

Abhängigkeiten konfigurieren

Im Block dependencies können Sie eine Bibliotheksabhängigkeit mit einer von mehreren verschiedenen Abhängigkeitskonfigurationen deklarieren (z. B. implementation, wie oben gezeigt). Jede Abhängigkeitskonfiguration liefert Gradle unterschiedliche Anweisungen 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 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 Source-Set einer Build-Variante oder für ein Test-Source-Set deklarieren möchten, müssen Sie den Konfigurationsnamen großschreiben und ihm den Namen der Build-Variante oder des Test-Source-Sets voranstellen.

Wenn Sie beispielsweise eine Remote-Binärabhängigkeit nur mit der implementation-Konfiguration zu Ihrer „kostenlosen“ Produktvariante 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 Instrumentierungstests 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 nicht von androidTest abhängen können, erhalten Sie beispielsweise die folgende Warnung, 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 Abhängigkeit an. Beispielsweise hat die erste Bibliothek eine höhere Priorität als die zweite und die zweite eine höhere Priorität als die dritte. Diese Reihenfolge ist wichtig, wenn Ressourcen zusammengeführt oder Manifestelemente aus den Bibliotheken in Ihre App zusammengeführt werden.

Wenn Ihr Projekt beispielsweise 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 ist auch von LIB_C abhängig.

Die flache Abhängigkeitsreihenfolge sieht dann so aus:

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

So 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 oder 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. Wenn Sie Ihre App hochladen, prüft die Play Console diese Metadaten, um Sie auf bekannte Probleme mit SDKs und Abhängigkeiten hinzuweisen, 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 der Release-App gespeichert. Wir empfehlen, diese Abhängigkeitsdatei beizubehalten, um eine sichere und positive Nutzererfahrung zu gewährleisten. Sie können diese Option 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 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 markiert.
• Die SDKs verstoßen gegen die Google Play-Richtlinien.
• Die SDKs weisen bekannte Sicherheitslücken auf.
• Die SDKs wurden von ihren Entwicklern eingestellt.

Die Warnungen sind ein Hinweis darauf, dass du diese Abhängigkeiten aktualisieren solltest, da du sonst in Zukunft möglicherweise keine Apps mehr in der Google Play Console veröffentlichen kannst.

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 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“ innerhalb der Namespace-Gruppe „com.example.android“ deklariert. Die Deklaration der Remote-Binärabhä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 namens „mylibrary“ deklariert. Dieser Name muss mit dem Bibliotheksnamen übereinstimmen, der in Ihrer settings.gradle.kts-Datei mit einem include: definiert ist. Wenn Sie Ihre App erstellen, kompiliert das Build-System das Bibliotheksmodul und verpackt die resultierenden kompilierten Inhalte 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, können Sie nur eine einzige Version des Plug-ins im Build-Klassenpfad für alle Module haben. Anstatt die Version in jedem Build-Skript des Moduls anzugeben, sollten Sie die Plug-in-Abhängigkeit im Stamm-Build-Skript mit der Version einfügen 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, es aber nicht im Stamm-Build zu verwenden. In der Regel ist das Stamm-Build-Script bis auf diesen plugins-Block 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'
}