Migrer votre build vers des catalogues de versions

Les catalogues de versions Gradle vous permettent d'ajouter et de gérer des dépendances et des plug-ins de manière évolutive. L'utilisation de catalogues de versions Gradle facilite la gestion des dépendances et des plug-ins lorsque vous avez plusieurs modules. Au lieu de coder en dur les noms et les versions des dépendances dans des fichiers de compilation individuels et de mettre à jour chaque entrée chaque fois que vous devez mettre à niveau une dépendance, vous pouvez créer un catalogue de versions central des dépendances que divers modules peuvent référencer de manière sécurisée avec l'assistance d'Android Studio.

Cette page fournit des informations de base sur la migration de votre application Android vers des catalogues de versions. Pour en savoir plus, consultez Ajoutez des dépendances de compilation et consultez la documentation Gradle.

Créer un fichier de catalogue de versions

Commencez par créer un fichier de catalogue de versions. Dans le dossier gradle de votre projet racine, créez un fichier nommé libs.versions.toml. Gradle recherche le catalogue dans le fichier libs.versions.toml par défaut. Nous vous recommandons donc d'utiliser ce nom par défaut.

Dans le fichier libs.versions.toml, ajoutez les sections suivantes :

[versions]

[libraries]

[plugins]

Elles seront utilisées comme suit :

  • Dans le bloc versions, définissez les variables contenant les versions de vos dépendances et plug-ins. Vous utiliserez ces variables dans les blocs suivants (blocs libraries et plugins).
  • Dans le bloc libraries, définissez vos dépendances.
  • Dans le bloc plugins, définissez vos plug-ins.

Procédure de migration

Nous vous recommandons de suivre les étapes dans l'ordre indiqué. Une compilation peut consommer simultanément des dépendances et des plug-ins de scripts et de catalogues de compilation. Par conséquent, prenez le temps de migrer vos dépendances et plug-ins individuellement.

Le processus de migration est le suivant :

  1. Ajoutez la nouvelle entrée au catalogue.
  2. Synchronisez votre projet Android.
  3. Remplacez la déclaration de chaîne précédente par l'accesseur sécurisé du catalogue.

Migrer les dépendances

Ajoutez une entrée pour chaque dépendance dans les sections versions et libraries du fichier libs.versions.toml. Synchronisez votre projet, puis remplacez leurs déclarations dans les fichiers de compilation par leur nom de catalogue.

Cet extrait de code affiche le fichier build.gradle.kts avant de supprimer la dépendance :

Kotlin

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

}

Groovy

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

}

Cet extrait de code montre comment définir la dépendance dans le fichier de catalogue de versions :

[versions]
ktx = "1.9.0"

[libraries]
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }

La dénomination recommandée pour le bloc de dépendances dans les catalogues est la casse kebab (par exemple, androidx-ktx) pour une meilleure assistance pour la saisie automatique de code dans vos fichiers de compilation.

Dans le fichier build.gradle.kts de chaque module qui nécessite une dépendance, définissez les dépendances à l'aide des noms que vous avez définis dans le fichier TOML.

Kotlin

dependencies {
   implementation(libs.androidx.ktx)

}

Groovy

dependencies {
   implementation libs.androidx.ktx

}

Migrer les plug-ins

Ajoutez une entrée pour chaque plug-in dans les sections "Versions" et "Plug-ins" du fichier libs.versions.toml. Synchronisez votre projet, puis remplacez leurs déclarations dans le le bloc plugins{} dans les fichiers de compilation par leur nom de catalogue.

Cet extrait de code affiche le fichier build.gradle.kts avant de supprimer le plug-in :

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'

}

Cet extrait de code montre comment définir le plug-in dans le fichier de catalogue des versions :

[versions]
androidGradlePlugin = "7.4.1"

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

Comme pour les dépendances, la mise en forme recommandée pour le catalogue de blocs plugins pour une meilleure qualité, saisissez android-application assistance pour la saisie automatique de code dans vos fichiers de compilation.

Le code suivant montre comment définir le plug-in com.android.application dans les fichiers build.gradle.kts du haut et au niveau du module. Utilisez alias pour les plug-ins provenant du fichier de catalogue des versions et id pour les plug-ins qui ne proviennent pas du fichier de catalogue de versions, comme les plug-ins de convention.

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

}

En savoir plus

Pour en savoir plus sur les autres options de configuration de votre catalogue de versions, consultez les ressources suivantes :

Problèmes connus

Les catalogues de versions Gradle sont toujours en cours de développement. Pour en savoir plus sur ce qui n'est pas encore pris en charge, consultez la section Limites et problèmes connus.