examples: 每个示例只写规则那一条边

规则包在 0.2.4 起自带它驱动的载荷,所以示例里那些 `[xlings.workspace]` 块是
在重复规则已经知道的事 —— 一份会悄悄过期的副本,因为规则会动而这些工程不会。

删掉的行就是使用者不必再写的行:cuda 五条、hip 七条、sycl 五条、cann 一条、
vulkan 一条、multi-backend 六条。

留下的两类,各有理由:

- `xim:mesa-lavapipe`(vulkan 与 multi-backend):它是**设备**不是构建工具。
  规则声明它会给每一个有 GPU 的消费者强加一个软件渲染器。规则声明它编译时
  用的,工程声明它运行时跑在上面的。
- `xim:cuda-nvcc`(仅 multi-backend 一行):整个仓库唯一一处覆盖示范。留着
  是为了让例外路径可见——离产物更近的声明赢,只装一个版本,而不满足规则所述
  下界的钉会被拒绝并点出两侧。

`compat:*` 运行期适配器全部保留:插件是一条 `[build-dependencies]` 边,它自己的
`[dependencies]` 有意不到达消费者的 target。

需要 mcpp 2026.9.6.6 与 mcpp:plugins 0.2.4。

Author: speak-agent

.github/tools/build_examples.sh

@@ -51,7 +51,7 @@ SKIP=(
     "examples/09-heterogeneous/hip/app|same, for the HIP payloads"
     "examples/09-heterogeneous/sycl/app|needs the dpcpp payload (over a gigabyte) and a device its runtime accepts"
     "examples/09-heterogeneous/vulkan/app|built AND RUN by the next step of this job, on the lavapipe payload, which needs no GPU"
-    "examples/09-heterogeneous/cann/app|its device leg needs the Ascend DRIVER, which a runner does not have: the kernel compiles and the object links, and then `libascend_hal.so` is missing, which is correct on a machine with no NPU. Its CPU leg does build -- and is not built here only because the plugins pin would make this job resolve a fifth rule package for one example. Covered by the measurements in its README"
+    "examples/09-heterogeneous/cann/app|its device leg needs the Ascend DRIVER, which a runner does not have: the kernel compiles and the object links, and then `libascend_hal.so` is missing -- and only that one, since 2026.9.6.6 models DT_RPATH inheritance. Correct on a machine with no NPU. Its CPU leg does build, and is not built here only because it would make this job resolve a fifth rule package for one example. Covered by the measurements in its README"
 )
 
 # Every ROOT manifest in the tree: a directory with an `mcpp.toml` that has no

examples/09-heterogeneous/README.md

@@ -102,7 +102,7 @@ working build stops working on another machine.
 |---|---|---|
 | engine | the graph, the identity, the axis | mcpp itself |
 | rule package | the spelling of one model | `mcpp.rules.cuda` in `mcpp:plugins` |
-| payload | the binaries, versioned by the project | `xim:cuda-nvcc`, `xim:dpcpp`, `xim:glslang` |
+| payload | the binaries, versioned by the rule and overridable by the project | `xim:cuda-nvcc`, `xim:dpcpp`, `xim:glslang` |
 | adapter | a built artifact's reach to something the host owns | `compat:cuda-driver`, `compat:vulkan-runtime`, `compat:sycl-runtime` |
 
 The adapter layer exists for one reason. An mcpp-built program runs under
@@ -112,9 +112,10 @@ NVIDIA driver, a Vulkan ICD — is reached by an index package that puts a
 directory on the artifact's runtime search path. A project declares it as an
 ordinary dependency and does not otherwise think about it.
 
-Everything else is a payload, so the version is the project's choice rather
-than the machine's, and no example here contains an absolute path or reads the
-host's toolkit.
+Everything else is a payload. Which package and how old it may be belongs to
+the rule; *exactly which version* is the project's to override and nobody's to
+discover from the machine. No example here contains an absolute path or reads
+the host's toolkit, and only `multi-backend/` names a payload version at all.
 
 ## Running them
 

examples/09-heterogeneous/cann/app/mcpp.toml

@@ -14,19 +14,22 @@ import_std = true
 # imports it as `mcpp.rules.ascendc`. `[build-dependencies]`, because a rule
 # package's library must never reach the target while its rule is wanted.
 [build-dependencies.mcpp]
-plugins = { version = "0.2.3", features = ["rules-ascendc"], host-module = true }
+plugins = { version = "0.2.4", features = ["rules-ascendc"], host-module = true }
 
-# The toolkit carries BOTH halves this lane needs, so it is one payload rather
-# than two:
+# NO [xlings.workspace]. `mcpp.rules.ascendc` declares `xim:cann-toolkit`
+# itself, gated on this accelerator and on the feature that selects the rule --
+# so a build that names no accelerator installs none of its 2.9 GB, and a
+# project that wants the lane writes the edge above and nothing else.
+#
+# The toolkit carries BOTH halves the rule needs, which is why it is one payload
+# rather than two:
 #
 #   <toolkit>/cann/<arch>-linux/ccec_compiler/bin/bisheng   the device compiler
 #   <toolkit>/cann/<arch>-linux/simulator/<SoC>/lib         38 SoCs, no hardware
 #
-# Gated on the accelerator: it is 2.9 GB installed, and `mcpp build` with no
-# accelerator has no use for it. That gating needs mcpp 2026.9.6.5; before it
-# the only spellings were "unconditionally" and "not at all".
-[target.'cfg(accelerator = "ascend")'.xlings.workspace]
-"xim:cann-toolkit" = "8.5.0"
+# The rule states `>=8.5.0` rather than an exact version: nothing here is
+# coupled to a driver, and that is the release the mixed-mode object and the
+# simulators arrive in. Needs mcpp 2026.9.6.6 and mcpp:plugins 0.2.4.
 
 [build]
 # `dav-2201` is the device architecture, the role `sm_89` plays for CUDA. The

examples/09-heterogeneous/cuda/README.md

@@ -70,17 +70,26 @@ is compiled, with `accel-mismatch` on the machine-readable channel.
 
 ## Where the toolkit comes from
 
-The project names it:
+The rule names it. This project writes one edge and no payload list at all:
 
 ```toml
-[xlings.workspace]
-"xim:cuda-nvcc"   = "12.9.86"
-"xim:cuda-cudart" = "12.9.79"
+[build-dependencies.mcpp]
+plugins = { version = "0.2.4", features = ["rules-cuda"], host-module = true }
 ```
 
-These are payloads, so the version is the project's choice and not the
-machine's. The rule package resolves them with `mcpp::xpkg_dir` and builds the
-whole invocation from what it finds — the compiler, the include directories
+`mcpp.rules.cuda` declares nvcc, cudart, cuRAND's headers, CCCL and the driver
+sentinel for itself, under `cfg(accelerator = "cuda")` and the feature that
+selects it — so a build that names no accelerator installs none of them. To use
+a different CUDA line, write the entry in this project and it wins:
+
+```toml
+[target.'cfg(accelerator = "cuda")'.xlings.workspace]
+"xim:cuda-nvcc" = "13.3.33"
+```
+
+One version is installed either way, and mcpp says which. The rule resolves
+what it declared with `mcpp::xpkg_dir` and builds the whole invocation from what
+it finds — the compiler, the include directories
 and the library search paths. No path in this example is absolute, and a build
 here touches nothing of the host's CUDA:
 

examples/09-heterogeneous/cuda/app/mcpp.toml

@@ -20,7 +20,7 @@ default = "llvm@22.1.8"
 # The rule that compiles the island lives in the official plugin collection,
 # selected by its feature; `build.mcpp` imports it as `mcpp.rules.cuda`.
 [build-dependencies.mcpp]
-plugins = { version = "0.2.1", features = ["rules-cuda"], host-module = true }
+plugins = { version = "0.2.4", features = ["rules-cuda"], host-module = true }
 
 # The driver's userspace library, reached through an index package that owns
 # the one hop mcpp needs: a directory on the artifact's runtime search path.
@@ -31,23 +31,17 @@ plugins = { version = "0.2.1", features = ["rules-cuda"], host-module = true }
 [dependencies.compat]
 cuda-driver = "2026.09.05"
 
-# The toolkit this project builds with, named rather than discovered. These
-# are PAYLOADS, so the version is the project's choice and not the machine's.
-# The 12.9 line is named on purpose: a runtime must not be newer than the
-# driver it will meet, and 12.x reaches every driver from r525 onward. The
-# rule package states the driver relation and mcpp compares it before the
-# first compile.
-[xlings.workspace]
-"xim:cuda-nvcc"         = "12.9.86"
-"xim:cuda-cudart"       = "12.9.79"
-# cuRAND's headers and CCCL. clang's CUDA wrapper includes
-# curand_mtgp32_kernel.h for every device unit, and that header includes
-# <nv/target> from CCCL, so the clang route needs both even though this kernel
-# calls neither; on a developer machine the host's /usr/include used to supply
-# them silently. 10.3.x and 12.9.27 are the 12.9 line.
-"xim:libcurand"         = "10.3.10.19"
-"xim:cuda-cccl"         = "12.9.27"
-"xim:libcuda-host-link" = { linux = "0.0.1" }
+# NO [xlings.workspace]. The toolkit is declared by the rule itself, under
+# `cfg(accelerator = ...)` and the feature that selects it, so this project
+# names the rule and nothing else. To pin a different version, write the same
+# entry here and it wins -- see `One package, one version` in
+# docs/05-mcpp-toml.md. Needs mcpp 2026.9.6.6 and mcpp:plugins 0.2.4.
+#
+# What the rule declares for this lane: nvcc, cudart, cuRAND's headers, CCCL and
+# the driver sentinel. The 12.9 line is an EXACT default rather than a floor,
+# because a runtime must not be newer than the driver it will meet -- 12.x
+# reaches every driver from r525 onward and 13.x raises that to r580, which is a
+# property of the machines the artifact will run on.
 
 [build]
 # What this build compiles device code FOR. Written once, here: the rule

examples/09-heterogeneous/hip/app/mcpp.toml

@@ -20,7 +20,7 @@ import_std = true
 default = "llvm@22.1.8"
 
 [build-dependencies.mcpp]
-plugins = { version = "0.2.1", features = ["rules-hip"], host-module = true }
+plugins = { version = "0.2.4", features = ["rules-hip"], host-module = true }
 
 # The driver's userspace library. HIP reaches the device through the CUDA
 # runtime here, so this is the same one hop the CUDA consumer needs: mcpp's
@@ -30,24 +30,16 @@ plugins = { version = "0.2.1", features = ["rules-hip"], host-module = true }
 [dependencies.compat]
 cuda-driver = "2026.09.05"
 
-# The payloads. `hip-nvidia` is headers only -- on this platform that is all
-# HIP is -- and the four CUDA entries are the back end it compiles through.
-# cuRAND and CCCL are on the list for the reason the CUDA consumer records:
-# clang's CUDA wrapper includes curand_mtgp32_kernel.h for every device unit
-# and that header includes <nv/target>, so a unit that calls neither still
-# needs both.
-[xlings.workspace]
-"xim:hip-nvidia"        = "7.2.4"
-"xim:cuda-nvcc"         = "12.9.86"
-"xim:cuda-cudart"       = "12.9.79"
-"xim:libcurand"         = "10.3.10.19"
-"xim:cuda-cccl"         = "12.9.27"
-# `nvidia_hip_runtime_api.h` includes <cuda_profiler_api.h> at its second line,
-# and CUDA ships that header in its own component. A machine with a host CUDA
-# installation finds it in /usr/include without saying so, which is how this
-# entry came to be missing from a build that worked.
-"xim:cuda-profiler-api" = "12.9.79"
-"xim:libcuda-host-link" = { linux = "0.0.1" }
+# NO [xlings.workspace]. `mcpp.rules.hip` declares the payloads it drives:
+# `hip-nvidia` (headers only -- on this platform that is all HIP is) plus the
+# CUDA back end it compiles through, including `cuda-profiler-api`, which
+# `nvidia_hip_runtime_api.h` includes at its second line. A machine with a host
+# CUDA installation finds that header in /usr/include without saying so, which
+# is how the entry came to be missing from a build that worked -- and it is now
+# the rule's business rather than every consumer's.
+#
+# To pin a different version, write the same entry here and it wins. Needs mcpp
+# 2026.9.6.6 and mcpp:plugins 0.2.4.
 
 [build]
 # Two chunks: the programming model, and the device. A device is spelled once

examples/09-heterogeneous/multi-backend/README.md

@@ -47,11 +47,18 @@ glob out the way `--no-accel` leaves both out, and the `cfg(accelerator =
 the two halves stay together. Only an accelerator this build *does* name whose
 architecture it does not cover is refused (mcpp 2026.9.6.5).
 
-**Nothing is installed for a device this build did not name.** The payloads sit
-under `[target.'cfg(accelerator = ...)'.xlings.workspace]`, so `mcpp run`
-fetches neither the CUDA toolkit nor the shader compiler. That gating needs
-mcpp 2026.9.6.5; before it, the only spellings available were "unconditionally"
-and "not at all", and the cheapest build paid for the most expensive one.
+**Nothing is installed for a device this build did not name.** The payloads are
+declared by the two rules, under `cfg(accelerator = ...)` and the feature that
+selects each — so `mcpp run` fetches neither the CUDA toolkit nor the shader
+compiler. That gating needs mcpp 2026.9.6.5; before it, the only spellings
+available were "unconditionally" and "not at all", and the cheapest build paid
+for the most expensive one.
+
+**This is also the one example that overrides a rule's default.** One line names
+`xim:cuda-nvcc`, and it is kept to show the escape hatch working: the
+declaration nearer the artifact wins, one version is installed, and a pin that
+failed a floor the rule stated would be refused naming both sides. Every other
+example writes the rule edge and nothing else.
 
 ## The CUDA leg takes the clang route
 

examples/09-heterogeneous/multi-backend/mcpp.toml

@@ -40,7 +40,7 @@ default = "llvm@22.1.8"
 # The rules are declared unconditionally because `build.mcpp` imports them
 # unconditionally -- each returns immediately when its own backend is absent.
 [build-dependencies.mcpp]
-plugins = { version = "0.2.2", features = ["rules-cuda", "rules-spirv"], host-module = true }
+plugins = { version = "0.2.4", features = ["rules-cuda", "rules-spirv"], host-module = true }
 
 # ── the payloads, gated on the device they are for ──────────────────────────
 #
@@ -65,20 +65,21 @@ plugins = { version = "0.2.2", features = ["rules-cuda", "rules-spirv"], host-mo
 # to 13.x fixes that and raises the driver floor to r580, which is a machine
 # requirement rather than a project decision. The clang route never includes
 # that header and imposes no such floor.
+# ONE ENTRY, AND IT IS THE ONLY OVERRIDE IN THIS REPOSITORY'S EXAMPLES.
+#
+# `mcpp.rules.cuda` declares the whole toolkit -- nvcc, cudart, cuRAND, CCCL and
+# the driver sentinel -- so the four beside this one are gone and this project
+# would build with no `[xlings.workspace]` at all. The line is kept to show the
+# escape hatch working: the declaration nearer the artifact wins, one version is
+# installed either way, and a pin that failed a floor the rule stated would be
+# refused naming both sides.
+#
+# Which CUDA line matters here is what makes it a plausible override rather than
+# a contrived one: a runtime must not be newer than the driver it will meet, so
+# a project whose machines are older or newer than the rule's default is exactly
+# the project that should say so.
 [target.'cfg(accelerator = "cuda")'.xlings.workspace]
-"xim:cuda-nvcc"         = "12.9.86"
-"xim:cuda-cudart"       = "12.9.79"
-# clang's CUDA wrapper includes a cuRAND header for every device unit, and that
-# header includes <nv/target> from CCCL. Neither is called by this kernel; on a
-# developer machine the host's /usr/include used to supply them silently.
-"xim:libcurand"         = "10.3.10.19"
-"xim:cuda-cccl"         = "12.9.27"
-
-# The host-link stub is Linux-only, and the OS goes in the PREDICATE rather
-# than in the value: a value carrying platform keys under an already-predicated
-# table would state the condition twice and let the two disagree.
-[target.'cfg(all(accelerator = "cuda", linux))'.xlings.workspace]
-"xim:libcuda-host-link" = "0.0.1"
+"xim:cuda-nvcc" = "12.9.86"
 
 # The driver's userspace library, reached through an index package rather than
 # the host: mcpp's private loader does not consult /usr/lib, so a statically
@@ -88,11 +89,12 @@ plugins = { version = "0.2.2", features = ["rules-cuda", "rules-spirv"], host-mo
 [target.'cfg(accelerator = "cuda")'.dependencies.compat]
 cuda-driver = "2026.09.05"
 
+# The shader compiler is NOT here: `mcpp.rules.spirv` declares `xim:glslang` for
+# itself. What stays is a DEVICE -- a Vulkan driver that is always present
+# because it is the CPU, which is what makes the Vulkan leg runnable on a
+# machine with no GPU, and what every CI runner in this ecosystem is. A rule
+# declares what it needs to COMPILE; a project declares what it needs to RUN.
 [target.'cfg(accelerator = "vulkan")'.xlings.workspace]
-# The shader compiler, and a Vulkan driver that is always present because it is
-# the CPU. The second is what makes the Vulkan leg runnable on a machine with
-# no GPU, which is what every CI runner in this ecosystem is.
-"xim:glslang"       = "15.1.0"
 "xim:mesa-lavapipe" = "26.2.1"
 
 # The Khronos loader, built by the index rather than taken from the host, and

examples/09-heterogeneous/sycl/README.md

@@ -47,13 +47,17 @@ engine orders them by the graph rather than by declaration order.
 
 Without the second, this program links, starts, and finds no kernel.
 
-## Three payloads, and what each one closes
+## Five payloads, and what each one closes
+
+This project declares none of them. `mcpp.rules.sycl` does, under the feature
+that selects it and the accelerator it serves:
 
 ```toml
-[xlings.workspace]
-"xim:dpcpp"     = "7.1.0"      # the compiler: its clang has the SYCL front end
-"xim:gcc"       = "15.1.0"     # the C++ standard library the unit compiles against
-"xim:cuda-nvcc" = "12.9.86"    # the NVIDIA back end's libdevice
+"xim:dpcpp"         = ">=7.1.0"   # the compiler: its clang has the SYCL front end
+"xim:gcc"           = "15.1.0"    # the C++ standard library the unit compiles against
+"xim:glibc"         = ""          # …and the C library underneath it, unpinned
+"xim:linux-headers" = ""
+"xim:cuda-nvcc"     = "12.9.86"   # the NVIDIA back end's libdevice, only when the accel names cuda
 ```
 
 `xim:gcc` is not a second toolchain. Left alone, the SYCL compiler takes its

examples/09-heterogeneous/sycl/app/mcpp.toml

@@ -20,7 +20,7 @@ import_std = true
 default = "llvm@22.1.8"
 
 [build-dependencies.mcpp]
-plugins = { version = "0.2.1", features = ["rules-sycl"], host-module = true }
+plugins = { version = "0.2.4", features = ["rules-sycl"], host-module = true }
 
 # The SYCL runtime, on the artifact's runtime search path. mcpp's private
 # loader does not consult /usr/lib, so `libsycl.so.9` -- which the rule
@@ -33,37 +33,22 @@ plugins = { version = "0.2.1", features = ["rules-sycl"], host-module = true }
 [dependencies.compat]
 sycl-runtime = "2026.09.07"
 
-# Five payloads, each closing one hole the host would otherwise fill, written
-# on the TWO TOOL AXES rather than one (docs/05 section 2.13, SPEC-004 section 4).
+# NO [xlings.workspace]. `mcpp.rules.sycl` declares all five payloads this lane
+# needs, each closing one hole the host would otherwise fill: `dpcpp` (the
+# compiler, a host-axis entry -- it runs here whatever it is asked to emit);
+# `gcc`, `glibc` and `linux-headers` (the C++ and C libraries the SYCL unit is
+# compiled against -- dpcpp's clang is configured with neither, so left alone
+# its include search list reaches /usr/include with no ecosystem library on it,
+# which is measurable in `clang -v` and invisible on the command line); and
+# `cuda-nvcc` for the NVIDIA back end's libdevice, declared only when the accel
+# actually names cuda.
 #
-# The compiler runs on THIS machine whatever it is asked to emit, so it is a
-# host-axis entry. The other four are what the produced code is compiled
-# against, so they belong under a target selector; on a native build the two
-# axes name one platform, which is why writing them all in one table was right
-# by accident and stops being right the first time this is cross-compiled.
-[xlings.workspace]
-"xim:dpcpp" = "7.1.0"          # the compiler, and it runs here
-
-#   gcc        NOT a second toolchain: the C++ standard library the SYCL unit
-#              compiles against. Left alone, dpcpp's clang reads the HOST's
-#              /usr/include/c++ -- measured, and invisible until a machine
-#              without it refuses the build.
-#   cuda-nvcc  the NVIDIA back end's libdevice. Also measured: without
-#              `--cuda-path` clang finds the host's CUDA installation and says
-#              nothing about it.
-#   glibc      and linux-headers: the C library. `xim:gcc` supplies the C++
-#              standard library; the C library underneath it is a separate
-#              declaration, and without it a `.sycl` unit that includes
-#              `<cstdio>` reaches the host's /usr/include. Both are UNPINNED:
-#              the C library version is the runtime binding's choice, not the
-#              project's, and a pinned entry resolves for exactly that version
-#              or for nothing. rules-sycl 0.2.1 refuses the build and names
-#              these two lines when they are absent.
-[target.'cfg(os = "linux")'.xlings.workspace]
-"xim:gcc"           = "15.1.0"
-"xim:cuda-nvcc"     = "12.9.86"
-"xim:glibc"         = ""
-"xim:linux-headers" = ""
+# The C library entries are UNPINNED there for a reason worth keeping: its
+# version is the runtime binding's choice, not the project's, and a pinned entry
+# resolves for exactly that version or for nothing.
+#
+# To pin a different version, write the same entry here and it wins. Needs mcpp
+# 2026.9.6.6 and mcpp:plugins 0.2.4.
 
 [build]
 # Two chunks: the programming model, and the device. Written `sycl` alone, the