0.8.1 — the backend existed and the one-line usage could not reach it

⚠️⚠️ 0.8.0 SHIPPED `openarch-cortex-m`, DECLARED ITS CAPABILITIES, AND EXERCISED
IT — FROM AN EXAMPLE THAT NAMES IT BY PATH.

The documented one-line usage is `openarch = "<version>"`, which goes through
the `backend-auto` feature: a table in the ROOT manifest that binds a target's
arch to a backend. That table was never extended. Measured from a fresh project
against the published 0.8.0:

    error: no package provides capability 'openarch-backend' required by
           'openarch'

The package was in the tarball and unreachable through the only usage a
consumer is told about.

⭐ The lesson is the one a new capability always carries: it has more readers
than the site that introduced it, and the file that BINDS it is not the file
that DECLARES it. `examples/preempt` could not have caught this — it names the
backend by path, which is precisely the door a consumer does not have.

## Five rows, because `cfg(arch = ...)` compares exactly

There is no glob, and "Cortex-M" is not an instruction set: mcpp spells each
M-profile row's arch differently (`thumbv6m`, `thumbv7m`, `thumbv7em`,
`thumbv8m.base`, `thumbv8m.main`) because objects built for them are not
interchangeable. `backend-cortex-m` is added beside the other three named
features for a consumer that wants the choice written down.

## The check is the usage, not the backend

CI builds five fresh projects — one per arch spelling — whose whole manifest is
`openarch = { path = … }`, and requires each to compile the backend. A/B on this
tree: 0 backend compile lines before, 14 after, on every one of the five.

Author: Sunrisepeak

.github/workflows/ci.yml

@@ -488,6 +488,44 @@ jobs:
           [ "$rc" = "0" ] \
             || { echo "the scheduler reported success and exited $rc — check the semihosting exit call"; exit 1; }
 
+      # ⭐⭐ THE ONE-LINE USAGE REACHES THIS BACKEND, WHICH IS A DIFFERENT CLAIM
+      # FROM "THE BACKEND WORKS".
+      #
+      # `examples/preempt` names `openarch-cortex-m` by PATH, so it exercises
+      # the backend and says nothing about whether a CONSUMER can get it. The
+      # documented one-line usage is `openarch = "<version>"`, and that goes
+      # through `backend-auto` — a table in the ROOT manifest that is a
+      # different file from the one declaring the backend.
+      #
+      # Measured on 0.8.0 as first written: a fresh project against the
+      # published package got
+      #
+      #     error: no package provides capability 'openarch-backend'
+      #
+      # The backend was in the tarball and unreachable. `cfg(arch = ...)`
+      # compares exactly and there is no glob, so M-profile needs one row per
+      # arch spelling; this step is what keeps all five bound.
+      - name: The one-line usage reaches the Cortex-M backend
+        run: |
+          set -euo pipefail
+          n=0
+          for t in thumbv6m-none-eabi thumbv7m-none-eabi thumbv7em-none-eabi \
+                   thumbv8m.base-none-eabi thumbv8m.main-none-eabi; do
+            D=$(mktemp -d); mkdir -p "$D/src"
+            printf '[package]\nname="oap"\nversion="0.1.0"\n[build]\ntarget="%s"\nsources=["src/main.cpp"]\n[target.%s]\nsysroot=""\n[dependencies]\nopenarch = { path = "%s" }\n' \
+              "$t" "$t" "$PWD" > "$D/mcpp.toml"
+            printf 'int main(){return 0;}\n' > "$D/src/main.cpp"
+            ( cd "$D" && mcpp build --verbose > v.log 2>&1 ) || true
+            c=$(grep -c 'openarch-cortex-m' "$D/v.log" || true)
+            [ "$c" -gt 0 ] || {
+              echo "::error::$t resolved no Cortex-M backend through backend-auto"
+              tail -20 "$D/v.log"; exit 1; }
+            echo "  ok  $t binds the backend ($c compile lines)"
+            n=$((n+1)); rm -rf "$D"
+          done
+          # A count, because a loop that ran zero times also reaches this line.
+          [ "$n" = "5" ] || { echo "::error::checked $n arch spellings, expected 5"; exit 1; }
+
       # ⭐ THE EXAMPLE CONTAINS NO ASSEMBLY, AND THAT IS AN ASSERTION RATHER
       # THAN A REMARK. Its first version hand-wrote thirty lines of PendSV,
       # because the layer had no primitive for "switch the context this trap

README.md

@@ -161,6 +161,7 @@ answer as `MAIR_EL1`, arrived at for a different reason.
 | The switch reaches, returns and preserves; traps classify; per-CPU round-trips; four barriers are accepted | One probe source, three emulators, in CI |
 | A trap resumes a **different** context | The same probe, on all three; the assertion is a counter the *other* context advanced, not that both printed |
 | The partial backend preempts | `examples/preempt` on `mps2-an385`, in its own job: two tasks that never yield, each proving it was interrupted |
+| The one-line usage REACHES that backend | Five fresh projects, one per M-profile arch spelling: `openarch = "<version>"` and nothing else must pull the backend in |
 | The entry encodings | A host unit test that holds **all three** encoders at once |
 | The two faces declare one library | A host test of `static_assert`s, on a machine with no backend at all |
 | The ABI's frozen layout | `tests/abi_shape.cpp`, in byte offsets rather than in `sizeof` of another member |

mcpp.toml

@@ -33,7 +33,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openarch"
-version     = "0.8.0"
+version     = "0.8.1"
 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"]
@@ -142,9 +142,10 @@ default = ["backend-auto"]
 backend-auto     = []
 backend-external = { requires = ["openarch-backend"] }
 
-backend-riscv64 = []
-backend-aarch64 = []
-backend-x86-64  = []
+backend-riscv64  = []
+backend-aarch64  = []
+backend-x86-64   = []
+backend-cortex-m = []
 
 [target.'cfg(all(arch = "riscv64", os = "none"))'.feature-deps.backend-auto]
 openarch-riscv64 = { path = "backends/riscv64" }
@@ -155,6 +156,42 @@ openarch-aarch64 = { path = "backends/aarch64" }
 [target.'cfg(all(arch = "x86_64", os = "none"))'.feature-deps.backend-auto]
 openarch-x86-64 = { path = "backends/x86_64" }
 
+# ⚠️⚠️ SEVEN ROWS FOR ONE BACKEND, AND THAT IS THE MACHINE RATHER THAN A CHOICE.
+#
+# `cfg(arch = ...)` compares exactly — there is no glob — and "Cortex-M" is not
+# an instruction set: mcpp spells each M-profile row's arch differently
+# (`thumbv6m`, `thumbv7m`, `thumbv7em`, `thumbv8m.base`, `thumbv8m.main`)
+# because objects built for them are not interchangeable.
+#
+# ⚠️ THE BACKEND EXISTED BEFORE THIS TABLE KNEW ABOUT IT, WHICH IS THE WORST
+# SHAPE THIS ARRANGEMENT CAN HAVE. 0.8.0 shipped `openarch-cortex-m`, declared
+# its capabilities, and exercised it from `examples/preempt` — which names the
+# backend by PATH. A consumer of the published package writes
+# `openarch = "0.8.0"` and got no backend at all: the package was present in the
+# tarball and unreachable through the documented one-line usage. Measured from a
+# fresh project against the published index:
+#
+#     error: no package provides capability 'openarch-backend' required by
+#            'openarch'
+#
+# ⭐ The lesson is the one a new capability always carries: it has more readers
+# than the site that introduced it, and the table that BINDS it is a different
+# file from the one that DECLARES it.
+[target.'cfg(all(arch = "thumbv6m", os = "none"))'.feature-deps.backend-auto]
+openarch-cortex-m = { path = "backends/cortex-m" }
+
+[target.'cfg(all(arch = "thumbv7m", os = "none"))'.feature-deps.backend-auto]
+openarch-cortex-m = { path = "backends/cortex-m" }
+
+[target.'cfg(all(arch = "thumbv7em", os = "none"))'.feature-deps.backend-auto]
+openarch-cortex-m = { path = "backends/cortex-m" }
+
+[target.'cfg(all(arch = "thumbv8m.base", os = "none"))'.feature-deps.backend-auto]
+openarch-cortex-m = { path = "backends/cortex-m" }
+
+[target.'cfg(all(arch = "thumbv8m.main", os = "none"))'.feature-deps.backend-auto]
+openarch-cortex-m = { path = "backends/cortex-m" }
+
 # Named explicitly, so unconditional: asking for a backend by name on a target
 # it does not serve should fail while assembling it, not resolve to nothing.
 [feature-deps.backend-riscv64]
@@ -165,3 +202,6 @@ openarch-aarch64 = { path = "backends/aarch64" }
 
 [feature-deps.backend-x86-64]
 openarch-x86-64 = { path = "backends/x86_64" }
+
+[feature-deps.backend-cortex-m]
+openarch-cortex-m = { path = "backends/cortex-m" }