Commit b066b3b
feat(freestanding): a BSP supplies the runner, mcpp test runs on bare metal, and the artifact set is real (#457)
* feat(freestanding): a BSP supplies the runner, `mcpp test` runs on bare metal, and the artifact set is real
Three of the four gaps the phase-3 plan named. The consumer's manifest now has
no `[target.*]` section at all:
[dependencies]
board = { path = "../board" }
$ mcpp run --target riscv64-none-elf → boots in qemu
$ mcpp test --target riscv64-none-elf → ok_one ok, ok_two ok,
deliberate_fail FAIL (exit 1)
$ mcpp build --target riscv64-none-elf → firmware, .bin, .map
Size firmware text 8836 data 80 bss 5668 total 14584
R1 — THE RUNNER BELONGS TO THE BOARD-SUPPORT PACKAGE
`mcpp:runner=`, one argv token per line in emission order, with its own
`Slot::Runner` and its own `Scope::RunGlobal`. Both are new values and neither
is a detail: LdFlags would put an emulator's argv on the linker command line,
and reusing LinkGlobal would hand this the conflict rule for link flags — two
dependencies' link flags concatenate correctly, two runners cannot.
It has to come from `build.mcpp` rather than from a manifest key, and that is
measured, not stylistic: the emulator must be named by ABSOLUTE path (a bare
name resolves through PATH to a shim that dispatches against its owner home —
CI reported `xlings: 'qemu-system-riscv64' is not installed` from a job where
the same name had answered `--version` two steps earlier), the path carries a
home and a version, and only a build program can compute it.
Three sides verified: a BSP supplying it means the consumer needs no
`[target.*]`; two dependencies supplying it is a hard error naming BOTH; a
consumer writing its own wins and is told which dependency it overrode.
⚠️ R3 — TWO PLAN ASSUMPTIONS WERE WRONG, AND MEASURING THEM DELETED MOST OF IT
The plan called for a `batch` mode and a structured stdout protocol. Both
premises were false:
* "qemu cold start is ~0.4s, so 30 isolated cases cost 12s" — measured 12ms
per start (5 runs in 63ms). 30 cases cost 0.36s. The reason for batching
disappeared, and with it the "on timeout, re-run isolated to find the
culprit" machinery: isolated already names the culprit.
* "bare metal has no exit code, so results need their own channel" —
semihosting propagates the firmware's `main` return value to the emulator's
exit code (`return 7` → qemu exits 7, verified). "Exit code is the verdict"
holds here exactly as on the host.
So `mcpp test` needed one change: route the test binary through the SAME runner
`mcpp run` uses. Both callers now read `choose_runner()` — deriving it twice is
the shape this codebase has paid for repeatedly.
R4 — THE ARTIFACT SET
`.bin` via llvm-objcopy, `.map` via `-Wl,-Map=`, and a size summary, because
capacity is the constraint on a bare-metal target and mcpp already knows the
number. ⚠️ `.bin` is a SEPARATE ninja edge on the ELF, not a second output of
the link: folding it in would make the two share one up-to-date check, and an
incremental build would hand back a stale image. Pinned by content, not mtime.
Also fixes an inconsistency this work introduced: `mcpp run` took
`--target-triple` while every other subcommand took `--target`. `--target` now
works everywhere; `--target-triple` stays as `run`'s unambiguous alias, because
its POSITIONAL is also called target and means a binary name.
TESTS
91/91 unit (7 new on the runner directive and the artifact helpers) and three
e2e, all three run by the `baremetal` CI job which asserts each PASS line
appeared — every one of them can exit 0 without running.
* fix(cli): `mcpp run` cannot spell it `--target` — the positional already is
Adding `--target` to `mcpp run` for symmetry with every other subcommand broke
`mcpp run <binary>`:
$ mcpp run q
error: unknown target 'q'
The parser keys options and positionals by the same word, and this subcommand's
POSITIONAL is called target and means the binary NAME. `e2e/73` caught it
within the hour.
The positional's declaration already carried a comment saying so; I overrode it
reaching for consistency. `run` keeps `--target-triple`; `test` has no such
positional and keeps `--target`.
Consistency is one of the criteria, and it ranks below not breaking things.
* feat(build.mcpp): a missing `mcpp::` API now says the engine may be too old
A package that adopts a new typed directive cannot be used by an older mcpp,
and until now the only thing the reader saw was
error: 'runner' is not a member of 'mcpp'
which reads like the package author's typo rather than the reader's engine
being out of date. The wire protocol's own answer (protocol_error names
`mcpp self update`) never reaches this case: it needs the program to have
compiled first.
The package cannot solve it either. Measured:
if constexpr (requires { mcpp::runner("qemu"); }) // hard error
A requires-expression over a qualified name that does not exist is ill-formed,
not `false`, so there is no in-language feature probe.
So the compile failure carries the hint, matched across all three frontends'
spellings and anchored on our namespace so an ordinary error does not get it.
This covers every future typed-API addition, not just `runner`.
Also corrects docs/07 (both languages), which still claimed an unknown
directive "can only be a typo" within one protocol version — the engine's own
diagnostic was corrected away from that when link-script landed: the protocol
number is stamped by whichever mcpp compiled the program, so two matching
numbers say nothing about whether the key is from the future.
* fix(cli): rename `run`'s positional to `bin`, which frees `--target`
The collision was real — `mcpp run q` became `mcpp run --target=q` — but
retreating to `--target-triple` on this one subcommand paid for it with a
lasting inconsistency.
The actual cause is narrower than "one word, two axes": ParsedArgs::value()
falls back from an unset option to a positional OF THE SAME NAME, and that
positional was named `target`. cmd_run never reads the name (it takes
positional(0) by index) — it only labels the slot in --help, where `bin` is
the more accurate word.
So `--target` works on `run` like everywhere else, `--target-triple` stays as
an alias because it shipped in 2026.8.19.1, and e2e/130 now pins both
spellings while e2e/73 pins the positional.
* docs(plan): record R2/R5 implementation findings
R5's builtin template was the wrong shape — mcpp's builtin registry is frozen
at `bin` by design and templates ship with the package that provides them, so
the template lives in riscv-virt-rt and mcpp needs no change at all.
R2 hit a real gap: a dependency's `[xlings] deps` is materialized for the ROOT
project only, so a consumer of the board package would get neither libc nor
emulator. The fix is xim's own install-time dependency edge in the descriptor,
verified by removing picolibc from the store and watching `mcpp add` put it
back — not by observing an already-provisioned machine.
* chore(release): 2026.8.19.2 — the runner travels with the board
`mcpp run` and `mcpp test` on a bare-metal target now take their runner from
an ordinary dependency, so a firmware project's manifest names no emulator, no
linker script, no libc and no load address — it has no [target.*] section at
all. Builds emit .bin and .map beside the ELF and print a text/data/bss
summary, because capacity is the constraint that decides whether an image ships.
New surface:
* `mcpp:runner=` / `mcpp::runner(token)` — a package says how to execute
* `mcpp run --target` — the spelling every other subcommand uses
* a missing `mcpp::` API in build.mcpp now says the engine may be too old
The ecosystem half ships alongside: mcpplibs/riscv-virt-rt supplies the board
(and, from 0.2.0, `mcpp new <name> --template riscv-virt-rt`).
* docs: a freestanding target does have `main` when a board package supplies crt0
docs/05 §2.7.2 told the reader there is no `main` on a bare-metal target and
to point the target at a file carrying `_start`. That is only true for a board
with no C library at all — with picolibc's semihosting crt0, which is what a
board-support package ships, the entry point is an ordinary `int main()` whose
return value reaches the host.
Also leads the section with the short path (`mcpp new blinky --template
riscv-virt-rt`), since the hand-written form below it is what to reach for when
writing a package for a board that has none — not what to start with.
* fix(diag): the freestanding `import std` message pointed at a package that does not exist
It ended with a copy-pasteable
[dependencies]
mcpplibs.std.freestanding = "0.1"
and no such package is published. Following the advice fails at the very next
command with "package not found", which sends the reader off to debug their
index instead of their code.
Now it points at what a bare-metal project actually has — the module its board
package exports, named concretely — and describes a freestanding subset package
as a shape rather than a line to paste, saying plainly that none is published
yet. The concrete line comes back when one ships.
Every suggestion in a diagnostic is a promise; this one had not been checked
against reality before being written.
* fix(ninja): declare the link map as an implicit output, not a side effect
`-Wl,-Map=` is a flag on the link command, so the map cannot be its own edge
— a second edge claiming to produce it would run the link twice. It was
therefore written but never declared, which means nothing tracked it: delete
`firmware.map` and ninja considers the ELF up to date and puts nothing back.
Declaring it as an implicit output of the link edge fixes that and makes
`ninja -t clean` remove it with everything else. e2e/132 now deletes the map
and asserts it returns, which is the only form of this test that can fail
before the fix.
---------
Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>1 parent ec9c9e3 commit b066b3b
24 files changed
Lines changed: 1388 additions & 49 deletions
File tree
- .agents/docs
- .github/workflows
- docs
- zh
- src
- build
- cli
- freestanding
- manifest
- tests
- e2e
- unit
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -173,7 +173,8 @@ jobs: | |||
| 173 | 173 | # Invoked directly, a skip is visible: the script either prints its | |
| 174 | 174 | # PASS line or it does not. | |
| 175 | 175 | for t in tests/e2e/130_freestanding_riscv_build_and_run.sh \ | |
| 176 | - tests/e2e/131_freestanding_bsp_supplies_everything.sh; do | ||
| 176 | + tests/e2e/131_freestanding_bsp_supplies_everything.sh \ | ||
| 177 | + tests/e2e/132_freestanding_test_and_artifacts.sh; do | ||
| 177 | 178 | echo "=== $t ===" | |
| 178 | 179 | bash "$t" 2>&1 | tee "$(basename "$t").log" | |
| 179 | 180 | rc=${PIPESTATUS[0]} | |
@@ -188,6 +189,9 @@ jobs: | |||
| 188 | 189 | grep -q 'PASS: BSP supplies the sysroot' \ | |
| 189 | 190 | 131_freestanding_bsp_supplies_everything.sh.log || { | |
| 190 | 191 | echo "131 (ecosystem chain) skipped on the runner that must run it"; exit 1; } | |
| 192 | + grep -q 'PASS: bare-metal mcpp test names its failure' \ | ||
| 193 | + 132_freestanding_test_and_artifacts.sh.log || { | ||
| 194 | + echo "132 (test + artifacts) skipped on the runner that must run it"; exit 1; } | ||
| 191 | 195 | ||
| 192 | 196 | # ────────────────────────────────────────────────────────────────── | |
| 193 | 197 | # Hermetic (no host toolchain): the ONLY environment class that | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -906,17 +906,33 @@ can produce them. | |||
| 906 | 906 | ||
| 907 | 907 | ```bash | |
| 908 | 908 | mcpp build --target riscv64-none-elf | |
| 909 | - mcpp run --target-triple riscv64-none-elf # via [target.<triple>].runner | ||
| 909 | + mcpp run --target riscv64-none-elf # via [target.<triple>].runner | ||
| 910 | 910 | ``` | |
| 911 | 911 | ||
| 912 | + **Starting from a board package** | ||
| 913 | + | ||
| 914 | + Almost nothing below has to be written by hand. A board-support package carries | ||
| 915 | + the C library, the startup code, the memory layout and the emulator, so the | ||
| 916 | + shortest path to a booting image is: | ||
| 917 | + | ||
| 918 | + ```bash | ||
| 919 | + mcpp new blinky --template riscv-virt-rt | ||
| 920 | + cd blinky && mcpp run | ||
| 921 | + ``` | ||
| 922 | + | ||
| 923 | + The generated manifest names no linker script, load address, libc or emulator — | ||
| 924 | + it has no `[target.*]` section at all. The rest of this section describes what | ||
| 925 | + such a package supplies, which is what to reach for when writing one for a board | ||
| 926 | + that has none. | ||
| 927 | + | ||
| 912 | 928 | **What changes on a freestanding target** | |
| 913 | 929 | ||
| 914 | 930 | | | | | |
| 915 | 931 | |---|---| | |
| 916 | 932 | | Link line | `-nostdlib -nostartfiles -static`, and nothing hosted — no crt files, no dynamic linker, no C++ runtime. The linker is addressed by **absolute path** (`-fuse-ld=<payload>/bin/ld.lld`), because `-fuse-ld=lld` resolves through `PATH` and finds GNU ld on any machine with binutils earlier on it. | | |
| 917 | 933 | | ISA flags | `-march` / `-mabi` / `-mcmodel` come from the target table, so `--target <triple>` alone is enough to produce a correct object file. | | |
| 918 | - | `import std` | **Unavailable.** `std` is one module over the entire library — threads, filesystem and iostreams included — so there is no subset of it to build without an OS. The freestanding subset package replaces it, and mcpp's diagnostic names it. | | ||
| 919 | - | Entry point | There is no `main`. Declare the target explicitly and point `main` at the file carrying `_start`. | | ||
| 934 | + | `import std` | **Unavailable.** `std` is one module over the entire library — threads, filesystem and iostreams included — so there is no subset of it to build without an OS. What a firmware imports instead is the module its **board package** exports, which is where the target's C library is already wrapped. | | ||
| 935 | + | Entry point | `int main()` works **as long as something supplies a `crt0`** — a board package normally does, and then a firmware's entry point is an ordinary `main` whose return value reaches the host through semihosting. Only a zero-libc board needs an explicit target whose `main` points at the file carrying `_start`. | | ||
| 920 | 936 | ||
| 921 | 937 | **A minimal firmware** | |
| 922 | 938 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -52,6 +52,7 @@ is ignored, so diagnostics may be logged freely. | |||
| 52 | 52 | | `mcpp:source=<path>` *(0.0.100+)* | select a **pre-existing** source file into the build (absolute, or relative to the package root). Same downstream effect as `generated=`; use it for files the program *chose* (payload/vendored tree) rather than wrote — e.g. a per-target source selection over a large tarball | | |
| 53 | 53 | | `mcpp:include-dir=<dir>` *(0.0.100+)* | add a **private** include directory (`-I`) for this package's own TUs (absolute, or relative to the package root; normalized). Replaces the `cxxflag=-I` + `cflag=-I` double emission | | |
| 54 | 54 | | `mcpp:include-dir-after=<dir>` *(0.0.100+)* | like `include-dir`, but searched **after** the system directories (`-idirafter`) — for payload trees that shadow system headers | | |
| 55 | + | `mcpp:runner=<token>` *(2026.8.19.2+)* | one argv token of the command that EXECUTES this build's artifact, when the host cannot. Emitted once per token, in order; the artifact path is appended (or substituted for `{}`). Reaches the **consumer**. ⚠️ Emit the executable as an ABSOLUTE path, and only **one** dependency may supply it | | ||
| 55 | 56 | | `mcpp:link-script=<path>` *(2026.8.19+)* | link with this **linker script** (`-T`; relative resolves against the package root, and the emitted path is absolute because the link runs in the build directory). Reaches the **consumer**, unlike `include-dir` — a board's memory layout is the one thing a consumer cannot write for itself | | |
| 56 | 57 | | `mcpp:rerun-if-changed=<path>` | re-run `build.mcpp` when this file changes | | |
| 57 | 58 | | `mcpp:rerun-if-env-changed=<VAR>` | re-run `build.mcpp` when this env var changes | | |
@@ -101,9 +102,37 @@ int main() { | |||
| 101 | 102 | | `mcpp::rerun_if_changed_glob(pat)` *(2026.8.6.2+)* | `mcpp:rerun-if-changed-glob=` — re-run when the **set** of files matching `pat` changes (see below) | | |
| 102 | 103 | | `mcpp::dep_bin(pkg, tool)` *(2026.8.5.1+)* | reads `MCPP_DEP_<PKG>_BIN_<TOOL>` — the absolute path of a **host tool** built by a dependency (see below) | | |
| 103 | 104 | | `mcpp::link_script(p)` *(2026.8.19+)* | `mcpp:link-script=` | | |
| 105 | + | `mcpp::runner(tok)` *(2026.8.19.2+)* | `mcpp:runner=` — see below | | ||
| 104 | 106 | | `mcpp::xpkg_dir(ns, name)` / `mcpp::xpkg_dir(name)` *(2026.8.19+)* | the payload directory of a package this manifest declared in `[xlings] deps`; `""` when it was not declared or is not installed (see below) | | |
| 105 | 107 | | `mcpp::action{…}.submit()` *(2026.8.5.1+)* | `mcpp:action=` — declares a **build-graph node** instead of doing the work here (see below) | | |
| 106 | 108 | ||
| 109 | + ### `runner` — how the artifact is executed (2026.8.19.2+) | ||
| 110 | + | ||
| 111 | + A board-support package knows the emulator, its machine model and its firmware | ||
| 112 | + mode. It also knows where the emulator IS, which a static manifest cannot: the | ||
| 113 | + payload path carries a home and a version. | ||
| 114 | + | ||
| 115 | + ```cpp | ||
| 116 | + const char* qemu = mcpp::xpkg_dir("xim", "qemu-riscv"); | ||
| 117 | + mcpp::runner(std::format("{}/bin/qemu-system-riscv64", qemu).c_str()); | ||
| 118 | + for (auto a : {"-machine","virt","-nographic","-no-reboot","-kernel"}) | ||
| 119 | + mcpp::runner(a); | ||
| 120 | + ``` | ||
| 121 | + | ||
| 122 | + The consumer then needs no `[target.<triple>]` section at all. If it writes one | ||
| 123 | + anyway, **it wins** — swapping `-bios default` for `-bios none -semihosting` | ||
| 124 | + while debugging is a legitimate thing to want — and mcpp says which dependency | ||
| 125 | + it overrode. | ||
| 126 | + | ||
| 127 | + ⚠️ **Emit the executable as an absolute path.** A bare name resolves through | ||
| 128 | + `PATH` to a shim that dispatches against its own owner home, which is not | ||
| 129 | + necessarily the home this build uses. | ||
| 130 | + | ||
| 131 | + ⚠️ **Exactly one dependency may supply a runner.** Two board-support packages | ||
| 132 | + both claiming to know how to run the artifact is a configuration error, and | ||
| 133 | + mcpp reports it naming both rather than merging them into an argv that is | ||
| 134 | + neither one's. | ||
| 135 | + | ||
| 107 | 136 | ### Finding an `[xlings] deps` payload: `xpkg_dir` (2026.8.19+) | |
| 108 | 137 | ||
| 109 | 138 | `dep_dir` answers for **mcpp** dependencies. An xlings package is a different | |
@@ -297,16 +326,44 @@ write it yourself). mcpp uses that two ways: | |||
| 297 | 326 | with an upgrade hint. Continuing would silently drop directives the build | |
| 298 | 327 | depends on — and "the build succeeded but the flag never arrived" is the | |
| 299 | 328 | worst class of build bug. | |
| 300 | - - Because the two sides then provably agree, an **unrecognized directive is an | ||
| 301 | - error** rather than a warning: within one protocol version it can only be a | ||
| 302 | - typo. | ||
| 329 | + - An **unrecognized directive is an error** rather than a warning, and the error | ||
| 330 | + names *both* possible causes. It cannot name one: the protocol number is | ||
| 331 | + stamped by whichever mcpp **compiled** the program, not carried by the | ||
| 332 | + package, so a package written for a newer mcpp arrives at an older one | ||
| 333 | + wearing the older engine's number. Two matching numbers therefore say nothing | ||
| 334 | + about whether the key came from the future. | ||
| 303 | 335 | ||
| 304 | 336 | A `printf`-style program announces nothing, so it keeps the historical | |
| 305 | 337 | warn-and-ignore behaviour. That surface is **frozen at the eleven directives in | |
| 306 | 338 | the table above** — it still works and will keep working, but new capabilities | |
| 307 | 339 | land only in the typed API. Prefer `import mcpp;` for anything intended to | |
| 308 | 340 | maintain. | |
| 309 | 341 | ||
| 342 | + #### A package that needs a newer mcpp | ||
| 343 | + | ||
| 344 | + When a published package calls a typed function this mcpp does not have, the | ||
| 345 | + compile error naming it is followed by: | ||
| 346 | + | ||
| 347 | + ``` | ||
| 348 | + The `mcpp` build module this engine bundles does not have that name. | ||
| 349 | + Either the package was written for a newer mcpp (try `mcpp self update`; | ||
| 350 | + this is mcpp 2026.8.19.2), or the name is misspelled … | ||
| 351 | + ``` | ||
| 352 | + | ||
| 353 | + The package cannot handle this itself, and it is worth knowing why — the | ||
| 354 | + obvious guard does not compile: | ||
| 355 | + | ||
| 356 | + ```cpp | ||
| 357 | + if constexpr (requires { mcpp::runner("qemu"); }) // ✗ hard error when absent | ||
| 358 | + mcpp::runner("qemu"); | ||
| 359 | + ``` | ||
| 360 | + | ||
| 361 | + A `requires`-expression over a **qualified name that does not exist** is | ||
| 362 | + ill-formed, not `false`. So there is no in-language feature probe, and a | ||
| 363 | + package that adopts a new directive states its floor in prose (its README) and | ||
| 364 | + relies on the diagnostic above. Such a package should name the mcpp version it | ||
| 365 | + requires. | ||
| 366 | + | ||
| 310 | 367 | ### `import std;` (mcpp 2026.8.2.1+) | |
| 311 | 368 | ||
| 312 | 369 | A `build.mcpp` may `import std;` (and `import std.compat;`), alone or together | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -804,17 +804,31 @@ cxxflags = ["-march=x86-64-v2"] | |||
| 804 | 804 | ||
| 805 | 805 | ```bash | |
| 806 | 806 | mcpp build --target riscv64-none-elf | |
| 807 | - mcpp run --target-triple riscv64-none-elf # 经 [target.<triple>].runner | ||
| 807 | + mcpp run --target riscv64-none-elf # 经 [target.<triple>].runner | ||
| 808 | 808 | ``` | |
| 809 | 809 | ||
| 810 | + **从板级支持包起步** | ||
| 811 | + | ||
| 812 | + 下面这些几乎都不需要手写。板级支持包(BSP)自带 C 库、启动代码、内存布局和模拟器, | ||
| 813 | + 所以跑起一个镜像的最短路径是: | ||
| 814 | + | ||
| 815 | + ```bash | ||
| 816 | + mcpp new blinky --template riscv-virt-rt | ||
| 817 | + cd blinky && mcpp run | ||
| 818 | + ``` | ||
| 819 | + | ||
| 820 | + 生成的 manifest 里没有链接脚本、没有加载地址、没有 libc、没有模拟器 —— 连 | ||
| 821 | + `[target.*]` 段都没有。本节余下的内容讲的是**这样一个包提供了什么**,也就是要给 | ||
| 822 | + 一块还没有 BSP 的板子写一个时该照着做什么。 | ||
| 823 | + | ||
| 810 | 824 | **freestanding target 上有什么不同** | |
| 811 | 825 | ||
| 812 | 826 | | | | | |
| 813 | 827 | |---|---| | |
| 814 | 828 | | 链接线 | `-nostdlib -nostartfiles -static`,且不带任何 hosted 的东西 —— 没有 crt 文件、没有动态链接器、没有 C++ 运行时。链接器用**绝对路径**寻址(`-fuse-ld=<载荷>/bin/ld.lld`),因为 `-fuse-ld=lld` 走 `PATH` 解析,在任何 binutils 排前面的机器上都会找到 GNU ld。 | | |
| 815 | 829 | | ISA flag | `-march` / `-mabi` / `-mcmodel` 来自 target 表,所以只写 `--target <triple>` 就足以产出正确的目标文件。 | | |
| 816 | - | `import std` | **不可用。** `std` 是覆盖整个库的一个模块 —— 线程、文件系统、iostreams 全在内 —— 没有 OS 就没有它的子集可编。freestanding 子集包取代它,mcpp 的诊断会点名。 | | ||
| 817 | - | 入口点 | 没有 `main`。显式声明 target,并把 `main` 指向携带 `_start` 的那个文件。 | | ||
| 830 | + | `import std` | **不可用。** `std` 是覆盖整个库的一个模块 —— 线程、文件系统、iostreams 全在内 —— 没有 OS 就没有它的子集可编。固件真正 import 的是**板级包导出的模块**,目标的 C 库已经在那里包好了。 | | ||
| 831 | + | 入口点 | **只要有人提供 `crt0`,`int main()` 就能用** —— 板级支持包通常就提供它,于是固件的入口就是普通的 `main`,它的返回值经 semihosting 传回宿主。**只有零 libc 的板子**才需要显式声明 target 并把 `main` 指向携带 `_start` 的那个文件。 | | ||
| 818 | 832 | ||
| 819 | 833 | **一个最小固件** | |
| 820 | 834 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -49,6 +49,7 @@ mcpp build # 编译 + 运行 build.mcpp,然后构建工程 | |||
| 49 | 49 | | `mcpp:source=<path>` *(0.0.100+)* | 把一份**既有**源文件选入构建(绝对路径,或相对包根)。下游效果与 `generated=` 相同;语义区别在于文件是程序*选中*的(tarball payload / vendored 源树)而非程序写出的——例如对大型源码包做 per-target 源选择 | | |
| 50 | 50 | | `mcpp:include-dir=<dir>` *(0.0.100+)* | 为本包自身 TU 增加一个**私有** include 目录(`-I`;绝对路径或相对包根,自动规范化)。取代过去 `cxxflag=-I` + `cflag=-I` 的双重裸发 | | |
| 51 | 51 | | `mcpp:include-dir-after=<dir>` *(0.0.100+)* | 同 `include-dir`,但排在系统目录**之后**搜索(`-idirafter`)——用于会遮蔽系统头的 payload 源树 | | |
| 52 | + | `mcpp:runner=<token>` *(2026.8.19.2+)* | 执行本次构建产物的命令的**一个 argv token**(宿主跑不了它时)。一个 token 一次调用、按顺序;产物路径会被追加(或替换 `{}`)。**到达消费者**。⚠️ 可执行文件要发**绝对路径**,且**只能有一个**依赖提供它 | | ||
| 52 | 53 | | `mcpp:link-script=<path>` *(2026.8.19+)* | 用这个**链接脚本**链接(`-T`;相对路径按包根解析,发出的是绝对路径,因为链接是在构建目录里跑的)。与 `include-dir` 不同,它**到达消费者** —— 板子的内存布局恰恰是消费者写不出来的那一项 | | |
| 53 | 54 | | `mcpp:rerun-if-changed=<path>` | 该文件变化时重跑 `build.mcpp` | | |
| 54 | 55 | | `mcpp:rerun-if-env-changed=<VAR>` | 该环境变量变化时重跑 `build.mcpp` | | |
@@ -94,9 +95,32 @@ int main() { | |||
| 94 | 95 | | `mcpp::rerun_if_changed_glob(pat)` *(2026.8.6.2+)* | `mcpp:rerun-if-changed-glob=` —— 匹配 `pat` 的文件**集合**发生变化时重跑(见下) | | |
| 95 | 96 | | `mcpp::dep_bin(pkg, tool)` *(2026.8.5.1+)* | 读 `MCPP_DEP_<PKG>_BIN_<TOOL>` —— 依赖构建出的 **host 工具**的绝对路径(见下) | | |
| 96 | 97 | | `mcpp::link_script(p)` *(2026.8.19+)* | `mcpp:link-script=` | | |
| 98 | + | `mcpp::runner(tok)` *(2026.8.19.2+)* | `mcpp:runner=` —— 见下 | | ||
| 97 | 99 | | `mcpp::xpkg_dir(ns, name)` / `mcpp::xpkg_dir(name)` *(2026.8.19+)* | 本 manifest 在 `[xlings] deps` 里声明的包的载荷目录;没声明或没安装时返回 `""`(见下) | | |
| 98 | 100 | | `mcpp::action{…}.submit()` *(2026.8.5.1+)* | `mcpp:action=` —— **声明一个构建图节点**,而不是在这里把活干了(见下) | | |
| 99 | 101 | ||
| 102 | + ### `runner` —— 产物的执行方式(2026.8.19.2+) | ||
| 103 | + | ||
| 104 | + 板级支持包知道模拟器、机器型号和固件模式,也知道模拟器**在哪** —— 而静态 manifest | ||
| 105 | + 写不出来:载荷路径里带着 home 和版本号。 | ||
| 106 | + | ||
| 107 | + ```cpp | ||
| 108 | + const char* qemu = mcpp::xpkg_dir("xim", "qemu-riscv"); | ||
| 109 | + mcpp::runner(std::format("{}/bin/qemu-system-riscv64", qemu).c_str()); | ||
| 110 | + for (auto a : {"-machine","virt","-nographic","-no-reboot","-kernel"}) | ||
| 111 | + mcpp::runner(a); | ||
| 112 | + ``` | ||
| 113 | + | ||
| 114 | + 这样消费者**完全不需要 `[target.<triple>]` 段**。它若还是写了,**以它为准** —— | ||
| 115 | + 调试时把 `-bios default` 换成 `-bios none -semihosting` 是正当需求 —— 且 mcpp 会说明 | ||
| 116 | + 它覆盖了哪个依赖。 | ||
| 117 | + | ||
| 118 | + ⚠️ **可执行文件要发绝对路径。** 裸名会经 `PATH` 解析到一个 shim,而 shim 按**拥有它 | ||
| 119 | + 的 home** 派发,那未必是本次构建用的 home。 | ||
| 120 | + | ||
| 121 | + ⚠️ **只能有一个依赖提供 runner。** 两个板级支持包都声称知道怎么跑这个产物是配置 | ||
| 122 | + 错误;mcpp 会**同时点名两个**并报错,而不是把它们并成一个谁也不是的 argv。 | ||
| 123 | + | ||
| 100 | 124 | ### 找到 `[xlings] deps` 的载荷:`xpkg_dir`(2026.8.19+) | |
| 101 | 125 | ||
| 102 | 126 | `dep_dir` 回答的是 **mcpp** 依赖。xlings 包是另一个命名空间、另一套 store 布局, | |
@@ -266,13 +290,36 @@ mcpp 会播下一个带着该声明的占位文件,使 prepare 期的扫描与 | |||
| 266 | 290 | ||
| 267 | 291 | - 程序声明的协议**高于** mcpp 所理解的 → **拒绝执行**,并给出升级提示。继续跑会 | |
| 268 | 292 | 静默丢掉构建依赖的指令,而「构建成功了但那个 flag 根本没到」是最难查的一类问题。 | |
| 269 | - - 既然双方已被证明一致,**未知指令就是错误**而不是警告:在同一个协议版本内, | ||
| 270 | - 它只可能是拼写错误。 | ||
| 293 | + - **未知指令是错误**而不是警告,而且这条错误会把**两种可能的原因都说出来**。 | ||
| 294 | + 它没法只说一种:协议号是由**编译**该程序的那个 mcpp 现场打上的,并不由包本身携带 | ||
| 295 | + —— 于是一个写给新 mcpp 的包到了老 mcpp 手里,身上戴的是老引擎的号。 | ||
| 296 | + **两个号一致因此完全不能说明这个键是不是来自未来。** | ||
| 271 | 297 | ||
| 272 | 298 | `printf` 风格的程序什么都不声明,因此保留历史上的「警告并忽略」行为。这一面 | |
| 273 | 299 | **冻结在上表的 11 条指令**上——它仍然能用、也会继续能用,但新能力只在类型化 API 里 | |
| 274 | 300 | 落地。**要长期维护的程序请用 `import mcpp;`。** | |
| 275 | 301 | ||
| 302 | + #### 一个需要更新 mcpp 的包 | ||
| 303 | + | ||
| 304 | + 当已发布的包调用了当前 mcpp 没有的类型化函数时,点名的编译错误之后会跟着: | ||
| 305 | + | ||
| 306 | + ``` | ||
| 307 | + The `mcpp` build module this engine bundles does not have that name. | ||
| 308 | + Either the package was written for a newer mcpp (try `mcpp self update`; | ||
| 309 | + this is mcpp 2026.8.19.2), or the name is misspelled … | ||
| 310 | + ``` | ||
| 311 | + | ||
| 312 | + **包自己处理不了这件事**,而原因值得知道 —— 最直觉的那道防护编译不过: | ||
| 313 | + | ||
| 314 | + ```cpp | ||
| 315 | + if constexpr (requires { mcpp::runner("qemu"); }) // ✗ 名字不存在时是硬错误 | ||
| 316 | + mcpp::runner("qemu"); | ||
| 317 | + ``` | ||
| 318 | + | ||
| 319 | + `requires` 表达式作用在一个**不存在的限定名**上时是 ill-formed,而**不是求值为 | ||
| 320 | + `false`**。所以语言内没有特性探测这条路:采用了新指令的包只能在自己的 README 里 | ||
| 321 | + 用文字写明版本下限,并依赖上面那条诊断。**这类包应当写清楚它需要哪个版本的 mcpp。** | ||
| 322 | + | ||
| 276 | 323 | ### `import std;`(mcpp 2026.8.2.1+) | |
| 277 | 324 | ||
| 278 | 325 | `build.mcpp` 可以 `import std;`(以及 `import std.compat;`),单用或与 | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1,6 +1,6 @@ | |||
| 1 | 1 | [package] | |
| 2 | 2 | name = "mcpp" | |
| 3 | - version = "2026.8.19.1" | ||
| 3 | + version = "2026.8.19.2" | ||
| 4 | 4 | description = "Modern C++ build & package management tool" | |
| 5 | 5 | license = "Apache-2.0" | |
| 6 | 6 | authors = ["mcpp-community"] | |
0 commit comments