Why can running external processes break Gradle's configuration cache, and how do ExecOperations and an Exec task differ in this regard?

## What the configuration cache is Gradle's **configuration cache** serializes the fully-configured task graph after the configuration phase and reuses it on later builds, skipping configuration entirely. For this to be sound, configuration must be **deterministic and free of live side effects** — it can't run processes, read mutable environment, or capture `Project` objects, because those can't be faithfully cached and replayed. ## Why exec breaks it Two distinct mistakes: 1. **Executing a process at configuration time.** Calling `project.exec { ... }` or `"git rev-parse HEAD".execute()` directly in a build script body (not inside a task action) runs during configuration. The configuration cache reports this as a problem because the result isn't a cacheable value — it's a live side effect. 2. **Holding a reference to `Project` (or `Task`, `Gradle`, etc.) at execution time.** Even custom tasks that try to run a process via `project.exec` from inside `@TaskAction` are invalid, because tasks must not reference `project` when they execute — `project` isn't serializable into the cache. ## The Exec task is fine A built-in `Exec` task is configuration-cache compatible because: - Its properties (`commandLine`, `args`, `workingDir`, `environment`) are configuration, captured as serializable values. - The actual process fork happens in the task's **action**, during the execution phase, not during configuration. So `tasks.register<Exec>(...) { commandLine(...) }` is the cache-safe way to shell out as a graph node. ## ExecOperations for custom tasks When you write your own task type and need to run a process in its action, inject the **`ExecOperations`** service: ```kotlin abstract class GenerateTask : DefaultTask() { @get:Inject abstract val execOps: ExecOperations @TaskAction fun run() { execOps.exec { commandLine("protoc", "--version") } } } ``` `ExecOperations` is a managed service Gradle can supply without a `Project` reference, so it's safe under the configuration cache. There's an analogous `FileSystemOperations` for copy/delete in custom tasks. ## Cache-safe values at configuration time If you genuinely need the *output* of a command as a configuration value (e.g. the git SHA to stamp into a manifest), use `ProviderFactory`: ```kotlin val gitSha = providers.exec { commandLine("git", "rev-parse", "--short", "HEAD") }.standardOutput.asText.map { it.trim() } ``` This returns a `Provider` whose value Gradle resolves in a cache-aware way (and re-checks for invalidation), rather than running the process eagerly during configuration. ## Takeaways - Built-in `Exec` task: safe — process runs at execution time. - Custom task running a process: inject `ExecOperations`, never touch `project` at execution time. - Need a command's output as config: use `providers.exec { ... }`, not a raw config-time exec.