Build zu Versionskatalogen migrieren

Mit Gradle-Versionskatalogen können Sie Abhängigkeiten und Plug-ins auf skalierbare Weise hinzufügen und verwalten. Mit Gradle-Versionskatalogen lassen sich Abhängigkeiten und Plug-ins einfacher verwalten, wenn Sie mehrere Module haben. Anstatt Abhängigkeitsnamen und ‑versionen in einzelnen Build-Dateien fest zu codieren 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.

Auf dieser Seite finden Sie grundlegende Informationen zur Migration 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 im libs.versions.toml-Verzeichnis nach dem Katalog. Wir empfehlen daher, diesen Standardnamen zu verwenden.

Fügen Sie in Ihrer libs.versions.toml-Datei die folgenden Abschnitte hinzu:

[versions]

[libraries]

[plugins]

Die Abschnitte werden so verwendet:

  • Definieren Sie im Block versions Variablen, die die Versionen Ihrer Abhängigkeiten und Plug-ins enthalten. Sie verwenden diese Variablen in den nachfolgenden Blöcken (libraries- und plugins-Blöcke).
  • Definieren Sie im Block libraries Ihre Abhängigkeiten.
  • Definieren Sie Ihre Plug-ins im Block plugins.

Migrationsschritte

Wir empfehlen, die Schritte in der angegebenen Reihenfolge auszuführen. Bei einem Build können gleichzeitig Abhängigkeiten und Plug-ins aus Build-Skripts und Katalogen verwendet werden. Nehmen Sie sich also Zeit, um Ihre Abhängigkeiten und Plug-ins einzeln zu migrieren.

So läuft die Migration ab:

  1. Fügen Sie den neuen Eintrag dem Katalog hinzu.
  2. Synchronisieren Sie Ihr Android-Projekt.
  3. Ersetzen Sie die vorherige String-Deklaration durch den typsicheren Katalog-Accessor.

Abhängigkeiten migrieren

Fügen Sie für jede Abhängigkeit einen Eintrag in den Abschnitten versions und libraries der Datei libs.versions.toml hinzu. Synchronisieren Sie Ihr Projekt und ersetzen Sie dann die Deklarationen in den Build-Dateien durch die Katalognamen.

Dieses Code-Snippet zeigt die Datei build.gradle.kts vor dem Entfernen der Abhängigkeit:

Kotlin

dependencies {
    implementation("androidx.core:core-ktx:1.9.0")

}

Groovy

dependencies {
    implementation 'androidx.core:core-ktx:1.9.0'

}

In diesem Code-Snippet sehen Sie, 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" }

Für den Abhängigkeitsblock in Katalogen wird die Kebab-Schreibweise (z. B. androidx-ktx) empfohlen, um die automatische Vervollständigung in Ihren Build-Dateien zu verbessern.

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)

}

Groovy

dependencies {
   implementation libs.androidx.ktx

}

Plug-ins migrieren

Fügen Sie für jedes Plug-in in den Abschnitten „versions“ und „plugins“ der Datei libs.versions.toml einen Eintrag hinzu. Synchronisieren Sie Ihr Projekt und ersetzen Sie dann die Deklarationen im plugins{}-Block in den Build-Dateien durch die Katalognamen.

Dieses Code-Snippet zeigt die build.gradle.kts-Datei 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")

}

Groovy

// 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'

}

In diesem Code-Snippet sehen Sie, wie das Plugin in der Versionskatalogdatei definiert wird:

[versions]
androidGradlePlugin = "7.4.1"

[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }

Wie bei Abhängigkeiten wird für plugins-Blockkatalogeinträge das Kebab-Case-Format (z. B. android-application) empfohlen, um die Code-Vervollständigung in Ihren Build-Dateien zu verbessern.

Der folgende Code zeigt, wie das com.android.application-Plug-in in den Dateien build.gradle.kts auf oberster Ebene und auf Modulebene definiert wird. Verwenden Sie alias für Plug-ins aus der Versionskatalogdatei und id für Plug-ins, die nicht aus der Versionskatalogdatei stammen, z. B. Konventions-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)

}

Groovy

// Top-level build.gradle
plugins {
   alias libs.plugins.android.application apply false

}

// module build.gradle
plugins {
   alias libs.plugins.android.application

}

Weitere Informationen

Weitere Informationen zu zusätzlichen Optionen zum Konfigurieren Ihres Versionskatalogs finden Sie in den folgenden Ressourcen: