perf: build optimization (P0/P1/P2) (#26)

* perf(P0): frontend dirty check — skip prepare_build when inputs unchanged

On a successful build, writes target/.build_cache with the output dir
and ninja binary path. On the next invocation, if build.ninja in that
dir is newer than all source files and mcpp.toml, invokes ninja directly
without re-running toolchain resolve, scanner, make_plan, or emit.

Reduces no-change builds from ~10s to <0.5s.

* perf(P1): per-file dyndep — only rebuild changed modules

Replace the global build.ninja.dd (one dyndep file for all modules)
with per-file .dd files. Each .cppm gets its own .ddi → .dd conversion
via the new cxx_dyndep rule, and each compile edge references only its
own .dd file.

Before: touching one file → all 39 modules dirty → full rebuild (~21s)
After:  touching one file → only that file's .dd dirty → incremental

New `mcpp dyndep --single --output <file.dd> <file.ddi>` mode added
for the per-file conversion. Legacy multi-file mode still available.

* perf(P2): BMI copy_if_different — prevent cascade rebuilds

GCC always updates the .gcm (BMI) file's timestamp even when the
module interface hasn't changed. This causes all downstream modules
to be recompiled unnecessarily.

Fix: the cxx_module rule now backs up the BMI before compilation,
and if the new BMI is byte-identical to the backup, restores the
old file (preserving its timestamp). Combined with restat = 1 in
the per-file dyndep entries, ninja skips downstream modules when
only the implementation changed.

This means modifying a function body without changing the module
interface no longer triggers a cascade rebuild of all importers.

* docs: add build optimization analysis report

Author: Sunrisepeak

.agents/docs/2026-05-12-build-optimization-analysis.md

@@ -0,0 +1,216 @@
+# mcpp 构建优化深度分析报告
+
+> 2026-05-12 — 模块化编译优化、缓存机制、增量编译分析
+> 基于 mcpp 0.0.10 代码库分析
+
+## 1. 当前构建流程与耗时分解
+
+### 1.1 mcpp 自身项目的构建数据
+
+| 场景 | 耗时 | 分析 |
+|---|---|---|
+| 全量构建（冷） | ~21s | 合理 |
+| 无改动重新 build | **~10s** | ❌ 前端开销 |
+| touch 一个文件 | **~21s** | ❌ 全量重编译 |
+| ninja 直接 no-op | 0.023s | 参考基线 |
+
+### 1.2 耗时分解
+
+```
+mcpp build (touch 一个文件):
+├── mcpp 前端 (~10s)
+│   ├── toolchain resolve (xlings interface 子进程)
+│   ├── manifest parse + dep fetch
+│   ├── regex scanner (扫描所有 .cppm 文件)
+│   ├── modgraph validate
+│   ├── fingerprint compute
+│   ├── ensure_built std module
+│   ├── make_plan (BuildPlan 构建)
+│   ├── BMI cache check/stage
+│   └── build.ninja + compile_commands.json 生成
+│
+└── ninja 执行 (~11s)
+    ├── Phase 1: SCAN (1 个 .ddi 变化)  ~1s
+    ├── Phase 2: COLLECT (build.ninja.dd 重生成)  ~0.1s
+    ├── Phase 3: ALL 39 个模块重编译  ~10s ← 核心问题
+    └── LINK  ~0.5s
+```
+
+## 2. 两大核心问题
+
+### 2.1 问题一：全局 dyndep 导致全量重编译
+
+**根因**：所有编译边依赖同一个 `build.ninja.dd` 文件。
+
+```
+cli.cppm 被 touch
+    ↓
+cli.cppm.ddi (scan) 重新生成
+    ↓
+build.ninja.dd 依赖 ALL 39 个 .ddi → build.ninja.dd 被重新生成
+    ↓
+所有 39 个 compile edge 都有 `| build.ninja.dd` 作为 implicit dep
+    ↓
+全部 39 个模块标记为 dirty → 全量重编译
+```
+
+**理想行为**：只有 `cli.cppm` 和直接依赖 `mcpp.cli` 模块的文件需要重编译。
+
+**ninja 的 dyndep 机制本身支持 per-file dyndep**，当前实现选择了最简单的全局方案。
+
+### 2.2 问题二：mcpp 前端每次全量重算
+
+即使没有任何文件改动，mcpp 仍然花 ~10s 做：
+- 启动 xlings 子进程解析工具链
+- 扫描所有源文件的 module 声明
+- 生成 BuildPlan
+- 重新写入 build.ninja
+
+这些步骤的结果在大多数增量编译场景下都不变。
+
+## 3. 优化策略
+
+### 3.1 策略一：per-file dyndep（影响最大）
+
+**目标**：改一个文件只重编译该文件及其下游依赖。
+
+**方案**：将全局 `build.ninja.dd` 拆分为 per-file dyndep。
+
+```ninja
+# 当前（全局 dyndep）：
+build build.ninja.dd : cxx_collect obj/cli.cppm.ddi obj/ui.cppm.ddi ...
+build obj/cli.m.o | gcm.cache/mcpp.cli.gcm : cxx_module src/cli.cppm | build.ninja.dd
+  dyndep = build.ninja.dd
+
+# 优化后（per-file dyndep）：
+build obj/cli.cppm.dd : cxx_dyndep obj/cli.cppm.ddi
+  restat = 1
+build obj/cli.m.o | gcm.cache/mcpp.cli.gcm : cxx_module src/cli.cppm | obj/cli.cppm.dd
+  dyndep = obj/cli.cppm.dd
+```
+
+**效果**：touch `ui.cppm` 时，只有 `ui.cppm.ddi` → `ui.cppm.dd` 变化，只有 `ui.m.o` 和依赖 `mcpp.ui` 的下游文件需要重编译。
+
+**实现复杂度**：中等。需要修改 `ninja_backend.cppm` 的 emit 逻辑和 `dyndep.cppm` 的生成方式。
+
+### 3.2 策略二：BMI restat + copy_if_different（减少级联重编译）
+
+**目标**：当模块接口不变时（只改了实现），阻止级联重编译。
+
+**方案**（业界标准做法，CMake 采用）：
+1. 编译器输出 BMI 到临时文件
+2. 比较临时文件与当前 BMI 内容
+3. 内容不同才覆盖（保持旧时间戳）
+4. ninja `restat = 1` 检测到 BMI 未变，跳过下游
+
+```ninja
+rule cxx_module
+  command = $cxx $cxxflags -c $in -o $out.tmp && \
+            (cmp -s $bmi_out.tmp $bmi_out && rm $bmi_out.tmp || mv $bmi_out.tmp $bmi_out) && \
+            mv $out.tmp $out
+  restat = 1
+```
+
+**效果**：修改 `ui.cppm` 的函数体但不改接口 → BMI 不变 → 依赖 `mcpp.ui` 的下游不重编译。
+
+**GCC 注意**：GCC 每次都会重新生成 BMI 文件（即使内容相同时间戳也变），所以必须在构建系统层面做 copy_if_different。
+
+### 3.3 策略三：mcpp 前端缓存（减少 10s 前端开销）
+
+**目标**：无改动时 mcpp 应在 <1s 内完成。
+
+**方案**：
+
+1. **快速脏检查**：在调用 scanner/make_plan 之前，检查 `build.ninja` 是否比所有源文件更新。如果是，直接跳到 ninja 执行。
+
+2. **增量 scanner**：缓存上一次的扫描结果（module graph），只重新扫描修改过的文件。
+
+3. **工具链缓存**：toolchain resolve 结果缓存到 `.mcpp/cache/toolchain.json`，避免每次启动 xlings 子进程。
+
+**效果**：无改动 → ~0.1s（直接 ninja no-op），改一个文件 → ~1s（增量 scan + ninja）。
+
+### 3.4 策略四：Clang 两阶段编译（未来多工具链支持）
+
+**当前**：GCC 一次生成 BMI + .o，串行依赖。
+
+**Clang 支持两阶段**：
+```
+Phase 1: clang --precompile A.cppm -o A.pcm    (生成 BMI)
+Phase 2: clang -c A.pcm -o A.o                 (BMI → .o)
+```
+
+**好处**：A 的 BMI 就绪后，B 可以开始编译 BMI，同时 A 继续编译 .o。并行度更高。
+
+**Clang 还支持 Reduced BMI**（`-fmodules-reduced-bmi`）：BMI 只包含接口信息，不包含实现细节，更小、更少级联。
+
+## 4. 架构设计建议
+
+### 4.1 构建后端抽象层
+
+当前 `Backend` 接口已经有抽象，但实际只有 NinjaBackend。建议扩展：
+
+```
+Backend (abstract)
+├── NinjaBackend          (当前，GCC + Ninja)
+├── NinjaClangBackend     (未来，Clang + Ninja，两阶段编译)
+├── MSBuildBackend        (未来，MSVC)
+└── DirectBackend         (未来，无 ninja，mcpp 直接调度编译)
+```
+
+### 4.2 Scanner 抽象层
+
+```
+ModuleScanner (abstract)
+├── RegexScanner          (当前，快速但不精确)
+├── P1689Scanner          (当前，GCC -fdeps-format=p1689r5)
+├── ClangScanDepsScanner  (未来，clang-scan-deps)
+└── CachedScanner         (装饰器，缓存上一次结果，增量更新)
+```
+
+### 4.3 BMI 管理层
+
+```
+BmiManager
+├── ProjectBmiCache       (per-project target/ 目录)
+├── GlobalBmiCache        (当前 $MCPP_HOME/bmi/，跨项目共享)
+├── BmiRestatHelper       (copy_if_different + restat 机制)
+└── BmiContentHash        (未来，基于 BMI 内容哈希而非时间戳)
+```
+
+### 4.4 工具链抽象层
+
+```
+Toolchain
+├── GccToolchain          (当前，GCC 16.1)
+├── ClangToolchain        (未来)
+├── MsvcToolchain         (未来)
+└── ToolchainCache        (缓存 resolve 结果)
+```
+
+## 5. 优先级建议
+
+| 优先级 | 策略 | 预期收益 | 实现复杂度 |
+|---|---|---|---|
+| P0 | 前端快速脏检查 | 无改动 10s → <0.5s | 低 |
+| P1 | per-file dyndep | 改一文件 21s → ~3s | 中 |
+| P2 | BMI restat + copy_if_different | 改实现不改接口 → 0 级联 | 低 |
+| P3 | 增量 scanner | scanner 耗时减少 80%+ | 中 |
+| P4 | 工具链 resolve 缓存 | 减少 1-2s 启动开销 | 低 |
+| P5 | Clang 两阶段编译支持 | 并行度提升，减少级联 | 高 |
+
+## 6. 业界参考
+
+| 构建系统 | 模块编译策略 | 增量方案 |
+|---|---|---|
+| CMake 3.28+ | per-file scan + per-target collation dyndep | restat + copy_if_different |
+| build2 | GCC module mapper 协议（编译时动态发现依赖） | 无需 scan 阶段 |
+| xmake | 编译器原生 scan + jobgraph 并行 | 增量 scan |
+
+## 7. 总结
+
+mcpp 的模块构建基础架构是正确的（三阶段 dyndep pipeline + BMI 缓存 + 指纹隔离），但在增量编译效率上有显著优化空间。最大的两个 win 是：
+
+1. **前端脏检查**（P0）— 即刻将无改动场景从 10s 降到 <0.5s
+2. **per-file dyndep**（P1）— 将单文件修改场景从 21s 降到 ~3s
+
+这两个优化不影响正确性，不需要改变架构，可以增量实施。

src/build/backend.cppm

@@ -21,6 +21,7 @@ struct BuildResult {
     std::chrono::milliseconds               elapsed { 0 };
     std::size_t                             cacheHits   = 0;
     std::size_t                             cacheMisses = 0;
+    std::string                             ninjaProgram;     // P0: cached for fast-path rebuilds
 };
 
 struct BuildError {

src/build/ninja_backend.cppm

@@ -187,8 +187,33 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     append("  command = mkdir -p $$(dirname $out) && cp -f $in $out\n");
     append("  description = STAGE $out\n\n");
 
+    // P1: per-file dyndep rule. Converts one .ddi → .dd independently.
+    append("rule cxx_dyndep\n");
+    append("  command = $mcpp dyndep --single --output $out $in\n");
+    append("  description = DYNDEP $out\n");
+    append("  restat = 1\n\n");
+
+    // P2: cxx_module preserves BMI timestamps when interface is unchanged.
+    // GCC always updates the .gcm timestamp even if content is identical.
+    // We backup the BMI before compilation, compile, then restore the old
+    // file if content is byte-identical. Combined with restat = 1 in the
+    // dyndep file, this prevents cascading rebuilds when only the module
+    // implementation changed (not the interface).
+    //
+    // $bmi_out is set per build edge to the BMI path (gcm.cache/<module>.gcm).
+    // If $bmi_out is empty (no module provided), we just compile normally.
     append("rule cxx_module\n");
-    append("  command = $cxx $cxxflags -c $in -o $out\n");
+    append("  command = "
+           "if [ -n \"$bmi_out\" ] && [ -f \"$bmi_out\" ]; then "
+             "cp -p \"$bmi_out\" \"$bmi_out.bak\"; "
+           "fi && "
+           "$cxx $cxxflags -c $in -o $out && "
+           "if [ -n \"$bmi_out\" ] && [ -f \"$bmi_out.bak\" ] && "
+              "cmp -s \"$bmi_out\" \"$bmi_out.bak\"; then "
+             "mv \"$bmi_out.bak\" \"$bmi_out\"; "
+           "else "
+             "rm -f \"$bmi_out.bak\"; "
+           "fi\n");
     append("  description = MOD $out\n");
     if (dyndep)
         append("  restat = 1\n");
@@ -287,16 +312,21 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         }
         append("\n");
 
-        // ── Phase 2: collect into dyndep file. ──────────────────────────
-        std::string ddi_inputs;
-        for (auto& d : ddi_paths)
-            ddi_inputs += " " + d;
-        append("build build.ninja.dd : cxx_collect" + ddi_inputs + "\n\n");
+        // ── Phase 2: per-file dyndep (P1 optimization). ────────────────
+        // Each .ddi → .dd independently, so modifying one source file only
+        // invalidates that file's .dd and its compile edge, not all edges.
+        // Map ddi path → dd path for Phase 3 reference.
+        std::map<std::string, std::string> ddi_to_dd;
+        for (auto& ddi : ddi_paths) {
+            auto dd = ddi + ".dd";   // e.g. obj/cli.cppm.ddi.dd
+            ddi_to_dd[ddi] = dd;
+            append(std::format("build {} : cxx_dyndep {}\n", dd, ddi));
+        }
+        append("\n");
 
-        // ── Phase 3: compile edges with dyndep. ─────────────────────────
-        // BMI implicit outputs are still declared statically (we know
-        // them from the plan); the dyndep file adds implicit BMI INPUTS
-        // (the requires) so ninja schedules in the right order.
+        // ── Phase 3: compile edges with per-file dyndep. ────────────────
+        // Each compile edge references its OWN .dd file instead of a global one.
+        // P2: module compile edges get a $bmi_out variable for BMI preservation.
         for (auto& cu : plan.compileUnits) {
             std::string rule = pick_rule(cu.source);
 
@@ -306,10 +336,19 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             }
             out_line += std::format(" : {} {}", rule, escape_ninja_path(cu.source));
             if (rule != "c_object") {
-                // build.ninja.dd is the dyndep file; ninja requires it as an
-                // implicit input (so it's built before the compile runs).
-                out_line += " | build.ninja.dd";
-                out_line += "\n  dyndep = build.ninja.dd\n";
+                auto ddi = (cu.object.parent_path() / cu.source.filename()).string() + ".ddi";
+                auto it = ddi_to_dd.find(ddi);
+                if (it != ddi_to_dd.end()) {
+                    out_line += " | " + it->second;
+                    out_line += "\n  dyndep = " + it->second;
+                    // P2: set bmi_out for the copy_if_different logic in cxx_module.
+                    if (cu.providesModule) {
+                        out_line += "\n  bmi_out = " + bmi_path(*cu.providesModule);
+                    }
+                    out_line += "\n";
+                } else {
+                    out_line += "\n";
+                }
             } else {
                 out_line += "\n";
             }
@@ -446,6 +485,10 @@ std::expected<BuildResult, BuildError> NinjaBackend::build(const BuildPlan& plan
     std::string ninjaProgram =
         !ninjaBin.empty() ? std::format("'{}'", ninjaBin.string()) : std::string{"ninja"};
 
+    // Record ninja binary for P0 fast-path cache.
+    BuildResult r;
+    r.ninjaProgram = ninjaProgram;
+
     std::string cmd = std::format("{} -C '{}'", ninjaProgram, plan.outputDir.string());
     if (opts.verbose)
         cmd += " -v";
@@ -459,7 +502,6 @@ std::expected<BuildResult, BuildError> NinjaBackend::build(const BuildPlan& plan
         std::fputs(out.c_str(), stdout);
     }
 
-    BuildResult r;
     r.exitCode = ok ? 0 : 1;
     r.elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
         std::chrono::steady_clock::now() - t0);