0.19.0: one resolver for a member's tool, payloads installed on request, and a toolchain a build program states (#41)

[speak-agent]

Summary

A member that runs a program answers one question before it can plan anything: which program. Each member answered it its own way — an option here, a variable there, a silent PATH fallback in two members and a refusal of PATH in two others — and a tool named in build.mcpp did not stop the declared payload from being downloaded. On the engine of mcpp-community/mcpp#755 this release answers it once, for every member.

mcpp.plugins.tool (in plugins-core)

One order, written once:

1. the build program's choice — o.cmake = "/usr/bin/cmake", tool::root(dir), tool::on_path();
2. the variable that member has always read (MCPP_SLANGC, MCPP_GLSLC, MCPP_GLSLANG);
3. the engine's override — [xlings.overrides], MCPP_XLINGS_OVERRIDE_<NS>_<NAME>, config.toml;
4. the declared payload, asked for here when it is declared provision = "on-request".

A choice never asks for the payload, which is what makes "the build program names its own tool" mean "the payload is not downloaded". Every answer is recorded with mcpp::decision, so a build reports the source and mcpp why tool <name> can answer, and describe_missing is the one refusal text that lists every way to name the tool.

An option field is a tool::choice, which a string constructs: o.cmake = "/usr/bin/cmake" keeps working, and the build.mcpp line that wrote it is what the build reports.

Members

• deps-cmake, deps-archive, deps-vcpkg, rules-spirv, rules-slang, rules-sycl, dist-appimage, dist-wix and rules-qt resolve their tools through the resolver.
• rules-cuda, rules-hip, rules-ascendc and dist-apk gain the options they had none of: toolkit, and for dist-apk the six payloads it runs.
• deps-cmake, deps-archive, deps-vcpkg, dist-appimage and dist-apk's bundletool declare their payloads provision = "on-request": an ordinary Linux build no longer installs appimagetool, an --format apk build no longer installs bundletool, and a project that names its own cmake downloads none.
• rules-spirv and rules-slang keep their PATH fallback behind a warning that names the choice to write instead, until 2027-04-01 (SPEC-007 R6.2).

mcpp.plugins.toolchain (feature plugins-toolchain)

The builders a root build program states the build toolchain with, in the toolchain phase of a project whose [toolchain] says configure = "build.mcpp": layout, prefixed, compose, from_env_script (a vendor SDK's environment-setup-*), with_launcher, with_sysroot, with_tool, managed, env, configure(fn) and use(d).

Engine floor

2026.10.1.3, the release whose protocol 15 states where each tool and payload comes from. The per-member floors in the README and the member documents are raised for the members that use it.

Closes #41

Test plan

• tests/plugin-logic: 27 cases pass, five of them new for the resolver — a choice asks for no payload, an override answers, a pending payload is requested and plans nothing, the payload answers last, and the refusal lists every way to name the tool. mcpp.plugins.testing gained xpkg_source, xpkg_program and phase so a case can state them.

• 11 consumer fixtures build against the engine branch; all-rules-compile compiles every rule and dist member; a default build's output is unchanged.

• New CI criterion tool-sources on all three platforms: with nothing named the member asks for the payload; with the build program naming a cmake the payload is not asked for and the source is reported; an override says the same and is reported as custom; --managed-only refuses both. It reads resolution.json, so it holds on a runner that already has the payload installed.

• A defect this found in the resolver: it used the compile-time executable suffix, so a case stating a Windows row on Linux could not find vcpkg.exe. Both spellings are tried on every host now, as rules-spirv has always done.

• Two defects the other platforms found, each with a measurement:

  • mcpp.plugins.testing left the real build's MCPP_XPKG_* in the environment. These cases run inside a build program, which the engine gives one _DIR, _PROGRAM and _SOURCE per payload its package declares — pending among them, for a payload declared provision = "on-request" that nothing asked for. Eight vcpkg cases therefore asked for xim:vcpkg and planned nothing wherever the payload was not installed: 19 of 27 on macOS arm64 and on Windows, 27 of 27 on a machine that had it. Measured both ways on one binary with the inherited value present: 19 of 27 before, 27 of 27 after. The keys are enumerated, not listed, because they are derived from package names.
  • Darwin exports environ to a main program only, so the first fix failed to compile there; _NSGetEnviron() is used instead.

• The spirv fixture's step asserted on a status line while capturing stdout alone. mcpp writes narration to standard error from 2026.10.1.1, so the log was empty and the step reported that the rule had not run while it had.

• An ecosystem reading this release produces: xim:vcpkg no longer appears in the macOS or Windows rules job logs, where main provisions xim:vcpkg@>=2026.7.27. The saving is real, and it is also what exposed the first defect above — installing one payload less makes a test environment's assumption visible.

Order

This PR needs mcpp 2026.10.1.3, which is mcpp-community/mcpp#758. CI here is pinned to that release and goes green once it is published; until then it is validated by dispatching this workflow with mcpp_source_ref=feat/build-sources, which builds the engine from that branch.