0.4.0: every payload a compile reads is in the build graph

[speak-agent]

Every payload a compile reads is in the build graph

Two mechanisms carry that, and which one applies is decided by when the thing is known.

Discovered while the compiler runs: a shader's #include

a.input() is fixed when build.mcpp runs, before the compiler has read a line. A shader or kernel that includes another file therefore had no edge to it: editing that file rebuilt nothing and the build stayed green over a stale artifact. grep depfile rules/ returned nothing across all six rules.

Every spelling was measured against the tool, not read from its help text:

rule	driver	flag	what it actually wrote
spirv	glslangValidator	--depfile <f>	out.spv: scale.comp ./common.glsl
spirv	glslc	-MD -MF <f>	out2.spv: scale.comp common.glsl
slang	slangc	-depfile <f>	out.spv: <entry>.slang <included>.slang
cuda	nvcc	-MMD -MF <f>	n.o : k.cu \ common.cuh
hip / sycl	clang++	-MMD -MF <f>	c.o: k.cpp common.cuh
ascendc	bisheng	-MMD -MF <f>	k2.o: k.asc inc.h

ascendc is the one lane with no CI consumer — there is no Ascend runner and the toolkit is a 4 GB download — so "bisheng is clang-derived, so it should support it" would have shipped an unverified flag into the only rule nothing checks. The toolkit is on this machine, so it was asked.

-MMD and not -MD, matching what mcpp passes for its own C and GAS units: user includes only. -MD on BiSheng was measured pulling in fifty host headers under /usr/include, which makes an object depend on absolute host paths a shared build directory must not carry.

Discovered by nobody: .incbin

The assembler opens the embedded file at assembly time, and the generated .S's own text does not change when the payload does, so the object is assembled once. Reproduced against the published 0.3.0, in a sandbox, from packages resolved through the index:

before: bytes=1480
after:  bytes=1480      and `Finished dev in 0.06s` — nothing rebuilt at all

Asking the assembler does not fix it, and that was measured: the compiler driver's -MD is a preprocessor channel that never sees .incbin; GNU as names it in its own --MD; clang's integrated assembler has no dependency output of any kind (-Wa,-MD, -Wa,--dependency-file and clang -cc1as -dependency-file are all rejected). Tracking it that way would work under GCC and fail silently under Clang — worse than failing under both.

The fix is not a new channel. It is to stop writing the file at the wrong time.

An mcpp::action declares its inputs. Make the generation an action and the payloads its declared inputs, and the edge is an ordinary one, expressed with the graph primitive the engine already has. Prototyped before this was written: BYTES=64 -> 192, with no engine change at all.

Traced file by file: the payload's mtime moves, the .S's does not (its content is unchanged, so write_if_different leaves it), and the object's does — ninja reruns the action because a declared input changed, and without restat its outputs count as new. Remove the payload inputs and the object stops moving and the byte count stands still. Both directions measured.

What that required, and why each part is right on its own terms

1. mcpp.plugins.surface imports only std. It used to read mcpp::target_os(), mcpp::compiler() and mcpp::package_name(); those are parameters now. A generator that takes its inputs rather than reading its environment is the same code in a build program and in a program — and an action's command has to be a program. Measured before this: an ordinary build of this package failed with mcpp: failed to read compiled module.

2. mcpp-embed is built from this package, through tools = ["mcpp-embed"] on the same dependency edge that brings the rules in. Not published as a payload: docs/05 §2.14 gives the reason and it is not convenience — "the tool's version IS the dependency's version, so a protoc that does not match its runtime is not expressible. This is the problem with packaging the tool separately, and it is the failure mode that bites at run time rather than compile time." The generator and the declarations it writes are one decision.

3. src/declare.cppm is a second unit, carrying the build-program half: mcpp::action, mcpp::dep_bin, and the decision of which route a storage takes. It needs mcpp 2026.9.8.1, in which a package's host modules are ordered by their import graph rather than by their paths — before that, rules/ sorted before src/ and importing it failed. (mcpp-community/mcpp#589 is that fix, and its own account notes that this package's 700-line lib root was adopted because that sort was misread.)

Two actions rather than one, and that is a fact about inputs: the interface is a function of the item list, the body of the item list and the payloads. One action would rewrite the interface whenever a payload changed and rebuild every BMI importing it. (mcpp::action::provides is also per-action rather than per-output, so one action with three outputs and one provides makes the scanner report "already provided by" — measured.)

Only object needs any of it. header reaches the artifact through generated data headers the payload's own compiler already writes as action outputs; sidecar is never compiled at all — both checked rather than assumed. The default path builds no tool, and a consumer that never opts into object storage writes nothing extra.

Criteria

Four CI steps, all with the criterion on the artifact's bytes — not the exit code (the defective build exits 0) and not a log line (mcpp build passes ninja --quiet on a successful non-verbose build, so grepping for an edge's description is vacuous either way).

1. An edited shader reaches the artifact under every storage. The denominator is the point: header storage was already correct, so a run where only object fails names the mechanism, and a run where all three fail names the harness. The three storage steps that already existed assert structure — is there an .incbin, is the section aligned — and all three passed against 0.3.0 while the artifact was stale.
2. An edited include reaches the artifact, on the header fixture. Measured: run against object storage it fails when either mechanism is missing, so a red run would not say which.
3. Every rule declares a depfile, denominator from ls rules/*.cppm, so a seventh rule is counted the day it is added.
4. Object storage without the tool is refused, naming the fix. The tool is default-off, so the message is a contract: asserted on the three strings a reader needs — the tool, the key that supplies it, and the storage that needs none.

All four were run verbatim under bash -e with $GITHUB_WORKSPACE set, because this workflow cannot run until mcpp 2026.9.8.1 is published and a shell bug would otherwise cost a release cycle.

Also

• options::store changed shape, so this is a breaking release: 0.3.x → 0.4.0.
• storage::object requires item::payload_path, and now refuses without it. The constraint had been written in a comment with nothing enforcing it; that it holds today is a coincidence, not a guarantee.
• rules/spirv.cppm's comment on options::module_name said the default derives from the package directory, while the function it calls opens with "THE PACKAGE'S NAME. NOT ITS DIRECTORY'S."

Depends on mcpp-community/mcpp#589 being released: this CI downloads a released mcpp and pins MCPP_VERSION: 2026.9.8.1.