Version Catalog Generator Plugin

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

9.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.4.0")
}

dependencyResolutionManagement {
  repositories {
    mavenCentral() (1)
  }
  versionCatalogs {
    create("libs") { (2)
      from(files("gradle/libs.versions.toml"))
    }
    generate("libs") { (3)
      fromToml("springBootDependencies") { (4)
        propertyOverrides = mapOf(
          "jackson-bom.version" to "2.16.1", (5)
          "mockito.version" to versionRef("mockito"), (6)
        )
        generateBomEntry = true (7)
      }
    }
    generate("awsLibs") {
      fromToml("awsBom") {
        aliasPrefixGenerator = GeneratorConfig.NO_PREFIX (8)
      }
    }
    generate("manyLibs") {
      using { (9)
        aliasPrefixGenerator = GeneratorConfig.NO_PREFIX
      }
      fromToml("aws-bom", "jackson-bom") { (10)
        aliasSuffixGenerator = { prefix, groupId, artifactId -> (11)
          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") { (12)
        aliasPrefixGenerator = GeneratorConfig.DEFAULT_ALIAS_PREFIX_GENERATOR (13)
      }
    }
  }
}

1	Must include repositories here for dependency resolution to work from settings
2	If you want to append to an existing catalog, you must declare it before using it in a generate block (even if it’s the default `libs.versions.toml`)
3	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.
4	The name of the bom library in the version catalog
5	Optionally override some version properties using a literal value
6	Or, you can reference version aliases in the source TOML
7	Optionally generate an entry in the catalog for the BOM itself
8	All dependencies in the AWS BOM are for AWS so we can skip the prefix
9	Set the default generation options that will apply to all sources unless overridden
10	Include all dependencies from both `aws-bom` and `jackson-bom`
11	Override the default `aliasSuffixGenerator` for dependencies in these two BOMs
12	Also include all dependencies from the `spring-boot-dependencies` BOM in the generated catalog
13	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.4.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.4.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.

Appending to an Existing Catalog

settings.gradle.kts

import dev.aga.gradle.versioncatalogs.Generator.generate

plugins {
  id("dev.aga.gradle.version-catalog-generator") version "3.4.0"
}

dependencyResolutionManagement {
  versionCatalogs {
    create("libs") { (1)
      from(files("gradle/libs.versions.toml"))
    }
    generate("libs") {
      bundleMapping = { (2)
        // excluded for brevity
      }
    }
  }
}

1	If you want to append to an existing catalog, the catalog must be created before using that same name in a `generate` declaration. This is true even if you want to append to the default `libs` catalog.
2	When appending to an existing catalog, you can create bundles composed of dependencies from both the original catalog and the new entries from the BOMs you are generating from.

settings.gradle

plugins {
  id 'dev.aga.gradle.version-catalog-generator' version '3.4.0'
}

dependencyResolutionManagement {
  versionCatalogs {
    libs { (1)
      from(files("gradle/libs.versions.toml"))
    }
    generator.generate("myLibs") { (2)
      it.bundleMapping = {
        // excluded for brevity
      }
    }
  }
}

1	If you want to append to an existing catalog, the catalog must be created before using that same name in a `generate` declaration. This is true even if you want to append to the default `libs` catalog.
2	When appending to an existing catalog, you can create bundles composed of dependencies from both the original catalog and the new entries from the BOMs you are generating from.

When appending to an existing catalog, you must explicitly declare the catalog first, even if it is the default libs catalog.

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 Additional Dependencies in the Generated Catalog

Sometimes you may want to include dependencies in the generated catalog that may not be declared in the BOM(s) you are generated from. For example, mockito-bom does not include mockito-kotlin in its dependencyManagement section, so it would be cumbersome (or impossible) to include this dependency with your generated catalog and access it in a single place, or to include that dependency in a bundle.

To include additional dependencies, you can either use withDep, withDeps, or withDepsFromToml.

settings.gradle.kts

import dev.aga.gradle.versioncatalogs.Generator.generate

plugins {
  id("dev.aga.gradle.version-catalog-generator") version "3.4.0"
}

dependencyResolutionManagement {
  versionCatalogs {
    generate("testingLibs") {
      fromToml("junit-bom", "mockito-bom", "assertj-bom") {
        withDepsFromToml("mockito-kotlin") (1)
        withDep("org.mockito.kotlin", "mockito-kotlin", "6.1.0") (2)
        withDeps("org.mockito.kotlin:mockito-kotlin:6.1.0") (3)
      }
    }
  }
}

1	Include the dependency associated with the specified alias(es) in the generated catalog
2	Include an extra dependency specified by its group, name, and version
3	Include one or more extra dependencies specified their shorthand concatenated notation

settings.gradle

plugins {
  id 'dev.aga.gradle.version-catalog-generator' version '3.4.0'
}

dependencyResolutionManagement {
  versionCatalogs {
    generator.generate("testingLibs") {
      it.from { from ->
        from.toml { toml ->
          toml.libraryAliases = ["junit-bom", "mockito-bom", "assertj-bom"]
        }
        from.using { using ->
          using.withDepsFromToml("mockito-kotlin") (1)
          using.withDep("org.mockito.kotlin", "mockito-kotlin", "6.1.0") (2)
          using.withDeps("org.mockito.kotlin:mockito-kotlin:6.1.0") (3)
        }
      }
    }
  }
}

1	Include the dependency associated with the specified alias(es) in the generated catalog
2	Include an extra dependency specified by its group, name, and version
3	Include one or more extra dependencies specified their shorthand concatenated notation

When using withDepsFromToml, you must be loading a BOM from a catalog file within that block, and the version alias must exist in that same catalog.

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 groupId of the dependency is split by .
If the split only returns a list of one item and the value is the string bundles, plugins, or versions, an IllegalArgumentException is 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

Condition	Value	Generated Prefix
Group begins with	`com.fasterxml.jackson`	`jackson`
Group begins with	`com.oracle.database`	`oracle`
Group begins with	`com.google.android`	`android`
Group begins with	`com.facebook`	`facebook`
Group begins with	`org.springframework`	`spring`
Group begins with	`org.hibernate`	`hibernate`
Group begins with	`org.apache.httpcomponents`	`httpcomponents`
Group begins with	`org.apache.tomcat`	`tomcat`
Group begins with	`org.eclipse.jetty`	`jetty`
Group begins with	`org.elasticsearch`	`elasticsearch`
Group begins with	`org.firebirdsql`	`firebird`
Group begins with	`org.glassfish.jersey`	`jersey`
Group begins with	`org.jetbrains.kotlinx`	`kotlinx`
Group begins with	`org.jetbrains.kotlin`	`kotlin`
Group begins with	`org.junit`	`junit`
Group begins with	`org.mariadb`	`mariadb`
Group begins with	`org.neo4j`	`neo4j`
Group begins with	`io.projectreactor`	`projectreactor`
Group begins with	`io.zipkin`	`zipkin`
Group begins with	`io.dropwizard`	`dropwizard`
Group begins with	`jakarta.`	`jakarta`
Group begins with	`commons-`	`commons`
Group begins with	`androidx`	`androidx`

Group begins with

com.fasterxml.jackson

jackson

Group begins with

com.oracle.database

oracle

Group begins with

com.google.android

android

Group begins with

com.facebook

facebook

Group begins with

org.springframework

spring

Group begins with

org.hibernate

hibernate

Group begins with

org.apache.httpcomponents

httpcomponents

Group begins with

org.apache.tomcat

tomcat

Group begins with

org.eclipse.jetty

jetty

Group begins with

org.elasticsearch

elasticsearch

Group begins with

org.firebirdsql

firebird

Group begins with

org.glassfish.jersey

jersey

Group begins with

org.jetbrains.kotlinx

kotlinx

Group begins with

org.jetbrains.kotlin

kotlin

Group begins with

org.junit

junit

Group begins with

org.mariadb

mariadb

Group begins with

org.neo4j

neo4j

Group begins with

io.projectreactor

projectreactor

Group begins with

io.zipkin

zipkin

Group begins with

io.dropwizard

dropwizard

Group begins with

jakarta.

jakarta

Group begins with

commons-

commons

Group begins with

androidx

Suffix Generation

Replace any . or _ character in the artifactId of 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 version with 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 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

If you are appending to an existing catalog, you can create bundles that contain dependencies from both original catalog and the BOM(s) you are generating from.

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 providing a filter or by providing regex patterns to exclude by groupId or by name (artifactId)

Customizable Filtering

The most flexible and granular way of filtering is by setting a filter in the UsingConfig. When this function returns true for a dependency it will be included in the generated catalog. Otherwise, it will be excluded.

settings.gradle.kts

generate("testLibs") {
  // excluded for brevity
  using { (1)
    filter = { "testing" in it.artifactId } (2)
  }
  from {
    // excluded for brevity
    using { (3)
      filter = "..." // excluded for brevity
    }
  }
}

1	Set the default `filter` for all `from` blocks
2	Only include dependencies whose `artifactId` contain the word "testing"
3	Set/override the `filter` for just this from block

settings.gradle

generator.generate("testLibs") {
  // excluded for brevity
  it.using { using ->  (1)
    using.filter = { dep -> dep.artifactId.contains("testing") } (2)
  }
  it.from { from ->
   // excluded for brevity
   from.using { using -> (3)
     using.filter = { "..." } // excluded for brevity
   }
  }
}

1	Set the default `filter` for all `from` blocks
2	Only include dependencies whose `artifactId` contain the word "testing"
3	Set/override the `filter` for just this from block

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.

When appending to an existing catalog, the output of the saved catalog may be incorrect for entries from the original catalog with aliases that contain .. When building the catalog, Gradle converts all - to . and does not provide a way to recover the original value. When we copy the catalog to prepare it for appending, we convert all periods in the alias into hyphens. This is required to prevent invalid TOML tables from being created by multiple aliases that share a common prefix, such as kotlin-logging and kotling-logging-jvm. The end result of this is that using the catalog will be correct, but the printed values in the persisted catalog may not be the exact value from the original catalog. See #251 for more information.

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-dependences imports mockito-bom, etc)
Easy to override versions (similar to ext["version.property"] = … in Spring Boot Dependencies plugin)

1. You can always use standard Gradle mechanisms such as resolution strategies or platforms if a property is not used to specify the version