Build zu Versionskatalogen migrieren

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öcken libraries und plugins).
• 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:

1. Fügen Sie den neuen Eintrag dem Katalog hinzu.
2. Synchronisieren Sie Ihr Android-Projekt.
3. 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:

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

}

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.

dependencies {
   implementation(libs.androidx.ktx)

}

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:

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

}

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

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

}

// module build.gradle.kts
plugins {
   alias(libs.plugins.android.application)

}

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