0.6.0 —— 干净机器上,构建程序现在说得出话

mcpp 2026.8.21.2 给了构建程序一条「成功但有话说」的通道。这个工程正是它的
动机:清单的 [xlings] deps 是声明不是安装触发器,干净机器上 xpkg_dir 返回空、
不配 runner,而 mcpp run 给出一条一般情况下对、在此处不对的建议。

- examples/switch 与 clock-study 的 else 分支改用 mcpp::warning(),说出确切
  的那条安装命令
- CI 新增「A clean machine is told what is missing」,放在**装模拟器之前** ——
  那是生态里唯一能观察到这条通知的地方
- .ci-identical-files 声明「示例与模板的构建程序自 The emulator 起逐字节相同」,
  由 CI 断言。0.5.0 的缺陷正是这两份拷贝改了一份漏了另一份,而修法不是更仔细
- 模板 build.mcpp.in 已同步

⚠️ 写那条一致性检查时先用了 sed 地址,而标记里含 /,sed 把它当模式结尾:
两边都空、diff 通过。改用 grep -F + tail,并断言两侧非空 —— 那正是这条规则
要防的形状,它先在自己身上出现了一次。

Author: Sunrisepeak

.ci-identical-files

@@ -0,0 +1,10 @@
+# Pairs that must stay byte-identical from a marker onward, checked by
+# mcpp's tools/lint-ci-assertions.sh (rule R2).
+#
+# ⚠️ THIS FILE EXISTS BECAUSE 0.5.0 SHIPPED A TEMPLATE WHOSE BUILD PROGRAM
+# DISAGREED WITH ITS OWN README. The example's build program was updated and
+# the template's copy was not; the fix is not "be more careful", which had
+# already been tried, but to assert sameness.
+#
+# Format: <a>TAB<b>TAB<marker>
+examples/switch/build.mcpp	templates/three-machines/build.mcpp.in	// The emulator.

.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
           # carries it, and the row is now the same shape as the other two.
           - { arch: x86_64,  triple: x86_64-none-elf,  qemu: 'xim:qemu-x86'  }
     env:
-      MCPP_VERSION: 2026.8.21.1
+      MCPP_VERSION: 2026.8.21.2
       XLINGS_VERSION: v2026.8.17.2
       XLINGS_NON_INTERACTIVE: '1'
     steps:
@@ -110,6 +110,33 @@ jobs:
       # The three packages are different builds, one per target family:
       # `qemu-riscv` carries the RISC-V emulators, `qemu-arm` the Arm ones and
       # `qemu-x86` the x86_64 one. Measured; no single package runs all three.
+      # ⭐ BEFORE THE EMULATOR IS INSTALLED, AND THAT ORDER IS THE ASSERTION.
+      #
+      # `[xlings] deps` is a DECLARATION, not an install trigger, so on a clean
+      # machine `xpkg_dir` answers empty and this project's build program
+      # configures no runner. That is correct and it used to be SILENT: mcpp
+      # prints a build program's output only on a non-zero exit, so a
+      # `std::cerr` note printed nothing on exactly the builds that needed it.
+      #
+      # mcpp 2026.8.21.2's `mcpp::warning()` is the channel. This step is the
+      # only place the ecosystem can observe it, because every later step has
+      # the emulator — so it runs here, once, and asserts the sentence a first
+      # -time user sees.
+      - name: A clean machine is told what is missing
+        working-directory: examples/switch
+        run: |
+          set -euo pipefail
+          COLD=$(mktemp -d)
+          MCPP_HOME="$COLD" mcpp build --target ${{ matrix.triple }} 2>&1 | tee cold.log
+          grep -q "is not installed" cold.log \
+            || { cat cold.log; echo "the build program said nothing about the missing emulator"; exit 1; }
+          grep -q "xlings install" cold.log \
+            || { cat cold.log; echo "the advisory does not name the command that fixes it"; exit 1; }
+          # An advisory is not an error: the build still succeeded.
+          grep -q "Finished" cold.log \
+            || { cat cold.log; echo "the build did not finish"; exit 1; }
+          rm -rf "$COLD" target
+
       - name: Install the emulator
         run: |
           xlings install ${{ matrix.qemu }} -y
@@ -188,7 +215,10 @@ jobs:
       # while mcpp wants a native path — a mismatch this repository has been
       # bitten by before.
       - name: The template generates a project that builds for all three machines
-        if: matrix.arch == 'riscv64'
+        # The claim here is host-independent — the template's CONTENT builds for
+        # all three machines — so one row is the right place for it. The per-row
+        # claim, that it RUNS, is the separate step below.
+        if: matrix.arch == 'riscv64'   # ci-lint: allow-r1: host-independent claim
         run: |
           set -euo pipefail
           T=templates/three-machines
@@ -255,6 +285,39 @@ jobs:
       # The same source produced that output. Asserted rather than trusted: a
       # probe that had quietly grown a per-architecture branch would still pass
       # every line above, and the gate would be measuring two programs.
+      # ⚠️ ONE PIECE OF LOGIC LIVING IN TWO FILES IS WHAT SHIPPED 0.5.0's DEFECT:
+      # the example's build program was updated and the template's copy was not,
+      # so the template's README claimed something its own program could not do.
+      #
+      # The fix is not "be more careful" — that had already been tried once. The
+      # pairs are declared in `.ci-identical-files` and asserted here.
+      - name: Files declared identical are identical
+        run: |
+          set -euo pipefail
+          test -s .ci-identical-files
+          n=0
+          while IFS=$'\t' read -r a b marker; do
+            case "${a:-}" in ''|'#'*) continue ;; esac
+            test -f "$a" && test -f "$b" || { echo "declared pair missing a side: $a / $b"; exit 1; }
+            # ⚠️ `grep -F` + `tail`, NOT a sed address. The marker is a line of
+            # C++ and contains `/`, which sed reads as the end of its pattern —
+            # measured: `unknown command: '/'`, both sides empty, and the diff
+            # would then have PASSED. That is the emptiness-as-success shape
+            # this repository has already been bitten by once.
+            la=$(grep -nF -m1 "$marker" "$a" | cut -d: -f1)
+            lb=$(grep -nF -m1 "$marker" "$b" | cut -d: -f1)
+            test -n "$la" && test -n "$lb" \
+              || { echo "marker '$marker' not found in $a or $b"; exit 1; }
+            tail -n +"$la" "$a" > /tmp/ia
+            tail -n +"$lb" "$b" > /tmp/ib
+            test -s /tmp/ia && test -s /tmp/ib \
+              || { echo "marker '$marker' matched an empty tail in $a or $b"; exit 1; }
+            diff -u /tmp/ia /tmp/ib || { echo "$a and $b diverge after '$marker'"; exit 1; }
+            n=$((n+1))
+          done < .ci-identical-files
+          test "$n" -ge 1 || { echo ".ci-identical-files declared no pairs"; exit 1; }
+          echo "$n declared pair(s) identical"
+
       - name: The probe is one source, and the layering is a directory tree
         run: |
           set -euo pipefail
@@ -347,7 +410,7 @@ jobs:
       run:
         shell: bash
     env:
-      MCPP_VERSION: 2026.8.21.1
+      MCPP_VERSION: 2026.8.21.2
       XLINGS_VERSION: v2026.8.17.2
       XLINGS_NON_INTERACTIVE: '1'
     steps:
@@ -437,7 +500,7 @@ jobs:
       run:
         shell: bash
     env:
-      MCPP_VERSION: 2026.8.21.1
+      MCPP_VERSION: 2026.8.21.2
       XLINGS_VERSION: v2026.8.17.2
       XLINGS_NON_INTERACTIVE: '1'
     steps:

abi/mcpp.toml

@@ -24,7 +24,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openarch-abi"
-version     = "0.5.1"
+version     = "0.6.0"
 description = "openarch's C ABI: the contract between the interface and an instruction set's backend"
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]

backends/aarch64/mcpp.toml

@@ -14,7 +14,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openarch-aarch64"
-version     = "0.5.1"
+version     = "0.6.0"
 description = "openarch's aarch64 backend: the instructions behind the ABI"
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]

backends/riscv64/mcpp.toml

@@ -14,7 +14,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openarch-riscv64"
-version     = "0.5.1"
+version     = "0.6.0"
 description = "openarch's riscv64 backend: the instructions behind the ABI"
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]

backends/x86_64/mcpp.toml

@@ -22,7 +22,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openarch-x86-64"
-version     = "0.5.1"
+version     = "0.6.0"
 description = "openarch's x86_64 backend: the instructions behind the ABI"
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]

examples/clock-study/build.mcpp

@@ -69,14 +69,19 @@ int main() {
     // those ARE installed with the package. This project has no board package —
     // none serves three machines — so it declares them itself.
     //
-    // ⚠️ AND IT CANNOT WARN. A build program's output reaches the user only
-    // when it FAILS: mcpp captures the process and prints what it captured
-    // solely on a non-zero exit. A `std::cerr` note here was written, measured,
-    // and removed — it printed nothing on the very builds that needed it, which
-    // is worse than no note at all because it looks like a fix. Failing instead
-    // would be wrong too: `mcpp build` has no need of an emulator.
+    // ⚠️ IT USED NOT TO BE ABLE TO SAY SO, AND THAT GAP IS NOW CLOSED.
     //
-    // So the README carries it, and this comment records why it has to.
+    // A build program's output reaches the user only when it FAILS: mcpp
+    // captures the process and prints what it captured solely on a non-zero
+    // exit. A `std::cerr` note here was written, measured, and removed — it
+    // printed nothing on the very builds that needed it, which is worse than no
+    // note at all because it looks like a fix. Failing instead would be wrong
+    // too: `mcpp build` has no need of an emulator.
+    //
+    // mcpp 2026.8.21.2 added `mcpp::warning()` for exactly this: a program that
+    // handled a condition correctly and still has something to say. The `else`
+    // branch below is what that channel exists for, and it survives the build
+    // cache, so it does not appear once and then look resolved.
     if (const char* dir = mcpp::xpkg_dir("xim", pkg); dir && *dir) {
         mcpp::runner(std::format("{}/bin/qemu-system-{}", dir, sys).c_str());
         // ⚠️ THE MACHINE TYPE IS NOT UNIVERSAL. `virt` is the para-virtual
@@ -99,6 +104,12 @@ int main() {
         // instruction: with `-kernel` and no `-bios` it runs the image directly.
         if (arch == "riscv64") { mcpp::runner("-bios"); mcpp::runner("none"); }
         mcpp::runner("-kernel");
+    } else {
+        mcpp::warning(std::format(
+            "{} is not installed, so `mcpp run --target {}-none-elf` has no "
+            "runner. `mcpp build` is unaffected. Install the three emulators "
+            "once:  xlings install qemu-riscv qemu-arm qemu-x86 -y",
+            pkg, arch).c_str());
     }
 
     mcpp::rerun_if_env_changed("MCPP_TARGET_ARCH");

examples/switch/build.mcpp

@@ -69,14 +69,19 @@ int main() {
     // those ARE installed with the package. This project has no board package —
     // none serves three machines — so it declares them itself.
     //
-    // ⚠️ AND IT CANNOT WARN. A build program's output reaches the user only
-    // when it FAILS: mcpp captures the process and prints what it captured
-    // solely on a non-zero exit. A `std::cerr` note here was written, measured,
-    // and removed — it printed nothing on the very builds that needed it, which
-    // is worse than no note at all because it looks like a fix. Failing instead
-    // would be wrong too: `mcpp build` has no need of an emulator.
+    // ⚠️ IT USED NOT TO BE ABLE TO SAY SO, AND THAT GAP IS NOW CLOSED.
     //
-    // So the README carries it, and this comment records why it has to.
+    // A build program's output reaches the user only when it FAILS: mcpp
+    // captures the process and prints what it captured solely on a non-zero
+    // exit. A `std::cerr` note here was written, measured, and removed — it
+    // printed nothing on the very builds that needed it, which is worse than no
+    // note at all because it looks like a fix. Failing instead would be wrong
+    // too: `mcpp build` has no need of an emulator.
+    //
+    // mcpp 2026.8.21.2 added `mcpp::warning()` for exactly this: a program that
+    // handled a condition correctly and still has something to say. The `else`
+    // branch below is what that channel exists for, and it survives the build
+    // cache, so it does not appear once and then look resolved.
     if (const char* dir = mcpp::xpkg_dir("xim", pkg); dir && *dir) {
         mcpp::runner(std::format("{}/bin/qemu-system-{}", dir, sys).c_str());
         // ⚠️ THE MACHINE TYPE IS NOT UNIVERSAL. `virt` is the para-virtual
@@ -99,6 +104,12 @@ int main() {
         // instruction: with `-kernel` and no `-bios` it runs the image directly.
         if (arch == "riscv64") { mcpp::runner("-bios"); mcpp::runner("none"); }
         mcpp::runner("-kernel");
+    } else {
+        mcpp::warning(std::format(
+            "{} is not installed, so `mcpp run --target {}-none-elf` has no "
+            "runner. `mcpp build` is unaffected. Install the three emulators "
+            "once:  xlings install qemu-riscv qemu-arm qemu-x86 -y",
+            pkg, arch).c_str());
     }
 
     mcpp::rerun_if_env_changed("MCPP_TARGET_ARCH");

mcpp.toml

@@ -33,7 +33,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openarch"
-version     = "0.5.1"
+version     = "0.6.0"
 description = "openarch: the architecture-mechanism layer — execution contexts, traps, per-CPU state and address spaces, as one interface over several instruction sets"
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]

templates/three-machines/build.mcpp.in

@@ -69,14 +69,19 @@ int main() {
     // those ARE installed with the package. This project has no board package —
     // none serves three machines — so it declares them itself.
     //
-    // ⚠️ AND IT CANNOT WARN. A build program's output reaches the user only
-    // when it FAILS: mcpp captures the process and prints what it captured
-    // solely on a non-zero exit. A `std::cerr` note here was written, measured,
-    // and removed — it printed nothing on the very builds that needed it, which
-    // is worse than no note at all because it looks like a fix. Failing instead
-    // would be wrong too: `mcpp build` has no need of an emulator.
+    // ⚠️ IT USED NOT TO BE ABLE TO SAY SO, AND THAT GAP IS NOW CLOSED.
     //
-    // So the README carries it, and this comment records why it has to.
+    // A build program's output reaches the user only when it FAILS: mcpp
+    // captures the process and prints what it captured solely on a non-zero
+    // exit. A `std::cerr` note here was written, measured, and removed — it
+    // printed nothing on the very builds that needed it, which is worse than no
+    // note at all because it looks like a fix. Failing instead would be wrong
+    // too: `mcpp build` has no need of an emulator.
+    //
+    // mcpp 2026.8.21.2 added `mcpp::warning()` for exactly this: a program that
+    // handled a condition correctly and still has something to say. The `else`
+    // branch below is what that channel exists for, and it survives the build
+    // cache, so it does not appear once and then look resolved.
     if (const char* dir = mcpp::xpkg_dir("xim", pkg); dir && *dir) {
         mcpp::runner(std::format("{}/bin/qemu-system-{}", dir, sys).c_str());
         // ⚠️ THE MACHINE TYPE IS NOT UNIVERSAL. `virt` is the para-virtual
@@ -99,6 +104,12 @@ int main() {
         // instruction: with `-kernel` and no `-bios` it runs the image directly.
         if (arch == "riscv64") { mcpp::runner("-bios"); mcpp::runner("none"); }
         mcpp::runner("-kernel");
+    } else {
+        mcpp::warning(std::format(
+            "{} is not installed, so `mcpp run --target {}-none-elf` has no "
+            "runner. `mcpp build` is unaffected. Install the three emulators "
+            "once:  xlings install qemu-riscv qemu-arm qemu-x86 -y",
+            pkg, arch).c_str());
     }
 
     mcpp::rerun_if_env_changed("MCPP_TARGET_ARCH");