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 bloqueslibrariesyplugins). - 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:
- Agrega la nueva entrada al catálogo.
- Sincroniza tu proyecto de Android.
- 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:
- El formato de archivo TOML del catálogo de versiones documentos opciones adicionales para configurar tu archivo de catálogo.
- Ahora en Android es nuestra app de ejemplo que usa catálogos de versiones.
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.