Where does the time go in a slow Java monolith build?
Before changing any build logic, measure where the time actually goes. Gradle has two built-in ways to do this.
Running a build with --profile writes an HTML report under build/reports/profile. It breaks wall-clock time into startup, configuration and task execution, and lists every task with its duration. Running with --scan publishes a Build Scan with the same data plus task outcomes, dependency resolution time and a timeline showing which tasks ran in parallel. A scan uploads build metadata to an external server, so check your organisation's policy before using it on proprietary code.
In either report, look at the outcome of each task. A task marked UP-TO-DATE or FROM-CACHE was skipped. A task with no label actually ran. In most slow monoliths, the problem is not that javac is slow per file. The problem is that a one-line change causes hundreds of compile and test tasks to run, because Gradle cannot prove their inputs are unchanged. Configuration time matters too. If it grows with project size, every build pays that cost, including builds that do nothing.
Record these baselines before you touch anything:
- Clean build time. Measure with caches disabled.
- No-op build time. Run the same command twice and record the second run. This should be close to configuration time alone.
- Rebuild after a single-line change in a leaf class.
- Rebuild after a single-line change in a widely used core class.
- Executed versus skipped task counts for each of the runs above.
- The split of execution time between
compileJavaandtesttasks.
These numbers tell you whether to focus on avoiding work, on configuration, or on tests.
#!/usr/bin/env bash
set -euo pipefail
LEAF=app/src/main/java/com/example/app/ReportFormatter.java # placeholder: rarely depended on
CORE=core/src/main/java/com/example/core/Money.java # placeholder: used everywhere
mkdir -p baseline
run() {
local label=$1; shift
local start end total skipped
start=$(date +%s)
./gradlew "$@" --profile --console=plain > "baseline/$label.log" 2>&1
end=$(date +%s)
total=$(grep -c '^> Task ' "baseline/$label.log" || true)
skipped=$(grep -cE '^> Task .* (UP-TO-DATE|FROM-CACHE|NO-SOURCE|SKIPPED)$' "baseline/$label.log" || true)
echo "$label: $((end - start))s wall, $total tasks, $skipped skipped, $((total - skipped)) executed"
}
run clean clean build --no-build-cache
./gradlew build -q
run noop build
for target in leaf:"$LEAF" core:"$CORE"; do
label=${target%%:*}; file=${target#*:}
echo '// baseline probe' >> "$file"
run "$label-change" build
git checkout -- "$file"
./gradlew build -q
done
ls build/reports/profile/
A script that records clean, no-op, leaf-change and core-change build times with executed versus skipped task counts. Gradle writes a --profile report for each run, which shows the configuration/execution split and the compileJava versus test split.
Who should use these techniques?
This article is for teams that run a large Java codebase on Gradle and spend significant time waiting for builds. Typical signs:
- A one-line change in one place triggers a rebuild that takes minutes, locally or in CI.
- Your baseline shows that most tasks execute on a rebuild even though few files changed.
- CI agents spend most of each run recompiling and retesting code that no pull request touched.
- The codebase is a single large module, or a handful of large modules, and keeps growing.
The techniques suit teams that can change build files and, ideally, move code between modules. Splitting a monolith requires the people who own the code to agree on module boundaries. Build engineers alone usually cannot do it.
If you have a small codebase, a build that already finishes quickly, or a baseline where most tasks are already UP-TO-DATE or FROM-CACHE, the restructuring work later in this article will probably not pay for itself. The cheaper settings described in "What other cheap wins are worth checking first?" are still worth trying.
How do up-to-date checks, incremental compilation, compile avoidance and the build cache differ?
Gradle has four separate ways to avoid work. Each one compares a different fingerprint, so each one fails in a different way.
Up-to-date checks run on every task. Gradle hashes a task's declared inputs and outputs and compares them with the last execution in the same workspace. If nothing changed, the task is skipped. This only works if inputs are declared correctly. An undeclared input makes the task either always rerun or wrongly skip.
Incremental compilation applies when compileJava does have to run. Gradle analyses class dependencies within the module and recompiles only the changed classes and the classes that depend on them.
Compile avoidance works across modules. A downstream module's compile classpath is fingerprinted by its ABI: public signatures, not method bodies. Changing a private method or an implementation detail upstream leaves downstream modules untouched.
The build cache stores task outputs keyed by a hash of their inputs. Any build with matching inputs, on any machine, can restore those outputs instead of running the task.
| Mechanism | Scope | Saves time during |
|---|---|---|
| Up-to-date checks | One task, same workspace | Local edit loop |
| Incremental compilation | Classes within one module | Local edit loop |
| Compile avoidance | Across modules | Local edit loop, CI |
| Build cache | Across builds and machines | Branch switching (local cache), clean CI checkout (remote cache) |
Three things commonly defeat incremental compilation:
- Non-incremental annotation processors. Gradle cannot track what a processor generated, so it falls back to recompiling the whole module.
- Compile-time constants.
javacinlinesstatic finalprimitives and strings into the classes that use them. Changing one constant can force recompilation well beyond the file you edited. - Oversized modules. When a widely used class changes, everything inside the module that depends on it recompiles.
How does Gradle incremental compilation work?
When a JavaCompile task runs, Gradle does not simply hand every source file to javac. After each successful compilation it records an analysis of the module's classes: which classes depend on which, and which constants they use. On the next run it uses that analysis to decide how little it can recompile.
The sequence on a rebuild is roughly as follows:
- Detect changes. Gradle compares the current source files and compile classpath with the fingerprints from the previous execution. If nothing changed, the task is
UP-TO-DATEandjavacnever runs. - Work out the affected set. For each changed source file, Gradle uses the stored class analysis to find the classes that depend on it. If a class on the compile classpath changed, it looks at that class's ABI. A change that leaves the ABI identical does not affect dependents.
- Remove stale outputs. Gradle deletes the class files belonging to the affected sources, so a deleted or renamed class does not linger in the output directory.
- Compile only the affected set. Gradle invokes the compiler on the changed and dependent sources, with the module's existing class files on the classpath for everything else.
- Update the analysis so that the next build starts from the new state.
When Gradle cannot prove the affected set is safe, it falls back to a full recompilation of the module rather than risk a wrong result. Common triggers are a non-incremental annotation processor, a changed constant whose users cannot be determined precisely, and the first build after a clean. Running the task with --info logs the reason when Gradle decides to recompile everything, which is the quickest way to find out why a small edit caused a full module rebuild.
Annotation processors take part in incremental compilation only when they declare themselves incremental. A processor does this through a META-INF/gradle/incremental.annotation.processors resource that registers it as either isolating or aggregating. An isolating processor generates output from a single annotated element, so Gradle can map each generated file back to one source. An aggregating processor combines several elements into its output, so Gradle has to reprocess more when one of them changes, though it still avoids a full recompile. A processor without this declaration is treated as non-incremental.
The other mechanisms build on the same idea of fingerprinting. Compile avoidance applies the ABI comparison across module boundaries. Up-to-date checks and the build cache apply input hashing to whole tasks rather than individual classes.
How should you split a monolith into a multi-module Gradle build?
Split along the dependency graph, not along team or package names. Gradle schedules work per module (project) and caches task outputs per module, so a build made of many small modules gives it more units to run in parallel and more outputs it can reuse. A few giant modules give it almost nothing to skip.
The shape of the graph matters more than the number of modules. The usual failure is a common module that every other module depends on:
Hub-shaped: edit common Leaf-heavy: edit pricing-impl
common * money-api pricing-api
/ / | \ \ | \ |
orders billing auth search reports orders pricing-impl *
(all five recompile and retest) (only pricing-impl rebuilds)
In the hub, any edit to common invalidates every module downstream of it. Break it apart by concept, such as money, time, and ids, so each consumer depends only on what it uses. Keep the leaf modules, where most daily edits happen, free of dependents.
Then control what leaks through each module's ABI. With the java-library plugin, declare a dependency as api only when its types appear in your public signatures. Declare everything else as implementation. Gradle compiles consumers against your ABI. If you change a method body, a private field, or an implementation-only dependency, the ABI does not change, and downstream compilation is skipped. Every unnecessary api declaration widens the set of changes that force consumers to recompile.
// settings.gradle.kts: one project per concept, no catch-all 'common'
rootProject.name = "shop"
include("money-api", "pricing-api", "pricing-impl", "orders", "app")
// gradle.properties: run independent modules in parallel, reuse cached outputs
// org.gradle.parallel=true
// org.gradle.caching=true
// pricing-api/build.gradle.kts
plugins { `java-library` }
dependencies {
// Money appears in PricingService method signatures, so it is part of this ABI
api(project(":money-api"))
}
// pricing-impl/build.gradle.kts: a leaf where daily edits happen; nothing compiles against it
plugins { `java-library` }
dependencies {
// Used inside method bodies only; consumers never see these types
implementation(project(":pricing-api"))
implementation(project(":money-api"))
}
// orders/build.gradle.kts: compiles against the pricing ABI, not the implementation
plugins { `java-library` }
dependencies {
implementation(project(":pricing-api"))
implementation(project(":money-api"))
}
// app/build.gradle.kts: the only place that wires in the implementation
plugins { application }
dependencies {
implementation(project(":orders"))
// Needed at runtime only, so editing pricing-impl never recompiles app or orders
runtimeOnly(project(":pricing-impl"))
}
Gradle Kotlin DSL build files that split pricing into an API module and a leaf implementation module. api is used only where types appear in public signatures, and implementation/runtimeOnly keep changes to pricing-impl from recompiling its consumers.
How do you enable and verify the Gradle build cache?
The build cache cannot help when an ABI change forces downstream recompilation, so keep the ABI narrow before relying on caching to absorb the cost.
Turn on the local cache
Add org.gradle.caching=true to gradle.properties. Gradle then stores task outputs under a cache key computed from the task's implementation and declared inputs. A task is cacheable only when every input and output is declared and the task opts in. Built-in tasks such as JavaCompile already do this. Custom tasks need @CacheableTask.
Make keys stable across machines
A cache key that embeds /home/alice/repo will never match on CI. To keep keys stable:
- Annotate file inputs on custom tasks with
@PathSensitive(PathSensitivity.RELATIVE)so that only paths relative to the project contribute to the key. - Keep build timestamps, hostnames and unordered collections out of generated files.
- Use the
normalization { runtimeClasspath { ... } }block to ignore volatile entries such as abuild-info.propertiesfile.
Diagnose misses
Run the same build twice with -Dorg.gradle.caching.debug=true. Gradle logs the hash of each input that went into the key. Diff the two logs, and the input that changed is the cause of the miss. Then confirm that a clean rebuild reports tasks as FROM-CACHE.
Share a remote cache
In settings.gradle, configure an HttpBuildCache with push enabled only when a CI environment variable is set. Developers read from the cache but never write to it.
This matters for two reasons. Correctness: a laptop with uncommitted changes or a nonstandard JDK can poison entries that everyone else then consumes. Security: anyone with write access can plant compiled bytecode that downstream builds trust without recompiling. Restrict write credentials to CI.
// settings.gradle (Groovy DSL)
// Requires org.gradle.caching=true in gradle.properties (or --build-cache).
// Treat the build as CI only when the pipeline sets this variable.
def isCi = System.getenv('CI') != null
buildCache {
local {
// Keep the local cache on developer machines.
// On ephemeral CI agents it rarely survives between runs.
enabled = !isCi
}
remote(HttpBuildCache) {
// Placeholder endpoint for the shared cache node.
url = ''
// Everyone reads. Only trusted CI uploads entries.
// A laptop with uncommitted edits or an odd JDK cannot poison the cache.
push = isCi
// CI gets read-write credentials. Developers get read-only ones.
// Enforce the split on the server too, not only through this flag.
def user = System.getenv('GRADLE_CACHE_USER')
def pass = System.getenv('GRADLE_CACHE_PASSWORD')
if (user && pass) {
credentials {
username = user
password = pass
}
}
}
}
A settings.gradle that turns on the local cache for developers and a shared HTTP remote cache that every build reads but only CI, identified by the CI environment variable, can push to.
What other cheap wins are worth checking first?
These settings don't change how your code is structured, so they cost less to try than splitting modules. Work through them roughly in this order:
| Technique | Effort | What it saves | Main limitation |
|---|---|---|---|
org.gradle.parallel=true |
One line in gradle.properties |
Runs tasks from independent projects at the same time | No gain in a single-module build. Exposes projects that share mutable state |
| Warm Gradle daemon | Mostly default locally | JVM startup, JIT warm-up and cached build-script classes | Ephemeral CI agents start cold every run |
| Less configuration-time work | Script review | Fixed overhead paid on every invocation, even help |
Needs discipline: lazy task registration, no I/O or dependency resolution during configuration |
| Configuration cache | Flag plus fixes | Skips the configuration phase entirely when inputs are unchanged | Every plugin and script must be compatible. Incompatible ones fail the build or force you to disable it |
| Bigger CI machines | Budget request | More cores and memory for parallel work | Pays for redundant work instead of removing it |
Measure configuration time before you change anything. In a large build, configuration time grows with the number of projects and with careless scripts, and it is paid even when nothing needs compiling.
Larger hardware helps when the build is already parallel and CPU-bound. In that case it is a reasonable stopgap while you restructure. It does little for a single-module monolith, because one compileJava task cannot spread across idle cores. If engineers rebuild code they didn't change, faster machines only make that wasted work finish sooner, and the cost of that waste keeps growing with the codebase.
org.gradle.parallel=true
org.gradle.daemon=true
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g
org.gradle.configuration-cache=true
org.gradle.configuration-cache.problems=warn
A gradle.properties file that turns on parallel project execution, keeps the daemon in use with an explicit heap size, and enables the configuration cache in warn mode during migration, with a comment showing how to measure configuration overhead first using ./gradlew help --profile.
How much engineering time can build avoidance save?
A useful way to put a number on this waste is to count module-builds rather than minutes. Each module that misses the cache costs its compile and test time. Each module served from the cache costs close to nothing.
Illustrative estimate (assumed numbers, not a benchmark). The assumed inputs are:
- 40 modules.
- A typical change edits 1 module, and 6 downstream modules depend on it (fan-out F = 6).
- Each module takes 30 s to compile and 60 s to test, so t = 90 s.
- Everything runs serially. Parallel execution shrinks the absolute times, but the ratios between scenarios stay the same.
Modules executed = (1 + F) + (N − 1 − F) × (1 − h), where N is the module count and h is the cache hit rate.
Serial CI time = modules executed × t
| Scenario | Modules executed | Serial CI time |
|---|---|---|
| Single module (monolith) | 40 | 60 min |
| 40 modules, cold cache (h = 0) | 40 | 60 min |
| 40 modules, F = 6, h = 0.5 | 23.5 | ~35 min |
| 40 modules, F = 6, h = 0.9 | 10.3 | ~15.5 min |
| 40 modules, F = 15, h = 0.9 | 18.4 | ~27.5 min |
Two things follow from the table. First, splitting into modules saves nothing until the cache is actually hit. Second, high fan-out erodes much of the gain even when the hit rate is good. Developers see the same effect locally: a change to a widely used module still triggers a long rebuild.
Weigh the savings against cost with this formula:
Payback (weeks) = refactor engineer-hours ÷ (hours saved per run × runs per week − weekly maintenance hours)
Assume a 160-hour refactor, 120 runs per week each saving 0.75 h of agent time, and 4 h per week maintaining build files. That gives a payback of about two weeks of CI time. However, agent hours are cheaper than engineer hours. The real case depends on how often people sit idle waiting for a build.
What are the alternatives?
Gradle's work-avoidance features are not the only way to shorten build times. Depending on where your baseline shows the time going, one of these may fit better or work alongside them:
- Throw hardware at it. Bigger or more CI agents reduce wall-clock time without touching the code. As described above, this pays for redundant work rather than removing it, and it does little for a single large module.
- Split the build across CI jobs. Running test suites or groups of modules on separate agents in parallel reduces wall-clock time per pipeline. It does not reduce the total compute spent, and each job pays its own startup and configuration cost.
- Run only the tests affected by a change. Test-selection approaches map changed code to the tests that exercise it. They target the
testshare of the build, which caching cannot help when inputs did change. The risk, noted in the trade-offs below, is missing dependencies that only appear at runtime. - Publish stable modules as binary artifacts. Moving rarely changed code into separately versioned libraries, consumed from an artifact repository, removes it from the main build entirely. The cost is a release process for those libraries and slower cross-cutting changes, because a change now spans a library release and a version bump.
- Use a different build tool. Maven builds Java projects through a fixed lifecycle and is widely used, but it does not offer the same per-task up-to-date checks and output caching that Gradle has out of the box. Fine-grained, hermetic build systems model the code as many small targets with fully declared inputs and support remote caching and remote execution. They can avoid more work than a module-level Gradle build, but migrating a large codebase to them is a substantial project and requires every input to be declared precisely.
- Do nothing structural. If the baseline shows a small, fast build, or one where most tasks are already skipped, the measurement step itself may be the only work needed.
In most large Gradle codebases, the cheap settings and a better module graph come first, because they reuse the existing build. A tool migration or artifact split is worth considering when the module graph cannot be untangled or when the build has outgrown what module-level caching can save.
When should you avoid these techniques, and what are the trade-offs?
Each of these techniques has a cost. Some of those costs are paid in correctness rather than minutes.
Module count. Every module adds a build file, dependency declarations to keep in sync, and configuration time. Split along real ownership or change boundaries. Beyond that point, you trade compile time for dependency-management friction.
Annotation processors. Replacing a non-incremental processor can mean migrating annotations and generated code across the whole codebase. First measure how often it actually forces full recompiles. If that is rare, the migration costs more than it saves.
Remote cache latency. A cache hit still costs a network round trip and a download. For small, cheap tasks, rerunning locally is often faster, so leave those tasks uncacheable.
Undeclared inputs. A task that reads an environment variable or file it never declared will produce cache hits with stale outputs. A slow build wastes time. A wrong artifact that passed CI ships bugs.
Cache trust. If any developer machine can write to the shared cache, one compromised laptop can inject binaries into everyone's builds. Restrict writes to CI.
Tests. Caching skips tests whose inputs did not change. It does nothing for slow or flaky tests. Change-based test selection can miss runtime dependencies such as reflection or configuration files.
Plugins. Older or custom plugins that access the project model at execution time can block the configuration cache.
Release builds. These usually run clean, so they still pay the full cost.
Skip this work if the codebase is small or most tasks are already cache hits.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to speed up large java build, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.