Mit Gradle-Versionskatalogen können Sie Abhängigkeiten und Plug-ins auf skalierbare Weise hinzufügen und verwalten. Die Verwendung von Gradle-Versionskatalogen erleichtert die Verwaltung von Abhängigkeiten und Plug-ins, wenn Sie mehrere Module verwenden. Anstatt Abhängigkeitsnamen und -versionen in einzelnen Build-Dateien hartzucodieren und jeden Eintrag zu aktualisieren, wenn Sie eine Abhängigkeit aktualisieren müssen, können Sie einen zentralen Versionskatalog mit Abhängigkeiten erstellen, auf den verschiedene Module mit Unterstützung von Android Studio typsicher verweisen können.
Diese Seite enthält grundlegende Informationen zum Migrieren Ihrer Android-App zu Versionskatalogen. Weitere Informationen finden Sie unter Build-Abhängigkeiten hinzufügen und in der Gradle-Dokumentation.
Versionskatalogdatei erstellen
Erstellen Sie zuerst eine Versionskatalogdatei. Erstellen Sie im Ordner gradle
Ihres Stammprojekts eine Datei mit dem Namen libs.versions.toml
. Gradle sucht standardmäßig in der Datei libs.versions.toml
nach dem Katalog. Daher empfehlen wir die Verwendung dieses Standardnamens.
Fügen Sie der Datei libs.versions.toml
diese Abschnitte hinzu:
[versions]
[libraries]
[plugins]
Die Abschnitte werden wie folgt verwendet:
- Definieren Sie im
versions
-Block Variablen für die Versionen Ihrer Abhängigkeiten und Plug-ins. Sie verwenden diese Variablen in den nachfolgenden Blöcken (in den Blöckenlibraries
undplugins
). - Definieren Sie im
libraries
-Block die Abhängigkeiten. - Definieren Sie Ihre Plug-ins im
plugins
-Block.
Migrationsschritte
Wir empfehlen, die Schritte in der aufgeführten Reihenfolge auszuführen. Ein Build kann Abhängigkeiten und Plug-ins aus Build-Skripts und Katalogen gleichzeitig verarbeiten. Nehmen Sie sich also Zeit, um Ihre Abhängigkeiten und Plug-ins einzeln zu migrieren.
Der Migrationsprozess läuft so ab:
- Fügen Sie den neuen Eintrag dem Katalog hinzu.
- Synchronisieren Sie Ihr Android-Projekt.
- Ersetzen Sie die vorherige Stringdeklaration durch die katalogtypsichere Zugriffsfunktion.
Abhängigkeiten migrieren
Fügen Sie für jede Abhängigkeit in den Abschnitten versions
und libraries
der Datei libs.versions.toml
einen Eintrag hinzu. Synchronisieren Sie Ihr Projekt und ersetzen Sie dann die Deklarierungen in den Build-Dateien durch die jeweiligen Katalognamen.
Dieses Code-Snippet zeigt die Datei build.gradle.kts
, bevor die Abhängigkeit entfernt wird:
Kotlin
dependencies { implementation("androidx.core:core-ktx:1.9.0") }
Groovig
dependencies { implementation 'androidx.core:core-ktx:1.9.0' }
Dieses Code-Snippet zeigt, wie die Abhängigkeit in der Versionskatalogdatei definiert wird:
[versions]
ktx = "1.9.0"
[libraries]
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }
Zur besseren Unterstützung bei der Codevervollständigung in Ihren Build-Dateien wird die Benennung eines Abhängigkeitsblocks in Katalogen empfohlen (z. B. nach androidx-ktx
).
Definieren Sie in der Datei build.gradle.kts
jedes Moduls, das die Abhängigkeit erfordert, die Abhängigkeiten anhand der Namen, die Sie in der TOML-Datei definiert haben.
Kotlin
dependencies { implementation(libs.androidx.ktx) }
Groovig
dependencies { implementation libs.androidx.ktx }
Plug-ins migrieren
Fügen Sie für jedes Plug-in in der Datei libs.versions.toml
sowohl im Abschnitt „Versionen“ als auch im Abschnitt „Plug-ins“ einen Eintrag hinzu. Synchronisieren Sie Ihr Projekt und ersetzen Sie dann deren Deklarierungen im Block plugins{}
in den Build-Dateien durch die jeweiligen Katalognamen.
Dieses Code-Snippet zeigt die Datei build.gradle.kts
vor dem Entfernen des Plug-ins:
Kotlin
// Top-level `build.gradle.kts` file plugins { id("com.android.application") version "7.4.1" apply false } // Module-level `build.gradle.kts` file plugins { id("com.android.application") }
Groovig
// Top-level `build.gradle` file plugins { id 'com.android.application' version '7.4.1' apply false } // Module-level `build.gradle` file plugins { id 'com.android.application' }
Dieses Code-Snippet zeigt, wie das Plug-in in der Versionskatalogdatei definiert wird:
[versions]
androidGradlePlugin = "7.4.1"
[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }
Genau wie bei Abhängigkeiten wird für plugins
-Blockkatalogeinträge die Formatierung gemäß der Schreibweise von Kebab empfohlen (z. B. android-application
), um die Unterstützung bei der Codevervollständigung in Ihren Build-Dateien zu verbessern.
Der folgende Code zeigt, wie das Plug-in com.android.application
in den build.gradle.kts
-Dateien auf der obersten und Modulebene definiert wird. Verwenden Sie alias
für Plug-ins, die aus der Versionskatalogdatei stammen, und id
für Plug-ins, die nicht aus der Versionskatalogdatei stammen, z. B. Konventionen-Plug-ins.
Kotlin
// Top-level build.gradle.kts plugins { alias(libs.plugins.android.application) apply false } // module build.gradle.kts plugins { alias(libs.plugins.android.application) }
Groovig
// Top-level build.gradle plugins { alias libs.plugins.android.application apply false } // module build.gradle plugins { alias libs.plugins.android.application }
Weitere Informationen
Informationen zu zusätzlichen Optionen zum Konfigurieren des Versionskatalogs finden Sie in den folgenden Ressourcen:
- Im TOML-Dateiformat des Versionskatalogs finden Sie weitere Optionen zum Konfigurieren Ihrer Katalogdatei.
- Jetzt in Android ist unsere Beispiel-App, die Versionskataloge verwendet.
Bekannte Probleme
Die Gradle-Versionskataloge befinden sich noch in der aktiven Entwicklung. Weitere Informationen dazu, was noch nicht unterstützt wird, finden Sie unter Bekannte Probleme und Einschränkungen.