扫描器 M1 限制：条件 import 与头单元在移植真实工程时是硬门槛（附一处诊断透传）

[Sunrisepeak]

把 XRGUI（一个 MSVC-first 的 C++23 模块化 GUI 库，~124k LOC / ~322 个模块接口单元）适配到 mcpp 的过程中，扫描器的两条 M1 限制是唯一需要大面积改源码的地方。想把实测数据留给你们做优先级参考，顺带记一处诊断透传。

环境：mcpp 2026.8.11.3 + gcc 16.1.0，x86_64-linux-gnu。

1. 条件 import 被拒 — 命中 17 处

error: import statement inside conditional preprocessor block (forbidden in M1)

src/modgraph/scanner.cppm:660。

命中的几乎全是同一个模式 —— 一个宏在两种拿到同一批第三方头的方式之间切换：

module;
#ifndef XRGUI_FUCK_MSVC_INCLUDE_CPP_HEADER_IN_MODULE
#include "plf_hive.h"
#include <gtl/phmap.hpp>
#endif

export module mo_yanxi.graphic.image_atlas;
import std;

#ifdef XRGUI_FUCK_MSVC_INCLUDE_CPP_HEADER_IN_MODULE
import <plf_hive.h>;
import <gtl/phmap.hpp>;
#endif

这个宏从未在 mcpp 侧定义，所以那条 import 是死代码 —— 但扫描是纯词法的，照样拒。

同类还有两处形态不同的：

• neargye/magic_enum 的 module/magic_enum.cppm：#ifdef MAGIC_ENUM_USE_STD_MODULE / import std;。索引包 neargye.magic_enum 靠 scan_overrides 绕过了，但直接 vendor 上游 submodule 的人会撞上。
• 一个实现单元把 import 写在 #if defined(__cpp_lib_stacktrace) 里（这处确实该修 —— import 本来就该在 purview 开头）。

观察：docs/zh/05-mcpp-toml.md §2.3 写了 [build].defines "会进入 P1689 模块扫描 —— 这正是被宏保护的 import 能被解析的前提"。但实际上扫描器在看到条件块里有 import 就直接报错，不看条件是否可判定。文档描述与实现有出入，至少值得对齐一下措辞。

一个可能的中间档：如果条件只依赖 [build].defines / [targets.*].defines 里出现过的宏，扫描器其实有足够信息判定，可以求值而不是拒绝。真正不可判定的（依赖工具链内建宏如 __cpp_lib_stacktrace）再报错。

2. 头单元被拒 — 与 1 是同一批文件

error: header units (import "h" / import <h>) are forbidden in M1

src/modgraph/scanner.cppm:666。

两条加起来的效果是：MSVC 工程里"用头单元吃第三方头"这条路在 mcpp 下没有任何保留余地。我最后只能把 16 个文件的 #include 分支改成无条件、把头单元分支整个删掉。

这个改动会影响该工程的 MSVC 构建行为（xmake 那边仍然定义着那个宏），所以对一个"只想加一套 mcpp 构建、不动原有构建"的工程来说，这是适配成本里最扎眼的一项。不是说 M1 的取舍不对 —— 头单元本身就是个泥潭 —— 只是想让你们知道它在真实工程上的实际代价。

3. 一处诊断透传：私有模块片段

module : private; 会得到：

font.ixx:703:1: error: module already declared
  703 | module : private;
      | ^~~~~~

这是 GCC 的错误，不是 mcpp 的 —— 我一开始归因错了，用 5 行文件逐字复现 mcpp 的扫描命令后确认：

$ cat m.ixx
export module m;
export int f();
module : private;
int helper() { return 1; }
int f() { return helper(); }

$ g++ -std=c++23 -fmodules -c m.ixx
m.ixx:3:1: sorry, unimplemented: private module fragment          ← 清楚

$ g++ -std=c++23 -fmodules -fdeps-format=p1689r5 -fdeps-file=m.ddi \
      -fdeps-target=m.o -M -MM -MF m.ddi.dep -x c++ -E m.ixx -o m.o
m.ixx:3:1: error: module already declared                          ← 误导

同一件事（GCC 16 没实现私有模块片段），编译路径给的是 sorry, unimplemented，P1689 扫描路径给的是 module already declared。用户看到后者只会去找"重复的 module 声明"，找不到。

不是要 mcpp 修 GCC，只是：既然扫描器已经在做词法解析，识别出 module : private; 并给一句"当前工具链未实现私有模块片段（GCC 16）"的话，能省掉一轮误导性排查。优先级应该很低。

（顺带：我那个工程里这处用法本身也不合规 —— 带私有片段的模块单元必须是该模块唯一的模块单元，而 mo_yanxi.font 还有一个实现单元。IFNDR，所以谁都没义务报。）

其余部分的体验

想说清楚上面三条是全部的摩擦点 —— 这次适配里 mcpp 侧其他一切都按预期工作，包括几个我事先专门验证过的载荷性假设：

• module_extensions = [".ixx"] 让默认 glob 自动变宽，一行搞定 MSVC 拼法
• path 依赖包里的任意模块，消费者可直接 import，不需要 lib-root、不需要在根模块 re-export
• 无 lib-root 的"模块袋"能作为 kind = "lib"
• path 依赖的 include_dirs 正确传播给消费者
• 多个 [targets.*] bin 共享同一批 object（compile-once 模型），各自只有自己的入口 .o
• sources glob 可以用 ../ 越出包根 —— 这条让我能给三个第三方 submodule 写"薄包"，零上游改动就把它们变成 path 依赖
• [features] + [feature-deps] 把 gtest 完全挡在默认构建之外（feature 不激活时根本不下载）

126k LOC 的模块依赖图一次扫对，没有一处图错误。

适配的完整记录（含 GCC vs MSVC 的源码符合性差异清单）在
Sunrisepeak/xrgui#1

[Sunrisepeak]

补一条这一轮查出来的 scanner bug —— 它和 issue 正文里那三条同源（都是词法扫描阶段），但影响面不同：只在 clang 工具链下才暴露。

UTF-8 BOM 让扫描器认不出 export module

error: unable to open output file '': 'No such file or directory'

空的输出路径。原因是源文件以 UTF-8 BOM（EF BB BF）开头：

$ head -c 3 src/utility/container/array_stack.ixx | od -An -tx1
 ef bb bf
$ head -1 src/utility/container/array_stack.ixx
export module mo_yanxi.array_stack;

扫描器没有跳过 BOM，于是紧随其后的 export module … 没被识别，模块名解析为空，
clang 的 -fmodule-output= 就拿到了空串。

为什么只在 clang 下暴露： GCC 的 BMI 按模块名存进 gcm.cache/<module>.gcm，
不依赖扫描出的名字去拼输出路径；clang 走 -fmodule-output=<path>，名字为空路径就为空。
所以同一批文件在 GCC 下一直正常，换 clang 才炸，而且报的是一个完全不指向根因的错误。

复现

$ printf '\xef\xbb\xbfexport module m;\nimport std;\nexport int f(){return 1;}\n' > src/m.ixx
$ printf 'import std;\nimport m;\nint main(){ std::println("{}", f()); }\n' > src/main.cpp
$ mcpp build            # [toolchain] default = "llvm@22.1.8"
error: unable to open output file '': 'No such file or directory'

去掉 BOM 即通过。

建议

扫描器在读取每个 TU 时跳过开头的 BOM。BOM 在 MSVC-first 的代码库里很常见
（MSVC 一直建议给非 ASCII 源码加 BOM），所以这会持续咬到从 Windows 迁过来的工程 ——
XRGUI 这一个仓库里就有 8 个。

顺带一个诊断质量的建议：-fmodule-output= 为空时，与其把空路径原样交给 clang，
不如在扫描阶段就报「无法从该文件解析出模块名」并点出文件 —— 现在这个错误信息
完全不指向根因。

---

另外补一条上下文：这一轮把工具链换成 clang，是为了验证 GCC 16 的
recursive lazy load / failed to load pendings for 'std::vector' 是不是编译器 bug。
结论是肯定的 —— clang 冷构建完整编过同一份代码，还越过了整棵树（196 个模块）。
但 libc++ 缺了本代码库用到的约 100 处 C++23 库特性（move_only_function、
views::enumerate/stride/slide、is_pointer_interconvertible_with_class、
const_iterator），所以 clang 目前还不能作为该工程的实际工具链。这条与 mcpp 无关，
只是说明为什么上面那个 BOM bug 是在这个时候才被发现的。

[Sunrisepeak]

GCC 16 recursive lazy load —— 归属已经用 clang 对照钉死

这条与 mcpp 无关，是 GCC 的 bug。放在这里是因为它是本次适配唯一剩下的阻塞，
而且判定过程里用到的对照实验对 mcpp 侧也有参考价值（尤其是 §4 那条 BMI 命名差异）。
后续会另行提给 GCC。

现象

node.spec.ixx:23:24: error: recursive lazy load [-Wtemplate-body]
node.spec.ixx:23:24: fatal error: failed to load pendings for 'std::vector'

工具链：gcc@16.1.0，x86_64-linux-gnu，import std;。

1. 触发条件（已定位）

模块 mo_yanxi.react_flow 有 6 个分区。其中 :manager 在导出的类里声明了
std::vector 成员：

export module mo_yanxi.react_flow:manager;
// 注意：这个分区自身没有 import std —— std::vector 是经 mo_yanxi.utility 传递到达的

export struct manager{
    std::vector<node_pointer> nodes_anonymous_{};
    std::vector<node*>        pulse_subscriber_{};
    linear_flat_set<std::vector<node*>> expired_nodes_{};   // 跨模块模板，std::vector 作实参
    // …
};

任何同时满足两条的分区都会炸：import :manager; + 随后惰性需要 std::vector。
命中 :endpoint 与 :modifier 两个。

2. 诊断实验：确认触发点就是这条 import

把 import :manager; 从 node.spec.ixx 去掉（连带它的 friend manager;），
该 TU 立刻编过，错误只剩另一个分区。把 import 加回来、只保留 friend 不加，
错误换个位置照样出现（移到了首次触碰 std::vector 的那一行）。

3. 试过并全部无效的 7 种规避

#	尝试	结果
1	把 import std; 提到分区 import 之前	无效
2	使用点前强制 sizeof(std::vector<int>) 触碰	无效，错误移到该行
3	GMF 里 #include <vector>	无效
4	-fno-module-lazy	无效，错误移到 import :manager; 那一行 —— 反证根因在 BMI 加载
5	给 manager.ixx 补 import std;（干净重建）	无效
6	--param=lazy-modules=1000	无效
7	降级 gcc@15.1.0	更糟 —— gcc 15 连 import std 都预编译不出来（ext/concurrence.h / std_mutex.h 报 cannot convert '<brace-enclosed initializer list>' to 'unsigned int'）

4. clang 对照：同一份代码完整编过

$ # [toolchain] default = "llvm@22.1.8"，冷构建
$ rm -rf target .mcpp && mcpp build --cache off
    Resolved llvm@22.1.8 → …/bin/clang++
   Compiling react_flow v0.1.0 (.)
   Compiling utility (path)
    Finished dev in 1.17s

$ ls target/*/*/pcm.cache/ | grep -E 'endpoint|modifier'
mo_yanxi.react_flow-endpoint.pcm
mo_yanxi.react_flow-modifier.pcm

不止 react_flow —— clang 越过了整棵树（196 个模块 + 全部依赖），
最后只停在一个当时尚未实现的生成头文件上，与编译器无关。

所以这是 GCC 模块实现的 bug，不是代码问题。

（clang 目前仍不能作为该工程的实际工具链：libc++ 缺了本仓用到的约 100 处 C++23 库设施 ——
move_only_function 33 处、views::enumerate 46 处、views::stride 11 处、
views::slide 3 处、is_pointer_interconvertible_with_class 4 处、
const_iterator（P2278 全局别名模板）3 处。llvm 20 与 22 都一样缺。
这条与 mcpp 无关，只是说明为什么最终仍留在 GCC 上。）

5. 最小复现：还没剥出来，如实说明

从零构造试了三轮，都没能复现：

1. :manager（含 std::vector 成员）+ :endpoint（import 它并实例化第三方模块的
   constexpr 变量模板）→ 编过；
2. 加上 :node_interface 与 :successor_list（后者也含 std::vector），
   让 :endpoint 的类派生自另一分区的类模板、并带 friend manager; → 仍编过；
3. 在真实代码上做减法定位具体成员 → 那三个成员在 manager 内部被广泛使用，
   单独摘掉会先撞一串 not declared in this scope，无法单变量隔离。

推测还需要第三方模块具备一定的 pendings 规模（真实链路里是 26k LOC 的
mo_yanxi.utility），但这一点我没有验证，不作为结论。

提给 GCC 前需要继续做 delta 归约。上面 §1–§4 都是可复现的事实，§5 是已知的缺口。

---

复现材料：Sunrisepeak/xrgui#1 （./mcpp/patches/apply.sh 后 mcpp build）

[Sunrisepeak]

GCC recursive lazy load：自建 GCC 17 后的完整结论

为了把这条查到底，在 mcpp-community/mcpp-gcc（private）拉了 GCC 17.0.0 trunk（上游基线 977fd87ba，2026-08-11）从源码构建并加了插桩。以下都是实测。

1. GCC 17 trunk 仍然复现

$ g++ --version
g++ (GCC) 17.0.0 20260811 (experimental)

node.spec.ixx:23:24: error: recursive lazy load [-Wtemplate-body]
node.spec.ixx:23:24: fatal error: failed to load pendings for 'std::vector'

同样两个 TU、同样错误。升级解决不了，两个已知同族修复（PR116382、PR122785）都已在 16.1 内（比对 releases/gcc-16.1.0 tag 确认过），所以这是一个未报告的新实例。

2. 我先前的根因判断是错的，插桩推翻了它

之前我说是 module_state::read_language 里分区的 eager bulk 读持有守卫。不对。 插桩输出：

mcpp: recursive lazy blocked; holder=mo_yanxi.react_flow:manager
      reason=lazy_load_binding held_snum=385 requested_snum=4294967295

holder 不是 bulk 读，held_snum=385 是个具体 section 号（bulk 读会留 ~0u）。真实序列：

1. 名字查找要一个绑定 → lazy_load_binding 在 section 385 取走全局守卫 lazy_snum
2. load_section(385) 流式化该 section
3. 流式化过程中 lookup_template_class → lazy_load_pendings(std::vector)
4. recursive_lazy() 看到守卫已被占 → 拒绝 → fatal_error

和分区没有本质关系，分区只是让它容易发生。

3. 为什么我的修复失败了 —— 这部分最有价值

插桩把那 87 个 pending 实体逐个分类了：

归属	数量	仍需惰性加载	会违反 snum >= slurp->current
std	66	部分	否
:manager（= 持有者自己）	17	一个都不是	否
:successor_list	4	是	否

一个都不会违反 section 顺序。 同模块那 17 个全部已加载（没东西可重入），仍需加载的 36 个全在别的 module_state，各有各的读取位置。

据此我放宽了守卫：只在真会违反顺序时才拒绝，并在结束时恢复外层守卫值而非清零。结果：

recursive lazy load  →  消失
                     →  换成 ICE:
bits/stl_vector.h:303: internal compiler error:
  in finish_member_declaration, at cp/semantics.cc:4260

那个断言是 "Don't add decls after definition"。

所以守卫保护的不只是 section 顺序，还有类定义期状态：嵌套的 pendings 加载会往一个外层正在流式化中的类里追加成员。我又试了 push_to_top_level / pop_from_top_level（GCC 自己在 post_load_processing 里对 NTTP 对象用的就是这个惯用法）——也没用。问题不在保存/恢复上下文，而在于成员被塞进了一个半成品类。

测试套件给了终审（GCC 自带 g++.dg/modules）：

基线（未打补丁的 GCC 17 trunk）：  4 unexpected failures
打补丁后：                        17 unexpected failures

13 个回归落在 pr99166、pr99377-3、pr99425-1、tls-1、tpl-friend-13、iostream-1 —— 其中好几个本身就是历史上的 lazy-loading bug，正是这个守卫当初为之而设的场景。

补丁作为负面结果保留在 attempt/relax-lazy-guard 分支，主线只留插桩。

这次失败的净收获：把问题从「一个看不懂的错误」收窄成了一个具体问题 ——

pendings 加载在某个类流式化中途被触发时如何安全完成：是重排工作顺序，还是先让该类完成。不是放宽守卫。

4. 能不能从项目侧解决？部分能，而且值得做

查了失败 TU 到底需要 manager 什么：

:endpoint 与 :modifier —— 根本不需要。 manager 只出现在两处：friend manager;，以及 on_pulse_received(manager& m) 的引用参数——三个函数体一次都没碰过 m。而 :node_interface 早就有 export struct manager; 前向声明。

去掉这两个文件的 import :manager; 后，它们立刻编过，失败 TU 从 2 个降到 1 个。这不是绕过，是真实的依赖清理：本来就不该 import。

:async —— 真的需要。 它继承 :manager 里的 progressed_async_node_base、用 progress_check，还调 push_task / get_manager_stop_token。我试过「瘦访问器」解耦（把两个非模板调用抽成自由函数，声明放前向声明所在的分区、定义放实现单元），但继承关系解不掉——那是结构性依赖，要动分区边界的设计。

所以项目侧的结论：

	结果
:endpoint / :modifier	✅ 去掉无用 import 即可，独立正确
:async	⛔ 结构性依赖 :manager，需重新设计分区边界

单靠项目侧不足以解锁构建，但那两处清理本身就该做。

5. 材料

• mcpp-community/mcpp-gcc（private）：插桩、.mcpp/trace-gcc17.log、两份测试套件 sum、repro.sh
• 复现：./.mcpp/repro.sh（复用 mcpp 生成的 build.ninja，只换编译器）

下一步是把 §1–§3 提给 GCC。§3 那个「关掉守卫会撞上 finish_member_declaration」的观察，应该能帮上游省不少时间。