0Pricing
Groovy & Gradle: JVM Automation and Build Engineering · Lesson

Composite Builds and Build Composition

Combine independent Gradle builds into one using composite builds (includeBuild), letting you develop and test interdependent projects together without publishing artifacts.

Composite Builds and Build Composition is a free Groovy & Gradle: JVM Automation and Build Engineering lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Groovy & Gradle: JVM Automation and Build Engineering learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What is a Composite Build?

A composite build stitches multiple otherwise-independent Gradle builds together. Unlike subprojects, each included build keeps its own settings.gradle and lifecycle.

  • Subprojects: one build, many modules
  • Composite: many builds, joined on demand

Why Use Composites?

Composite builds shine when you work across repository boundaries:

  • Develop a library and its consumer side by side
  • Avoid publishing SNAPSHOTs just to test a change
  • Debug a plugin in the context of a real project

includeBuild Basics

You join another build with includeBuild in settings.gradle. The path points at a directory containing its own settings file.

includeBuild("../shared-library")

Dependency Substitution

The magic is automatic dependency substitution. When your project declares a dependency on a module that an included build produces, Gradle wires the in-source build in place of the published artifact.

dependencies {
    implementation("com.acme:shared-library:1.0")
}

Explicit Substitution

If group/name do not match, declare the mapping manually so Gradle knows which project replaces the coordinate.

includeBuild("../shared-library") {
    dependencySubstitution {
        substitute(module("com.acme:shared")).using(project(":"))
    }
}

Running Tasks Across Builds

You can invoke tasks from an included build using the :buildName:task syntax from the root.

gradle :shared-library:build

Composite vs Multi-Project

Use a multi-project build when modules always ship together. Use a composite when builds are independently versioned and released but you occasionally need them linked.

Plugin Development Workflow

Composite builds are the recommended way to test a custom plugin. Include the plugin build, and consuming projects pick up your local changes instantly.

includeBuild("../my-gradle-plugin")

IDE Behavior

IntelliJ IDEA and Android Studio import composite builds as a single workspace, so navigation, refactoring, and debugging span all included builds seamlessly.

Limitations to Know

A few constraints apply:

  • Included builds cannot themselves define the same root build
  • A build cannot include itself (no cycles)
  • Publishing tasks are not substituted, only consumable artifacts

Best Practices

Keep composites ergonomic:

  • Use relative paths so teammates can clone side by side
  • Keep coordinates consistent to rely on automatic substitution
  • Document which builds are expected to be included

Quick Check

Test your understanding of composite builds.

Recap

You learned composite builds:

  • includeBuild joins independent builds
  • Dependency substitution swaps artifacts for live source
  • Ideal for cross-repo and plugin development
  • Differs from multi-project: builds stay independently versioned

Frequently asked questions

Is the “Composite Builds and Build Composition” lesson free?

Yes — the full text of “Composite Builds and Build Composition” is free to read here on the web, and the Groovy & Gradle: JVM Automation and Build Engineering course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Groovy & Gradle: JVM Automation and Build Engineering course, upgrade to CoddyKit PRO.

What will I learn in “Composite Builds and Build Composition”?

Combine independent Gradle builds into one using composite builds (includeBuild), letting you develop and test interdependent projects together without publishing artifacts. You practise Groovy & Gradle: JVM Automation and Build Engineering with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Groovy & Gradle: JVM Automation and Build Engineering?

No prior experience is required. Groovy & Gradle: JVM Automation and Build Engineering on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Composite Builds and Build Composition” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Groovy & Gradle: JVM Automation and Build Engineering lesson?

Yes. Every Groovy & Gradle: JVM Automation and Build Engineering lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Monorepo Project Structure
  2. Subprojects & Configurations
  3. Inter-Project Dependencies
  4. Composite Builds and Build Composition
← Back to Groovy & Gradle: JVM Automation and Build Engineering