Stopping the 'Clean Build' Cycle: Implementing Gradle Build Caching

The Cost of the Clean Build

Many development teams fall into the habit of running ./gradlew clean build whenever a build behaves unexpectedly or before pushing to CI. This is often a symptom of distrust in the build system's ability to track changes. The problem is that as a project grows, a full clean build becomes a productivity killer, wasting minutes—or hours—recompiling code that hasn't changed.

The solution isn't just relying on Gradle's default "up-to-date" checks, which only work if the build directory remains intact. To truly optimize, you need the Gradle Build Cache. Unlike basic incremental builds, the build cache allows Gradle to reuse outputs from any previous invocation, even if the build folder was deleted or the task was executed on a different machine.

Up-to-Date Checks vs. Build Cache

It is common to confuse these two mechanisms, but they operate differently:

• Up-to-Date Checking: Gradle looks at the local build folder. If the inputs haven't changed since the last run in that specific directory, it marks the task as UP-TO-DATE. If you run clean, this history is wiped.
• Build Cache: Gradle hashes the task inputs (source files, compiler flags, dependencies) to create a unique key. It then checks a local or remote directory for a stored output matching that key. If found, it restores the files, marking the task as FROM-CACHE.

Implementing a Local and Remote Cache Strategy

For a team to see real gains, you must move beyond the local cache. A Remote Build Cache allows your CI server to build a feature branch once and "share" those compiled classes with every developer on the team.

To enable this, add the following to your settings.gradle (or settings.gradle.kts) file. This configuration assumes you have a Gradle Enterprise or a compatible HTTP cache server:

buildCache {
    local {
        enabled = true
    }
    remote("https://gradle-cache.internal.company.com") {
        push = System.getenv("CI") != null // Only CI should push to the remote cache
        allowInsecureProtocol = false
    }
}

Critical Permission Logic

Notice the push logic above. Never allow local developer machines to push to the remote cache. If a developer has a local environment quirk (like a different JDK minor version or a custom system property) that affects a task's output, they could "poison" the cache. This would force every other team member to download a broken or incompatible artifact.

Verifying Cache Effectiveness

To verify that your cache is working, run your build from the terminal with the build cache flag enabled. You do not need root permissions for this, but you must have execution permissions for the Gradle wrapper.

# Run this from the project root
./gradlew assemble --build-cache

Look for the FROM-CACHE label next to your tasks in the console output. To test a cache hit after a wipe, run the following sequence:

1. Run ./gradlew assemble --build-cache (Initial run, populates cache).
2. Run ./gradlew clean (Deletes local build artifacts).
3. Run ./gradlew assemble --build-cache again.

If the tasks are marked FROM-CACHE instead of EXECUTED, the system is functioning correctly.

The "Cache Miss" Trap

The most common reason for cache misses is non-deterministic inputs. If a custom task embeds a timestamp, a build number, or an absolute file path into a generated file, the input hash changes every single time the task runs.

If you are writing custom tasks, ensure you use the @Input and @OutputDirectory (or @OutputFile) annotations correctly. A task missing these annotations is not cacheable and will force all downstream tasks to re-execute, creating a bottleneck in your pipeline.

Trade-offs and Limitations

While powerful, the build cache introduces its own overhead:

• Storage Growth: The .gradle/caches directory can grow rapidly. You may need to implement a cleanup policy for your remote cache server.
• Network Latency: If your remote cache is hosted in a different region than your developers, the time spent downloading a large artifact can occasionally exceed the time it would take to simply recompile it locally.