0.19.0: one tool-source resolver for every member, on-request payloads, and a toolchain description library

[speak-agent]

Motivation

Fifteen members declare xlings payloads, and each decides on its own where its tool comes from: some take an option, some an environment variable, rules-spirv and rules-slang fall back to PATH silently (contrary to SPEC build-plugins R6.2), dist-wix and dist-appimage refuse PATH, and rules-cuda, rules-hip, rules-ascendc and dist-apk offer no way to name a tool at all. A tool named in build.mcpp does not prevent the declared payload from being downloaded (mcpp-community/mcpp#755).

Design

Recorded in .agents/docs/2026-10-01-ecosystem-build-plugin-framework-design.md (v3). For 0.19.0, on the engine of mcpp#755:

• mcpp.plugins.tool (in plugins-core): one resolver for every member -- a tool::choice option type (constructible from a string, so o.cmake = "/usr/bin/cmake" keeps working), one priority order (the build program's choice, a member's legacy variable, the engine's override, the payload requested on demand), one refusal text, and a decision recorded with the build.mcpp line that made it.
• mcpp.plugins.toolchain (feature toolchain): builders of a toolchain description for the root build program's toolchain phase (layout, prefixed, compose, from_env_script, with_launcher, managed).
• Every member that runs a payload tool migrates to tool::resolve; members whose tools are needed only for some builds declare their payloads provision = "on-request"; the silent PATH fallbacks become warnings.
• Documentation and fixtures for each source.

[speak-agent]

Released as 0.19.0

One resolver answers, for every member, where the tool it runs comes from: mcpp.plugins.tool, in one order — the build program's choice, the member's legacy variable, the engine's override, then the declared payload, asked for there 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> answers from the same record; describe_missing is the one refusal text, listing every way to name the tool.

Thirteen members use it: deps-vcpkg, deps-cmake, deps-archive, rules-cuda, rules-hip, rules-sycl, rules-ascendc, rules-slang, rules-spirv, rules-qt, dist-apk, dist-appimage, dist-wix. Five entries are now installed on request: xim:vcpkg, xim:cmake (twice), xim:appimagetool, xim:bundletool.

mcpp.plugins.toolchain (feature plugins-toolchain) builds the statement a root build program makes in a toolchain phase: layout, prefixed, managed, from_env_script, newest_under, env, the with_* refinements, configure(fn) / use(d).

What this release measured in its own CI, beyond the 28 plugin-logic cases and the consumer fixtures:

• xim:vcpkg no longer appears in the macOS or Windows rules job logs, where main provisions xim:vcpkg@>=2026.7.27. That saving is also what exposed a defect in the test kit: it left the real build's MCPP_XPKG_* in the environment, including pending for an on-request payload nothing had asked for, so eight vcpkg cases planned nothing wherever the payload was absent — 19 of 27 on macOS and Windows, 27 of 27 where it was installed. Measured both ways on one binary: 19 → 27.
• rules-sycl's migration conflated the payload root with the program, so -L pointed at the compiler's path and the SYCL consumer failed with unable to find library -lsycl. Fixed, and every migrated member audited for the same swap.
• A stated program path now follows the host's own executable-suffix rule: on Windows command -v cmake answers a path with no .exe, which the resolver had refused.

Engine floor: mcpp 2026.10.1.3 (protocol 15, mcpp-community/mcpp#755).

Released

• Merged as 7f5f0ed after the PR run came back green on all four jobs against the released mcpp 2026.10.1.3 (Linux consumers, macOS rules, Windows rules, Windows deps).
• Tagged v0.19.0, released on GitHub, and mirrored to GitCode (mcpp-res/mcpp-plugins@0.19.0) with the local gtc; the mirrored asset was downloaded back and cmp-verified byte-identical to the GitHub archive, sha256 2dd13d81cffd77babdb1070d24659348d2f699c634981f66e3e97206389c5c7e.
• Registered in mcpp.plugins 0.19.0 mcpplibs/mcpp-index#505 (56990ac), whose workspace matrix rebuilds every member against this version; the index artifact is published, so clients resolve it.
• fix(qt): track files referenced by QRC resources #42 was reviewed and merged first, so its qrc_files fix is in this release rather than displaced by it. Measured before merging: 22 of 23 cases without the fix, with both resource assertions failing, and 23 of 23 with it.

Verified against the released artefacts in xlings subos eco-1001, through the CN mirror, in a private MCPP_HOME: PASS s755_plugins -- a named cmake is used and the payload is not asked for, alongside the two engine scenarios (3 passed, 0 failed).

docs/tool-sources.md is the reference for both audiences; its chapter 3 gives each way of naming a tool as a complete build.mcpp, every one of them compiled against this release before being written down.