Os catálogos de versões do Gradle (link em inglês) permitem adicionar e manter dependências e plug-ins de maneira escalonável. O uso desses catálogos facilita o gerenciamento de dependências e plug-ins quando você tem vários módulos. Em vez de fixar no código os nomes e versões de dependência em arquivos de build individuais e atualizar cada entrada sempre que for necessário fazer upgrade de uma dependência, é possível criar um catálogo de versões central de dependências que vários módulos podem referenciar de maneira segura com a ajuda do Android Studio.
Esta página traz informações básicas sobre a migração do seu app Android para catálogos de versões. Para saber mais, consulte Adicione dependências de build e a documentação do Gradle.
Criar um arquivo de catálogo de versões
Comece criando um arquivo de catálogo de versões. Na pasta gradle
do projeto raiz,
crie um arquivo chamado libs.versions.toml
. O Gradle vai procurar o catálogo
no arquivo libs.versions.toml
por padrão (link em inglês).
Recomendamos usar esse nome.
No seu arquivo libs.versions.toml
, adicione estas seções:
[versions]
[libraries]
[plugins]
As seções são usadas desta forma:
- No bloco
versions
, defina variáveis que contêm as versões das suas dependências e plug-ins. Você vai usar essas variáveis nos blocos subsequentes (libraries
eplugins
). - No bloco
libraries
, defina suas dependências. - No bloco
plugins
, defina seus plug-ins.
Etapas da migração
Recomendamos que você siga as etapas na ordem listada. Um build pode consumir dependências e plug-ins de scripts e catálogos simultaneamente. Migre suas dependências e plug-ins um a um.
O processo de migração consiste em:
- Adicionar a nova entrada ao catálogo.
- Sincronizar seu projeto do Android.
- Substituir a declaração de string anterior pelo acessador com segurança de tipos de catálogo.
Migrar dependências
Adicione uma entrada para cada dependência nas seções versions
e libraries
do arquivo libs.versions.toml
. Sincronize o projeto e substitua as
declarações nos arquivos de build pelos nomes do catálogo.
O snippet de código abaixo mostra o arquivo build.gradle.kts
antes da remoção da
dependência:
Kotlin
dependencies { implementation("androidx.core:core-ktx:1.9.0") }
Groovy
dependencies { implementation 'androidx.core:core-ktx:1.9.0' }
O snippet de código abaixo mostra como definir a dependência no arquivo de catálogo de versões:
[versions]
ktx = "1.9.0"
[libraries]
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }
A nomenclatura recomendada para o bloco de dependências nos catálogos é o caso kebab (como
androidx-ktx
) para melhorar
assistência para preenchimento de código
nos arquivos de build.
No arquivo build.gradle.kts
de cada módulo que requer a dependência,
defina-as pelos nomes que você escolheu no arquivo TOML.
Kotlin
dependencies { implementation(libs.androidx.ktx) }
Groovy
dependencies { implementation libs.androidx.ktx }
Migrar plug-ins
Adicione uma entrada para cada plug-in nas seções de versões e de plug-ins do
arquivo libs.versions.toml
. Sincronize o projeto e substitua as
declarações no bloco plugins{}
dos arquivos de build pelos nomes do
catálogo.
O snippet de código abaixo mostra o arquivo build.gradle.kts
antes da remoção do
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' }
O snippet de código abaixo mostra como definir o plug-in no arquivo de catálogo de versões:
[versions]
androidGradlePlugin = "7.4.1"
[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }
Assim como nas dependências, a formatação recomendada para o catálogo de blocos plugins
entrada é kebab case (como android-application
) para melhor
assistência para preenchimento de código
nos arquivos de build.
O código abaixo mostra como definir o plug-in com.android.application
nos
arquivos build.gradle.kts
de nível superior e de módulo. Use alias
para plug-ins
que vêm do arquivo de catálogo de versões e id
para plug-ins que não vêm
desse arquivo, como
plug-ins de convenção (link em inglês).
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 }
Saiba mais
Para mais informações sobre outras opções de configuração do catálogo de versões, consulte estes recursos:
- O formato de arquivo TOML do catálogo de versões documenta opções adicionais para configurar seu arquivo de catálogo.
- O Now in Android (link em inglês) é nosso app de exemplo que usa catálogos de versões.
Problemas conhecidos
Os catálogos de versões do Gradle ainda estão em desenvolvimento. Para saber mais sobre o que ainda não está disponível, consulte os problemas e limitações conhecidos.