docs: runner on hosted targets, not-run reporting, [xlings] values per host platform (#544)

Author: speak-agent

docs/05-mcpp-toml.md

@@ -1086,7 +1086,7 @@ The selector `<sel>` has three forms:
 |---|---|---|
 | **bare OS alias** | a single OS / family — the concise, common form | `[target.windows]`, `[target.unix]` |
 | **`cfg(...)` predicate** | a compound condition (arch / env / combinators) | `[target.'cfg(all(linux, not(arch = "aarch64")))']` |
-| **exact triple** | one specific target (also carries `toolchain` / `linkage`) | `[target.x86_64-linux-musl]` |
+| **exact triple** | one specific target (also carries `toolchain` / `linkage` / `sysroot` / `runner`; see §2.7.3) | `[target.x86_64-linux-musl]` |
 
 A selector may carry platform-conditional **dependencies** and **build flags**:
 
@@ -1284,6 +1284,75 @@ different argv (`-bios default` for an OpenSBI boot, `-bios none -semihosting`
 for a picolibc image) — and an engine that guesses one is an engine the other
 board has to fight. A board-support package normally supplies it.
 
+### 2.7.3 `runner` on a hosted target (2026.9.2.1+)
+
+`[target.<triple>].runner` applies to every exact triple, not only to bare
+metal. A hosted cross artifact — `aarch64-linux-musl` built on an x86_64
+machine — is executable by some hosts (binfmt_misc with qemu-user registered)
+and refused by others with `Exec format error`, and which of the two applies is
+a property of the machine, not of the triple. mcpp does not predict it. It
+either executes the artifact through the runner the project declared, or it
+attempts direct execution and reports what the kernel answered.
+
+```toml
+[target.aarch64-linux-musl]
+runner = ["qemu-aarch64-static"]
+```
+
+The rules, for `mcpp run` and `mcpp test` alike:
+
+- **A declared runner is used.** Its first element is located by mcpp: first in
+  the `bin/` directory of each payload declared under `[xlings] deps` (§2.13),
+  then on `PATH`. A bare name on `PATH` resolves to an xvm shim, which answers
+  for the current SubOS rather than for the package; the payload lookup is what
+  lets a runner name a program the project declared.
+- **A declared runner that cannot be found or started is an error**, with the
+  program, the directories searched and the errno. There is no fallback to
+  direct execution: running the artifact under a different interpreter with
+  different arguments is the failure the key exists to prevent.
+- **No runner, and the kernel refuses the artifact:** `mcpp run` reports the
+  refusal and the key to write, and exits 2. `mcpp test` reports every test as
+  not run, with the reason once, and exits 2 (§2.7.3.1).
+- **`--no-runner`** executes the artifact directly and ignores a declared
+  runner. It states a fact about this host — the triple is native here — that
+  the manifest has no axis to carry; a project whose runner was written for
+  x86_64 developers is still readable on an aarch64 machine.
+
+Provisioning the emulator through `[xlings] deps` is the form for a CI job or
+a project built on one host class. `qemu-user-aarch64` in the index is built
+for x86_64 Linux only, and `[xlings] deps` provisions on every host that builds
+the project, so the entry is written per platform (§2.13):
+
+```toml
+[xlings]
+deps = [{ linux = "qemu-user-aarch64" }]
+
+[target.aarch64-linux-musl]
+runner = ["qemu-aarch64-static"]
+```
+
+A package the host cannot install is a hard build error, so an entry without
+the platform form would make the project unbuildable on macOS and Windows. The
+Linux/aarch64 host, where the package does not exist either, passes
+`--no-runner`.
+
+#### 2.7.3.1 `mcpp test` and tests that were not run
+
+A test whose artifact this host cannot execute has neither passed nor failed.
+`mcpp test` reports it as **not run**, prints the reason once when it is
+established, repeats the first line of the reason in the summary, and exits 2:
+
+```
+warning: this host cannot execute aarch64-linux-musl artifacts: Exec format error (error 8); declare [target.aarch64-linux-musl].runner, or pass --no-runner on a host that can
+smoke ... not run
+error: test result: NOT RUN. 0 passed; 0 failed; 1 not run (this host cannot execute aarch64-linux-musl artifacts: Exec format error (error 8); ...); finished in 0.41s (build 0.39s + run 0.00s)
+```
+
+Exit code 1 keeps its meaning — a test ran and failed — and 0 means every test
+ran and passed. `--message-format json` carries `"status":"not_run"` and a
+`reason` on each record, and `not_run` / `not_run_reason` on the summary
+record (see [11 — Machine-Readable Output](11-machine-output.md)).
+
 ### 2.8 `[features]` — Features (Cargo-style, additive)
 
 ```toml
@@ -1820,6 +1889,27 @@ build needs (`make`/`cmake`/`protoc`/…), pin tool versions per project, or set
 build-time env vars — without hand-editing `.xlings.json`. `[toolchain]` (§2.7) remains
 the ergonomic shorthand for the compiler; `[xlings.workspace]` is the general form.
 
+**Values per host platform (2026.9.2.1+).** A `deps` entry and a
+`[xlings.workspace]` value may be a table keyed by platform, the form xlings'
+own `.xlings.json` accepts for `workspace`:
+
+```toml
+[xlings]
+deps = ["xim:ninja", { linux = "qemu-user-aarch64" }, { windows = "nasm", default = "yasm" }]
+
+[xlings.workspace]
+gcc  = { linux = "15.1.0" }
+llvm = { macos = "20", default = "22" }
+```
+
+The keys are `linux`, `macos`, `windows` and `default`; `macosx` is accepted as
+xlings' spelling of `macos`. mcpp resolves the table against the host it runs
+on when the manifest is loaded: the host's key wins, `default` is the fallback,
+and a table with neither declares nothing on that host — the entry is absent,
+not empty. An unknown key is an error rather than a dropped entry. The axis is
+the host operating system only; a package that exists for the OS but not for
+the architecture is still a provisioning error on that host.
+
 `subos` selects the root project's **local build/run OS environment**. If the
 key is absent, mcpp uses its initialized, release-verified `McppDefault` SubOS;
 `subos = "default"` is an explicit `NamedSubos("default")` selection. There is

docs/11-machine-output.md

@@ -358,3 +358,54 @@ from the same resolution a build performs, which may fetch packages, install a
 payload and run a dependency's build program. A client gates on that table
 *before* running anything, so an omission would be a safety claim that is not
 true.
+
+### `mcpp test --message-format json` — the test stream
+
+```
+mcpp test [pattern] [--workspace] --message-format json
+```
+
+This stream predates the envelope of §2 and is not wrapped in it: it is NDJSON,
+one record per test as each finishes, then one summary record per member. A
+`--workspace` run ends with one `workspace_summary` record. The §6 guarantees
+apply to it — fields are added and never removed, and a field's meaning never
+changes — and the fields below are the contract as of 2026.9.2.1.
+
+Per test:
+
+| field | |
+|---|---|
+| `member` | the workspace member, or `""` outside a workspace |
+| `test` | the path-based test name (`tests/00-a/0.cpp` → `00-a/0`) |
+| `status` | `pass`, `compile_fail`, `run_fail`, or `not_run` |
+| `exit_code` | the test's exit status; `0` for `not_run` |
+| `signal` | the signal number when the status encodes one, else `null` |
+| `duration_ms` | build+run wall time of this test |
+| `timed_out` | `true` when `--timeout` killed it (`run_fail`) |
+| `compile_output`, `run_output` | captured diagnostics |
+| `reason` | `not_run` only: why, in one sentence; `""` otherwise |
+
+Summary record, `{"summary": {...}}`:
+
+| field | |
+|---|---|
+| `member`, `passed`, `failed` | counts |
+| `not_run` | tests that were built and not executed |
+| `not_run_reason` | the reason shared by all of them, or `""` |
+| `elapsed_ms`, `build_ms`, `run_ms` | wall time, split |
+
+⚠️ **`not_run` is neither `pass` nor `run_fail`, and the exit code says so
+(2026.9.2.1).** A test is `not_run` when this host cannot load its artifact
+(`Exec format error` on a cross target with no runner declared), or when the
+declared `[target.<triple>].runner` could not be found or started. The
+condition is a fact about the invocation: it is established once, the
+remaining tests are reported `not_run` without being started, and the process
+exits **2**. Exit 1 keeps meaning "a test ran and failed"; exit 0 means every
+test ran and passed. A client that read the exit code alone as pass/fail must
+handle 2, and a client that inferred "everything passed" from `failed == 0`
+must also read `not_run`.
+
+`workspace_summary` adds `tests_not_run` (the sum over members) and
+`unrunnable_members` (members all of whose tests were `not_run`), alongside the
+existing `not_run` list, which continues to name members the
+`--workspace-timeout` stopped before they started.

docs/13-baremetal.md

@@ -549,6 +549,14 @@ error: no runner is configured for 'riscv64-none-elf' — a freestanding artifac
        A board-support package normally supplies this so you do not have to.
 ```
 
+The key is not specific to bare metal. A hosted cross target — an
+`aarch64-linux-musl` artifact on an x86_64 host — takes the same
+`[target.<triple>].runner`, with a user-mode emulator such as
+`qemu-aarch64-static` in place of the system emulator; on such a target an
+absent runner is not an error until the kernel refuses the artifact. The rules
+for hosted targets, the `--no-runner` escape and the not-run reporting of
+`mcpp test` are in [5 — mcpp.toml](05-mcpp-toml.md), §2.7.3.
+
 ## Writing a board-support package
 
 A board-support package is an ordinary mcpp package. It declares the emulator

docs/15-openkal-cross.md

@@ -190,6 +190,25 @@ runner  = ["qemu-system-riscv64", "-machine", "virt", "-nographic",
 firmware mode to use are board facts, and an engine that guesses one is an
 engine a different board has to fight.
 
+A hosted cross target takes the same key with a user-mode emulator
+(2026.9.2.1). An `aarch64-linux-musl` artifact built on an x86_64 host is
+executed through `qemu-aarch64-static` when the project declares it, and the
+package that provides the emulator is declared for the hosts that can install
+it:
+
+```toml
+[xlings]
+deps = [{ linux = "qemu-user-aarch64" }]
+
+[target.aarch64-linux-musl]
+runner = ["qemu-aarch64-static"]
+```
+
+Without the key, `mcpp run` reports the kernel's refusal (`Exec format error`)
+and the key to write, and `mcpp test` reports every test as not run and exits
+2. A host that executes the artifact natively passes `--no-runner`. The rules
+are in [5 — mcpp.toml](05-mcpp-toml.md), §2.7.3.
+
 ### The Source Is The Same, The Program Is Not
 
 "The same source" is a claim about the toolchain and the standard library, and

docs/17-the-project-environment.md

@@ -124,6 +124,19 @@ instead of installing, and names the packages so they can be provisioned
 out of band — the same two knobs `[toolchain]` honours, for the same reason: an
 unasked-for download is not something a build decides on a project's behalf.
 
+The declaration is provisioned on every host that builds the project, and a
+package the host cannot install is an error, not a skipped entry. A tool that
+exists for one host platform only is therefore declared for that platform
+(2026.9.2.1): `deps = [{ linux = "qemu-user-aarch64" }]` declares the emulator
+on Linux and nothing elsewhere. The keys and the resolution rule are in
+chapter 5, §2.13.
+
+**The runner.** A program under `[xlings] deps` is also where
+`[target.<triple>].runner` looks first for its first element, before `PATH`
+(chapter 5, §2.7.3). The two keys together provision a user-mode emulator on a
+CI host and execute a cross-built artifact through it, without the manifest
+naming the payload's path.
+
 ## 6. What belongs somewhere else
 
 | Need | Where it goes |

docs/zh/05-mcpp-toml.md

@@ -952,7 +952,7 @@ linkage   = "static"
 |---|---|---|
 | **裸 OS 别名** | 单个 OS / 族 —— 简洁且常用的形式 | `[target.windows]`、`[target.unix]` |
 | **`cfg(...)` 谓词** | 复合条件(arch / env / 组合子) | `[target.'cfg(all(linux, not(arch = "aarch64")))']` |
-| **精确三元组** | 某个具体目标(同时承载 `toolchain` / `linkage`) | `[target.x86_64-linux-musl]` |
+| **精确三元组** | 某个具体目标(同时承载 `toolchain` / `linkage` / `sysroot` / `runner`,见 §2.7.3) | `[target.x86_64-linux-musl]` |
 
 一个选择器可以承载平台条件的**依赖**与**构建 flag**:
 
@@ -1122,6 +1122,63 @@ mcpp **刻意不提供默认 runner**。用哪个模拟器、哪个机器型号
 镜像用 `-bios none -semihosting`)—— 引擎一旦猜一个,另一块板就得跟它打架。板级
 支持包通常会提供它。
 
+### 2.7.3 hosted 目标上的 `runner`(2026.9.2.1+)
+
+`[target.<triple>].runner` 对每一个精确三元组生效,不限于裸机。一个 hosted 交叉产物
+—— 在 x86_64 机器上构建的 `aarch64-linux-musl` —— 有的宿主能直接执行(binfmt_misc
+注册了 qemu-user),有的宿主以 `Exec format error` 拒绝;属于哪一种是机器的性质,不是
+三元组的性质。mcpp 不预测它:要么通过工程声明的 runner 执行产物,要么尝试直接执行并
+报告内核的回答。
+
+```toml
+[target.aarch64-linux-musl]
+runner = ["qemu-aarch64-static"]
+```
+
+规则对 `mcpp run` 与 `mcpp test` 相同:
+
+- **声明了 runner 就使用它。** 其第一个元素由 mcpp 定位:先在 `[xlings] deps`(§2.13)
+  声明的每个载荷的 `bin/` 目录里找,再找 `PATH`。`PATH` 上的裸名会命中 xvm shim,而
+  shim 按当前 SubOS 而非按包作答;先查载荷,runner 才能直接写工程声明过的程序名。
+- **声明的 runner 找不到或启动不了是错误**,错误里带程序名、搜索过的目录和 errno。
+  不回落到直接执行:让产物在另一个解释器下带着另一组参数运行,正是这个键要防止的
+  失败。
+- **没有 runner 且内核拒绝产物:** `mcpp run` 报告拒绝原因与应当写的键,退出码 2。
+  `mcpp test` 把每个测试报告为未运行,原因只打印一次,退出码 2(§2.7.3.1)。
+- **`--no-runner`** 直接执行产物并忽略声明的 runner。它陈述的是关于本机的事实 ——
+  这个三元组在本机是原生的 —— 清单没有承载它的轴;为 x86_64 开发者写的 runner 在
+  aarch64 机器上仍可用。
+
+通过 `[xlings] deps` 装模拟器是 CI 任务或单一宿主类别工程的形态。索引里的
+`qemu-user-aarch64` 只为 x86_64 Linux 构建,而 `[xlings] deps` 在每台构建本工程的
+宿主上都会 provisioning,所以条目按平台写(§2.13):
+
+```toml
+[xlings]
+deps = [{ linux = "qemu-user-aarch64" }]
+
+[target.aarch64-linux-musl]
+runner = ["qemu-aarch64-static"]
+```
+
+宿主装不了的包是硬构建错误,所以不带平台形式的条目会让工程在 macOS 与 Windows 上
+无法构建。同样没有这个包的 Linux/aarch64 宿主传 `--no-runner`。
+
+#### 2.7.3.1 `mcpp test` 与未运行的测试
+
+产物在本机无法执行的测试既没有通过也没有失败。`mcpp test` 把它报告为**未运行**,
+在确立原因时打印一次,在汇总里重复原因的第一行,退出码 2:
+
+```
+warning: this host cannot execute aarch64-linux-musl artifacts: Exec format error (error 8); declare [target.aarch64-linux-musl].runner, or pass --no-runner on a host that can
+smoke ... not run
+error: test result: NOT RUN. 0 passed; 0 failed; 1 not run (this host cannot execute aarch64-linux-musl artifacts: Exec format error (error 8); ...); finished in 0.41s (build 0.39s + run 0.00s)
+```
+
+退出码 1 含义不变 —— 有测试运行并失败;0 表示每个测试都运行并通过。
+`--message-format json` 在每条记录上带 `"status":"not_run"` 与 `reason`,在汇总记录上
+带 `not_run` / `not_run_reason`(见 [11 —— 机器可读输出](11-machine-output.md))。
+
 ### 2.8 `[features]` —— Feature(Cargo 风格,可加性)
 
 #### 表形式 —— 让 feature 贡献的不止是隐含 feature
@@ -1555,6 +1612,24 @@ OPENBLAS_NUM_THREADS = "1"
 host 工具(`make`/`cmake`/`protoc`…)、按项目固定工具版本、或设构建期环境变量——无需手改
 `.xlings.json`。`[toolchain]`(§2.7)仍是编译器的便捷简写;`[xlings.workspace]` 是其通用形式。
 
+**按宿主平台取值(2026.9.2.1+)。** `deps` 的一个条目与 `[xlings.workspace]` 的一个值可以是
+按平台为键的表,即 xlings 自身 `.xlings.json` 对 `workspace` 接受的形式:
+
+```toml
+[xlings]
+deps = ["xim:ninja", { linux = "qemu-user-aarch64" }, { windows = "nasm", default = "yasm" }]
+
+[xlings.workspace]
+gcc  = { linux = "15.1.0" }
+llvm = { macos = "20", default = "22" }
+```
+
+键为 `linux`、`macos`、`windows` 与 `default`;`macosx` 作为 xlings 对 `macos` 的拼写也被
+接受。mcpp 在加载清单时按运行它的宿主解析这张表:宿主对应的键优先,`default` 兜底,两者
+都没有时该条目在本宿主上不作声明 —— 是缺席,不是空值。未知的键是错误,不是被丢弃的条目。
+这条轴只到宿主操作系统:一个包存在于该 OS 但不存在于该架构时,在那台宿主上仍是
+provisioning 错误。
+
 `subos` 选择根项目用于 build/run 的**本地开发 OS 环境**。未声明该键时固定使用 mcpp 已初始化、
 经 release 验证的 `McppDefault`;`subos = "default"` 则仍是显式的
 `NamedSubos("default")`。没有 CLI/环境变量 override,也不会隐式跟随 xlings active/current。

docs/zh/11-machine-output.md

@@ -316,3 +316,47 @@ mcpp why toolchain [--target <triple>] [--toolchain <spec>] --format json
 `network`、`write-global-cache` 与 `exec-build-script`:答案来自与构建同一次的
 解析,而那可能拉取包、安装载荷、并运行某个依赖的构建程序。客户端是在**运行之前**
 读这张表来决定放不放行的,漏报一项就是一句不成立的安全承诺。
+
+### `mcpp test --message-format json` —— 测试流
+
+```
+mcpp test [pattern] [--workspace] --message-format json
+```
+
+这条流早于 §2 的信封,也不被信封包裹:它是 NDJSON,每个测试结束时一条记录,随后每个
+成员一条汇总记录。`--workspace` 运行以一条 `workspace_summary` 记录结束。§6 的保证
+对它同样成立 —— 字段只增不减,字段含义不变 —— 下表是 2026.9.2.1 时的契约。
+
+每个测试:
+
+| 字段 | |
+|---|---|
+| `member` | workspace 成员;workspace 之外为 `""` |
+| `test` | 按路径命名的测试名(`tests/00-a/0.cpp` → `00-a/0`) |
+| `status` | `pass`、`compile_fail`、`run_fail` 或 `not_run` |
+| `exit_code` | 测试的退出状态;`not_run` 时为 `0` |
+| `signal` | 状态编码了信号时是信号号,否则 `null` |
+| `duration_ms` | 这个测试构建+运行的墙钟时间 |
+| `timed_out` | 被 `--timeout` 杀掉时为 `true`(`run_fail`) |
+| `compile_output`、`run_output` | 捕获的诊断输出 |
+| `reason` | 仅 `not_run`:一句话说明原因;其余为 `""` |
+
+汇总记录 `{"summary": {...}}`:
+
+| 字段 | |
+|---|---|
+| `member`、`passed`、`failed` | 计数 |
+| `not_run` | 已构建但没有执行的测试数 |
+| `not_run_reason` | 它们共同的原因,或 `""` |
+| `elapsed_ms`、`build_ms`、`run_ms` | 墙钟时间,分段 |
+
+⚠️ **`not_run` 既不是 `pass` 也不是 `run_fail`,退出码也这么说(2026.9.2.1)。**
+本机无法加载测试产物(交叉目标未声明 runner 时的 `Exec format error`),或声明的
+`[target.<triple>].runner` 找不到、启动不了时,测试为 `not_run`。这是关于整次调用的
+事实:确立一次,其余测试直接报告为 `not_run` 而不再启动,进程以 **2** 退出。退出码 1
+含义不变 —— 有测试运行并失败;0 表示每个测试都运行并通过。只读退出码判 pass/fail 的
+客户端必须处理 2;由 `failed == 0` 推断「全部通过」的客户端还必须读 `not_run`。
+
+`workspace_summary` 增加 `tests_not_run`(各成员之和)与 `unrunnable_members`(所有
+测试都 `not_run` 的成员),与既有的 `not_run` 列表并列;后者仍然指
+`--workspace-timeout` 到达时尚未开始的成员。