fix: fold [build].defines into cflags/cxxflags before P1689 scan

[ZheFeng7110]

Summary

[build].defines was parsed by the TOML loader but never folded into the compile flags used by the P1689 module scanner. When import statements were guarded by a macro declared in [build].defines, the scanner saw no imports, while the planner (via scan_overrides) expected them, causing a plan-vs-scan divergence.

This PR fixes that by:

1. Adding defines to BuildConfig in src/manifest/types.cppm.
2. Parsing [build].defines in src/manifest/toml.cppm.
3. Introducing fold_build_defines_into_flags() in src/build/prepare.cppm to desugar defines into -D<x> on both cflags and cxxflags before the manifest is snapshotted into packages and before fingerprinting.
4. Adding a unit test and an E2E regression test (tests/e2e/167_build_defines_module_scan.sh) that mirrors the conditional-import + scan_overrides scenario.
5. Updating docs/05-mcpp-toml.md and docs/zh/05-mcpp-toml.md.

Closes #296

Test plan

• mcpp build self-hosts successfully.
• mcpp test unit/test_manifest passes.
• New E2E test tests/e2e/167_build_defines_module_scan.sh passes.
• Reproduced the original failure with the unpatched binary and confirmed the patched binary builds the user's example.

[Sunrisepeak]

Review 跟进 —— 已 push 一个 follow-up commit

先说结论:原修复方向是对的。我把链路实测追了一遍 —— fold 落在 makePackageRoot 快照之前,scan_packages 读的 privateBuild.cxxflags 正是那份快照,ninja_backend 再把它拼进 P1689 扫描规则;三个 fold 点也精确复刻了既有的 #229 conditional-merge 漏斗。机制没有问题,compute_fingerprint 在三处 fold 之后跑,所以指纹参与也成立。

在这个基础上补了两处。

1. defines 该是 BuildInputs 成员,而不是 BuildConfig 成员

cfg 轴承载的是 ConditionalConfig::inputs(一个 BuildInputs),而这正是 #258 造出这个类型的目的 —— types.cppm 里的原话:

membership here is the answer, and it is a type rather than a hand-kept list, so it cannot drift

挂在 BuildConfig 上的字段,在 [target.'cfg(...)'.build] 下结构性地无法表达;而条件段读取器只读它认识的键,于是:

[target.'cfg(windows)'.build]
defines = ["USE_WIN32"]

会被静默丢弃 —— 正是 #296 本身的失败模式,只是挪到了隔壁一个段落。(原 commit 里 fold 函数的注释写了 "so conditional defines land too",这句当时无法成立。)

现在 defines 移进 BuildInputs:append() 带上它,条件段读取器读它,非空闸也计入它 —— 之前只写 defines 的条件段会在被求值之前就整个丢掉。

2. 根因订正:不是"defines 没被 fold",而是 [build] 会静默吞掉未知键

这点也影响 PR 描述。描述里写 defines "was parsed by the TOML loader but never folded",但 diff 里是新增了解析那一行 —— 这个 PR 之前 [build].defines 根本没被读过,它是一个被静默丢弃的未知键。

这正是 #131 的坑,而 [targets.<name>] 早就加了守卫,注释写的就是 #296 的剧本:

a [targets.x] cxxflags typo on an older mcpp just vanished

现在 [build] 和 [target.<pred>.build] 同样处理:schema warning,--strict 下是 error。这才是能从根上避免 #296 的那一半。

误报风险已实测:扫了仓库全部 116 个 mcpp.toml 以及 tests/ 里所有 heredoc 清单,零误报。(e2e fixture 里的 build.default_jobs / default_backend 是全局 config.toml,由 config.cppm 解析,不经过这条路径。)

3. 顺带:xpkg 描述符里的 defines 不再是 did-you-mean 错误

xpkg.cppm 之前把 defines 列为重定向到 flags 的易混淆别名。两个 manifest 表面是同一套 schema 的两种拼写,mcpp.toml 里合法的键不该在描述符里报 unknown key。现在 defines 在 mcpp 段和 target_cfg 里都是正式键,只剩单数 define 还做重定向。

测试

新增的三个 fold 调用点原本零覆盖,而已有 fold 点有三分之二没测:

• 单测 129 → 136:条件 defines 解析、只含 defines 的条件段、append() 合并、两个未知键守卫,以及一个用满每一个受支持 [build] 键的清单 —— 防止守卫误伤自己人,因为 --strict 下那会直接变成构建失败。
• e2e 167 重写:
  • 改用本地模块而不是 import std,于是在 Windows 上也能跑 —— fix: [build].defines 未被传入 P1689 模块扫描，导致条件 import 与 scan_overrides 冲突 #296 正是 Windows 报的;
  • 断言改成 #error 守卫,让编译器本身成为断言(参考 85_target_cfg_build_flags.sh);
  • 补齐:NAME=value、含空格的宏值([bug] defines 值含空格时未转义,命令行被拆散(-DX="long long" → 孤立 long 参数) #234 的 -D 引号路径)、cfg 轴、path 依赖自己的 defines、以及"不泄漏给消费者";
  • 修掉 out=$("$MCPP" run | tail -2) —— 管道的退出码取自 tail,mcpp run 崩了会被吞掉。
• e2e 93 断言 defines 是合法描述符键。

版本

bump 到 2026.7.28.1(check_version_pins.sh 绿;bootstrap MCPP_PIN 保持已发布的 2026.7.27.1 不动)。

本地验证

全量单测 37/37 二进制通过(136 个 manifest 用例);e2e 167 / 93 / 85 / 108 / 109 / 116 / 149 / 119 / 80 / 83 全过。

CI

15/15 全绿(01c800c):四平台自举 + e2e、hermetic 容器、aarch64-musl 交叉、mingw→wine、macOS LLVM 端到端、Windows toolchains + regressions。