Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Multi-project Builds

Project Dependencies in Multi-project Gradle Builds

Learn how subprojects depend on each other in Gradle: project() dependencies, build order, api versus implementation, test fixtures, cycles and typesafe project accessors.

In a multi-project build, modules depend on each other the same way they depend on external libraries, with one difference: instead of a Maven coordinate you write a project path. Gradle then builds the other project first, uses its output (its jar, or its classes folder for compile-only needs) and reruns work only when that project changes.

This lesson shows the syntax, how build order is derived, how api and implementation work across projects, how to share test helpers with test fixtures, and how to avoid circular dependencies. Read settings and subprojects first for the layout.

Gradle cannot run on this site; the build files are read-only. The Java stand-ins run on Piston and model build order and cycles.

Declaring a project dependency

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

dependencies {
    implementation(project(":core"))
    implementation(project(":services:api"))
    testImplementation(testFixtures(project(":core")))
}

application {
    mainClass = "shop.cli.Main"
}
GROOVY
// Groovy DSL
dependencies {
    implementation project(':core')
}

project(":core") refers to the project at path :core. Gradle adds the core project's jar (or class directories) to the classpath and makes core:jar a prerequisite of cli:compileJava. You never write the order yourself; it follows from dependencies.

Typesafe project accessors

Strings like ":services:api" can be mistyped. Enable generated accessors in settings.gradle.kts:

Kotlin
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")

Then write implementation(projects.services.api). The IDE completes the names and renames work. (In recent Gradle versions this feature is stable, in older ones it needs the preview flag.)

Build order and parallel work

flowchart LR
    core[":core"] --> api[":services:api"]
    core --> worker[":services:worker"]
    api --> cli[":cli"]
    worker --> cli

Gradle builds core first; api and worker can run in parallel; cli waits for both.

With org.gradle.parallel=true in gradle.properties, independent projects compile at the same time. A flat dependency graph (many projects depending on a few) parallelizes much better than a long chain.

Java Stand-in: build order and parallel waves (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.

api, implementation and transitive exposure

The same rules as for external libraries apply, only java-library projects have api:

Kotlin
// core/build.gradle.kts
plugins { `java-library` }

dependencies {
    api("org.apache.commons:commons-lang3:3.17.0")
    implementation("com.fasterxml.jackson.core:jackson-databind:2.18.2")
}

A project that depends on :core with implementation(project(":core")) can see commons-lang3 types at compile time, but not Jackson. Use api(project(":core")) only when your own public API exposes core types to your consumers.

Test fixtures

Sometimes tests in several modules need the same helpers: builders, fake clients, test data. Putting them in src/test makes them unreachable. Use the java-test-fixtures plugin:

Kotlin
// core/build.gradle.kts
plugins {
    `java-library`
    `java-test-fixtures`
}

dependencies {
    testFixturesApi("org.assertj:assertj-core:3.27.0")
}

Put helpers in core/src/testFixtures/java, then consume them with testImplementation(testFixtures(project(":core"))). Fixtures can see main code, tests of core can see fixtures, and production code never sees them. This is cleaner than a separate shared-test module that everyone depends on.

Circular dependencies

If :a depends on :b and :b depends on :a, Gradle cannot decide what to build first and the build fails with a circular dependency message for tasks. Fixes:

  1. Move the shared code into a third project that both depend on.
  2. Invert the dependency using an interface in the lower module and an implementation in the higher one.
  3. Merge the two modules if they cannot live apart.
Java Stand-in: detecting a dependency cycle

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.

Useful commands

  • ./gradlew :cli:dependencies --configuration runtimeClasspath shows the resolved tree, including project dependencies.
  • ./gradlew :cli:dependencyInsight --dependency commons-lang3 explains why a library is there.
  • ./gradlew :cli:build --dry-run lists the tasks that would run, including upstream ones.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does implementation(project(":core")) do?

    A project dependency uses the other project's artifact and creates the task dependency that makes Gradle build it first.
  2. 2. How do you let tests in several modules share helper code without exposing it to production code?

    Test fixtures live in src/testFixtures and are consumed only by test configurations.
  3. 3. Project a depends on b and b depends on a. What happens?

    There is no valid build order, so Gradle reports a cycle. Break it with a third module or an interface.
  4. 4. Which setting lets independent projects compile at the same time?

    org.gradle.parallel=true in gradle.properties runs tasks of independent projects concurrently.

Summary

  • Depend on a sibling with project(":path") or, with accessors, projects.name.
  • Gradle derives build order from dependencies, and builds independent projects in parallel when enabled.
  • api exposes dependencies of a library project; default to implementation.
  • Share test helpers via java-test-fixtures.
  • Break cycles with a new shared module or by inverting dependencies.

Next: Composite builds and version catalogs