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 Cómo agregar 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:

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

}

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 asignación de nombres recomendada para el bloque de dependencias en catálogos es un caso de kebab (como androidx-ktx) a fin de mejorar la 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.

dependencies {
   implementation(libs.androidx.ktx)

}

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:

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

}

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 las entradas de catálogo de bloques plugins es el caso de los kebab (como android-application), que brinda una mejor asistencia para completar código en los 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.

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

}

Más información

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

• El formato de archivo TOML del catálogo de versiones documenta las opciones adicionales para configurar el archivo de catálogo.
• Ahora en Android es nuestra app de ejemplo que usa catálogos de versiones.

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