OCaml compiler .cmt/.cmi and Dune cache invalidation on compiler flag changes

Direct Answer

Dune does not currently hash arbitrary compiler flags into the cache key for .cmi, .cmt, .cmo, or .cmx artifacts. It keys these targets on the source file content, the compiler version, and the declared dependencies discovered by ocamldep. As a result, changing flags such as -I, -ppx, -g, or -ccopt does not by itself trigger a rebuild of those metadata or object files. If you are seeing stale artifacts after a flag change, the likely explanation is that the flag is absent from the dependency graph, not that the compiler is reusing an invalid file.

Confirmed Behavior vs. Likely Explanation

Confirmed: Dune's action for OCaml modules includes the preprocessed source digest, the compiler executable identity, and the .ml.depends file contents. Likely: because flags passed via (flags ...) are not serialized into that action, they do not participate in cache validation. This is a known gap in how build systems represent compiler options as dependencies, and it remains an open design question rather than a documented, stable contract.

Criteria for a Flag-Sensitive Cache Key

A robust key would need to partition flags by the artifact they affect:

• Interface-affecting flags (must invalidate .cmi and .cmt): -I/-include-dir, -pp/-ppx, -principal/-no-principal, -rectypes/-no-rectypes, -short-paths, and warning flags that promote errors such as -warn-error. These change module resolution, the parsed AST, or the serialized type information.
• Codegen-affecting flags (must also invalidate .cmo/.cmx): all of the above plus -g, -O family, -ccopt, -float-const-prop, -unbox-closures, and inlining controls.

The key should normalize flag order, expand @response files, and be computed per build context (native, bytecode, cross-compiled).

Tracking Include Paths

Hashing the literal -I path strings is insufficient because the same string can resolve to different .cmi files as directories change. A better model treats each include directory as a content-addressed dependency: hash the set of .cmi files actually found along that path during compilation. This introduces a circular-dependency risk if those .cmi files are themselves built with incompatible flags, so the hash must be computed only after the transitive interface dependencies are stable.

Verification Steps

1. Run dune build --verbose before and after the flag change and compare whether the OCaml action for the target is re-executed.
2. Inspect the rule with dune rules _build/default/path/to/target.cmi to see the action and dependencies Dune has computed.
3. Use ocamlobjinfo _build/default/path/to/target.cmi to inspect the interface file; if it is unchanged after a flag that should alter types, the artifact was not rebuilt.

Because cache-key behavior evolves across Dune releases, the exact version matters. Which Dune version are you using, and did the flag change also modify the dune file stanza or only an environment variable?