Migrar o build para catálogos de versões

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 e plugins).
• 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:

1. Adicionar a nova entrada ao catálogo.
2. Sincronizar seu projeto do Android.
3. 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:

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

}

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.

dependencies {
   implementation(libs.androidx.ktx)

}

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:

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

}

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

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

}

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.