skip to content

What is the buildCache {} block in settings.gradle.kts for, and how does it relate to org.gradle.caching=true?

level: middleimportance: must knowfreq 50%

answer

  1. switch vs. configuration
  2. buildCache {} lives in settings.gradle.kts
  3. evaluated before any project configured
  4. global switch gates all backends
  5. default local cache without any block

basics

~10 s

org.gradle.caching=true is the on/off switch; the buildCache {} block in settings.gradle.kts configures the cache backends (local and remote). The switch decides whether caching runs; the block decides where outputs are stored.

solid answer

~40 s

There are two distinct concerns. `org.gradle.caching=true` (or `--build-cache`) is the **enablement switch** — it decides whether the build cache machinery runs at all. The **`buildCache {}` block in `settings.gradle.kts`** is where you *configure the backends*: `local { ... }` for the on-disk directory cache and `remote(...) { ... }` for a shared cache. It lives in `settings.gradle.kts` (not `build.gradle.kts`) because the cache configuration must be known before any project is configured. If you set neither, enabling caching still gives you the default local cache. You typically open the `buildCache` block when you need to tune the local cache or wire up a remote one — but you do not need it merely to switch caching on.

code

kotlin · 8 lines
kotlin
// settings.gradle.kts
buildCache {
    local {
        isEnabled = true
    }
}
// gradle.properties
// org.gradle.caching=true   <- the actual on/off switch

go deeper

for a junior

Know that the switch (org.gradle.caching) turns caching on and the buildCache block configures where entries are stored.

for a middle

Explain the orthogonality of switch vs. configuration and that the block lives in settings.gradle.kts.

for a senior

Articulate why settings-script timing matters (configuration-time caching) and that the global switch gates all backends.

for a principal

Position the block as the integration point for org-wide remote cache strategy while the committed switch sets the default policy.

## Two separate questions Enabling the build cache involves answering two independent questions: 1. **Should caching run?** — answered by the enablement switch: `org.gradle.caching=true` in `gradle.properties`, or `--build-cache` on the command line. 2. **Where should cache entries live?** — answered by the **`buildCache {}` configuration block**. The two are orthogonal. You can enable caching and never touch the block (you get the default local cache). You can also declare the block but leave caching disabled — the configuration sits dormant until the switch flips on. ## Why the block lives in settings.gradle.kts The `buildCache {}` block belongs in **`settings.gradle.kts`** (the *settings* script), not a project `build.gradle.kts`. Gradle evaluates the settings script first, before configuring any project, and the cache backend must be ready by then because configuration-time work can already be cached. Putting it in a build script is a common mistake and will not work the way you expect. ## What goes inside ```kotlin // settings.gradle.kts buildCache { local { isEnabled = true // the on-disk directory cache (default on) } remote<HttpBuildCache> { url = uri("https://cache.example.com/cache/") isPush = false // pull by default; CI typically pushes } } ``` Note the per-backend `isEnabled` / `isPush` flags here are about *which backend* is active, layered under the global `org.gradle.caching` switch. If the global switch is off, none of these backends do anything. (The detailed semantics of the local and remote backends are their own topics; here the point is simply that the block is the *configuration* counterpart to the *enablement* switch.) ## Mental model - `org.gradle.caching=true` = the main breaker. - `buildCache {}` = the wiring diagram for the outlets. Flip the breaker to power the system; edit the wiring to decide where the power goes. Powering on with no custom wiring still lights the default local outlet.

  • Why must buildCache {} be in settings.gradle.kts rather than build.gradle.kts?
    Because the settings script runs before any project is configured, and the cache backend must be available for configuration-time caching. A project build script is evaluated too late.
  • Do you need a buildCache {} block to enable caching?
    No. Setting org.gradle.caching=true alone gives you the default local cache. The block is only needed to customize local settings or add a remote backend.

saying these in an interview costs you the question

  • Placing buildCache {} in build.gradle.kts instead of settings.gradle.kts.
  • Thinking the buildCache {} block by itself enables caching when org.gradle.caching is off.
  • Conflating the global enablement switch with the per-backend isEnabled flags.

context

resolving links…