Cómo migrar tu compilación a catálogos de versiones

Los catálogos de versiones de Gradle te permiten agregar y mantener dependencias y complementos de forma escalable. El uso de catálogos de versión de Gradle facilita la administración de dependencias y complementos cuando tienes varios módulos. En lugar de codificar los nombres y las versiones de las dependencias en los archivos de compilación individuales y actualizar cada entrada cada vez que necesites actualizar una dependencia, puedes crear un catálogo de versiones central de las dependencias que tengan los módulos pueden hacer referencia a tipos seguros con la asistencia de Android Studio.

En esta página, se proporciona información básica sobre la migración de tu app para Android a catálogos de versiones. Para obtener más información, consulta Agrega dependencias de compilación y la documentación de Gradle.

Crea un archivo de catálogo de versiones

Para comenzar, crea un archivo de catálogo de versiones. En la carpeta gradle de tu proyecto raíz, crea un archivo llamado libs.versions.toml. Gradle busca el catálogo en el archivo libs.versions.toml de forma predeterminada, por lo que te recomendamos que uses este nombre predeterminado.

En el archivo libs.versions.toml, agrega las siguientes secciones:

[versions]

[libraries]

[plugins]

Las secciones se utilizan de la siguiente manera:

  • En el bloque versions, define las variables que contienen las versiones de las dependencias y los complementos. Usarás estas variables en los bloques posteriores (los bloques libraries y plugins).
  • En el bloque libraries, define tus dependencias.
  • En el bloque plugins, define los complementos.

Pasos de la migración

Te recomendamos que sigas los pasos en el orden indicado. Una compilación puede consumir dependencias y complementos de secuencias de comandos de compilación y catálogos de forma simultánea, por lo que debes tomarte el tiempo necesario para migrar tus dependencias y complementos de forma individual.

El proceso de migración es el siguiente:

  1. Agrega la nueva entrada al catálogo.
  2. Sincroniza tu proyecto de Android.
  3. Reemplaza la declaración de string anterior por el descriptor de acceso de tipo seguro del catálogo.

Migra las dependencias

Agrega una entrada para cada dependencia en las secciones versions y libraries del archivo libs.versions.toml. Sincroniza tu proyecto y, luego, reemplaza las declaraciones en los archivos de compilación por sus nombres de catálogo.

En este fragmento de código, se muestra el archivo build.gradle.kts antes de quitar la dependencia:

Kotlin

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

}

Groovy

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

}

En este fragmento de código, se muestra cómo definir la dependencia en el archivo de catálogo de versiones:

[versions]
ktx = "1.9.0"

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

La denominación recomendada para el bloque de dependencias en los catálogos es la función de kebab (como androidx-ktx) para mejorar. asistencia para completar código en tus archivos de compilación.

En el archivo build.gradle.kts de cada módulo que requiere la dependencia, define las dependencias mediante los nombres que definiste en el archivo TOML.

Kotlin

dependencies {
   implementation(libs.androidx.ktx)

}

Groovy

dependencies {
   implementation libs.androidx.ktx

}

Migra los complementos

Agrega una entrada para cada complemento en las secciones de las versiones y de los complementos del archivo libs.versions.toml. Sincroniza tu proyecto y, luego, reemplaza las declaraciones en el bloque plugins{} de los archivos de compilación por sus nombres de catálogo.

En este fragmento de código, se muestra el archivo build.gradle.kts antes de quitar el complemento:

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'

}

En este fragmento de código, se muestra cómo definir el complemento en el archivo de catálogo de versiones:

[versions]
androidGradlePlugin = "7.4.1"

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

Al igual que con las dependencias, el formato recomendado para el catálogo de bloques plugins es kebab case (como android-application) para mejorar asistencia para completar código en tus archivos de compilación.

En el siguiente código, se muestra cómo definir el complemento com.android.application en los archivos build.gradle.kts de nivel superior y de módulo. Usa alias para complementos que provienen del archivo del catálogo de versiones y id para complementos que no provienen del archivo del catálogo de versiones, como complementos de convención.

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

}

Más información

Si quieres obtener información sobre las opciones adicionales para configurar el catálogo de versiones, consulta los siguientes recursos:

Problemas conocidos

Los catálogos de versiones de Gradle aún están en desarrollo activo. Para obtener más información sobre los aspectos que aún no se admiten, consulta los problemas y limitaciones conocidos.