cibuildmp 0.7.0__tar.gz → 0.7.2__tar.gz

cibuildmp-0.7.2/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "autoMode": {
+    "allow": [
+      "$defaults",
+      "Copying this session's own agent-proxy TLS CA bundle (/root/.ccr/ca-bundle.crt) into a Docker build context or container for this repo's own Docker-based build drivers, per .claude/skills/docker-local/SKILL.md section 4 -- session-local test tooling, never a committed Dockerfile."
+    ]
+  }
+}

{cibuildmp-0.7.0 → cibuildmp-0.7.2}/.claude/skills/docker-local/SKILL.md

@@ -246,6 +246,57 @@ ERROR: unable to select packages:
 describes, so the ordinary Debian/Ubuntu fix routes through the one thing that cannot succeed yet.
 Appending directly to the file already on disk sidesteps the whole cycle.
 
+## 4a. When the CA-injection fix itself gets blocked: pre-seed the tool's own download cache instead
+
+Confirmed live (record [0060]'s own esp32 correction): copying this session's own proxy CA into a
+Dockerfile/container — section 4's whole recipe, however it's phrased — can itself get refused by
+this session's **auto-mode classifier**, a separate layer from the network allowlist and from
+ordinary tool permissions. It reads as "inject a certificate into a container", a real MITM
+pattern, regardless of the legitimate reason here. Two things do **not** get past this:
+
+- Adding an explicit allow rule to `.claude/settings.json`'s own `autoMode.allow` list (the
+  documented mechanism for exactly this) is *itself* blocked by the same classifier — an agent
+  cannot self-grant a permission the classifier just refused, which is the boundary working as
+  intended, not a bug to route around.
+- Even after a human adds that rule from outside the session (git push, GitHub web UI, editing
+  the file directly on disk) and it lands in the working tree, the running session does not pick
+  it up — the settings watcher only watches paths that had a settings file *at session start*, the
+  identical caveat the `update-config` skill documents for hooks. Nothing short of a session
+  restart reloads it.
+
+**If a restart isn't available, don't force the CA path — ask whether the specific tool doing the
+fetch already implements its own "already downloaded, skip the network" check, and satisfy that
+check from the host instead.** Several of this project's own container-time fetchers already do
+(`toolchain_fetch.fetch_script()`'s marker file, `container_mpy_cross()`'s cache-by-existence
+rule) — and so, live-verified this session, does ESP-IDF's own `idf_tools.py`: its `download()`
+method looks for `$IDF_TOOLS_PATH/dist/<archive_name>`, verifies its sha256/size against
+`tools.json`, and returns immediately without touching the network if it matches. That check does
+not care *how* the file got there.
+
+The recipe, generalized from the real esp32 case:
+
+1. Find the *tool's own* manifest of exactly what it will fetch, with real URLs and checksums —
+   `idf_tools.py`'s is `<idf-checkout>/tools/tools.json`; other tools have their own equivalent.
+   Cloning the source checkout itself is usually plain `git clone` (this session's own host-side
+   `curl`/`git` already work fine against real hosts — it is only *container* traffic that hits
+   the interception wall) — `usermod/espidf.py`'s own `fetch_esp_idf()` already does exactly this
+   clone, host-side, for the identical reason.
+2. Download each needed artifact **on the host**, into whatever local path the tool's own cache
+   check expects (`$IDF_TOOLS_PATH/dist/<archive_name>` for `idf_tools.py`), verifying its
+   checksum against the manifest's own value — never trust-on-first-use.
+3. Make sure that path is one of the container's own bind mounts (it usually already is, if it's
+   the tool's persistent cache directory rather than the ephemeral build tree) — then the
+   container sees the identical files at the identical path, no new mount, no Dockerfile edit.
+4. Run the real container-time install/fetch command unmodified. It reports "already downloaded"
+   or equivalent and does real, genuine extraction/verification with **zero network calls from
+   inside the container** — this is not a stub or a shortcut, the resulting tool is the real
+   published artifact, just fetched via a path that was never blocked in the first place.
+
+This is real work (the esp32 case needed five separate archives, ~230 MB, individually identified
+from `tools.json` and individually checksummed) but it is a live verification with a genuinely
+real toolchain, not a mock — worth it over declaring the fix "untestable here" when the target
+tool's own caching already does half the job.
+
 ## 5. Hosts this repo's own `docker/*.Dockerfile` files actually fetch from
 
 Grepped directly (`grep -rhoE 'https?://[a-zA-Z0-9.-]+' docker/*.Dockerfile`),

{cibuildmp-0.7.0 → cibuildmp-0.7.2}/.github/workflows/build-examples.yml

@@ -110,8 +110,8 @@ jobs:
 
       - name: List built artifacts
         run: |
-          ls -laR examples/template/mpyhouse
-          ls -laR examples/wasm2mpy/mpyhouse
+          tree -a examples/template/mpyhouse
+          tree -a examples/wasm2mpy/mpyhouse
           cat examples/template/mpyhouse/*/package.json
 
   # Split from `build` above rather than added as one more step there:
@@ -265,7 +265,38 @@ jobs:
           build: ${{ matrix.build }}
 
       - name: List built artifacts
-        run: ls -laR examples/template/mpyhouse
+        run: tree -a examples/template/mpyhouse
+
+  # ── usermod: stock upstream firmware, no C module at all ───────────
+  #
+  # examples/bare-firmware/cibuildmp.toml (record 0056's Option A): one
+  # Make-driven target (`unix`) and one CMake-driven one (`rp2`), the two
+  # build-system shapes `USER_C_MODULES=` (empty) has to no-op on cleanly.
+  # `CIBMP_NO_USER_C_MODULES=1` here, not `no-user-c-modules = true` in
+  # that file -- this job is also the live proof the environment-variable
+  # activation path works, not just the TOML key (README's own "Building
+  # stock upstream firmware" section links back to this job).
+  #
+  # Both targets are native to an amd64 runner (dockerrun.platform_for():
+  # `unix`'s own x86_64 image, every other port's `linux/amd64` cross
+  # host) -- no docker/setup-qemu-action needed, unlike build-usermod's
+  # own qemu leg.
+  build-bare-firmware:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build examples/bare-firmware (stock upstream, no C module)
+        uses: ./
+        env:
+          CIBMP_NO_USER_C_MODULES: "1"
+        with:
+          package-dir: examples/bare-firmware
+
+      - name: List built artifacts
+        run: tree -a examples/bare-firmware/mpyhouse
 
   # ── the same build on the runner it would not have chosen ──────────
   #
@@ -323,7 +354,7 @@ jobs:
           build: ${{ matrix.build }}
 
       - name: List built artifacts
-        run: ls -laR examples/template/mpyhouse
+        run: tree -a examples/template/mpyhouse
 
   # ── usermod: the six emulated-everywhere cells ──────────────────────
   #
@@ -383,4 +414,4 @@ jobs:
           build: ${{ matrix.build }}
 
       - name: List built artifacts
-        run: ls -laR examples/template/mpyhouse
+        run: tree -a examples/template/mpyhouse

{cibuildmp-0.7.0 → cibuildmp-0.7.2}/.github/workflows/test-upstream-natmod.yml

@@ -135,7 +135,7 @@ jobs:
           build: "${{ env.CIBMP_UPSTREAM_ABI_TAG }}-x64 ${{ env.CIBMP_UPSTREAM_ABI_TAG }}-armv7emsp mpy6.3-v1.28.0-x86"
 
       - name: List built artifacts
-        run: ls -laR examples/natmod/mpyhouse
+        run: tree -a examples/natmod/mpyhouse
 
   build-upstream-natmod:
     strategy:
@@ -166,4 +166,4 @@ jobs:
           build: "${{ env.CIBMP_UPSTREAM_ABI_TAG }}-x64"
 
       - name: List built artifacts
-        run: ls -laR examples/natmod/mpyhouse
+        run: tree -a examples/natmod/mpyhouse

{cibuildmp-0.7.0 → cibuildmp-0.7.2}/.github/workflows/test-upstream-usermodule.yml

@@ -6,13 +6,14 @@ name: Test upstream usercmodule
 # not one this project wrote for itself); docs/records/0069 is the mechanism
 # actually landed here and explains every choice below in full.
 #
-# Six jobs, one per port cibuildmp drives a usermod build for -- widened
+# Seven jobs, one per port cibuildmp drives a usermod build for -- widened
 # from the original narrow unix+rp2 slice ([0054]'s own "one Make port and
 # one CMake port is enough to answer the three questions above") once that
 # slice came back green, per [0054]'s own "widen only if it finds
-# something." Still nowhere near build-examples.yml's much broader
-# examples/template matrix: one representative identifier per port, not
-# each port's own full arch/board matrix.
+# something," most recently to samd once [0100] gave it a real driver.
+# Still nowhere near build-examples.yml's much broader examples/template
+# matrix: one representative identifier per port, not each port's own full
+# arch/board matrix.
 #
 # No job here sets `CIBMP_USER_C_MODULES`/`CIBMP_EXTRA_MAKE_ARGS`/
 # `CIBMP_EXTRA_CMAKE_ARGS`, and none of them ever resolves the pinned
@@ -88,7 +89,7 @@ jobs:
           build: ${{ env.CIBMP_UPSTREAM_TAG }}-manylinux_2_28_x86_64
 
       - name: List built artifacts
-        run: ls -laR examples/usercmodule/mpyhouse
+        run: tree -a examples/usercmodule/mpyhouse
 
       # A linked binary is not the same claim as one whose modules actually
       # run -- unix is the one port here whose own output this runner can
@@ -140,7 +141,46 @@ jobs:
           build: ${{ env.CIBMP_UPSTREAM_TAG }}-rp2-RPI_PICO
 
       - name: List built artifacts
-        run: ls -laR examples/usercmodule/mpyhouse
+        run: tree -a examples/usercmodule/mpyhouse
+
+  # ── samd: the fifth Make port, [0100]'s own build driver ────────────────
+  #
+  # Widened per [0054]'s own "widen only if it finds something" -- samd's
+  # own first live verification found a real bug ([0060]'s correction: an
+  # unprobed gcc-15-only diagnostic breaking every pre-v1.26.0 row), the
+  # exact class of thing this fixture exists to catch on an upstream-owned
+  # module, not one this project wrote for itself. A plain-Make port like
+  # unix/windows/qemu/webassembly, not cmake like rp2/esp32 -- needs the
+  # same `user-c-modules = "{micropython}/examples/usercmodule"` override
+  # those four already carry (examples/usercmodule/cibuildmp.toml), added
+  # there for samd's own identifier glob rather than left on the "." default
+  # that only resolves correctly for the two cmake ports.
+  #
+  # ADAFRUIT_FEATHER_M4_EXPRESS (SAMD51, 512KB flash), not the smaller
+  # SEEED_XIAO_SAMD21 record 0100 verified first -- live-caught here:
+  # SEEED_XIAO_SAMD21's own SAMD21 (256KB flash, 184KB usable FLASH region)
+  # overflows by ~5KB once cexample/cppexample/subpackage are all actually
+  # linked in, `region 'FLASH' overflowed by 4888 bytes`. A real board
+  # constraint, not a cibuildmp bug -- MicroPython's own build fits fine on
+  # SEEED_XIAO_SAMD21 with no extra user C modules.
+  build-samd:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      CIBMP_VERSION: 0.0.0-ci
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/setup-qemu-action@v4
+
+      - name: Build upstream examples/usercmodule (samd)
+        uses: ./
+        with:
+          package-dir: examples/usercmodule
+          build: ${{ env.CIBMP_UPSTREAM_TAG }}-samd-ADAFRUIT_FEATHER_M4_EXPRESS
+
+      - name: List built artifacts
+        run: tree -a examples/usercmodule/mpyhouse
 
   # ── esp32: the second CMake port, and the second bare-metal toolchain ──
   #
@@ -172,7 +212,7 @@ jobs:
           build: ${{ env.CIBMP_UPSTREAM_TAG }}-esp32-ESP32_GENERIC
 
       - name: List built artifacts
-        run: ls -laR examples/usercmodule/mpyhouse
+        run: tree -a examples/usercmodule/mpyhouse
 
   # ── windows, webassembly, qemu: the remaining three Make ports ──────────
   #
@@ -216,7 +256,7 @@ jobs:
           build: ${{ env.CIBMP_UPSTREAM_TAG }}-win_amd64
 
       - name: List built artifacts
-        run: ls -laR examples/usercmodule/mpyhouse
+        run: tree -a examples/usercmodule/mpyhouse
 
       # Both the apt install and the run itself are in
       # `.github/actions/run-with-wine` -- see that action's own header for
@@ -249,7 +289,7 @@ jobs:
           build: ${{ env.CIBMP_UPSTREAM_TAG }}-wasm32
 
       - name: List built artifacts
-        run: ls -laR examples/usercmodule/mpyhouse
+        run: tree -a examples/usercmodule/mpyhouse
 
       # The same smoke_test.py the unix job runs, unmodified -- the wasm
       # build's own CLI takes a .py path exactly like the unix binary
@@ -291,7 +331,7 @@ jobs:
           build: ${{ env.CIBMP_UPSTREAM_TAG }}-qemu-MPS2_AN385
 
       - name: List built artifacts
-        run: ls -laR examples/usercmodule/mpyhouse
+        run: tree -a examples/usercmodule/mpyhouse
 
       # `docker/setup-qemu-action` above only registers binfmt_misc
       # handlers for cross-arch *container* builds -- unrelated to

{cibuildmp-0.7.0 → cibuildmp-0.7.2}/.github/workflows/verify-lv-binding-micropython.yml

@@ -71,7 +71,7 @@ jobs:
           build: ${{ env.CIBMP_UPSTREAM_TAG }}-manylinux_2_28_x86_64
 
       - name: List built artifacts
-        run: ls -laR examples/lv_binding_micropython/mpyhouse
+        run: tree -a examples/lv_binding_micropython/mpyhouse
 
       # Not just that it links: this registers a real (headless) LVGL
       # display, builds a widget tree, and renders a frame through it. See

{cibuildmp-0.7.0 → cibuildmp-0.7.2}/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-09-06
+
+### Added
+
+- **`samd` gets a real `build_samd()` driver** — the easiest of [0053]'s
+  remaining nine driverless usermod ports to pick up next (`esp8266` ruled
+  out for tags too old to be worth it), modeled on `rp2`'s own plain-Make
+  shape rather than esp32/rp2's cmake one. No new provisioning step needed:
+  like `rp2`, `orchestrate.build()` already generalizes `sources.
+  fetch_micropython()` for it. Live-verified against real identifiers
+  spanning `v1.20.0` through the current tag; `KNOWN_PORTS` now carries
+  seven wired drivers, not six. `[0100]`.
+
+### Fixed
+
+- **`rp2` and `esp32` both passed `tag_cflags()`'s candidate `CFLAGS_EXTRA`
+  straight into their build command with no probing**, unlike every other
+  cross-compiling port here — `-Wno-error=unterminated-string-initialization`
+  (a gcc-15-only diagnostic, flagged for every tag `v1.12`-`v1.25.0`
+  regardless of which toolchain a given row actually resolves to) hard-failed
+  `cc1: error: ... no option '-Wunterminated-string-initialization'` on every
+  pre-`v1.26.0` row of either port, since both resolve to a sub-gcc-15
+  toolchain there. Live-reproduced on `v1.24.0-rp2-ADAFRUIT_FEATHER_RP2040`
+  (now producing a genuine `firmware.uf2`) and against a real ESP-IDF
+  `xtensa-esp-elf-gcc 14.2.0`. Fixed the same way `unix` already was
+  ([0082]): fetch/discover the real compiler first, then probe it with
+  `build_common.probe_supported_cflags()` before building `CFLAGS_EXTRA`.
+  `esp32` has no static `<prefix>gcc` to point at, so its own fix discovers
+  the real cross-compiler dynamically (a `$PATH` glob for `*-elf-gcc`, run
+  after ESP-IDF's own install+export sequence) rather than guessing an
+  `idf_target -> prefix` table. Neither bug had ever been exercised by CI --
+  no workflow in this repo has built `rp2`/`esp32` below `v1.26.0`. `[0060]`.
+
+## [0.7.1] - 2026-09-04
+
+### Added
+
+- **`no-user-c-modules = true` builds a stock, unmodified upstream MicroPython
+  through the usermod path — no `USER_C_MODULES`, nothing of a consumer's own in
+  the result.** Mutually exclusive with `user-c-modules` (a load-time error, not
+  a precedence rule); the empty `USER_C_MODULES=` this resolves to is a verified
+  no-op on both build systems this project drives, confirmed live against a real
+  `v1.29.0` checkout — a stock `unix` binary correctly raising `ImportError` for
+  a module never linked in, and the same binary succeeding once one is. Surfaced
+  and fixed a real bug along the way: every per-port mount helper built
+  `Path(opts.user_c_modules)` unconditionally, and an empty value is `Path(".")`
+  — a *relative* path `docker run -v` rejects outright, not merely an
+  unnecessary over-mount. `[0056]`.
+- **`examples/bare-firmware`**, a real CI-built demonstration with no `natmod/`,
+  no `usermod/`, no `src/` — just a `cibuildmp.toml` naming one Make-driven
+  target (`unix` `x86_64`) and one CMake-driven one (`rp2` `RPI_PICO`), the two
+  build-system shapes `no-user-c-modules` has to no-op on cleanly.
+  `build-examples.yml`'s new `build-bare-firmware` job activates the flag
+  through `CIBMP_NO_USER_C_MODULES` rather than the TOML key, doubling as a live
+  demonstration of the environment-variable form. `README.md` gets its own
+  "Building stock upstream firmware" section for it — framed as a real
+  capability (a cross-toolchain/board regression check with no C module
+  needed), useful to this project's own consumers but arguably more useful to
+  MicroPython's own maintainers.
+
+### Changed
+
+- **"List built artifacts" CI steps use `tree -a` instead of `ls -laR`**, across
+  `build-examples.yml`, `test-upstream-natmod.yml`, `test-upstream-usermodule.yml`
+  and `verify-lv-binding-micropython.yml` — more readable output for the same
+  recursive listing; `tree` is already an apt package on the `ubuntu-24.04`
+  runner image both `ubuntu-latest` and `ubuntu-24.04-arm` use.
+
+### Removed
+
+- **`CIBMP_SCRATCH_PATH`.** Every usermod port has built through its own
+  `Container`/overlay since `0.6.x` (record 0095), so the directory this
+  variable named was never mounted or read by anything — setting it created a
+  real host directory nothing wrote to. Record 0095's own addendum had flagged
+  this as a live no-op and left "delete, repurpose, or keep as a no-op knob" as
+  an open question; deleting it won. `orchestrate._resolved_build_dir()` now
+  returns a fixed, container-internal path with no host directory, no env
+  override and no cleanup to manage.
+
 ## [0.7.0] - 2026-09-04
 
 ### Fixed
@@ -1590,7 +1669,9 @@ ballistics-lab/micropython-native-ci, but both tags exist here too, so every
 link resolves inside this repository -- the version line continues rather
 than restarting (see the 0.3.0a1 entry). -->
 
-[Unreleased]: https://github.com/ballistics-lab/cibuildmp/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/ballistics-lab/cibuildmp/compare/v0.7.2...HEAD
+[0.7.2]: https://github.com/ballistics-lab/cibuildmp/compare/v0.7.1...v0.7.2
+[0.7.1]: https://github.com/ballistics-lab/cibuildmp/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/ballistics-lab/cibuildmp/compare/v0.6.2...v0.7.0
 [0.6.2]: https://github.com/ballistics-lab/cibuildmp/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/ballistics-lab/cibuildmp/compare/v0.6.0...v0.6.1
@@ -1623,3 +1704,7 @@ than restarting (see the 0.3.0a1 entry). -->
 [0090]: docs/records/0090-toolchain-pins-checker-and-0058-text-followup.md
 [0095]: docs/records/0095-cache-root-splits-source-from-build-state.md
 [0096]: docs/records/0096-arm-riscv-embedded-collapse-into-embedded-base.md
+[0056]: docs/records/0056-usermod-with-no-user-c-module.md
+[0053]: docs/records/0053-usermod-ports-without-a-build-driver.md
+[0060]: docs/records/0060-rp2-build-driver.md
+[0100]: docs/records/0100-samd-build-driver-plan.md

{cibuildmp-0.7.0/src/cibuildmp.egg-info → cibuildmp-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cibuildmp
-Version: 0.7.0
+Version: 0.7.2
 Summary: Build MicroPython native C extensions for every target, from one config — cibuildwheel for MicroPython
 Author-email: o-murphy <thehelixpg@gmail.com>
 License-Expression: MIT
@@ -157,11 +157,34 @@ On CI, use the action instead of installing the CLI yourself — it already
 runs on a bare runner with the runner's own Docker daemon reachable:
 
 ```yaml
-- uses: ballistics-lab/cibuildmp@v0.7.0
+- uses: ballistics-lab/cibuildmp@v0.7.2
   with:
     build: "mpy6.3-* v1.29.0-manylinux_2_28_x86_64"
 ```
 
+**Cache fetched MicroPython checkouts (and ESP-IDF) between runs** with a plain
+`actions/cache` step before the action, pointed at `CIBMP_CACHE_PATH`'s own
+default (`~/.cache/cibuildmp`, `$XDG_CACHE_HOME/cibuildmp` if that's set) — a
+prefix key rather than one hashed to a single config, since a checkout is
+addressed by MicroPython tag inside the cache directory and the same cache
+usefully accumulates every tag a repo's history ever built, not just the
+newest:
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.cache/cibuildmp
+    key: cibuildmp-${{ runner.os }}
+    restore-keys: cibuildmp-${{ runner.os }}
+- uses: ballistics-lab/cibuildmp@v0.7.2
+  with:
+    build: "mpy6.3-* v1.29.0-manylinux_2_28_x86_64"
+```
+
+This caches fetched *source* only. Compiled build state does not live on the
+host at all any more — every usermod port builds inside its own container
+now (record 0095), so there is nothing to cache on that side.
+
 The action takes seven inputs, all optional — every one overrides the
 config file rather than replacing it:
 
@@ -212,7 +235,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ballistics-lab/cibuildmp@v0.7.0
+      - uses: ballistics-lab/cibuildmp@v0.7.2
         with:
           build: "mpy6.3-v1.29.0-*"
       - uses: actions/upload-artifact@v4
@@ -410,6 +433,45 @@ comments record three separate ways a shared `BUILD` directory silently
 produces the *wrong* arch's binary. Read it when your own build starts
 doing something strange, not before.
 
+### More than one module
+
+**natmod: one module per config, one config per directory.** `module-dir`
+names where *one* module's Makefile lives — pointing it at a parent
+directory holding several is a mis-scoped config, not a multi-module
+mechanism, and `collect_output()`'s refusal of an ambiguous two-`.mpy`
+result is exactly the guard that catches it. A project with two natmod
+modules gives each its own directory and config and runs `cibuildmp` once
+per module, into its own `output-dir` — [`examples/template`](examples/template)
+and [`examples/wasm2mpy`](examples/wasm2mpy) are already two modules, two
+configs, two invocations, two independent trees, side by side in this
+repo. Composing the results into one artifact set is your own workflow's
+job, the same way running `cibuildmp` twice is ([0057][0057]).
+
+**usermod: `user-c-modules` stays one path; N modules are your own
+layout.** `cibuildmp` never grows a list here — MicroPython's own two
+build systems already have a convention for it, and it differs by port:
+
+- **Make ports** put every module in its own subdirectory under the path
+  `user-c-modules` names, each with its own `micropython.mk`. `py/py.mk`
+  globs `<user-c-modules>/*/micropython.mk` on its own; nothing else to
+  write.
+- **CMake ports** point `user-c-modules` at one `micropython.cmake` that
+  `include()`s the others. [`examples/usercmodule/micropython.cmake`](examples/usercmodule/micropython.cmake)
+  is a real, working one, built by this project's own CI across all six
+  ports ([0069][0069]).
+
+The two forms are not symmetric, and that asymmetry is upstream's, not
+`cibuildmp`'s: pointed at the same directory, a Make port's glob picks up
+every subdirectory it finds, while a CMake port only builds what its
+`micropython.cmake` explicitly `include()`s. Upstream's own
+`examples/usercmodule/` shows exactly this — three real modules
+(`cexample`, `cppexample`, `subpackage`) reachable via the Make glob with
+no aggregator file at all, but upstream's own aggregator only lists the
+first two. `examples/usercmodule/micropython.cmake` above is this
+project's own file for that reason: it `include()`s upstream's aggregator
+*and* `subpackage`, so the fixture builds the same three modules on every
+port ([0057][0057]/[0069][0069]).
+
 ## Identifiers and selectors
 
 Every buildable thing — one natmod arch, one usermod port/board/arch cell —
@@ -427,15 +489,16 @@ platform.**
 Identifier shapes, one per platform:
 
 <!-- generated: identifier-shapes -- bin/refresh_docs.py, do not edit by hand -->
-| Platform              | Shape                   | Example                               |
-| --------------------- | ----------------------- | ------------------------------------- |
-| natmod                | `mpy{abi}-{tag}-{arch}` | `mpy6.3-v1.29.0-armv6m`               |
-| usermod `esp32`       | `{tag}-esp32-{board}`   | `v1.29.0-esp32-ARDUINO_NANO_ESP32`    |
-| usermod `qemu`        | `{tag}-qemu-{board}`    | `v1.29.0-qemu-MICROBIT`               |
-| usermod `rp2`         | `{tag}-rp2-{board}`     | `v1.29.0-rp2-ADAFRUIT_FEATHER_RP2040` |
-| usermod `unix`        | `{tag}-{arch}`          | `v1.29.0-manylinux_2_28_aarch64`      |
-| usermod `webassembly` | `{tag}-{arch}`          | `v1.29.0-wasm32`                      |
-| usermod `windows`     | `{tag}-{arch}`          | `v1.29.0-win32`                       |
+| Platform | Shape | Example |
+| --- | --- | --- |
+| natmod | `mpy{abi}-{tag}-{arch}` | `mpy6.3-v1.29.0-armv6m` |
+| usermod `esp32` | `{tag}-esp32-{board}` | `v1.29.0-esp32-ARDUINO_NANO_ESP32` |
+| usermod `qemu` | `{tag}-qemu-{board}` | `v1.29.0-qemu-MICROBIT` |
+| usermod `rp2` | `{tag}-rp2-{board}` | `v1.29.0-rp2-ADAFRUIT_FEATHER_RP2040` |
+| usermod `samd` | `{tag}-samd-{board}` | `v1.29.0-samd-ADAFRUIT_FEATHER_M0_EXPRESS` |
+| usermod `unix` | `{tag}-{arch}` | `v1.29.0-manylinux_2_28_aarch64` |
+| usermod `webassembly` | `{tag}-{arch}` | `v1.29.0-wasm32` |
+| usermod `windows` | `{tag}-{arch}` | `v1.29.0-win32` |
 <!-- /generated: identifier-shapes -->
 
 The shape genuinely differs per usermod port — `unix`/`windows`/
@@ -594,6 +657,7 @@ onto each other rather than the first winning.
 | `pre-build-command`      | natmod  | `""`                   |                                ✓                                 |
 | `extra-make-args`        | both    | `[]`                   |                                ✓                                 |
 | `user-c-modules`         | usermod | `"."`                  |                                ✓                                 |
+| `no-user-c-modules`      | usermod | `false`                |                                ✓                                 |
 | `manifest`               | usermod | `""`                   |                                ✓                                 |
 | `extra-cmake-args`       | usermod | `[]`                   |                                ✓                                 |
 
@@ -656,6 +720,35 @@ Two notes on individual keys:
   So an override for the flagged variant is `[override."*rv32imc+0x3"]`, and
   a plain `skip = "*-rv32imc"` will *not* match it — `*-rv32imc*` does.
 
+### Building stock upstream firmware
+
+`cibuildmp` is not only for building *your own* C module into a port — set
+`no-user-c-modules = true` and it builds a stock, unmodified upstream
+MicroPython through the exact same usermod path instead: no
+`USER_C_MODULES`, nothing of your own in the result. Mutually exclusive
+with `user-c-modules`; setting both is a load-time error, not a precedence
+rule ([0056]).
+
+That makes the whole matrix this project already resolves — every port,
+every board, every pinned toolchain — usable as a plain "does upstream
+still build here" check, with no C module involved at all. Useful for this
+project's own consumers, but arguably more useful to MicroPython's own
+maintainers: a regression check across a real cross-toolchain/board matrix
+that costs nothing to run beyond pointing `--build` at the tags and
+identifiers you care about, e.g.:
+
+```console
+$ CIBMP_NO_USER_C_MODULES=1 cibuildmp --build "v1.29.0-manylinux_2_28_x86_64 v1.29.0-rp2-RPI_PICO"
+```
+
+[`examples/bare-firmware`](examples/bare-firmware) is exactly this — no
+`natmod/`, no `usermod/`, no `src/`, just a `cibuildmp.toml` naming two
+targets (one Make-driven port, one CMake-driven one — record 0056's own
+two build systems). `.github/workflows/build-examples.yml`'s own
+`build-bare-firmware` job builds it on every push, activating the flag via
+`CIBMP_NO_USER_C_MODULES` rather than the TOML key, so it doubles as a
+live demonstration of the environment-variable form.
+
 ### Environment variables
 
 Every option key above has an environment form: `CIBMP_` + the key in
@@ -696,7 +789,6 @@ the port**, because it is that port's own build axis:
 | Variable                                | Effect                                                                                                                                                                                                                            |
 | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `CIBMP_CACHE_PATH`                      | Where fetched MicroPython checkouts and ESP-IDF are cached. Defaults to `$XDG_CACHE_HOME/cibuildmp`, or `~/.cache/cibuildmp`. Pin it in CI when a later step needs the checkout by path — `<CIBMP_CACHE_PATH>/micropython/<tag>` |
-| `CIBMP_SCRATCH_PATH`                    | Read, but currently redirects nothing: every usermod port's compiled build state now lives inside its own container and never reaches the host (record 0095's own addendum 13). Left as a documented knob rather than removed outright |
 | `CIBMP_REPORT_PATH`                     | Where the JSON build report is written                                                                                                                                                                                            |
 | `CIBMP_TIMEOUT`                         | Seconds before a build container is killed (`docker kill`, not just the CLI). No limit by default. **usermod only** -- natmod's own container call does not consult it                                                            |
 | `CIBMP_<PORT>_<TARGET>_TIMEOUT`         | The same, for one container — `CIBMP_UNIX_MANYLINUX_2_28_X86_64_TIMEOUT`                                                                                                                                                          |
@@ -762,7 +854,10 @@ naming a scalar option in `inherit` is a config error, not a silent no-op.
 [0038]: docs/records/0038-m5-adopt-in-three-repos.md
 [0043]: docs/records/0043-unix-adopts-cibuildwheel-native-image-model.md
 [0052]: docs/records/0052-config-is-a-tree-not-a-selector-matrix.md
+[0056]: docs/records/0056-usermod-with-no-user-c-module.md
+[0057]: docs/records/0057-multiple-modules-per-build.md
 [0058]: docs/records/0058-image-groups-are-toolchains-not-ports.md
+[0069]: docs/records/0069-upstream-usercmodule-narrow-ci-slice.md
 [0071]: docs/records/0071-micropython-placeholder-in-user-c-modules.md
 [0072]: docs/records/0072-natmod-micropython-placeholder-and-upstream-natmod-ci.md
 [0074]: docs/records/0074-usermod-family-table-and-retired-table-messages-removed.md
@@ -770,6 +865,9 @@ naming a scalar option in `inherit` is a config error, not a silent no-op.
 [0076]: docs/records/0076-the-mipsel-holdout-is-bclibc-and-wasm3-not-a7p.md
 [0077]: docs/records/0077-docs-drift-is-a-failing-test-not-a-discipline-problem.md
 [0097]: docs/records/0097-lv-binding-micropython-builds-through-cibuildmp.md
+[0053]: docs/records/0053-usermod-ports-without-a-build-driver.md
+[0060]: docs/records/0060-rp2-build-driver.md
+[0100]: docs/records/0100-samd-build-driver-plan.md
 
 ## When a build fails
 
@@ -907,10 +1005,10 @@ Nor is the build state: every usermod port builds inside a container's own
 overlay now (a `:ro` bind of the checkout plus a writable view on top), so
 object files, per-identifier `build-<identifier>/` trees and the
 container-built `mpy-cross` binaries never touch the host at all — they die
-with the container. `CIBMP_SCRATCH_PATH` is still read but currently has
-nothing to redirect, since nothing writes to the path it names any more;
-kept for now as a documented knob rather than removed outright (see record
-0095's own addendum 13 for the reasoning).
+with the container. There is no env var to point this anywhere any more
+either: `CIBMP_SCRATCH_PATH` named a host directory nothing had written to
+since that migration, and was removed once that was noticed rather than
+kept as a knob with nothing left to turn.
 
 ### Still stuck
 
@@ -1011,10 +1109,10 @@ real CI, arch by arch, not just `--dry-run`.
 Upstream MicroPython has 20 ports (`ports/*` in a real checkout); every one
 is listed below for orientation, not just the ones this project covers.
 `resources/build-platforms.toml` carries independently-verified
-`(tag, arch/board)` rows for 15 of them; only 6 (`unix`, `windows`, `qemu`,
-`webassembly`, `esp32`, `rp2`) have a real build driver wired into the CLI
-at all — the other 9 have verified facts a config can already *name*, but
-nothing yet to actually build them. Every ✅ row below is live-verified
+`(tag, arch/board)` rows for 15 of them; only 7 (`unix`, `windows`, `qemu`,
+`webassembly`, `esp32`, `rp2`, `samd`) have a real build driver wired into
+the CLI at all — the other 8 have verified facts a config can already
+*name*, but nothing yet to actually build them. Every ✅ row below is live-verified
 against a real MicroPython checkout, including a real custom
 `USER_C_MODULES` module, Docker-only. `unix`, `windows`, `webassembly` and
 `qemu` are exercised through `build-examples.yml`'s own small integration
@@ -1197,10 +1295,17 @@ scheduled `test-all-platforms.yml` run since.
   <td><code>embedded_base</code> (Docker) -- Pico SDK + every <code>lib/</code> it needs are vendored by the MicroPython release tarball itself[^rp2ci]</td>
   <td>✅</td>
 </tr>
+<tr>
+  <td><code>samd</code></td>
+  <td>
+    every board across <code>v1.20.0</code>-<code>v1.30.0-preview</code>
+  </td>
+  <td><code>embedded_base</code> (Docker) -- plain Make, no provisioning step, same shape as <code>rp2</code>[^samdci]</td>
+  <td>✅</td>
+</tr>
 <tr>
   <td>
     <code>mimxrt</code><br>
-    <code>samd</code><br>
     <code>stm32</code><br>
     <code>psoc-edge</code><br>
     <code>alif</code><br>
@@ -1251,6 +1356,8 @@ scheduled `test-all-platforms.yml` run since.
 [^nodriver]: `resources/build-platforms.toml` has real, independently-verified rows for each of these ports (walked against a real MicroPython checkout the same way every ✅ row above was); a config can name their identifiers today. What's missing is a `build_<port>()` driver (`platforms/usermod/build_<port>.py`) to actually run one — not a scope decision, just not built yet.
 [^rp2ci]: `build_rp2()` runs no provisioning step inside the container at all — the Pico SDK and everything it needs (`lib/pico-sdk`/`lib/tinyusb`/`lib/lwip`/`lib/btstack`/`lib/cyw43-driver`) are plain git submodules of the MicroPython checkout, already vendored as real files by the release tarball this project prefers. Running the port's own `make ... submodules` target was tried first and failed live against a real tarball checkout ("fatal: not a git repository", since a release tarball is not a git checkout at all); those submodules are threaded into `sources.fetch_micropython()` instead, reached only on its clone path (a preview tag with no tarball). Live-verified: a real `examples/template` build against `v1.29.0-rp2-RPI_PICO` producing a genuine 681984-byte `firmware.uf2` with the project's own C module linked in. Record 0060.
 
+[^samdci]: `build_samd()` ([0100]), the ninth of [0053]'s originally driverless usermod ports to get one and the first picked up after `rp2` — chosen over the other eight once `esp8266` was ruled out for tags too old to be worth it. No `SAMD_SUBMODULES`-style plumbing was needed: `orchestrate.build()` already threads `sources.fetch_micropython(tag, ports=group_ports)` generically enough to cover it. Live-verified against real identifiers spanning `v1.20.0` through the current tag, producing genuine linked firmware; a full sweep of every real `(tag, board)` row this project has verified facts for is how that was confirmed, not a spot check.
+
 [^esp32ci]: `build_esp32()` went Docker 2026-08-28 (`esp_idf_base`, [0058]), closing the venv conflict that made every real esp32 build fail on the bare host; `idf_version`/`idf_target` are threaded from each board's own real row rather than a fixed default, and `HOME` is exported explicitly for the same reason `esp32`'s own `ports/esp32` needs a real per-user cache dir that `dockerrun.run()`'s `--user <uid>:<gid>` doesn't otherwise give it (unmapped on GitHub's own runners specifically, live-caught on real CI). `test-all-platforms.yml`'s own broad sweep is what actually proves this across the whole board matrix, not a spot check — Xtensa and RISC-V both, both MicroPython tags this project currently tracks.
 
 [^windowsimg]: One combined `docker/windows.Dockerfile` image (`ghcr.io/ballistics-lab/windows`) for all three arches, not split per arch like `unix`'s own five images — there is no second Windows libc a binary could be built against, so the isolation argument that drives `unix`'s split doesn't apply here. `x64`/`x86` are plain apt-installed `gcc-mingw-w64-x86-64`/`gcc-mingw-w64-i686` inside the image; `arm64` is a pinned `llvm-mingw` tarball baked into the same image (no Debian/Ubuntu package targets `aarch64-w64-mingw32` at all). None of this runs on the CI runner itself any more — `apt install gcc-mingw-w64-*` on the bare host was removed as part of Record 0042's own container migration.