Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Multi-project Builds

Gradle Multi-project Builds: settings.gradle and Subprojects

Learn how Gradle multi-project builds work: settings.gradle.kts, include, project paths, directory layout, shared configuration, allprojects versus convention plugins.

Real applications rarely live in one module. You may have a core library, an api service, a cli tool and a shared-test helper. Gradle models this as a multi-project build: one root project and any number of subprojects, all configured and built together from one command.

This lesson explains the layout, how settings.gradle.kts declares projects, how project paths like :services:api work, how to run tasks in one or all projects, and the right way to share configuration.

Gradle cannot run on this site. Build files are shown read-only; Java stand-ins at the end run on Piston and model project paths and task selection.

Layout

TEXT
shop/
  settings.gradle.kts
  build.gradle.kts            (root, often nearly empty)
  core/
    build.gradle.kts
    src/main/java/...
  services/
    api/
      build.gradle.kts
    worker/
      build.gradle.kts
  cli/
    build.gradle.kts

The only file that defines the set of projects is settings.gradle.kts:

Kotlin
rootProject.name = "shop"

include("core")
include("cli")
include("services:api", "services:worker")

A colon in include means a directory separator. include("services:api") registers the project :services:api (its directory is services/api) and, implicitly, an intermediate project :services with no code of its own.

Project paths

Every project has a path starting at the root with a colon:

Directory Path
root :
core :core
services/api :services:api

You use paths in two main places: on the command line and in dependencies.

TEXT
./gradlew :core:build              # one project
./gradlew :services:api:test       # one task of one nested project
./gradlew build                    # the task in ALL projects (and root)
./gradlew test --continue          # keep going after a failure
./gradlew projects                 # print the tree

When you run ./gradlew build from the root, Gradle runs build in every project that has such a task. When you run it from inside core/, it builds only core and what it depends on.

Changing directories and names

By default the directory matches the name. You can override it, which is useful when migrating:

Kotlin
include("legacy-api")
project(":legacy-api").projectDir = file("old/api")
project(":legacy-api").name = "api-legacy"

Avoid this unless you must; it makes builds harder to read.

Sharing configuration

All subprojects often need the same repositories, Java version and test setup. There are three approaches, from worst to best.

1. allprojects / subprojects in the root script (works, discouraged)

Kotlin
// root build.gradle.kts
subprojects {
    apply(plugin = "java")
    repositories { mavenCentral() }
}

This pushes settings from the root into the children. It is easy but has real costs: subprojects can no longer be understood on their own, and "cross-project configuration" is slow and hard to parallelize. Gradle recommends against it.

Put shared configuration into a plugin such as shop.java-conventions (see custom plugins) and apply it where needed:

Kotlin
// core/build.gradle.kts
plugins {
    id("shop.java-conventions")
}

Every project says explicitly what it uses; nothing is injected from above.

3. Shared properties

Values that differ by project but are shared, such as version numbers, belong in gradle.properties, a version catalog or the convention plugin, not scattered strings.

Naming rules and the root project

rootProject.name is used for artifact names and IDE display. If you omit it, Gradle uses the directory name, which breaks when a CI system checks the code out into a folder called workspace. Always set it.

The root project can have its own code, but many builds leave it as a pure aggregator. Keep only plugins with apply false, lifecycle tasks such as an aggregated testReport, and documentation there.

Running tasks selectively

Gradle matches task names by name across projects. test means "every project's test". You can also use abbreviations: ./gradlew :co:bu expands to :core:build if unambiguous (camel case works too: cB for compileBuild).

To see why Gradle chose a project's task order, use --dry-run: ./gradlew build -m prints the plan without executing anything.

Stand-in: project tree and task selection

This Java model registers projects from include strings, resolves paths, and finds which projects have a requested task.

Java Stand-in: project paths and task selection (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.

Notice that :services exists as a project but has no tasks of its own, so :services:test matches nothing, exactly as in real Gradle where you would get a "task not found" error.

Visualizing the tree

flowchart TD
    R[":  (root, shop)"] --> C[":core"]
    R --> L[":cli"]
    R --> S[":services"]
    S --> A[":services:api"]
    S --> W[":services:worker"]

include("services:api") also creates the empty :services parent.

Common mistakes

  1. Forgetting to include a new module. The folder exists but Gradle ignores it.
  2. Dots instead of colons. Use include("services:api"), not services.api.
  3. Configuring everything from the root. It couples the modules and slows configuration.
  4. No rootProject.name. Artifact names change with the checkout folder.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file defines which projects are part of a multi-project build?

    settings.gradle.kts uses include to register subprojects. Gradle reads it before any build script.
  2. 2. What project path does include("services:api") create for the directory services/api?

    Colons separate path segments, and every project path begins with a colon for the root.
  3. 3. Why are convention plugins preferred over subprojects {} in the root script?

    Cross-project configuration hides where settings come from and hampers parallelism and caching. Convention plugins make dependencies explicit.
  4. 4. What does ./gradlew test do from the root of a multi-project build?

    A bare task name matches the task in all projects. Use :core:test to target one.

Summary

  • settings.gradle.kts lists projects with include; colons mean directory nesting.
  • Project paths start at : and are used on the command line and in dependencies.
  • Prefer convention plugins to allprojects {} and subprojects {}.
  • Always set rootProject.name.
  • Use ./gradlew projects and --dry-run to inspect the build.

Next: Project dependencies and shared conventions