Artigo 5: A Aventura do libs.versions.toml Compartilhado
Publié le 27 September 2025
Introdução
Em nossa busca para criar o plugin`site-baker`, tentamos manter uma base de código limpa e centralizada. Uma das melhores práticas no ecossistema Gradle moderno é o uso docatálogo de versões(U+200B(U+200B`translate`)(fr)libs.versions.toml) para gerenciar as dependências. Mas o que acontece quando seu projeto se torna mais complexo, como umconstruir compostoOnde um build independente (nosso plugin) deve ser incluído em outro?
Foi ali que nossa aventura tomou um rumo inesperado. Nós queríamos que nosso plugin`site-baker`, que é ele próprio um projeto Gradle, utiliza o mesmo catálogo de versões do nosso projeto principal. Este artigo, o quinto da nossa série, conta como resolvemos esse desafio.
1. O Catálogo de Versões (libs.versions.toml) : Um lembrete
O arquivo`gradle/libs.versions.toml`é uma funcionalidade do Gradle que permite centralizar as versões e as coordenadas das dependências do seu projeto. É geralmente estruturado em quatro seções:
-
[versions]: Define alias para os números de versão (ex:`kotlin = "1.9.20"`). -
[libraries]: Define alias para as dependências completas, usando as versões definidas acima (ex:`kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }`). -
[bundles]: Agrupa várias bibliotecas sob um único alias (ex:`jackson = ["jackson-core", "jackson-databind"]`) -
[plugins]: Define aliases para os plugins Gradle.
Uma vez definido, o Gradle gera automaticamente acessores tipados, o que deixa seu`build.gradle.kts`muito mais legível :
dependencies {
// Au lieu de : implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.20")
implementation(libs.kotlin.stdlib)
}
2. O Problema: um Build composto e dois mundos separados
A nossa estrutura de projeto é umconstruir composto. O projeto principal (thymeleaf.cheroliv.com) inclui o projeto do plugin (site-baker) via o comando`includeBuild("site-baker")no arquivo`settings.gradle.kts.
O problema é que, por padrão, um build incluído é ummundo separado. Ele tem sua própria configuração, seu próprio ciclo de vida e ele não vê o arquivo`libs.versions.toml`do build principal. Nosso`plugin/build.gradle.kts`tentava usar`libs.plugins.kotlin.jvm`, mas o objeto`libs`não estava sendo gerado a partir do arquivo TOML correto, provocando erros de build.
3. A Solução: Compartilhar a Resolução de Dependências
Após várias pesquisas, a solução se revelou ser uma funcionalidade do Gradle projetada precisamente para este caso:`dependencyResolutionManagement`.
No arquivo`settings.gradle.kts` du construir incluido(site-baker/settings.gradle.kts), podemos dizer ao Gradle onde encontrar o catálogo de versões a ser usado.
Aqui está a configuração que adicionamos a`site-baker/settings.gradle.kts`(No output, as the input text to translate is empty.)
// site-baker/settings.gradle.kts
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
gradlePluginPortal()
mavenCentral()
}
versionCatalogs {
create("libs") {
from(files("../gradle/libs.versions.toml"))
}
}
}
rootProject.name = "site-baker"
include("plugin")Analisemos a parte crucial :
versionCatalogs {
create("libs") { // Crée un catalogue nommé 'libs'
from(files("../gradle/libs.versions.toml")) // En utilisant ce fichier
}
}-
create("libs"): Declaramos um catálogo de versões que será acessível através do alias`libs`. -
from(files("../gradle/libs.versions.toml")): É a mágia. Dizemos ao Gradle que a fonte deste catálogo é o arquivo TOML localizado no diretório`gradle` du projeto pai(../).
Com esta configuração, o build`site-baker`sabe agora que ele deve usar o catálogo de versões do projeto principal. O objeto`libs`é gerado corretamente, e as dependências são resolvidas como previsto.
4. Conclusão: A Potência dos Builds Compostos Bem Gerenciados
Esta experiência foi rica em lições. O catálogo de versões é uma ferramenta fantástica para a manutenibilidade, mas o seu comportamento em cenários de compilações compostas nem sempre é intuitivo.
A chave é lembrar que um build incluído continua sendo um build independente. Para compartilhar configurações como o catálogo de versões, é necessário usar os mecanismos explícitos fornecidos pelo Gradle, como o bloco`dependencyResolutionManagement`dentro de`settings.gradle.kts`.
Ao resolver esse problema, não apenas deixamos nosso build mais limpo, mas também reforçamos a consistência de nosso projeto, garantindo que o plugin e o projeto principal compartilhem uma única fonte de verdade para suas dependências.
No próximo artigo, continuaremos a enriquecer nosso plugin adicionando tarefas mais complexas, agora que nossa gestão de dependências é sólida e centralizada.