Which module cache invalidation signal does Swift use for private implementation changes?

Question

Swift's incremental build system caches compiled modules as .swiftmodule files to avoid recompiling unchanged dependencies. In recent Swift toolchains, the compiler evaluates file timestamps and dependency hashes to decide whether a cached module remains valid. A known area of uncertainty involves changes confined to a module's private implementation—such as adding an internal function—where the public interface hash stays identical. If that internal code is exposed through inlineable declarations, clients may embed the old implementation while the library binary expects new behavior, creating a potential correctness gap. The Swift project has not settled whether any source-level modification should force cache invalidation or whether interface-level hashes alone are sufficient, balancing build speed against safety.

Which invalidation heuristic does the Swift compiler apply when a dependency's private source changes but its public interface hash does not? Under what conditions does the module cache reuse a .swiftmodule despite modifications to non-public implementation that affect inlineable code? Is there a documented distinction between timestamp-based and hash-based staleness checks for this scenario?

Tasadduq Burney · Answer

Short answer
Swift invalidates a cached .swiftmodule whenever the *module signature* changes. The signature is built from two hashes:

Public‑interface hash – the hash of the module’s exported API.
Source‑file hash – a hash derived from the contents of every source file that belongs to the module.

Because the source‑file hash changes on any edit to any file in the module, a private change (e.g. adding an internal function) will bump the signature and force a recompilation, even if the public API is unchanged.
How the compiler decides
When the compiler starts a build it constructs a cache key that looks roughly like:
module‑cache‑key =  +  +

The module‑signature is a concatenation of the two hashes mentioned above. The compiler stores the compiled module under this key. On a subsequent build it recomputes the signature and compares it to the key in the cache. If they differ, the cached module is considered stale and is discarded (or a new entry is created).
What triggers a signature change?

Any modification to a file that is part of the module’s compilation unit. The compiler tracks all files that were compiled when the module was last built.
Changes to the module’s public interface (e.g. adding a public type or method) – this changes the public‑interface hash.
Changes to a private file that contains @inlinable declarations. Even if the change is not in the public API, the source‑file hash is recomputed, causing the signature to change.

In practice, this means that *every* source‑file change invalidates the cache, regardless of whether the change touches the public API. The only time the cache is reused is when the set of source files and their contents are identical to the last build.
Timestamp vs. hash based checks
Earlier Swift releases (prior to Swift 5.7) relied primarily on file timestamps in the cache key. Since Swift 5.7, the compiler has moved to content hashes for the source‑file component, providing stability across rebuilds that only change timestamps. The public‑interface hash remains a timestamp‑based value that is recomputed when the exported API changes. Thus, the current algorithm is a hybrid: timestamps are used for the public API, while content hashes guard against private changes.
Verifying the behaviour

Create a small package with a public API:
swift package init --type library
# Add a public struct and an internal function

Build once to generate the cache:
swift build

Dump the module to see the signature:
swift -dump-module -module-cache-path .build/Debug/ModuleCache MyModule

Edit an internal function and rebuild:
swift build

Dump again – the public‑interface hash will be the same, but the overall signature will differ, and the cache entry will be replaced.

To see the compiler’s cache decisions directly, use the -debug-module-cache flag. It prints whether a module was reused or recompiled and the reason.
When the cache might still be reused

If a change occurs in a file that the compiler never compiles as part of the module (e.g. a test file or a file excluded by swift build --build-path), the source‑file hash is unchanged, so the cache remains valid.
If you build with -whole-module-optimization off and the module is split into separate compilation units, changes only to a unit that is not used by the current target may not affect the cached module. This is an edge case and rarely occurs in normal library builds.

Conclusion
In current Swift toolchains, the compiler uses a combined hash of all source files (the source‑file hash) as part of the module‑cache key. Any change to a file belonging to the module forces cache invalidation, ensuring that inlineable code is regenerated and clients cannot embed stale implementations.
Diagnostic question
Do you build the module with -whole-module-optimization or any other flags that affect incremental compilation? This can influence when the compiler consults the cache.

Which module cache invalidation signal does Swift use for private implementation changes?

1 answer

Short answer

How the compiler decides

What triggers a signature change?

Timestamp vs. hash based checks

Verifying the behaviour

When the cache might still be reused

Conclusion

Diagnostic question

Your perspective belongs here.

0 question comments