feat(freestanding): 目标 C 库可覆盖、零 libc 档、分配器分层,以及七个生态包 - #466
Merged
Conversation
Bare-metal support landed across #455-#459 but had no user-facing page. What existed was docs/05 §2.7.2 — the manifest reference for `[target.*]` — and an outlook section in docs/08 written before the work. Adds docs/13 (en + zh): the two commands that produce a booting image, what a freestanding target changes, the engine/target/board layering, worked examples (ISA width, the freestanding std subset, `mcpp test` on the target, the flashing artifact set, runner override), the two diagnostics, and how to write a board support package. ## The measurements are re-taken, not copied Every transcript was measured on 2026-08-20 with mcpp 2026.8.20.1 built from this tree, on x86_64-linux-gnu. That mattered: the recorded scenario notes say `text 8844` and this build measures `text 8572`, so a copied number would have been wrong on arrival. The chapter says so, and gives its component versions. Two claims that could have been repeated on trust were checked instead: * 103 of 110 headers — counted in both trees (`103` distinct `.inc` in the package, `110` `std/*.inc` in the llvm 22.1.8 payload); * five host targets for `xim:qemu-riscv` — read out of the descriptor (linux x64/arm64, darwin x64/arm64, win32 x64), which also carries the comment explaining why win32-arm64 is absent. The one claim not verified here is labelled as such: the 7 omitted headers are reported by the package to fail on a hosted x86_64 too. ## The defect writing it exposed The freestanding `import std` diagnostic ends in a copy-pasteable dependency line, and prepare.cppm carries a comment saying that line is a PROMISE which has to resolve today — because it once named a package that did not exist. It was broken again, in a second form. The line said `"0.1.0"` after `0.2.0` superseded it in the index, and 0.1.0 is not published: E_NOT_FOUND: package 'compat.std-freestanding@0.1.0' not found in the synced index So the version is part of the promise, not decoration. Fixed to `"0.2.0"` and verified end to end: trigger the diagnostic, paste its line, `mcpp run` prints `value 42`. The comment now records this recurrence, since the first note was not enough to prevent it. ## Adjacent documents * README target table gained `riscv64-none-elf` / `riscv32-none-elf` — both tier `verified` in triple.cppm, both executed under qemu by the `baremetal` CI job, and neither was listed. * docs/08 §7.3 stops being an outlook. Three of its predictions held; one was wrong in the way that matters — the C library is NOT inside the toolchain payload, it is a separate payload named by the target's own row, and that is what keeps a bare-metal package from having to name a libc. * docs/05 §2.7.2 stays as the manifest reference and now points at docs/13. `bash .github/tools/check_docs_style.sh` passes; the bilingual heading structure is identical by construction. `mcpp build` succeeds with the prepare.cppm change.
Sunrisepeak
force-pushed
the
docs/baremetal-chapter
branch
from
August 20, 2026 03:18
72cc0f1 to
968377c
Compare
上一轮 review 提了七个问题,其中两个更正了我的判断:freestanding 应当是包属性
(对),以及 mcpp 已有 openkal(已实现)与 openhal(已设计)——我此前把
「没有 embedded-hal 那套词汇」写成最大缺口,那是错的,真实状态是已设计未实现。
本文给出五项决策的形状与判据:
* A freestanding 成为包能力,复用既有 `provides`,但**由构建证据推导而非作者
声称** —— 判据近乎免费:包能为 riscv64-none-elf 编过就是 by construction,
因为引擎已把那四个 flag 强制到全图。这与 openkal 设计 §5 删掉能力位机制是
同一条纪律。
* B 目标表三步可扩展:先工程内定义、再随包走、最后索引化;⚠️ 单一读取点不可破。
* C std-freestanding 与 openkal 互补而非替代 —— openkal 解决 OS 服务可移植,
**解决不了目标版 libc++.a**,docs/13 的边界不因它而改变。
* D 零 libc 档:最小示例不是一个内核,是一个零 libc 的启动工程,它同时是该档
的唯一判据。
* E 下一个案例:Cortex-M + QEMU 先行,ESP32 分型号。
四条本机实测,其中两条改变了结论:
* `clang -print-targets` 未注册 `xtensa` ⇒ ESP32/S2/S3 在钉住的载荷上不成立;
已注册 `arm`/`thumb`/`riscv32`/`riscv64`。
* ⚠️ xim 索引里裸机 C 库只有 `picolibc-riscv` 一个,qemu 只有 `qemu-riscv` 一个
⇒ Cortex-M **不是「加一行」**,而是两个新载荷 + 一行 + 一个包。写进文档前
我差点把它写成「只缺一行目标表」。
* `cfg(os = "none")` 与 `cfg(arch = ...)` 实测可匹配 ⇒ 今天的兜底存在,但索引
检索不到,不能替代决策 A。
* 零依赖 freestanding 工程可构建(text 12)⇒ 仅凭 ISA 表行足以产出正确目标文件。
⚠️ 全文最弱的一环写在 §8.5 与 §11 第一行:这套分层只在 QEMU virt 一台几乎没有
外设的虚拟机上验证过。
五项决策全部不要求引擎认识 KAL/HAL/ARCH,也全部不新增引擎轴。
## openarch 实现方案(新)
它是三层里唯一实现者集合**有界**的一层(x86_64/aarch64/riscv64,基本只有自己),
因此仓库形态、里程碑顺序、判据都应与 openkal/openhal 相反:
* 单仓库 —— 因为**接口与实现必须共同演化**:D3 的门是「加第二个 arch 时抽象
不碎」,而只有加第二个 arch 才知道接口错在哪,拆仓会拖慢决定这一层生死的循环。
* ⭐ **先做最硬的两条**(上下文切换、页表项),与常规的先易后难相反 —— 容易的
部分(percpu/barrier)全部做完也不能证明这一层成立,而最硬的一碎,前面全是
沉没成本。方案 §7.1 的原话是「碎在这里,后面全是幻觉」。
* ⚠️ `context_switch` 必须是纯汇编符号,换栈后跑的 prologue 访问的是错误的栈
⇒ 它的「零成本」不来自 inline,而来自「它本来就是一次 call」。照搬方案
§16.2 的「显式 inline 优先」会得到一个崩溃的设计。
* 内存属性是 A 类裂缝的教科书例子:x86 走 PAT 索引、aarch64 走 MAIR 索引、
riscv 是 PTE 位直给 ⇒ 判据设计成能证伪的,碎了就把 addrspace 缩到「结构而非属性」。
* x86_64 是**第二道门**而不是「再加一个 arch」:rv64 与 aarch64 可能偶然相似,
x86_64 是最不像的那个,它检验接口有没有被前两个过拟合。
⚠️ 全文零实测 —— openarch 还没有一行代码,第一条实测只能由 A0 探针产生。这一点
写在 §7 第一行。
## 四条实测折回定位文档
1. ⭐ **推翻了我自己写的一句话。** 原文说 std-freestanding 需要堆、「没有办法说
不要堆」。实测三态:tier-0 完全不碰堆;`std::vector` 编得过链不上(缺
`operator new`);补齐 12 个重载后跑通(text 13492)。它是**分配中立**的。
2. ⭐ tier-0 程序的全部未定义符号是 `memmove` + `strlen` 两个纯计算函数
⇒ 「std-freestanding 应基于 openkal」的猜想被拆成两半:**头文件结构性绕不过,
而运行期面几乎已经绕过了**。接触面只有 tier-1 的分配器一处。
3. ⚠️ openkal 设计 §6.3 的选择键是 ISA 级 cfg,而 UART 基址是板级事实
⇒ 换板后**类型正确、能编能链、写到不存在的地址、静默无输出**。更正为
「后端由板级包提供,选择键是那条板级依赖」。
4. ⭐ `[target.X].sysroot` 从一条普通边界升格为**三条线的共同瓶颈**(零 libc 档 /
换 libc 实现 / 让 std-freestanding 坐到 openkal 的 C 库头上),实施顺序因此提前。
另新增:std-freestanding-alloc(约 30 行,默认转 kal_alloc)—— 按头文件拆
`freestanding.core` 会把一份**生成的**清单改回**手工策展的**清单,正好撤销包自己
写明的纪律;该拆的是「程序必须提供什么」。以及 UEFI 作为 bootloader 方向的好位置
(接口与 UEFI 服务几乎一一对应),而 legacy BIOS 不在射程内(16 位实模式)。
## 最终形状(方案文档 §6.6.1)
照搬 docs/05 §2.8.2 已文档化的 backend-openblas:一个 feature 同时拉 provider
并打开消费者开关。
[features]
alloc = { requires = ["freestanding-allocator"] }
alloc-kal = { implies = ["alloc"] }
[feature-deps.alloc-kal]
std-freestanding-alloc-kal = "0.1.x"
⇒ 实现分离(本体零依赖)· 默认一键可得(不必知道 provider 包名)· 可换 ·
并集风险被转化成解析期报错。
## 两条实测把三个备选形态判死了
1. ⭐ **依赖以裸 `.o` 参与链接,整份 build.ninja 零个 `.a`**(StaticLibrary 只在根
清单 kind="lib" 时产生,plan.cppm:1637)⇒ libc++ 那套「库常驻默认、程序顶掉」
靠的是归档语义,对包依赖不适用。这正是要用「开关控制是否存在」而不是「默认存在
可覆盖」的原因 —— 两份定义从不共存。
2. ⭐ **capability 消歧不裁剪链接行。** 两个包都 provides 同一能力且都定义同名符号:
未 pin 时解析期报错并点名两者;按提示 pin 一个之后,构建走到链接器才死于
`multiple definition`,两份 .o 都在链接边上。
⇒ 绑定的是「谁满足要求」,不是「哪些目标文件参与链接」。对单例符号类 provider,
pin 会把好错误换成坏错误 ⇒ 两个 provider 同时在图里是**待修的缺陷**而非可 pin
的歧义。这条已补进 docs/05 §2.8.1(中英)。
被否决的三个形态及理由也记了:按头文件拆 core/其它(把生成的清单改回手工策展)、
nolibc 做成 feature(非加性,且它是目标的属性)、弱符号默认(两份实现同时在图里
不报错,按链接顺序静默选)。
## 零 libc 的两条(§7.1)
* ⭐ 零 libc 链接已成立:只依赖 std-freestanding、无板级包、无 -lc、无 crt0,
自带 memmove+strlen+_start 后链接通过(text 15866)。
* ⚠️ 但**未验证能否启动,且已知不能**:加载地址 0x10000,qemu virt 要 0x80000000。
⇒ 零 libc 档缺的不是 libc,是**链接脚本** —— 而那是板级事实,恰好落在分层里
已有归属的那一格。
## mcpp 用户文档
docs/05(中英)§2.8.1 补「绑定不裁剪链接行」及其对单例符号能力的后果;
§2.8.2 补「保持可替换的默认实现」小节 —— 这是一个通用形状(operator new、
日志 sink、panic handler),不只分配器。
check_docs_style.sh 通过(双语标题层级一致)。
目标表把一份 C 库绑在每个 triple 上,而三条互不相干的需求都想和它分歧:内核要 一份都不要、厂商 SDK 上的工程要那份 newlib、std-freestanding 坐到 openkal 的 C 库上也要换。⇒ 一个旋钮解锁三条线。 ## 形状 `[target.<triple>].sysroot`,与 `toolchain` 覆盖 `pin` 同轴:一个指名编译器, 另一个指名 C 库,两者本来都只有引擎能决定。⚠️ 字段是 `std::optional<std::string>` 而不是 `std::string`,因为**缺席与空是 两个不同的答案**:缺席继承目标表行,`sysroot = ""` 是**零 libc 档**。用普通字符串 两者不可区分,而空串正是没有 sysroot 的目标行本来的样子 —— 内核工程会静默地把 picolibc 拿回去。 ## 单一读取点(它原本是两处) `prepare_build` 原先在两个地方各自推导「这个目标用哪份 sysroot」——一处算 include/ library 路径,一处物化 xim 包。只给其中一处加覆盖,会得到**装了一份 libc、编译时用 另一份**的构建。⇒ 收敛到 `triple::effective_sysroot()`,并把 `[target.X]` 的 拼写无关查找也factor 出来(否则会出现「对 toolchain 生效、对 sysroot 不生效」的段)。 零 libc 档返回空串是刻意的:hosted 目标行本来就是空串,每个下游消费者早已把空串 当作「不加目标 sysroot 路径」⇒ **新档位在下游不需要任何新分支**。 ## 实测(两侧都钉) * 不覆盖:picolibc 头在,`text 12`; * `sysroot = ""`:`fatal error: 'stdio.h' file not found` —— C 库确实没了; * 零 libc 自包含镜像:**`text 108`,qemu 里打印 `zero-libc ok`** —— 无 libc、无 crt0、无板级包。这是零 libc 档的判据,不是「能编过」。 9 个新单测:effective_sysroot 四态(继承/覆盖/空串/hosted)+ 解析五态 (覆盖/空串present/缺席nullopt/裸名拒绝/不被误报为 unsupported)。⚠️ 过程记录:验证时我用 `find | head -1` 取测试二进制,取到陈旧目录,一度得到 「新测试 0 个」的假结论。按内容选(`--gtest_list_tests | grep`)才对。这是同一个 坑的第四次。
⚠️ 这次解除的耦合**在任何 manifest 里都看不见**。`riscv-virt-rt` 自 #459 起既不 声明 LLVM 也不声明 picolibc,却依然服务不了第二种工具链或第二份 C 库 —— 因为它把 `clang_rt.builtins-riscv64`(compiler-rt 的事实,GCC 下是 `libgcc`)与 `rv64gc/lp64d`(picolibc 的 multilib 约定)写进了自己的 build.mcpp。 **声明出来的依赖可见可评审;写死的名字不可见,而且只在换东西时才失败** —— 恰好是 没人在看的时候。 ## 判据用的是既有的那条 位置是目标的事实,选择是板级的事实。据此: * 哪个 builtins 库存在,由**编译器**决定,而且没有板子会选择不要它 (rv64 上的触发者是 picolibc printf 的 128 位移位,ISA 无对应指令); * 某个 ISA 档位的库放在哪个子目录,是 **C 库的约定**,零板级输入。 两者引擎本来就知道 ⇒ `mcpp::target_builtins_lib()` / `mcpp::target_libc_profile()`。 第三个 `mcpp::target_libc()` **不消除耦合,而是让它显形**:crt0 的对象名在 picolibc 与 newlib 之间确实不同,而那确实是板级选择。显式分支可读可扩展, 藏在字面量里的假设两者都不是。 ## 单一读取点(又一次:它原本要变成两处) `bpEnv` 在两处构造(根工程 / 每个依赖)。四个值各推导两遍,会得到「作为根工程拿到 对的、作为依赖拿到旧的」的板级包 —— 而那只在**消费方**的构建里失败,是更难查的方向。 ⇒ 收敛为 `fill_target_build_env()`,两处同一次调用。 ##⚠️ 一处契约不一致,由实测暴露 零 libc 档上 `profile` 仍返回 `rv64gc/lp64d`,而它按名字是 **C 库的**子目录。 没有 C 库时它不是任何东西的约定,发出去等于把一条不存在的路径交给内核,访问器的 名字就成了假话。⇒ 已收紧:**三个 libc 面的答案一起为空**,而 builtins 是编译器 事实,保留。 ## 验证 新增 e2e/134,七步全部**两侧钉**:目标行的 libc 可用 ↔ `sysroot = ""` 后 `<stdio.h>` 确实找不到;零 libc 仍产出镜像;三个查询在 rv64/rv32/零 libc 三种 配置下的值;裸名被解析期拒绝。 ⭐ **做了 revert-A 探针**:把 `effective_sysroot` 的覆盖分支注释掉重建后,e2e 精确 地死在第 4 步那条承重断言(`sysroot = "" did not remove the C library`)。不做这一步 不算写完 —— 这两个特性都属于「在已配置好的机器上,在与不在长得一模一样」那一类。
⚠️ **同一个缺陷发过两次,而两次的修法都是「改字面量 + 加注释」。** freestanding 的 `import std;` 诊断末尾给一个 `[dependencies]` 块让读者直接粘贴。 它错过两次,形态不同: 1. 指向 `mcpplibs.std.freestanding`,而当时**没有这个包** —— 粘完下一条命令就是 `package not found`; 2. 包名对了,**版本过期**:索引里只有 `0.2.0`,而它印 `0.1.0` ⇒ `E_NOT_FOUND: package 'compat.std-freestanding@0.1.0' not found in the synced index`。 第二次发生时,**第一次修复留下的那条注释就在断掉的那一行正上方**。⇒ 注释强制不了 跨仓库不变量 —— 本仓库早就为版本 pin 学过这一课,`check_version_pins.sh` 就是那次的 产物。 ## 判据的形状⚠️ **测试不能写出版本号。** 断言 `std-freestanding = "0.3.0"` 只是把同一个字面量 抄到第二个地方,再检查两份抄件一致 —— 两份都错时它同样通过。 改为检查那条真正重要的性质:**诊断印什么,那个东西就能解析**。 触发诊断 → 从输出里 `grep -oE` 抠出那一行 → 原样写进 manifest → 构建 → 断言没有 not-found 类错误,且该依赖**确实进了构建图** (Downloading/Compiling/Cached 三个动词之一点名它)。 链接失败是允许的(这个工程没有板级包,没有 crt0),那不是本测试的对象;**解析失败** 才是,而两次历史事故都正是解析失败。 ## revert-A 探针 把字面量改回 `0.1.0`(第二次复发的原样)重建后,该 e2e **变红**,并打印: the diagnostic's copy-pasteable line does not resolve. advice was: std-freestanding = "0.1.0" update the literal in prepare.cppm's freestanding import-std message to a version the index actually carries, in the same change that publishes it. ⇒ 它对历史缺陷本身变红,而不只是对假想的缺陷变红。
裸机工程一用 `std::vector`,链接就死在标准库深处某个头文件里的 mangled 符号上:
ld.lld: error: undefined symbol: operator new(unsigned long)
>>> referenced by allocate.h:58 (…/include/c++/v1/__new/allocate.h:58)
这条消息读起来像工具链坏了,而它不是:freestanding 目标没有编译版 libc++,
`operator new` 就是不存在。消息里没有任何一处说明哪个包提供它,也没说答案只是
一行清单。
## 内容
新增 `link_failure_advice()`,在构建失败时按链接器输出追加:说明「会分配的那部分
需要程序提供分配器,不会分配的那部分什么都不需要」,并给出激活 feature 的写法,
以及自己实现时那 **12 个重载**(特别点名带 `align_val_t` 的四个 —— 漏掉它们会在
修好第一个错误之后再撞第二次,这是实测出来的)。
## 三处刻意的设计
* ⭐ **不带版本字面量。** 它点名的是包与 **feature**,而 feature 负责拉实现
⇒ 该行跨该包的每个版本都成立。`import std` 那条带版本的建议需要 e2e/135 才能
保持诚实;这一条**在构造上就不可能以同样方式过期**,并有单测钉住(出现形如
`0.` 的版本串即判失败)。
* **两条失败路径都接。** 快路径(execute.cppm)与完整路径(ninja_backend.cppm)
经不同渠道报错;只接一条,建议就会随 build.ninja 是否最新而出现或消失。
* **从原始输出而非过滤后的输出里判定。** 过滤器会丢掉命令行,而将来改过滤器
不应该能顺手把建议一起丢掉。
## 判据
两种链接器的两种拼写都认(lld 的 `undefined symbol:` 与 GNU ld 的
`undefined reference to \``)—— 只认一种会让建议在部分工具链上不出现。
四个单测,其中一个是**反向**的:板级符号缺失(`undefined symbol: board_uart_init`)
时必须保持沉默 —— 建议会追加到每一次失败的构建上,匹配太松就会把分配器建议贴到
一个缺 crt0 的错误上。
## 实施计划(.agents/docs) 八维度评估 + 任务依赖图 + 每步的可证伪判据。⭐ 最有价值的是 §3:**实施中被实测 推翻的八条设计主张**,其中七条若不实测就会写进文档 —— 包括「std-freestanding 需要 堆」「默认实现可被程序覆盖」「`[capabilities]` 能消歧单例符号」「Cortex-M 只缺一行 目标表」。 §5 如实记录未完成项:⚠️ **openarch 的 A0 门要求两个真实不同的 arch,而 aarch64 缺 目标行与模拟器。只做一个 arch 不能证明抽象不碎 —— 这正是该门存在的理由,伪造它比 不做更糟。** ## 用户文档 * `docs/13`(中英)新增两节:「会分配的那半边」与「没有 C 库的目标」,含 capability 两种失败的原文、零 libc 的 108 字节与模板的 369 字节; * `docs/05`(中英)§2.7.1 新增 `sysroot` 键的参考,写明**缺席与空是两个不同的 答案**; * `docs/13` 的「当前边界」按实现结果更新 ——⚠️ 并如实收窄:换 C 库这条**只有空值 一侧经过验证**,生态里没有第二份裸机 C 库,指向另一份的路径未经测试。 check_docs_style.sh 通过(双语标题层级一致)。
⚠️ **本轮唯一一次「已经写进已发布文本才被推翻」的断言。** `docs/13`(中英)、`std-freestanding-nolibc` 的 mcpp.toml 与 README、以及索引描述符 都写着:板级包链了 `-lc` 时该包会造成 `memcpy` 重复定义而失败。 **实测:冷构建成功,`nm` 只找到一处 `memcpy` 定义。** 真因是我只看了推理链的一半。依赖确实以裸 `.o` 参与链接(这一半是对的,并且有 build.ninja 为证),但 **C 库是归档**,归档成员只在符号仍未定义时才被拉入 —— 包的 `.o` 先定义了它,C 库那份就永远不进来。 ⭐ **危害因此比预测的更糟**:不是响亮的链接错误,而是**静默地**用逐字节实现替换掉 C 库经过优化的字长实现,没有任何东西报告这次替换。 已更正四处文本 + 包发 0.1.1(0.1.0 内容不变保留)。实施计划 §3 记下了这一条, 以及它为什么发生:「结构上可能 ≠ 运行时确实」这次是在我自己身上生效的。
## 两个新后端(生态侧已发布并进索引)
* `mcpplibs/openkal-opensbi` 0.1.0 —— ⭐ **可移植的那个 RISC-V 后端**:控制台是对
已经知道机器是什么的固件的一次 ecall,同一镜像在 QEMU virt 的 OpenSBI 下与真实
板子上都能跑;而板级后端往固定地址写,换板即静默失效。两者并列而非替代 ——
SBI 要求底下有固件,板级后端不要求。
* `mcpplibs/openkal-uefi` 0.1.0 —— UEFI Boot Services,OVMF 下作为
EFI/BOOT/BOOTX64.EFI 启动验证。
## ⚠️ 两条被实测推翻的判断
**1. 「UEFI 受阻于一个不存在的 PE 形态裸机目标」——错的。**
`x86_64-windows-gnu` + `-nostdlib -Wl,--subsystem,10 -Wl,-e,efi_main` 产出的正是
`IMAGE_SUBSYSTEM_EFI_APPLICATION (0xA)` 且**零 DLL 依赖**,该目标默认就是 MS x64
调用约定。原判断从「裸机链接行是 ELF 形状」推出,错在**没有考虑已有的 PE 目标能否
被降到 freestanding**。
**2. 「`kind = "lib"` 能让依赖以归档参与链接」——错的。**
两个变体产出的镜像**逐字节相同**(`text 1027`),`build.ninja` 里零个 `.a`。
⇒ 因此不拆分 `std-freestanding-nolibc` 的编译器档与库档:**能让那条边界产生收益的
机制并不存在**,拆开只多一个包名。
至此本轮被实测推翻的设计主张达 **11 条中的 10 条**,实施计划 §3 逐条记录。
Sunrisepeak
changed the title
⚠️ `docs/05` §2.8.2 的示例写着 `compat.openblas = "0.3.x"`。**该形式不解析。** 结尾的 `.x` 不是本解析器拥有的选择器,字面量原样送到安装器即 E_NOT_FOUND。 以索引中确定存在的包作对照: | 写法 | 结果 | |-------------------|--------------| | cmdline = "0.0.1" | 解析通过 | | cmdline = "0.0" | 解析通过 | | cmdline = "0.0.x" | **解析失败** | ⇒ 中英两版示例改为两段前缀,并补上这张对照表与它为何在此处更要紧:**实现取不回来的 feature 等于不存在的 feature**,而开发期用 path 依赖的工程根本不查索引,该失败只在 发布之后才出现。 ## 它已经造成了一次真实事故 我照抄该示例写进 `std-freestanding` 0.3.0 的 `[feature-deps]`,于是 **0.3.0 的 alloc-kal / alloc-libc 两个 feature 实际不可用**,而本地测试全绿 —— 因为它们全都用 path 依赖。已发 0.3.1 修复,0.3.0 保留(它不会分配的那半边不受影响)。 ## 另一条被实测推翻的 「feature 是消费者控制的,不开就不包含」——**中间库能替根工程打开**。实测:根不请求 `loud`,中间库请求了,根自己的翻译单元里就得到 `LOUD`。这是 `std-freestanding-nolibc` 必须独立成包而不是做成 feature 的决定性证据。 至此本轮 13 条设计主张被实测推翻 12 条,实施计划 §3 逐条记录。
⚠️ **解析器一直都在,而这条路径没有调用它。** `version_req::parse_req` 是决定「哪个已发布版本满足这条要求」的东西。依赖读取器却把 字符串直接交给安装器,于是一条**匹配器永远无法满足**的要求穿过网络,回来是: E_NOT_FOUND: package 'compat.std-freestanding-alloc-libc@0.1.x' not found in the synced index 它点名的是**包**,而那个包存在;不能解析的是要求。 ## 这个坏形式有三层来源 1. **文档教它** —— `docs/05` §2.8.2 的示例写着 `compat.openblas = "0.3.x"`; 2. **测试套件用它** —— `test_manifest.cpp` 的 fixture 写着 `zlib = "1.3.x"`; 3. **生态照抄它** —— 我据此写进 `std-freestanding` 0.3.0,使它的两个 alloc feature **实际不可用**。 三处没有一处会去解析它:fixture 只需要**能解析清单**,从不问索引;而开发期用 path 依赖的工程同样不查索引。⇒ **能用**在这三处证明的都是别的东西。 ## 校验用既有解析器,并钉住不许收窄 新增的检查不发明规则,它调用 `parse_req`。单测**先**钉住五种实测可解析的形式 (`0.0.1` / `0.0` / `^0.0.1` / `>=0.0.1, <0.1.0` / `*`)必须仍被接受,再钉两种坏形式 被拒 —— 这样将来任何收紧都会先在这里变红。 诊断也说清楚**什么是可接受的**,因为读者是写下一个看起来合理的东西才走到这里的。 ## 生态侧 `std-freestanding` 0.3.1 已发布并进索引(0.3.0 保留,其不分配的那半边不受影响); 三个包的 README 里可粘贴的版本行已指向可用版本。
⚠️ 上一次提交把 `docs/05` §2.8.2 的示例从 `"0.3.x"` 改成 `"0.3"`,而**两段前缀同样 不可用**:它解析通过,然后死在 `install path missing after fetch`。 我当时的判据是「没有 E_NOT_FOUND」—— 它看不见这一层。 ## 三个判据强度递增,前两个各放行一种不可用写法 本地能编过 < 没有 E_NOT_FOUND < 装得上 < 对着真实索引构建成功 中英两版的表格重写成四行,按**构建**判定: | 写法 | 结果 | |-------------------|---------------------------------------------| | cmdline = "0.0.1" | 构建通过 | | cmdline = "^0.0.1"| 构建通过 | | cmdline = "0.0" | 解析通过,随后 install path missing | | cmdline = "0.0.x" | E_NOT_FOUND,点名的是包 —— 而该包存在 | ## 单测的名字也在说谎 `DependencyVersionAcceptsEveryFormThatResolves` 里含 `"0.0"`,而它并不 resolve 到底。 改名为 `...ParserAcceptsEveryEstablishedForm`,并写明它钉的是**解析器不许收窄**, 与「能否取回」无关 —— 清单检查没有资格裁定安装器的路径推导。 生态侧:`std-freestanding` 0.3.2 已发布并进索引(0.3.0/0.3.1 保留,其不分配的那半边 不受影响)。
## 1.⚠️ 我上一次提交引入了一个回归,并且它正是我一直在防的那一类 把依赖版本校验做成**错误**,会让钉在**已发布包**上的工程在升级 mcpp 后彻底加载失败 —— 即使那条坏 entry 属于一个**没人开启的 feature**。 实测:钉 `std-freestanding = "0.3.0"` 的工程,升级后不再加载,而它用的那半边包 (不分配的部分)本来完全正常。 ⇒ 这是索引那条纪律的**镜像方向**:已发布的数据不得让运行中的程序失效,而**新程序 同样不得让已发布的数据失效**。清单检查没有资格因为一条可能从未被到达的 entry 而 否决整个包。 改为 schema warning。诊断价值完整保留 —— 它说出真实原因(「不能解析的是这条要求, 而不是那个包」),而破坏面归零。回归验证:钉 0.3.0 的工程恢复可用。 ## 2. ⭐ 「把 nolibc 也做成 std-freestanding 的 feature」—— 提法对,但状态不可达 该提法本身成立(默认关的 feature 与主动加依赖等价,且让包的表面一致),而且**我原来 反对它的理由确实站不住**:中间库无论经 feature 还是经直接依赖,都能把它注入全图。 否掉它的是一个第三方事实,实测得到: * 零 libc 档 + `std-freestanding` ⇒ **编译期**死于 `'inttypes.h' file not found` * 有 C 库 + `std-freestanding` ⇒ 编译通过,只死在已知的 T2 边界(标量 `__sort`) ⇒ **子集需要 C 库的头文件**,而 `sysroot = ""` 同时拿走头与库,没有「有头无库」 这一档。因此「用子集且缺 C 库」这个状态不可达,该 feature 会是**构造上恒不生效**的。 判据因此不是「这个设计好不好」,而是**「有没有一个用户能处在需要它的状态」**。 两个包服务于互斥的安排,已写入 `docs/13` 中英两版。
⚠️ **前三次测量全部无效,而每一次我都以为已经有答案了。** | 次 | 做法 | 为什么无效 | |----|------|-----------| | 1 | 手搓 clang++ -nostdinc++ | 回落到**宿主 glibc** 的头 | | 2 | 加 -nostdlibinc | 载荷 clang.cfg **无条件注入** -isystem <宿主 glibc>,仍穿透 | | 3 | 由此得出「32/103」 | 该数字量的是载荷配置,不是零 libc | | 4 | ⭐ **用 mcpp 本身构建**(它发 --no-default-config) | 有效 | ⇒ **判据必须走被测系统本身。** 手搓的命令行不是 mcpp 的编译行,而两者的差别恰好就是 这个问题的答案所在。 ## 正确测量的结果 * 零 libc 档上**编译器自带的** freestanding C 头都在(stdint/stddef/stdarg/ limits/float),缺的只是真正的 libc 头(string.h/stdio.h); * 21 个 tier-0 头里 **15 个直接可编**(array/span/expected/bit/charconv/ concepts/type_traits/tuple/utility/compare/limits/numbers…); * 余下 6 个的真因是 **libc++ 自带的 C 头包装头**靠 #include_next 到 C 库取 size_t,没有 C 库时断链; * 一份最小 string.h shim(⚠️ 必须放在 libc++ **之后**,否则 #include_next 跳过它) 解锁 optional 与 coroutine;string_view 还差 mbstate_t,atomic 还差 time_t。 ## 因此上一次的「不可达」判断也是错的 我据一次测错的探针写下「用子集且缺 C 库的状态不可达」,并据此否掉了把 nolibc 做成 feature 的提法。**正确测量后它可达** —— 但代价是让 std-freestanding-nolibc 从 「五个函数」长成「五个函数 + libc++ 真正需要的那一小组 C 头」。⚠️ 那是一个独立项目而不是一个 feature:**一份写错的 mbstate_t 不会报错,只会让类型 静默不匹配。** 本轮不做,记为后续项。
⚠️ **两个 Windows job 因此稳定变红,而报错点名的是我从未碰过的测试文件。** 助手原本位于模块 purview 的命名空间作用域,因此它的声明属于本模块接口记录的内容。 它的返回类型是 `std::optional<std::string>`,而在 clang + MSVC 标准库下,这一点足以 让**每一个构造该类型的下游翻译单元**编不过: MSVC\include\optional:307: error: no matching constructor for initialization of '_SMF_control<_Optional_construct_base<basic_string… * 报错点名 `test_scaffold.cpp` / `test_modgraph.cpp` —— 本次改动**从未触碰**它们; * Linux 侧全程绿。 这正是本仓库记过的形状:**新导出的模块接口里出现 std 类型,会毒化导入者的模块文件, 而不是在写下它的地方失败。** 文件外没有任何东西调用它,因此文件外也不应该看得见它 —— 移入匿名命名空间。⚠️ 我最初把这两个 job 读成 flake:同一个 SHA 上多数 run 显示 success。那是**不同的 workflow**,不是同一个 job。判据必须按 job 名对齐,不能按 SHA 数颜色。
⚠️ **`mcpp new k --template riscv-virt-rt:nolibc` 之后 `mcpp run` 直接失败**, 而那个模板的全部意义就是不依赖任何东西。 自依赖注入的存在是为了让模板不与它所属的库脱节,这对几乎所有模板都对。它对 「主题就是不依赖任何东西」的模板是错的:板级包自己的模块 `#include <stdio.h>`, 于是在一个**清单里没有任何依赖**的工程上,报错是 riscv_virt_rt.cppm:9: fatal error: 'stdio.h' file not found ⇒ `[template.inject] self = false`。布尔形式拒绝注入,既有的表形式(携带 features) 不受影响,默认仍然是开 —— 三个单测分别钉住这三种情形,其中「默认为开」那条是防止 将来悄悄翻转:每个没有声明的模板都依赖它。 ## 生态侧同批修复(riscv-virt-rt 0.4.1) 板级包此前把「没有 C 库」当成错误。它不是:处在零 libc 档的工程没有在向这块板子要 任何东西。现在该路径不再报错。⚠️ 但**模拟器照常发** —— 哪个模拟器能启动这台机器是板级事实,与哪份 C 库编出的镜像 无关。我第一版把它和其余部分一起早退掉了,那会让这类工程没有 runner。 实测:生成后 **362 字节**,qemu 中打印 `k: running with no C library` / `answer 42`。 ##⚠️ 这是本轮唯一一次发布之后才发现的缺陷 0.4.0 的模板在索引里可见、可生成,而生成出来的工程跑不起来。发现它的方式是**用发布后 的包从零走一遍新用户流程** —— 与上一轮 `.3` 那次同一个方法,也同一个教训: **「我这儿能跑」用的从来不是新用户的路径。**
Windows 上四个单测编译失败,而它们指名的文件这次改动一个都没碰:
test_modgraph、test_object_address、test_scaffold、test_xpkg_host_tools。
报错落在标准库里:
MSVC\include\optional:307: error: no matching constructor for
initialization of '_SMF_control<_Optional_construct_base<basic_string…
真因是 `TargetEntry::sysroot` 的类型。ABSENT 与 EMPTY 是两个不同的
答案——缺席继承目标行,`sysroot = ""` 是零 libc 档——所以单一 string
承载不了,第一版写成了 `std::optional<std::string>`。
`std::optional<std::string>` 作为导出结构体的**数据成员**,会强制这个
模块的接口实例化该特化的特殊成员函数机制;clang 配 MSVC 标准库时,
这份机制毒化了每一个构造它的下游翻译单元。同一个类型此前已经作为
**返回类型**出现在这个模块里且相安无事——是成员位置逼出了实例化。
两个普通成员承载同样的信息,且不实例化任何东西。同理,
`effective_sysroot` 的覆盖参数改为指针:三态语义不变,导出接口里
不再有该特化。
上一次把嫌疑判给了 `version_req_problem`(已移入匿名命名空间,那一步
本身是对的),但换成匿名命名空间后 Windows 仍以同样的报错失败——排除
了那条,才落到成员上。
本机是 GCC 配 libstdc++,复现不了这条路径;六个受影响的单测本机全绿,
MSVC 侧由 CI 判定。
上一次把嫌疑判给 `version_req_problem` 并把它移进匿名命名空间, Windows 仍以同样的报错失败;那证明它不是唯一的因,却没有证明它无辜。 成员那一处已经修好,但两个候选一次只排除一个,每轮要四十分钟。 `version_req_problem` 现在返回 `std::string`,空串表示没有问题。调用侧 不需要区分「没有问题」与「问题是空串」,所以不损失任何东西,而这个模块 的新代码里再没有 `std::optional<std::string>`——下一轮 CI 的结论因此 不含歧义。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
裸机方向从「有一份文档」推进到「生态闭环」:一个用户面章节、五项引擎能力、九个生态包,
以及 被实测推翻的十四条设计主张。
引擎(本 PR)
[target.<triple>].sysroottarget_builtins_lib()/target_libc_profile()/target_libc(),解除板级包对编译器与 C 库的隐式耦合operator new具名诊断std::vector不再死在标准库深处的 mangled 符号上parse_req检查,把「点名一个存在的包」的误导性错误换成说出真实原因的一条[target.X].sysroot—— 一个旋钮解锁三条线区分,而空串正是没有 sysroot 的目标行本来的样子 —— 内核工程会静默地把 picolibc 拿回去。
实测两侧:不覆盖时 picolibc 头可用;
sysroot = ""后'stdio.h' file not found;零 libc 自包含镜像
text 108,在 qemu 中打印zero-libc ok。三个查询 —— 解除的耦合在任何 manifest 里都看不见
判据不是「能编过」(只有一种取值时永远成立),而是板级包代码里两个字面量归零
且 rv32/rv64 双档仍通过。
生态(九个包,均已发布 + 双镜像逐字节一致 + 进索引)
std-freestandingalloc/alloc-kal/alloc-libc/nolibcstd-freestanding-nolibcstd-freestanding-alloc-kal/-libcoperator new/deleteriscv-virt-rtopenkal-opensbiopenkal-uefiopenarch⭐ 标准库子集现在能在完全没有 C 库的目标上用:94 / 103 个头
障碍从来不是「子集想要 C 库」:libc++ 为 C 头带了包装头,靠
#include_next到真正那份去取
size_t/mbstate_t/time_t/EOF。没有 C 库时这条链无处可续,而包装头报的是缺类型不是缺头 —— 所以从错误信息里看不出原因。
解锁 79 个。
实测:零 libc 工程用
std::array+std::ranges::sort(带比较器)+std::string_view,qemu 中打印
54321/zero-libc std ok,11156 字节,底下没有任何 C 库。分配器:feature 作开关,capability 作仲裁,实现在别的包
两种失败都在解析期报错并点名包,而不是链接期一句
duplicate symbol。实施计划 §3 逐条记录。最值得看的六条:
std-freestanding需要堆」 → tier-0 完全不碰堆。.o参与链接,归档语义不适用。nolibc与-lc并存会重复定义」 → 冷构建成功,危害是静默替换。或载荷
clang.cfg穿透。判据必须走被测系统本身。0.1.x是合法版本形式」 → 它写在本仓库的文档和测试 fixture 里,而三处都不解析它。已修 + 引擎侧补校验。
openarch A0 的门没有通过,而且一个 arch 通不过它。 aarch64 缺目标表行与模拟器。
只做一个 arch 不能证明抽象不碎 —— 伪造它比不做更糟。
Cortex-M 未开始:实测 xim 索引里裸机 C 库只有
picolibc-riscv、qemu 只有qemu-riscv,真实成本是两个新载荷而不是「加一行目标表」。