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.

structuring builds 8

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:

  1. Do you only need to share dependency versions and coordinates?
    Use a version catalog. You don’t need a plugin for this.

  2. Do several projects need the same plugins and configuration?
    Write a convention plugin as a .gradle.kts or .gradle file, called a precompiled script plugin. It uses the same syntax as a build script, and you don’t need to write a Plugin class.

  3. Does the logic need its own types, unit tests, or publishing for use in other builds?
    Write a binary plugin that implements Plugin<Project>.

  4. Where should the plugins live?
    Put them in an included build named build-logic. buildSrc works as a starting point, but plan to move to build-logic.

The same choices as a table:

To share Use Lives in

Dependency versions and coordinates

Version catalog

gradle/libs.versions.toml

Plugins and configuration for projects of the same kind, such as "every Java library"

Convention plugin written as a precompiled script plugin

build-logic (recommended) or buildSrc

Logic that needs its own types, unit tests, or publishing

Binary plugin

build-logic (recommended), buildSrc, or a published plugin

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:

api/build.gradle.kts
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()
}
services/build.gradle.kts
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()
}
shared/build.gradle.kts
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()
}
api/build.gradle
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()
}
services/build.gradle
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()
}
shared/build.gradle
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:

build-logic/build.gradle.kts
plugins {
    `kotlin-dsl`
}

repositories {
    gradlePluginPortal()
}
build-logic/build.gradle
plugins {
    id 'groovy-gradle-plugin'
}

repositories {
    gradlePluginPortal()
}

The convention plugin is a regular build script that contains the logic shared by the subprojects:

build-logic/src/main/kotlin/java-common-conventions.gradle.kts
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()
}
build-logic/src/main/groovy/java-common-conventions.gradle
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:

settings.gradle.kts
pluginManagement {
    includeBuild("build-logic")
}
settings.gradle
pluginManagement {
    includeBuild('build-logic')
}

Each subproject applies the convention plugin and keeps only its own logic:

api/build.gradle.kts
plugins {
    id("java-common-conventions")
}

dependencies {
    implementation("com.fasterxml.jackson.core:jackson-databind:2.17.1")
}
services/build.gradle.kts
plugins {
    id("java-common-conventions")
}

dependencies {
    implementation("com.google.guava:guava:32.1.2-jre")
}
shared/build.gradle.kts
plugins {
    id("java-common-conventions")
}

dependencies {
    implementation("com.google.guava:guava:32.1.2-jre")
}
api/build.gradle
plugins {
    id("java-common-conventions")
}

dependencies {
    implementation("com.fasterxml.jackson.core:jackson-databind:2.17.1")
}
services/build.gradle
plugins {
    id("java-common-conventions")
}

dependencies {
    implementation("com.google.guava:guava:32.1.2-jre")
}
shared/build.gradle
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.

structuring builds 9

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 buildSrc as a separate build with its own build.gradle(.kts) file and src/ directory.

  • Compiles all classes and scripts in buildSrc before 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:

buildSrc/build.gradle.kts
plugins {
    `kotlin-dsl`
}

repositories {
    gradlePluginPortal()
}
buildSrc/build.gradle
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 buildSrc invalidates the configuration of the whole build and makes all tasks out of date.

  • Libraries on the buildSrc classpath take precedence over the same libraries declared in build scripts. See How buildSrc affects the build script classpath.

Moving from buildSrc to build-logic

To move convention plugins from buildSrc to an included build:

  1. Rename the buildSrc directory to build-logic.

  2. Add a build-logic/settings.gradle(.kts) file that sets rootProject.name = "build-logic".

  3. Include build-logic in the pluginManagement {} block of the root settings file, as shown in the build-logic example.

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:

  1. Applying plugins or other configurations to subprojects of a certain type.
    Often, the cross-project configuration logic is if subproject is of type X, then configure Y. This is equivalent to applying X-conventions plugin directly to a subproject.

  2. Extracting information from subprojects of a certain type.
    This use case can be modeled using outgoing configuration variants.