skip to content

How do you configure runtime classpath normalization to ignore a volatile file like build-info.properties, and why is it needed?

level: middleimportance: must knowfreq 40%

answer

  1. settings.gradle(.kts) normalization block
  2. runtimeClasspath { ignore(...) }
  3. pattern matches path INSIDE the jar
  4. metaInf.ignoreAttribute for manifest
  5. fixes always-out-of-date / cache misses

basics

~10 s

In settings.gradle(.kts) use normalization { runtimeClasspath { ignore 'build-info.properties' } }. It strips that file from the runtime-classpath fingerprint so a volatile, build-stamped entry doesn't cause needless cache misses or out-of-date tasks.

solid answer

~40 s

Some files on the runtime classpath change on every build but don't affect behaviour — a `build-info.properties` with a timestamp/commit hash, a generated manifest, etc. Because `@Classpath` hashes jar **contents**, such a volatile entry flips the fingerprint each build, so cacheable tasks miss and up-to-date checks fail. **Runtime classpath normalization**, configured in `settings.gradle.kts`, lets you exclude those entries from the fingerprint: ```kotlin normalization { runtimeClasspath { ignore("build-info.properties") } } ``` The ignored pattern is matched against the path *inside* each jar/dir on the runtime classpath, so the file's presence and content no longer participate in the hash. This restores up-to-date-ness and build-cache hits without changing what's actually packaged. It's settings-level so it applies consistently to all projects. There's also `metaInf { ignoreAttribute(...) }` and `ignoreManifest()` for volatile manifest attributes.

code

kotlin · 9 lines
kotlin
// settings.gradle.kts
normalization {
    runtimeClasspath {
        ignore("build-info.properties")
        metaInf {
            ignoreAttribute("Implementation-Version")
        }
    }
}

go deeper

for a junior

Recognize the symptom (always out-of-date) and that a normalization ignore rule fixes it.

for a middle

Write the settings-level block correctly and explain matching is against the in-jar path.

for a senior

Weigh the correctness trade-off of ignoring and choose metaInf attribute-level ignores over blanket ones.

for a principal

Set org-wide conventions for which generated stamps are safe to normalize and enforce them across repos.

## The problem: volatile classpath entries Runtime-classpath fingerprinting (via `@Classpath`) hashes the logical contents of every jar and class dir. If one of those entries is regenerated on every build with embedded volatile data — a build timestamp, Git SHA, CI build number in a `build-info.properties`, or a `MANIFEST.MF` with `Build-Date` — then the fingerprint changes every single build. Consequences: - Cacheable tasks that consume the runtime classpath always **miss** the build cache. - Up-to-date checks always report **out-of-date**, so the work re-runs. The data is irrelevant to the task's *behaviour*, so this is pure waste. ## The fix: normalization rules Gradle lets you declare **normalization** rules — instructions that strip volatile parts out of the fingerprint *before* hashing. They live in `settings.gradle(.kts)` so they apply build-wide: ```kotlin normalization { runtimeClasspath { // path is matched relative to the root of each classpath entry (jar/dir) ignore("build-info.properties") ignore("**/*-version.txt") metaInf { ignoreAttribute("Implementation-Version") ignoreProperty("app.build.timestamp") } } } ``` - `ignore(pattern)` — drops matching files entirely from the fingerprint (Ant-style globs). - `metaInf { ignoreAttribute(...) }` — drops a single volatile `MANIFEST.MF` attribute while keeping the rest. - `metaInf { ignoreProperty(...) }` — drops a volatile key from properties files under `META-INF`. - `metaInf { ignoreManifest() }` / `ignoreCompletely()` — broader nukes when needed. ## Scope and matching - It applies to the **runtime** classpath fingerprint only — compile classpaths already ignore most volatile data via ABI extraction. - The pattern matches the path *inside* each entry (e.g. inside the jar), not the on-disk path of the jar itself. - Because it's in `settings`, it's global and consistent across modules and across machines, which is what you want for cache correctness. ## Don't over-ignore Ignoring a file means changes to it will NOT trigger reruns. If that file ever does affect behaviour, you've created a correctness hole — the task can be stale. Scope ignores narrowly to truly volatile, behaviour-irrelevant entries.

  • Why is the normalization block placed in settings.gradle rather than a build.gradle?
    So the rules apply consistently to every project in the build and to all machines sharing the cache. Cache keys must agree across modules, so a global declaration avoids per-module drift.
  • What is the risk of ignoring a file in normalization?
    If that file actually does influence behaviour, the task can become stale — Gradle won't re-run it when the file changes. Only ignore truly volatile, behaviour-irrelevant entries.
  • Does ignore() match the on-disk jar path or the path inside the jar?
    The path inside each classpath entry (e.g. inside the jar), not the absolute path of the jar on disk.

  • Putting the normalization block in build.gradle of a single module and expecting global effect.
  • Thinking ignore() removes the file from the packaged artifact — it only removes it from the fingerprint.
  • Over-broadly ignoring files that actually affect runtime behaviour.

context