What does org.gradle.configuration-cache do, and how does it differ from the build cache?

## The two phases of a Gradle build Every build has a **configuration phase** (evaluate settings + all build scripts, register and wire tasks, build the task graph) and an **execution phase** (run the selected tasks). On large builds, configuration alone can take many seconds on *every* invocation. ## What the configuration cache stores `org.gradle.configuration-cache=true` serializes the **outcome of configuration**: the task graph and the state each task needs to execute. On the next run, if the cache inputs are unchanged, Gradle **skips the configuration phase entirely** and deserializes the graph, jumping straight to execution. It also runs configuration of independent projects in parallel and caches across invocations. ## Cache invalidation inputs The entry is keyed on things the build *read* during configuration: the set of requested tasks, build script contents, system properties / environment variables consumed, and declared input files. Reading an undeclared environment variable or file at configuration time is a problem the cache must track, which is why Gradle restricts how external state is accessed. ## Why it imposes rules (and how it differs from build cache) | | Configuration cache | Build cache | |---|---|---| | Caches | the task graph / configuration result | task **outputs** (execution) | | Phase | configuration | execution | | Key | requested tasks + scripts + read inputs | per-task input hash | | Enable | org.gradle.configuration-cache | org.gradle.caching | Because tasks are deserialized without re-running configuration, a task may **not** reach back into live `Project`/`Gradle` objects at execution time. Forbidden patterns include calling `task.project` in a task action, referencing other tasks directly, or reading mutable build state. The fix is to capture everything a task needs as **inputs** up front — typically via `Property`/`Provider` wiring and `ValueSource` for external state (files, env, command output). ```kotlin // Capture external state cleanly for the configuration cache abstract class GitShaValueSource : ValueSource<String, ValueSourceParameters.None> { override fun obtain(): String = ProcessBuilder("git", "rev-parse", "HEAD").start() .inputStream.bufferedReader().readText().trim() } val gitSha = providers.of(GitShaValueSource::class) {} tasks.register("printSha") { val sha = gitSha // captured as input, CC-safe doLast { println(sha.get()) } } ``` ## Enabling and diagnosing - Persistent: `org.gradle.configuration-cache=true`. - Per build: `--configuration-cache` (and `--no-configuration-cache`). - Strictness: `org.gradle.configuration-cache.problems=warn` downgrades problems to warnings during migration; Gradle writes an HTML report listing incompatibilities. ## Relationship to other flags It composes with `org.gradle.parallel` and `org.gradle.caching` — together they cut both configuration and execution time. Configuration cache effectively *requires* the decoupling that parallel execution also wants, so adopting it tends to harden a build for both.