Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 36 ยท Multi-project Builds

Composite Builds, Version Catalogs and BOMs in Gradle

Learn includeBuild composite builds, dependency substitution, libs.versions.toml version catalogs, bundles, plugin aliases and platform (BOM) dependencies in Gradle.

Two features keep large Gradle setups tidy: composite builds, which let several independent builds work together as if they were one, and version catalogs, which hold all dependency and plugin versions in one file. A third piece, platforms (BOMs), aligns the versions of a library family.

This lesson shows each one in turn. It assumes you know project dependencies.

Gradle cannot run on this site; build files are read-only. The Java stand-ins parse a catalog and model dependency substitution on Piston.

Composite builds with includeBuild

Imagine you maintain an app in app/ and a library in ../my-lib/, each a full Gradle build with its own settings.gradle.kts. You want to fix a bug in the library and see it in the app without publishing a snapshot. Include the library build:

Kotlin
// app/settings.gradle.kts
rootProject.name = "app"
include("service")

includeBuild("../my-lib")

If the app declares implementation("com.example:my-lib:1.0") and ../my-lib produces exactly that coordinate (group and name), Gradle substitutes the external module with the included build. You get source-level integration, IDE navigation and no publishToMavenLocal dance.

When group and name do not match, tell Gradle:

Kotlin
includeBuild("../my-lib") {
    dependencySubstitution {
        substitute(module("com.example:old-name")).using(project(":"))
    }
}

Composite builds are used for:

  • developing a library and its consumer together,
  • build-logic included in pluginManagement (see custom plugins),
  • gradual splitting of a monolith into independent builds.

You can run a task of an included build from the root with ./gradlew :my-lib:build, and the included build is not an alternative to subprojects: it keeps its own settings, plugins and version.

Java Stand-in: dependency substitution (not Gradle)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Version catalogs

A catalog is a TOML file, by default gradle/libs.versions.toml, that Gradle reads automatically:

TOML
[versions]
junit = "5.11.4"
jackson = "2.18.2"
kotlin = "2.1.0"

[libraries]
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }
jackson-jsr310 = { module = "com.fasterxml.jackson.datatype:jackson-datatype-jsr310", version.ref = "jackson" }
commons-lang3 = "org.apache.commons:commons-lang3:3.17.0"

[bundles]
jackson = ["jackson-databind", "jackson-jsr310"]

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

Gradle generates type-safe accessors in the libs object. Hyphens become dots:

Kotlin
plugins {
    alias(libs.plugins.kotlin.jvm)
}

dependencies {
    implementation(libs.commons.lang3)
    implementation(libs.bundles.jackson)
    testImplementation(libs.junit.jupiter)
}

Benefits:

  • One place to upgrade. Bump jackson once; every module that uses it follows.
  • Completion and refactoring in the IDE instead of copy-pasted strings.
  • Bundles group libraries that always travel together.
  • Tools such as Renovate and Dependabot understand the format.

You can also define catalogs in settings.gradle.kts with dependencyResolutionManagement { versionCatalogs { create("libs") { from(files("...")) } } }, for example to share one catalog across several builds.

What a catalog does NOT do

A catalog is only a naming and version table. It does not force a version onto transitive dependencies. For that you need constraints or a platform.

Java Stand-in: reading a catalog and building accessors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Platforms and BOMs

A BOM (bill of materials) is a published POM that lists compatible versions of many modules. In Gradle you import it with platform() and then declare modules without versions:

Kotlin
dependencies {
    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.4.1"))
    implementation("org.springframework:spring-web")          // version from the BOM
    implementation("com.fasterxml.jackson.core:jackson-databind")
}

platform() affects transitive dependencies too, so every module in the family lines up. Use enforcedPlatform() only when you must override what libraries request, since it is strict.

You can build your own internal platform with the java-platform plugin and publish it so all your services share the same versions. It pairs well with a catalog: the catalog names things, the platform enforces alignment.

When to use what

Need Tool
Work on library and app together composite build (includeBuild)
Name and version dependencies centrally version catalog
Align versions of a family platform / BOM
Share code inside one repo subprojects

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does includeBuild("../my-lib") enable?

    A composite build lets Gradle replace a published module coordinate with a local build that produces it.
  2. 2. In libs.versions.toml, how is the library alias commons-lang3 written in a build script?

    Hyphens in aliases become dots in the generated accessor, so commons-lang3 becomes libs.commons.lang3.
  3. 3. What is a [bundles] entry in a catalog?

    Bundles list library aliases that are usually used together, such as several Jackson modules.
  4. 4. What does platform("...bom...") do?

    A platform brings version constraints from a BOM, including for transitive dependencies.

Summary

  • includeBuild joins independent builds and substitutes matching dependencies.
  • gradle/libs.versions.toml centralizes versions, libraries, bundles and plugins with typed accessors.
  • platform() imports a BOM to align module versions.
  • Catalogs name; platforms constrain; use both for big codebases.

Next: Testing with JUnit in Gradle