docs(examples): a multi-backend artifact, an Ascend one, and the table a rule package belongs in

Two examples, and one correction that applies to every example already here.

multi-backend -- several backends in ONE artifact, chosen at run time. The four
examples beside it are each one seam: a device file and a CPU file define the
same symbol and are never in one link, so exactly one exists and the choice is
made at build time. That is right for a program. A library cannot make that
choice; it is compiled once and consumed by people whose machines differ, so its
backends are additive.

It is also the first real use of cfg(accelerator = "none"). The dispatcher must
be built for cuda, for vulkan, for both, and for a backend that does not exist
yet, and not(any(cuda, vulkan)) needs editing every time the ecosystem grows --
the edit that is forgotten being silent. Its default accel is empty, so a plain
mcpp build needs no payloads at all, which is what lets CI build it and makes
the "none" path genuinely covered rather than described.

cann -- Ascend, behind the same seam. It DOES NOT BUILD, and the README says so
and names the two missing pieces: a rules-ascendc rule package, and an xim
package for the toolkit. It records what was measured instead of guessed: both
BiSheng and the simulator live in that one toolkit; the toolkit image pulls
anonymously; sim mode needs no hardware AND keeps the island, while cpu mode
does not keep it and therefore cannot stand in for a device criterion. The
manifest is written out rather than described so the shape is concrete. CANN's
own operator libraries already split op_kernel/ from op_host/, so the island is
not a shape mcpp imposes on Ascend.

THE CORRECTION. All four existing examples declare mcpp:plugins in
[dependencies], and docs/05 section 2.6.1 names exactly that case as what
[build-dependencies] is for: a package whose library must never reach the target
while its rule is still wanted. The two axes are separate -- host-module = true
says which build-time product is wanted, the section says whether the package
reaches the target, and a rule package answers no on the second. Verified by
moving it and rebuilding: build.mcpp compiles, the rule runs, shaders compile,
and the artifact runs on a real device.

Writing it in [dependencies] still works, which is precisely why the
distinction has to be stated rather than left to a failure to teach.

Author: speak-agent

.github/tools/build_examples.sh

@@ -24,6 +24,10 @@ BUILD=(
     examples/03-pack-static
     examples/04-workspace
     examples/08-build-rules/app
+    # The CPU-only path of the multi-backend example: no payloads, and it is
+    # where `cfg(accelerator = "none")` is exercised. The device paths are
+    # opt-in via --accel and are covered by the rule packages' own CI.
+    examples/09-heterogeneous/multi-backend
 )
 
 # `key|reason`.
@@ -38,6 +42,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|does not build yet, and says so in its README: it needs a rules-ascendc rule package and an xim package for the CANN toolkit, neither of which exists. The manifest is written out so the shape is concrete rather than described"
 )
 
 # Every ROOT manifest in the tree: a directory with an `mcpp.toml` that has no

CHANGELOG.md

@@ -5,6 +5,36 @@
 
 ## [Unreleased]
 
+### 两个新示例,以及一处所有既有示例都写错了的地方
+
+**`examples/09-heterogeneous/multi-backend`** —— 多个后端进**同一个产物**,运行期选择。
+既有四个示例每个都是**一道接缝**:设备文件与 CPU 文件定义同一个符号、永不同时进入一次
+链接,所以恰好存在一个,选择在构建期做完。那是程序的正确形态。库做不了这个选择:它
+只编译一次,而消费者的机器各不相同,所以它的后端是**叠加**的。这个示例是那种形态。
+
+它同时是 `cfg(accelerator = "none")` 的第一个真实用例:分发器要在 cuda、在 vulkan、在
+两者同时、以及在一个还不存在的后端下都被构建,而 `not(any(cuda, vulkan))` 每次生态新增
+后端都要改一遍 —— 忘掉的那次是静默的。默认 `accel` 为空,所以 `mcpp build` 不需要任何
+载荷,CI 因此能真正构建它,`none` 那条路径也就真的被覆盖。
+
+**`examples/09-heterogeneous/cann`** —— 昇腾。**目前构建不了**,README 点明缺的两块
+(`mcpp.rules.ascendc` 规则包,以及承载毕昇与仿真器的 `xim:cann-toolkit`),并记下已经
+查实的三件事:两者在同一个工具包里;工具包镜像可匿名拉取;`sim` 模式无需硬件且保留岛,
+而 `cpu` 模式**不保留**因而不能充当设备判据。manifest 写出来而不是描述出来,是为了让
+形状具体。CANN 自己的算子库本来就是 `op_kernel/` 与 `op_host/` 分开的,岛不是 mcpp 强加
+给昇腾的形状。
+
+### 规则包应当声明在 `[build-dependencies]`
+
+既有四个示例都把 `mcpp:plugins` 写在 `[dependencies]` 里,而 docs/05 §2.6.1 自己立的规则
+恰恰点名这种情形:**库绝不该到达目标,而它的规则仍然被需要**。两条轴是分开的 ——
+`host-module = true` 说要哪种构建期产物,section 说这个包是否到达目标,规则包在第二条轴
+上答"否"。四个示例与两份文档已改正。
+
+写在 `[dependencies]` 里同样能工作,这正是这条区分必须被**陈述**而不能指望由一次失败来
+教会的原因。
+
+
 ### 共享库能说出自己发布哪些符号:`exports`
 
 两个平台的默认都是"全导出":ELF 给符号默认可见性,PE 由引擎自动生成列出全部符号的

docs/01-examples.md

@@ -31,11 +31,13 @@ examples.
 | 06 | [`examples/06-openkal-cross`](../examples/06-openkal-cross/) | One program asking each machine what it is, built for four targets from any host | `--target`, openkal, cross-compilation without editing the source |
 | 07 | [`examples/07-project-subos`](../examples/07-project-subos/) | A build program that finds its tools in the environment the project declared | `[xlings] subos`, `[xlings.workspace]`, a build program whose `PATH` is the environment the project named |
 | 08 | [`examples/08-build-rules`](../examples/08-build-rules/) | Two rule packages and a project that uses both | `host-module = true`, `[build-dependencies]`, `mcpp::action` with `role = "check"` |
-| 09 | [`examples/09-heterogeneous`](../examples/09-heterogeneous/) | One computation on a device, in four programming models, with a CPU fallback in each | `accel`, constrained source globs, the seam module, rule packages from `mcpp:plugins`, `cfg(accelerator = …)` |
+| 09 | [`examples/09-heterogeneous`](../examples/09-heterogeneous/) | One computation on a device, in several programming models, with a CPU fallback in each; plus one artifact carrying several backends at once | `accel`, constrained source globs, the seam module, rule packages from `mcpp:plugins`, `cfg(accelerator = …)` |
 | 09a | [`…/cuda`](../examples/09-heterogeneous/cuda/) | A CUDA kernel behind a seam module | `mcpp.rules.cuda`, `mcpp::action` with `role = "object"`, the driver stated as a fact and a floor |
 | 09b | [`…/vulkan`](../examples/09-heterogeneous/vulkan/) | The same computation as a Vulkan compute shader, on a GPU or on the CPU | `mcpp.rules.spirv`, `mcpp::action` with `role = "source"`, generated headers, a software driver as a payload |
 | 09c | [`…/sycl`](../examples/09-heterogeneous/sycl/) | The same computation as a SYCL kernel, compiled by a second compiler | `mcpp.rules.sycl`, the `.sycl` device extension, a chained `mcpp::action` for the device link, `compat:sycl-runtime` |
 | 09d | [`…/hip`](../examples/09-heterogeneous/hip/) | The same computation in HIP, reaching an NVIDIA device | `mcpp.rules.hip`, HIP as a header layer over the CUDA runtime, a two-chunk `accel` |
+| 09e | [`…/multi-backend`](../examples/09-heterogeneous/multi-backend/) | Several backends in ONE artifact, chosen at run time — the library shape, not the program shape | `accel` as a set, `cfg(accelerator = "none")` and its negation, a dispatch chain, a module seam over a C island boundary |
+| 09f | [`…/cann`](../examples/09-heterogeneous/cann/) | An Ascend C kernel behind the same seam. **Does not build yet** — its README names the two missing pieces | the `.asc` device extension, `op_kernel`/`op_host` as an island CANN already has, `accelerator = "none"` for the fallback |
 
 ## Suggested Reading Order
 

docs/05-mcpp-toml.md

@@ -2379,9 +2379,18 @@ rules-spirv = { sources = ["rules/spirv.cppm"] } # export module mcpp.rules.spir
 
 ```toml
 # a consumer
-[dependencies.mcpp]
-plugins = { version = "0.1.1", features = ["rules-spirv"], host-module = true }
-```
+[build-dependencies.mcpp]
+plugins = { version = "0.2.1", features = ["rules-spirv"], host-module = true }
+```
+
+**`[build-dependencies]`, not `[dependencies]`** — a rule package is the case
+§2.6.1 describes exactly: its library must never reach the target while its
+rule is still wanted. The two axes are separate, so `host-module = true` says
+*which build-time product* is wanted and the section says *whether the package
+reaches the target*; a rule package answers "no" on the second axis, and the
+section is where that is said. Written in `[dependencies]` it still works, and
+that is precisely why the distinction has to be stated rather than enforced by
+a failure.
 
 The module set is the feature set: a unit whose feature is not active is not
 compiled, and importing it fails as an unknown module. `mcpp:plugins` is the

docs/zh/01-examples.md

@@ -28,11 +28,13 @@ mcpp build && mcpp run
 | 06 | [`examples/06-openkal-cross`](../../examples/06-openkal-cross/) | 同一个程序问每台机器它是什么,从任意宿主构建到四个目标 | `--target`、openkal、不改源码的交叉编译 |
 | 07 | [`examples/07-project-subos`](../../examples/07-project-subos/) | 构建程序在工程声明的环境里找工具,而不是问机器上恰好有什么 | `[xlings] subos`、`[xlings.workspace]`、构建程序的 `PATH` 来自工程声明的那个环境 |
 | 08 | [`examples/08-build-rules`](../../examples/08-build-rules/) | 两个规则包,以及同时用到它们的工程 | `host-module = true`、`[build-dependencies]`、`role = "check"` 的 `mcpp::action` |
-| 09 | [`examples/09-heterogeneous`](../../examples/09-heterogeneous/) | 同一个计算在设备上跑,写成四种编程模型,每种都带 CPU 回退 | `accel`、带约束的 source glob、接缝模块、来自 `mcpp:plugins` 的规则包、`cfg(accelerator = …)` |
+| 09 | [`examples/09-heterogeneous`](../../examples/09-heterogeneous/) | 同一个计算在设备上跑,写成多种编程模型,每种都带 CPU 回退;外加一个同时携带多个后端的产物 | `accel`、带约束的 source glob、接缝模块、来自 `mcpp:plugins` 的规则包、`cfg(accelerator = …)` |
 | 09a | [`…/cuda`](../../examples/09-heterogeneous/cuda/) | 接缝模块背后的 CUDA kernel | `mcpp.rules.cuda`、`role = "object"` 的 `mcpp::action`、把驱动陈述为 fact 与 floor |
 | 09b | [`…/vulkan`](../../examples/09-heterogeneous/vulkan/) | 同一个计算写成 Vulkan compute shader,在 GPU 上或在 CPU 上 | `mcpp.rules.spirv`、`role = "source"` 的 `mcpp::action`、生成的头文件、作为载荷的软件驱动 |
 | 09c | [`…/sycl`](../../examples/09-heterogeneous/sycl/) | 同一个计算写成 SYCL kernel,由第二个编译器编译 | `mcpp.rules.sycl`、`.sycl` 设备扩展名、为 device link 串起来的 `mcpp::action`、`compat:sycl-runtime` |
 | 09d | [`…/hip`](../../examples/09-heterogeneous/hip/) | 同一个计算写成 HIP,够到一台 NVIDIA 设备 | `mcpp.rules.hip`、HIP 作为 CUDA 运行时之上的一层头文件、两段式的 `accel` |
+| 09e | [`…/multi-backend`](../../examples/09-heterogeneous/multi-backend/) | 多个后端进**同一个产物**,运行期选择 —— 这是库的形态,不是程序的形态 | `accel` 作为集合、`cfg(accelerator = "none")` 及其否定、分发链、C 岛边界之上的模块接缝 |
+| 09f | [`…/cann`](../../examples/09-heterogeneous/cann/) | 同一道接缝背后的 Ascend C kernel。**目前还构建不了** —— README 里点明了缺的两块 | `.asc` 设备扩展名、CANN 本来就有的 `op_kernel`/`op_host` 岛、回退用 `accelerator = "none"` |
 
 ## 推荐阅读顺序
 

docs/zh/05-mcpp-toml.md

@@ -2027,10 +2027,17 @@ rules-spirv = { sources = ["rules/spirv.cppm"] } # export module mcpp.rules.spir
 
 ```toml
 # 消费者
-[dependencies.mcpp]
-plugins = { version = "0.1.1", features = ["rules-spirv"], host-module = true }
+[build-dependencies.mcpp]
+plugins = { version = "0.2.1", features = ["rules-spirv"], host-module = true }
 ```
 
+**用 `[build-dependencies]` 而不是 `[dependencies]`** —— 规则包正是 §2.6.1 描述的那种
+情形:它的库绝不该到达目标,而它的规则仍然被需要。两条轴是分开的:
+`host-module = true` 说的是**要哪一种构建期产物**,而 section 说的是**这个包是否到达
+目标**;规则包在第二条轴上的答案是"否",而 section 就是说这件事的地方。写在
+`[dependencies]` 里同样能工作 —— 这恰恰是为什么这条区分必须被**陈述**,而不能指望由
+一次失败来教会。
+
 模块集合就是 feature 集合:feature 未激活的单元不编译,import 它会以未知模块失败。
 `mcpp:plugins` 是 mcpp 项目维护的集合(仓库 `mcpp-community/mcpp-plugins`);其成员
 命名为 `mcpp.rules.<x>`(规则包)与 `mcpp.tools.<x>`(构建期工具)。

examples/09-heterogeneous/cann/app/README.md

@@ -0,0 +1,52 @@
+# Ascend, through the same island
+
+`op_kernel/` beside `op_host/` is how CANN's own operator libraries are already
+laid out — every operator in `ops-math` splits that way on disk. The island is
+therefore not a shape mcpp imposes on Ascend; it is the shape Ascend already
+has, and this example writes it in mcpp's vocabulary.
+
+`.asc` is that seam made checkable, exactly as `.sycl` is in the SYCL example:
+the file's content is C++ and nothing in it would tell a reader otherwise. What
+makes it a device translation unit is that it goes to BiSheng — a compiler with
+a device back end, and one that does not accept C++20 modules.
+
+## This example does not build yet
+
+Two pieces do not exist:
+
+| Missing | What it is |
+|---|---|
+| `mcpp.rules.ascendc` | the rule package that drives BiSheng, the sibling of `rules-cuda` / `rules-spirv` |
+| `xim:cann-toolkit` | an index package carrying the toolkit |
+
+Nothing else is missing, and that is why the manifest is written out rather than
+described. It is listed in `.github/tools/build_examples.sh` as skipped, with
+that reason.
+
+## What was established about the toolkit
+
+Measured 2026-09-07 and recorded in
+`.agents/docs/2026-09-07-general-build-infrastructure-gaps-design.md` section 10:
+
+* **One payload, not two.** BiSheng and the simulator live in the same toolkit:
+  `compiler/ccec_compiler/bin/bisheng` and `*/simulator/<SoC>/lib`.
+* **It can be obtained anonymously.** The official distribution is a container
+  image, `swr.cn-south-1.myhuaweicloud.com/ascendhub/cann`, and its registry
+  issues a pull token without credentials. Fetching from the vendor's own
+  registry is the tier this ecosystem's invariant already permits — linked
+  where it is, never copied into a release of ours.
+* **A device is not required to verify a device build.** Ascend C has three run
+  modes, and `sim` needs no hardware. It is not a substitute for `cpu` mode:
+  `cpu` links `tikicpulib` and compiles the same kernel source with the HOST
+  compiler, so that graph contains no island at all and passing in it would
+  prove the kernel's arithmetic rather than the build. Every `RUN_MODE` test in
+  asc-devkit is `STREQUAL "cpu"` — there is no `sim` branch — so `sim` takes the
+  same path as `npu` and BiSheng is invoked.
+
+## Why `accelerator = "none"` for the fallback
+
+`not(accelerator = "ascend")` would work today and rot tomorrow: `accelerator`
+is an open vocabulary, so a fallback written by enumerating what it is not
+changes meaning every time the ecosystem gains a backend. Ascend is itself an
+instance of that growth, which is the neatest possible argument for the
+spelling.

examples/09-heterogeneous/cann/app/include/saxpy/saxpy.h

@@ -0,0 +1,24 @@
+// The Ascend island's interface.
+//
+// `extern "C"` and free of standard-library types, for the reason every island
+// in this directory gives: the device half is compiled by BiSheng, a compiler
+// mcpp did not choose, so the two sides share no C++ ABI.
+#ifndef MCPP_EXAMPLE_ASCEND_SAXPY_H
+#define MCPP_EXAMPLE_ASCEND_SAXPY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// out[i] = a * x[i] + y[i], computed on the NPU. Returns 0 on success.
+int saxpy_device(float a, const float* x, const float* y, float* out, unsigned n);
+
+// Which device the last successful call ran on, or "" if none has. Both
+// implementations of this seam produce the same numbers, so the numbers alone
+// do not separate a device run from the fallback.
+const char* saxpy_device_name(void);
+
+#ifdef __cplusplus
+}
+#endif
+#endif

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

@@ -0,0 +1,51 @@
+[package]
+name         = "ascend-saxpy"
+namespace    = "example"
+version      = "0.1.0"
+description  = "An Ascend C kernel behind a seam module, with a CPU fallback"
+accelerators = ["ascend"]
+
+[language]
+standard   = "c++23"
+modules    = true
+import_std = true
+
+# NOT YET BUILDABLE, AND THE TWO MISSING PIECES ARE NAMED IN README.md.
+#
+# This manifest is the shape the Ascend lane takes, written out so that the
+# design it follows from is concrete rather than described. What it needs and
+# does not have: a rule package `mcpp.rules.ascendc`, and an xim package for the
+# CANN toolkit that carries BiSheng and the simulator.
+[build-dependencies.mcpp]
+plugins = { version = "0.2.1", features = ["rules-ascendc"], host-module = true }
+
+# The toolkit carries BOTH the device compiler and the per-SoC simulator, so
+# this is one payload rather than two:
+#
+#   <toolkit>/compiler/ccec_compiler/bin/bisheng     the device compiler
+#   <toolkit>/*/simulator/<SoC>/lib                  the hardware-free device
+[xlings.workspace]
+"xim:cann-toolkit" = "8.5.0"
+
+[build]
+# `dav-2201` is the device architecture, the role `sm_89` plays for CUDA. The
+# rule package derives BiSheng's own flag from it.
+accel = "ascend, dav-2201"
+sources = [
+  "src/*.cppm",
+  "src/*.cpp",
+  # The kernel carries the accel it is for. It is never offered to the C++
+  # compiler; the constrained glob routes it to the build program instead.
+  { glob = "src/kernels/*.asc", accel = "ascend, dav-2201" },
+]
+include_dirs = ["include"]
+
+# The CPU variant of the same seam. `accelerator = "none"` rather than
+# `not(accelerator = "ascend")`: `accelerator` is an open vocabulary, so a
+# fallback written by enumeration changes meaning as the ecosystem grows.
+[target.'cfg(accelerator = "none")'.build]
+sources = ["src/cpu/*.cpp"]
+
+[targets.ascend-saxpy]
+kind = "bin"
+main = "src/main.cpp"

examples/09-heterogeneous/cann/app/src/app.cppm

@@ -0,0 +1,25 @@
+// The seam, as a module.
+//
+// Its reason for existing is not that BiSheng rejects modules. It is that this
+// is the one place a backend can be exchanged: the island underneath can become
+// CUDA or a CPU fallback without a single importer changing.
+module;
+#include "saxpy/saxpy.h"
+export module app.saxpy;
+import std;
+
+export namespace app {
+
+std::optional<std::vector<float>>
+saxpy(float a, std::span<const float> x, std::span<const float> y) {
+    if (x.size() != y.size()) return std::nullopt;
+    std::vector<float> out(x.size());
+    if (saxpy_device(a, x.data(), y.data(), out.data(),
+                     static_cast<unsigned>(x.size())) != 0)
+        return std::nullopt;
+    return out;
+}
+
+std::string_view device_name() { return saxpy_device_name(); }
+
+} // namespace app