Easily use any BOM as a Gradle Version Catalog.
Compatibility
Gradle Version |
Plugin Version |
7.6.x |
1.x |
8.x |
1.x, 2.x, 3.x |
Quick Start
First, add your BOM dependencies to your version catalog
libs.versions.toml
[versions]
spring = "3.2.0"
aws = "2.22.0"
[libraries]
awsBom = { group = "software.amazon.awssdk", name = "bom", version.ref = "aws" }
springBootDependencies = { group = "org.springframework.boot", name = "spring-boot-dependencies", version.ref = "spring" }Then, add the plugin to your settings with the catalogs you want to generate
settings.gradle.kts
import dev.aga.gradle.versioncatalogs.Generator.generate
plugins {
id("dev.aga.gradle.version-catalog-generator") version("3.2.0")
}
dependencyResolutionManagement {
repositories {
mavenCentral() (1)
}
versionCatalogs {
generate("libs") { (2)
fromToml("springBootDependencies") { (3)
propertyOverrides = mapOf(
"jackson-bom.version" to "2.16.1", (4)
"mockito.version" to versionRef("mockito"), (5)
)
generateBomEntry = true (6)
}
}
generate("awsLibs") {
fromToml("awsBom") {
aliasPrefixGenerator = GeneratorConfig.NO_PREFIX (7)
}
}
generate("manyLibs") {
using { (8)
aliasPrefixGenerator = GeneratorConfig.NO_PREFIX
}
fromToml("aws-bom", "jackson-bom") { (9)
aliasSuffixGenerator = { prefix, groupId, artifactId -> (10)
val trimmed = artifactId.replaceFirst("junit-", "").replaceFirst("jackson-", "")
GeneratorConfig.DEFAULT_ALIAS_SUFFIX_GENERATOR(prefix, groupId, trimmed)
}
}
from("org.springframework.boot:spring-boot-dependencies:3.4.1") { (11)
aliasPrefixGenerator = GeneratorConfig.DEFAULT_ALIAS_PREFIX_GENERATOR (12)
}
}
}
}| 1 | Must include repositories here for dependency resolution to work from settings |
| 2 | The name of the generated catalog. If a catalog with that name already exists, the entries will be appended to it. Otherwise, a new catalog will be created. |
| 3 | The name of the bom library in the version catalog |
| 4 | Optionally override some version properties using a literal value |
| 5 | Or, you can reference version aliases in the source TOML |
| 6 | Optionally generate an entry in the catalog for the BOM itself |
| 7 | All dependencies in the AWS BOM are for AWS so we can skip the prefix |
| 8 | Set the default generation options that will apply to all sources unless overridden |
| 9 | Include all dependencies from both aws-bom and jackson-bom |
| 10 | Override the default aliasSuffixGenerator for dependencies in these two BOMs |
| 11 | Also include all dependencies from the spring-boot-dependencies BOM in the generated catalog |
| 12 | Override the default aliasPrefixGenerator for dependencies in the spring BOM |
Lastly, use the dependencies in your build
build.gradle.kts
dependencies {
implementation(awsLibs.s3)
implementation(awsLibs.dynamodb)
implementation(libs.spring.springBootStarterWeb)
implementation(libs.jackson.jacksonDatabind)
implementation(manyLibs.sts)
implementation(manyLibs.databind)
implementation(manyLibs.spring.springBootStarterJdbc)
}Detailed Usage
Applying the Plugin
settings.gradle.kts
import dev.aga.gradle.versioncatalogs.Generator.generate (1)
plugins {
id("dev.aga.gradle.version-catalog-generator") version "3.2.0"
}
dependencyResolutionManagement {
repositories { (2)
mavenCentral()
}
versionCatalogs {
generate("myLibs") {
// excluded for brevity
}
}
}| 1 | The extension function must be imported to allow the DSL to access the generate function.
Technically, the generate function can be placed anywhere in the settings script, but I like putting it inside the versionCatalogs block
since that’s also where you would put create statements. |
| 2 | In order for us to be able to resolve your BOM dependencies, you must specify the repositories in your settings file. When specifying repositories in settings you can (most of the time) remove the same declarations from your build file. According to the Gradle documentation, repositories declared in the build file will override whatever is declared in settings. |
settings.gradle
plugins {
id 'dev.aga.gradle.version-catalog-generator' version '3.2.0'
}
dependencyResolutionManagement {
repositories { (1)
mavenCentral()
}
versionCatalogs {
generator.generate("myLibs") { (2)
// excluded for brevity
}
}
}| 1 | In order for us to be able to resolve your BOM dependencies, you must specify the repositories in your settings file. When specifying repositories in settings you can (most of the time) remove the same declarations from your build file. According to the Gradle documentation, repositories declared in the build file will override whatever is declared in settings. |
| 2 | The generator extension should be available by default without an import |
| The import statement and repository declaration blocks may be excluded from future code samples for brevity. |
Dependency Sources
TOML
settings.gradle.kts
dependencyResolutionmanagement {
versionCatalogs {
generate("springLibs") {
defaultVersionCatalog = file("..") (1)
from {
toml {
libraryAliases = listOf("springBootDependencies") (2)
file = file("gradle/libs.versions.toml") (3)
}
}
}
generate("awsLibs") {
fromToml("awsBom") { (4)
// excluded for brevity (5)
}
}
generate("junitLibs") {
from {
toml {
libraryAliases = listOf("boms-junit5")
file = artifact("io.micronaut.platform:micronaut-platform:4.3.6") (6)
}
}
}
}
}| 1 | Optionally override the defaultVersionCatalog file. This defaults to gradle/libs.versions.toml relative to the root directory of the project if not otherwise specified.
This file will be used when the file for a TOML source is not specifically provided. |
| 2 | Required, the one or more aliases of BOMs to use from the TOML file |
| 3 | The TOML file to find the provided alias in. This only needs to be provided if not using the defaultVersionCatalog file |
| 4 | When using the default file, you can use the convenience function fromToml(..) and just provide the alias name(s) |
| 5 | Additional configuration options for the generated sources can be passed in a trailing lambda block |
| 6 | If your TOML is published to a repository, you can fetch it using the artifact function and standard string
notation. |
settings.gradle
dependencyResolutionmanagement {
versionCatalogs {
generator.generate("springLibs") {
it.defaultVersionCatalog = file("..") (1)
it.from { from ->
from.toml { toml ->
toml.libraryAliases = ["springBootDependencies"] (2)
toml.file = file("gradle/libs.versions.toml") (3)
}
}
}
generator.generate("awsLibs") {
it.fromToml("spring-boot-dependencies") (4)
}
generate("junitLibs") {
it.from { from ->
from.toml { toml ->
toml.libraryAliases = ["boms-junit5"]
toml.file = toml.artifact("io.micronaut.platform:micronaut-platform:4.3.6") (5)
}
}
}
}
}| 1 | Optionally override the defaultVersionCatalog file. This defaults to gradle/libs.versions.toml relative to the root directory of the project if not otherwise specified.
This file will be used when the file for a TOML source is not specifically provided. |
| 2 | Required, the one or more aliases of BOMs to use from the TOML file |
| 3 | The TOML file to find the provided alias in. This only needs to be provided if not using the defaultVersionCatalog file |
| 4 | When using the default file, you can use the convenience function fromToml(..) and just provide the alias name(s) |
| 5 | If your TOML is published to a repository, you can fetch it using the artifact function and standard string
notation. |
GitHub’s Dependabot only supports automatic updates in the default version catalog gradle/libs.versions.toml
|
String Notation
settings.gradle.kts
dependencyResolutionmanagement {
versionCatalogs {
generate("springLibs") {
from {
dependency("org.springframework.boot:spring-boot-dependencies:3.1.2") (1)
}
}
generate("awsLibs") {
from("software.amazon.awssdk:bom:2.25.6") { (2)
// excluded for brevity (3)
}
}
}
}| 1 | You can also use the standard string notation to specify your dependency |
| 2 | More conveniently, you can pass the string notation directly into from(). More than one dependency strings can be passed in. |
| 3 | Additional configuration options for the generated sources can be passed in a trailing lambda block |
settings.gradle
dependencyResolutionmanagement {
versionCatalogs {
generator.generate("springLibs") {
it.from { from ->
from.dependency("org.springframework.boot:spring-boot-dependencies:3.1.2") (1)
}
}
generator.generate("awsLibs") {
it.from("software.amazon.awssdk:bom:2.25.6") (2)
}
}
}| 1 | You can also use the standard string notation to specify your dependency |
| 2 | More conveniently, you can pass the string notation directly into from(). More than one dependency strings can be passed in. |
| Groovy is not my strong point so it’s likely that there is simpler / better syntax I’m not aware of. If you have any suggestions to improve the syntax in the documentation please open an issue or a PR. |
Combining Multiple Sources
Multiple sources from any combination of TOML files or string notation can be merged into a single generated catalog
settings.gradle.kts
dependencyResolutionmanagement {
versionCatalogs {
generate("manyLibs") {
using { (1)
// excluded for brevity
}
from {
toml {
libraryAliases = listOf("spring-boot-dependencies", "aws-bom") (2)
}
using { (3)
// excluded for brevity
}
}
from("org.junit.jupiter:junit-bom:5.11.4") (4)
}
}
}| 1 | Specify the default settings to use in all from declarations |
| 2 | Include all dependencies from spring-boot-dependencies and aws-bom which are declared in a TOML file |
| 3 | Override the default configuration options for just these two BOMs |
| 4 | Also include the dependencies from the JUnit BOM |
In the Kotlin DSL, when using the defaultVersionCatalog, the shorthand syntax fromToml("first-bom", "second-bom") { } can be used to declare the BOMs and customize the generation options.
|
settings.gradle
dependencyResolutionmanagement {
versionCatalogs {
geneartor.generate("manyLibs") {
it.using { (1)
// excluded for brevity
}
it.from { from ->
from.toml { toml ->
toml.libraryAliases = ["spring-boot-dependencies", "aws-bom"] (2)
}
from.using { (3)
// excluded for brevity
}
}
it.from("org.junit.jupiter:junit-bom:5.11.4") (4)
}
}
}| 1 | Specify the default settings to use in all from declarations |
| 2 | Include all dependencies from spring-boot-dependencies and aws-bom which are declared in a TOML file |
| 3 | Override the default configuration options for just these two BOMs |
| 4 | Also include the dependencies from the JUnit BOM |
Including a BOM Entry
Optionally, you can configure the generator to also generate an entry in the catalog for the BOM itself.
settings.gradle.kts
generate("springLibs") {
using {
generateBomEntry = true (1)
}
fromToml("springBootDependencies") {
generateBomEntry = false (2)
}
}| 1 | Set the default value of generateBomEntry to true to include an entry for the BOM in the generated catalog |
| 2 | Or set / override the value for just this from declaration |
settings.gradle
generator.generate("springLibs") {
it.generateBomEntry = true (1)
it.from { from ->
from.toml { toml ->
toml.libraryAliases = ["springBootDependencies"]
}
from.using { using ->
using.generateBomEntry = true (2)
}
}
}| 1 | Set the default value of generateBomEntry to true to include an entry for the BOM in the generated catalog |
| 2 | Or set / override the value for just this from declaration |
Entries for Nested BOMs
Optionally, you can configure the generator to not generate entries for BOMs that are found
within the parent BOM(s). For example, The spring boot dependencies BOM imports other BOMs
such as junit (junit-bom), jackson (jackson-bom) etc. By default, the generator will create entries for these just like any
other dependency.
settings.gradle.kts
generate("springLibs") {
using {
generateBomEntryForNestedBoms = true (1)
}
fromToml("springBootDependencies") {
generateBomEntryForNestedBoms = false (2)
}
}| 1 | Set the default value of generateBomEntryForNestedBoms to true to include an entry for BOMs that are imported by
the root-level BOMs |
| 2 | Or set / override the value for just this from declaration |
settings.gradle
generator.generate("springLibs") {
it.generateBomEntryForNestedBoms = true (1)
it.from { from ->
from.toml { toml ->
toml.libraryAliases = ["springBootDependencies"]
}
from.using { using ->
using.generateBomEntryForNestedBoms = true (2)
}
}
}| 1 | Set the default value of generateBomEntryForNestedBoms to true to include an entry for BOMs that are imported by
the root-level BOMs |
| 2 | Or set / override the value for just this from declaration |
Customizing Library Aliases
The aliases we generate for libraries discovered in the BOM are based on two separate components,
a prefix and a suffix. The prefix and suffix are separated by a hyphen to create the library’s alias.
If the prefix is blank, it will be ignored entirely.
Default Behavior
The default algorithm is as follows:
Prefix Generation
-
The
groupIdof the dependency is split by. -
If the split only returns a list of one item and the value is the string
bundles,plugins, orversions, anIllegalArgumentExceptionis thrown -
If the split returns a list of two or more items, and the last value is one of the invalid strings listed above, the last two items in the list are concatenated by a hyphen. The entirety of the string is the converted to camelCase
-
In any other scenario, the last item in the list is returned as-is
| Due to the popularity of many packages that may not necessarily fit our algorithm, a number of special cases have been added to simplify their generated prefixes. Please refer to the below table for the hardcoded aliases we have set up. If you do not wish to use the aliases, you will need to provide your own prefix generation function. |
| Condition | Value | Generated Prefix |
|---|---|---|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Group begins with |
|
|
Suffix Generation
-
Replace any
.or_character in theartifactIdof the dependency with a- -
Convert the resulting string to camelCase
Examples
-
org.springframework.boot:spring-boot-starter-web→spring-springBootStarterWeb -
com.fasterxml.jackson.core:jackson-databind→jackson-jacksonDatabind -
com.fasterxml.jackson.datatype:jackson-datatype-jsr310→jackson-jacksonDatatypeJsr310 -
software.amazon.awssdk:s3→awssdk-s3 -
org.hibernate.orm:hibernate-core→orm.hibernateCore
In some cases our default logic may not be sufficient and it may attempt to store two dependencies with the same
alias. If this happens, an exception will be thrown pointing to the errant dependencies and you will either need to
exclude one or more of the conflicting dependencies, or override the default behavior. spring-boot-dependencies in the 2.7.x
version range is known to cause problems due to conflicting entries of ehcache. See #100
|
Customizing Prefix Generation
The prefix generation logic can be modified by overriding the property aliasPrefixGenerator in GeneratorConfig
settings.gradle.kts
generate("myLibs") {
// excluded for brevity
using { (1)
aliasPrefixGenerator = { groupId, artifactId ->
if(groupId == "some.group") {
"somegroup"
} else {
GeneratorConfig.DEFAULT_ALIAS_PREFIX_GENERATOR(groupId, artifactId) (2)
}
}
}
from {
// excluded for brevity
using {
aliasPrefixGenerator = GeneratorConfig.DEFAULT_ALIAS_PREFIX_GENERATOR (3)
}
}
}| 1 | Set the default aliasPrefixGenerator for all from blocks |
| 2 | We can always fall back to the default logic if our condition isn’t met |
| 3 | Set/override the aliasPrefixGenerator for just this from block |
settings.gradle
generator.generate("myLibs") {
// excluded for brevity
it.using { using -> (1)
using.aliasPrefixGenerator = { groupId, artifactId ->
if(groupId == "some.group") {
"somegroup"
} else {
DEFAULT_ALIAS_PREFIX_GENERATOR.invoke(groupId, artifactId) (2)
}
}
}
it.from { from ->
// excluded for brevity
from.using { using ->
using.aliasPrefixGenerator = DEFAULT_ALIAS_PREFIX_GENERATOR (3)
}
}
}| 1 | Set the default aliasPrefixGenerator for all from blocks |
| 2 | We can always fall back to the default logic if our condition isn’t met |
| 3 | Set/override the aliasPrefixGenerator for just this from block |
Skipping Prefix Generation Entirely
In some BOMs which only contain their own dependencies, for example the AWS BOM, the inclusion of the prefix may not be useful and instead you may want to skip the prefix entirely. A convenience function is provided to do so.
settings.gradle.kts
generate("awsLibs") {
fromToml("awsBom") {
aliasPrefixGenerator = GeneratorConfig.NO_PREFIX (1)
}
}| 1 | The resulting generated alias for software.amazon.awssdk:s3 would just be s3. When accessing this library
in our build file, the accessor would subsequently be awsLibs.s3 instead of awsLibs.awssdk.s3 |
settings.gradle
generator.generate("awsLibs") {
it.fromToml("awsBom")
it.using { using ->
using.aliasPrefixGenerator = NO_PREFIX (1)
}
}| 1 | The resulting generated alias for software.amazon.awssdk:s3 would just be s3. When accessing this library
in our build file, the accessor would subsequently be awsLibs.s3 instead of awsLibs.awssdk.s3 |
Customizing Suffix Generation
The suffix generation logic can be modified by overriding the property aliasSuffixGenerator in GeneratorConfig
settings.gradle.kts
generate("myLibs") {
// excluded for brevity
using { (1)
aliasSuffixGenerator = { prefix, groupId, artifactId -> (2)
val suffix = GeneratorConfig.DEFAULT_ALIAS_SUFFIX_GENERATOR(groupId, artifactId) (3)
if(prefix == "spring") {
suffix.replaceFirst("spring","") (4)
} else {
suffix
}
}
}
from {
// excluded for brevity
using {
aliasSuffixGenerator = GeneratorConfig.DEFAULT_ALIAS_SUFFIX_GENERATOR (5)
}
}
}| 1 | Set the default aliasSuffixGenerator for all from blocks |
| 2 | The prefix argument refers to the generated prefix value for the dependency |
| 3 | The default logic can always be accessed through GeneratorConfig.DEFAULT_ALIAS_SUFFIX_GENERATOR |
| 4 | In this example we are extending the default behavior to remove the "duplicate" appearance of the word spring.
For example, instead of spring-springBootStarterWeb, we would generate spring-bootStarterWeb |
| 5 | Set/override the aliasSuffixGenerator for just this from block |
settings.gradle
generator.generate("myLibs") {
// excluded for brevity
it.using { using -> (1)
using.aliasSuffixGenerator = { prefix, groupId, artifactId -> (2)
def suffix = DEFAULT_ALIAS_SUFFIX_GENERATOR.invoke(groupId, artifactId) (3)
if(prefix == "spring") {
suffix.replaceFirst("spring","") (4)
} else {
suffix
}
}
}
it.from { from ->
from.using { using ->
using.aliasSuffixGenerator = DEFAULT_ALIAS_SUFFIX_GENERATOR (5)
}
}
}| 1 | Set the default aliasSuffixGenerator for all from blocks |
| 2 | The prefix argument refers to the generated prefix value for the dependency |
| 3 | The default logic can always be accessed through DEFAULT_ALIAS_SUFFIX_GENERATOR |
| 4 | In this example we are extending the default behavior to remove the "duplicate" appearance of the word spring.
For example, instead of spring-springBootStarterWeb, we would generate spring-bootStarterWeb |
| 5 | Set/override the aliasSuffixGenerator for just this from block |
Customizing Version Aliases
If any dependencies in the source BOM specify a dependency’s version via a property, we will create a version alias in the generated catalog for that behavior.
Default Behavior
The default algorithm to generate a version alias from a property is:
-
Replace all case-insensitive instances of the literal string
versionwith an empty string -
All instances of two or more consecutive periods are replaced with a single period
-
Any leading or trailing periods are trimmed
-
All periods are replaced with a hyphen
-
The entire string is converted to camelCase
Examples
-
jackson.version→jackson -
version.jackson→jackson -
jackson.modules.version→jacksonModules
Customizing Version Aliases
The version alias generation logic can be customized by overriding the property versionNameGenerator in GeneratorConfig
settings.gradle.kts
generate("myLibs") {
// excluded for brevity
using { (1)
versionNameGenerator = { propertyName -> (2)
if(propertyName == "somethingWeird") {
"notAsWeird"
} else {
GeneratorConfig.DEFAULT_VERSION_NAME_GENERATOR(propertyName) (3)
}
}
}
from {
// excluded for brevity
using {
versionNameGenerator = GeneratorConfig.DEFAULT_VERSION_NAME_GENERATOR (4)
}
}
}| 1 | Set the default versionNameGenerator for all from blocks |
| 2 | The property name from the maven POM, i.e. jackson.version |
| 3 | The default logic can always be accessed through GeneratorConfig.DEFAULT_VERSION_NAME_GENERATOR |
| 4 | Set/override the versionNameGenerator for just this from block |
settings.gradle
generator.generate("myLibs") {
// excluded for brevity
it.using { using -> (1)
using.versionNameGenerator = { propertyName -> (2)
if(propertyName == "somethingWeird") {
"notAsWeird"
} else {
DEFAULT_VERSION_NAME_GENERATOR.invoke(propertyName) (3)
}
}
}
it.from { from ->
// excluded for brevity
from.using { using ->
using.versionNameGenerator = DEFAULT_VERSION_NAME_GENERATOR (4)
}
}
}| 1 | Set the default versionNameGenerator for all from blocks |
| 2 | The property name from the maven POM, i.e. jackson.version |
| 3 | The default logic can always be accessed through DEFAULT_VERSION_NAME_GENERATOR |
| 4 | Set/override the versionNameGenerator for just this from block |
Customizing Bundle Generation
In addition to generating libraries, you can also customize how bundles are generated by providing a custom function
to the GeneratorConfig. The mapping is run after all libraries have been generated for the entire catalog. The default
behavior is to map a dependency to a bundle if and only if the version for that dependency is a versionRef, and the
the name of the bundle will be the versionRef itself.
settings.gradle.kts
generator.generate("myLibs") {
bundleMapping = {
if(it.group.contains("junit")) {
"junit" (1)
} else {
null (2)
}
}
}| 1 | Map all dependencies with a group containing junit into a bundle called junit |
| 2 | Dependencies mapped to null or a blank string will be ignored |
settings.gradle
generator.generate("myLibs") {
it.bundleMapping = { lib ->
if(lib.group.contains("junit")) {
"junit" (1)
} else {
null (2)
}
}
}| 1 | You will have to add an import for net.pearx.kasechange.CaseFormat into the build file. The dependency is already available for use when you apply the plugin |
Case Conversion
For converting between different text cases, for example lower-hyphen to lower-camel, you can use the convenience
function caseChange
settings.gradle.kts
aliasSuffixGenerator = { _, _, artifactId ->
GeneratorConfig.caseChange(artifactId, CaseFormat.LOWER_HYPEN, CaseFormat.CAMEL) (1)
}| 1 | You will have to add an import for net.pearx.kasechange.CaseFormat into the build file. The dependency is already available for use when you apply the plugin |
settings.gradle
using.aliasSuffixGenerator = { _, _, artifactId ->
caseChange(artifactId, CaseFormat.LOWER_HYPEN, CaseFormat.CAMEL) (1)
}| 1 | You will have to add an import for net.pearx.kasechange.CaseFormat into the build file. The dependency is already available for use when you apply the plugin |
Overriding Versions
In some cases you may want to override the version specified by the BOM you are generating the catalog from. At the current point in time, this is only possible if the BOM uses a property to specify the version[1]
settings.gradle.kts
generate("myLibs") {
// excluded for brevity
using { (1)
propertyOverrides = mapOf(
"jackson.version" to "2.16.1", (2)
"aws.version" to versionRef("aws") (3)
)
}
val someFile = file("/path/to/libs.versions.toml")
from {
toml {
libraryAliases = listOf("some-bom")
file = someFile
}
using { (4)
propertyOverrides = mapOf(
"jackson.version" to versionRef("jackson") (5)
)
}
}
from {
// excluded for brevity
using {
propertyOverrides = mapOf(
"jackson.version" to someFile.versionRef("jackson"), (6)
"aws.version" to defaultVersionCatalog.versionRef("aws") (7)
)
}
}
}| 1 | Set the default overrides which will be used in all from blocks unless overridden |
| 2 | Specify a string version to use in place of all occurrences of jackson.version when processing the BOM |
| 3 | Specify an existing version alias from your defaultVersionCatalog file. The version alias being
referenced must exist in TOML file. |
| 4 | Override the default propertyOverrides for this from block` |
| 5 | Use a versionRef from the TOML file declared in the toml block above |
| 6 | Use a versionRef from an arbitrary File declared in a variable. Must import the extension function dev.aga.gradle.versioncatalogs.versionRef |
| 7 | Using same extension function as above, the defaultVersionCatalog can always be referenced for a versionRef lookup |
settings.gradle
generator.generate("myLibs") {
// excluded for brevity
it.using { using -> (1)
using.propertyOverrides = [
"jackson.version": "2.16.1", (2)
"aws.version": it.versionRef("aws") (3)
]
}
it.from { from ->
from.toml { toml ->
toml.libraryAliases = listOf("some-bom")
toml.file = file("/path/to/libs.versions.toml")
}
from.using { using -> (4)
using.propertyOverrides = [
"jackson.version": using.versionRef("jackson") (5)
]
}
}
}| 1 | Set the default overrides which will be used in all from blocks unless overridden |
| 2 | Specify a string version to use in place of all occurrences of jackson.version when processing the BOM |
| 3 | Specify an existing version alias from your defaultVersionCatalog file. The version alias being
referenced must exist in TOML file. |
| 4 | Override the default propertyOverrides for this from block` |
| 5 | Use a versionRef from the TOML file declared in the toml block above |
You can use the extension function dev.aga.gradle.versioncatalogs.versionRef to fetch a versionRef from any File outside of the current scope.
|
Filtering Dependencies
If you want to exclude certain dependencies from having entries generated for them in your catalog, you can filter
dependencies either by groupId or by name (artifactId)
Filtering By GroupId
settings.gradle.kts
generate("myLibs") {
// excluded for brevity
using { (1)
excludeGroups = ".*spring.*" (2)
}
from {
// excluded for brevity
using { (3)
excludeGroups = "..." // excluded for brevity
}
}
}| 1 | Set the default excludeGroups for all from blocks |
| 2 | Exclude all dependencies that have "spring" in their groupId |
| 3 | Set/override the excludeGroups for just this from block |
settings.gradle
generator.generate("myLibs") {
// excluded for brevity
it.using { using -> (1)
using.excludeGroups = ".*spring.*" (2)
}
it.from { from ->
// excluded for brevity
from.using { using -> (3)
using.excludeGroups = "..." // excluded for brevity
}
}
}| 1 | Set the default excludeGroups for all from blocks |
| 2 | Exclude all dependencies that have "spring" in their groupId |
| 3 | Set/override the excludeGroups for just this from block |
Filtering By Name
settings.gradle.kts
generate("myLibs") {
// excluded for brevity
using { (1)
excludeNames = ".*hibernate.*" (2)
}
from {
// excluded for brevity
using { (3)
excludeNames = "..." // excluded for brevity
}
}
}| 1 | Set the default excludeNames for all from blocks |
| 2 | Exclude all dependencies that have "hibernate" in their name/artifactId |
| 3 | Set/override the excludeNames for just this from block |
settings.gradle
generator.generate("myLibs") {
// excluded for brevity
it.using { using -> (1)
using.excludeNames = ".*hibernate.*" (2)
}
it.from { from ->
// excluded for brevity
from.using { using -> (3)
using.excludeNames = "..."
}
}
}| 1 | Set the default excludeNames for all from blocks |
| 2 | Exclude all dependencies that have "hibernate" in their name/artifactId |
| 3 | Set/override the excludeNames for just this from block |
Persisting
Unfortunately, settings plugins in Gradle cannot take advantage of the same caching mechanisms that are provided for tasks with incremental builds. However, we have added the ability to save the generated TOML catalog to a file so that you can verify the contents of the generated catalog.
settings.gradle.kts
generate("myLibs") {
// excluded for brevity
saveGeneratedCatalog = true (1)
saveDirectory = file("build/version-catalogs") (2)
}| 1 | Enable saving the generated catalog to disk |
| 2 | The directory to save the generated catalogs in. If not specified, the generated catalogs will be saved in
build/version-catalogs, relative to the root project directory. |
settings.gradle
generator.generate("myLibs") {
// excluded for brevity
it.saveGeneratedCatalog = true (1)
it.saveDirectory = file("build/version-catalogs") (2)
}| 1 | Enable saving the generated catalog to disk |
| 2 | The directory to save the generated catalogs in. If not specified, the generated catalogs will be saved in
build/version-catalogs, relative to the root project directory. |
Build File
settings.gradle.kts
dependencies {
implementation(springLibs.spring.springBootStarterWeb) (1)
}| 1 | When using the libraries from your generated catalog, each - in the generated alias is replaced with a . |
settings.gradle
dependencies {
implementation springLibs.spring.springBootStarterWeb (1)
}| 1 | When using the libraries from your generated catalog, each - in the generated alias is replaced with a . |
The generated catalog won’t be immediately available (same as adding a new entry to your libs.versions.toml file).
You will need to evaluate the settings through another gradle task (i.e. assemble) to trigger the catalog generation.
|
Project Goals
-
Compatible with Dependabot
-
Nested BOM support (i.e.
spring-boot-dependencesimportsmockito-bom, etc) -
Easy to override versions (similar to
ext["version.property"] = …in Spring Boot Dependencies plugin)