Sharing Build Logic
Subprojects in a multi-project build often apply the same plugins, configure the same tasks, and declare the same dependencies. Copying this logic into every build script makes it hard to change consistently.
Sharing build logic involves two separate decisions:
-
How you package the shared logic: usually a convention plugin.
-
Where the shared logic lives: preferably an included build named
build-logic.
Choosing How to Share Build Logic
Answer these questions in order:
-
Do you only need to share dependency versions and coordinates?
Use a version catalog. You don’t need a plugin for this. -
Do several projects need the same plugins and configuration?
Write a convention plugin as a.gradle.ktsor.gradlefile, called a precompiled script plugin. It uses the same syntax as a build script, and you don’t need to write aPluginclass. -
Does the logic need its own types, unit tests, or publishing for use in other builds?
Write a binary plugin that implementsPlugin<Project>. -
Where should the plugins live?
Put them in an included build namedbuild-logic.buildSrcworks as a starting point, but plan to move tobuild-logic.
The same choices as a table:
| To share | Use | Lives in |
|---|---|---|
Dependency versions and coordinates |
|
|
Plugins and configuration for projects of the same kind, such as "every Java library" |
Convention plugin written as a precompiled script plugin |
|
Logic that needs its own types, unit tests, or publishing |
|
Avoid sharing logic with allprojects {} and subprojects {}.
See Avoid cross-project configuration for why.
Lifecycle callbacks registered in the settings file, such as gradle.lifecycle.beforeProject {}, run code for projects without the project applying anything.
They are described in Build Lifecycle.
To share plugins and configuration, prefer convention plugins, which each project applies explicitly in its build script.
Sharing Logic with Convention Plugins in build-logic
Take a typical multi-project build:
.
├── api
│ ├── src/
│ └── build.gradle.kts (1)
├── services
│ ├── src/
│ └── build.gradle.kts (1)
├── shared
│ ├── src/
│ └── build.gradle.kts (1)
└── settings.gradle.kts
| 1 | A build script that contains build logic, including parts that are shared with other subprojects. |
.
├── api
│ ├── src/
│ └── build.gradle (1)
├── services
│ ├── src/
│ └── build.gradle (1)
├── shared
│ ├── src/
│ └── build.gradle (1)
└── settings.gradle
| 1 | A build script that contains build logic, including parts that are shared with other subprojects. |
The build files for api, services, and shared have a lot in common:
plugins {
`java-library`
}
repositories {
mavenCentral()
}
dependencies {
implementation("org.slf4j:slf4j-api:2.0.9")
implementation("com.fasterxml.jackson.core:jackson-databind:2.17.1")
testImplementation("org.junit.jupiter:junit-jupiter:5.11.3")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named<Test>("test") {
useJUnitPlatform()
}
plugins {
`java-library`
}
repositories {
mavenCentral()
}
dependencies {
implementation("org.slf4j:slf4j-api:2.0.9")
implementation("com.google.guava:guava:32.1.2-jre")
testImplementation("org.junit.jupiter:junit-jupiter:5.11.3")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named<Test>("test") {
useJUnitPlatform()
}
plugins {
`java-library`
}
repositories {
mavenCentral()
}
dependencies {
implementation("org.slf4j:slf4j-api:2.0.9")
implementation("com.google.guava:guava:32.1.2-jre")
testImplementation("org.junit.jupiter:junit-jupiter:5.11.3")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named<Test>("test") {
useJUnitPlatform()
}
plugins {
id 'java-library'
}
repositories {
mavenCentral()
}
dependencies {
implementation 'org.slf4j:slf4j-api:2.0.9'
implementation 'com.fasterxml.jackson.core:jackson-databind:2.17.1'
testImplementation 'org.junit.jupiter:junit-jupiter:5.11.3'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named('test', Test) {
useJUnitPlatform()
}
plugins {
id 'java-library'
}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.google.guava:guava:32.1.2-jre'
implementation 'org.slf4j:slf4j-api:2.0.9'
testImplementation 'org.junit.jupiter:junit-jupiter:5.11.3'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named('test', Test) {
useJUnitPlatform()
}
plugins {
id 'java-library'
}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.google.guava:guava:32.1.2-jre'
implementation 'org.slf4j:slf4j-api:2.0.9'
testImplementation 'org.junit.jupiter:junit-jupiter:5.11.3'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named('test', Test) {
useJUnitPlatform()
}
To remove the duplication, move the shared parts into a convention plugin in a build-logic directory:
.
├── build-logic
│ ├── src
│ │ └──main
│ │ └──kotlin
│ │ └──java-common-conventions.gradle.kts (1)
│ ├── build.gradle.kts (2)
│ └── settings.gradle.kts
├── api
│ ├── src/
│ └── build.gradle.kts (3)
├── services
│ ├── src/
│ └── build.gradle.kts (3)
├── shared
│ ├── src/
│ └── build.gradle.kts (3)
└── settings.gradle.kts (4)
| 1 | The convention plugin. |
| 2 | Applies kotlin-dsl so the convention plugin is compiled. |
| 3 | Applies the convention plugin. |
| 4 | Includes build-logic. |
.
├── build-logic
│ ├── src
│ │ └──main
│ │ └──groovy
│ │ └──java-common-conventions.gradle (1)
│ ├── build.gradle (2)
│ └── settings.gradle
├── api
│ ├── src/
│ └── build.gradle (3)
├── services
│ ├── src/
│ └── build.gradle (3)
├── shared
│ ├── src/
│ └── build.gradle (3)
└── settings.gradle (4)
| 1 | The convention plugin. |
| 2 | Applies groovy-gradle-plugin so the convention plugin is compiled. |
| 3 | Applies the convention plugin. |
| 4 | Includes build-logic. |
build-logic is a separate Gradle build with its own settings file.
Its build file applies the plugin that compiles .gradle.kts or .gradle files into plugins:
plugins {
`kotlin-dsl`
}
repositories {
gradlePluginPortal()
}
plugins {
id 'groovy-gradle-plugin'
}
repositories {
gradlePluginPortal()
}
The convention plugin is a regular build script that contains the logic shared by the subprojects:
plugins {
`java-library`
}
repositories {
mavenCentral()
}
dependencies {
implementation("org.slf4j:slf4j-api:2.0.9")
testImplementation("org.junit.jupiter:junit-jupiter:5.11.3")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named<Test>("test") {
useJUnitPlatform()
}
plugins {
id 'java-library'
}
repositories {
mavenCentral()
}
dependencies {
implementation 'org.slf4j:slf4j-api:2.0.9'
testImplementation 'org.junit.jupiter:junit-jupiter:5.11.3'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named('test', Test) {
useJUnitPlatform()
}
The plugin ID is the file name without the .gradle.kts or .gradle extension, here java-common-conventions.
The root settings file includes build-logic in the pluginManagement {} block, so its plugins can be applied by ID:
pluginManagement {
includeBuild("build-logic")
}
pluginManagement {
includeBuild('build-logic')
}
Each subproject applies the convention plugin and keeps only its own logic:
plugins {
id("java-common-conventions")
}
dependencies {
implementation("com.fasterxml.jackson.core:jackson-databind:2.17.1")
}
plugins {
id("java-common-conventions")
}
dependencies {
implementation("com.google.guava:guava:32.1.2-jre")
}
plugins {
id("java-common-conventions")
}
dependencies {
implementation("com.google.guava:guava:32.1.2-jre")
}
plugins {
id("java-common-conventions")
}
dependencies {
implementation("com.fasterxml.jackson.core:jackson-databind:2.17.1")
}
plugins {
id("java-common-conventions")
}
dependencies {
implementation("com.google.guava:guava:32.1.2-jre")
}
plugins {
id("java-common-conventions")
}
dependencies {
implementation("com.google.guava:guava:32.1.2-jre")
}
To change something like the version of slf4j-api, you now update the convention plugin, and every subproject that applies it picks up the change.
To learn more about included builds, see Composite Builds.
To see why build-logic is preferred over buildSrc, see Favor build-logic Composite Builds for Build Logic.
Using buildSrc
buildSrc is a directory at the root of a build that Gradle detects and builds automatically, without an includeBuild() call.
It is a quick way to start sharing build logic, but build-logic is the recommended long-term location.
The same convention plugin works in buildSrc:
.
├── buildSrc
│ ├── src
│ │ └──main
│ │ └──kotlin
│ │ └──java-common-conventions.gradle.kts (1)
│ └── build.gradle.kts
├── api
│ ├── src/
│ └── build.gradle.kts (2)
├── services
│ ├── src/
│ └── build.gradle.kts (2)
├── shared
│ ├── src/
│ └── build.gradle.kts (2)
└── settings.gradle.kts
| 1 | The convention plugin. |
| 2 | Applies the convention plugin. |
.
├── buildSrc
│ ├── src
│ │ └──main
│ │ └──groovy
│ │ └──java-common-conventions.gradle (1)
│ └── build.gradle
├── api
│ ├── src/
│ └── build.gradle (2)
├── services
│ ├── src/
│ └── build.gradle (2)
├── shared
│ ├── src/
│ └── build.gradle (2)
└── settings.gradle
| 1 | The convention plugin. |
| 2 | Applies the convention plugin. |
When a buildSrc directory is present at the root of a build, Gradle:
-
Treats
buildSrcas a separate build with its ownbuild.gradle(.kts)file andsrc/directory. -
Compiles all classes and scripts in
buildSrcbefore evaluating any build script in the main build. -
Makes the compiled classes and scripts, and their dependencies, available on the classpath of every build script in the main build.
The buildSrc build file is the same as the one in build-logic:
plugins {
`kotlin-dsl`
}
repositories {
gradlePluginPortal()
}
plugins {
id 'groovy-gradle-plugin'
}
repositories {
gradlePluginPortal()
}
buildSrc follows the same source layout conventions as regular Java, Groovy, or Kotlin projects and has direct access to the Gradle API.
A build can have only one buildSrc directory, and it must be in the root project directory.
Compared to build-logic, buildSrc has these drawbacks:
-
Any change in
buildSrcinvalidates the configuration of the whole build and makes all tasks out of date. -
Libraries on the
buildSrcclasspath take precedence over the same libraries declared in build scripts. See HowbuildSrcaffects the build script classpath.
Moving from buildSrc to build-logic
To move convention plugins from buildSrc to an included build:
-
Rename the
buildSrcdirectory tobuild-logic. -
Add a
build-logic/settings.gradle(.kts)file that setsrootProject.name = "build-logic". -
Include
build-logicin thepluginManagement {}block of the root settings file, as shown in thebuild-logicexample.
Build scripts keep applying the convention plugins by the same IDs.
Avoid cross-project configuration using subprojects and allprojects
An improper way to share build logic between subprojects is cross-project configuration via the subprojects {} and allprojects {} DSL constructs.
With cross-project configuration, build logic can be injected into a subproject which is not obvious when looking at its build script.
In the long run, cross-project configuration usually grows in complexity and becomes a burden. Cross-project configuration can also introduce configuration-time coupling between projects, which can prevent optimizations like configuration-on-demand from working properly.
Convention plugins versus cross-project configuration
The two most common uses of cross-project configuration can be better modeled using convention plugins:
-
Applying plugins or other configurations to subprojects of a certain type.
Often, the cross-project configuration logic isif subproject is of type X, then configure Y. This is equivalent to applyingX-conventionsplugin directly to a subproject. -
Extracting information from subprojects of a certain type.
This use case can be modeled using outgoing configuration variants.