refactor(build): architecture-review pass — rsp path portability, one directive-fold owner, type/rule unification

Consolidated fixes from the three-lens pre-PR review (correctness /
cross-platform / architecture):

- #247 P0: escape_ninja_path emits generic (forward-slash) node names.
  rspfile_content copies node names verbatim into a response file that
  gcc/clang/GNU ar tokenize GNU-style, where backslash is an ESCAPE —
  obj\cli.o would arrive as objcli.o and break every Windows
  driver-style link. All Windows consumers accept forward slashes;
  POSIX output is byte-identical.
- link/archive/shared rules: ONE link_rule emitter for both dialect
  branches (useRsp = separateLinker || is_windows); msvc rule text
  byte-identical to the previous hand-written stanzas.
- prepare.cppm: markDirectiveTail/foldDirectiveTailIntoPrivateBuild —
  a single owner of 'which compile-visible channels a build.mcpp
  directive lands in', shared by the dep loop and the root call site
  (kills the #242 two-derivations shape the parallel tracks had
  reintroduced). Link/source/fingerprint residues stay at the call
  sites where they genuinely differ.
- BuildConfig::includeDirsAfter aligned to filesystem::path (was
  string), deleting per-consumer conversions.
- local_include_flags derives the NASM degradation from cu.source
  itself instead of a third parameter threaded by every caller.
- Windows shell fallback: cd /d (cmd.exe cd does not switch drives).
- docs: source= joins the cache-invalidation list; 0.0.100+ tags on
  the new directives/env rows; NASM -I degradation documented (en+zh).

Author: Sunrisepeak

docs/05-mcpp-toml.md

@@ -149,7 +149,9 @@ macos_deployment_target = "14.0"   # Minimum supported OS version for macOS arti
 
 `include_dirs_after` (#249) lists header directories that are searched **after**
 the toolchain's system directories (emitted as `-idirafter` on GCC/Clang, as
-trailing `/I` under the MSVC dialect, which has no equivalent). Use it instead of
+trailing `/I` under the MSVC dialect, and as plain `-I` for NASM
+assembly units — neither has an equivalent, and neither has a system-header
+chain to protect). Use it instead of
 `include_dirs` when the directory is an extracted source-tarball root that
 contains files whose names collide with standard headers — e.g. ffmpeg's
 top-level `VERSION` file shadows libc++'s `<version>` on case-insensitive macOS

docs/07-build-mcpp.md

@@ -49,9 +49,9 @@ is ignored, so you can freely log diagnostics.
 | `mcpp:link-search=<dir>`           | add a library search dir (`-L`; relative dirs resolve against the project root) |
 | `mcpp:cfg=<name>`                  | define `-D<name>` for both C and C++ |
 | `mcpp:generated=<path>`            | add a generated source (relative to the project root) to the build |
-| `mcpp:source=<path>`               | 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 |
-| `mcpp:include-dir=<dir>`           | 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 |
-| `mcpp:include-dir-after=<dir>`     | like `include-dir`, but searched **after** the system directories (`-idirafter`) — for payload trees that shadow system headers |
+| `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 |
+| `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 |
+| `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 |
 | `mcpp:rerun-if-changed=<path>`     | re-run `build.mcpp` when this file changes |
 | `mcpp:rerun-if-env-changed=<VAR>`  | re-run `build.mcpp` when this env var changes |
 
@@ -111,16 +111,16 @@ The running program receives the build context as `MCPP_*` variables
 | Variable | Typed reader | Value |
 |---|---|---|
 | `MCPP_TARGET` | `mcpp::target()` | resolved canonical triple (the `--target` triple under cross; the host triple natively) |
-| `MCPP_TARGET_OS` | `mcpp::target_os()` | the target's OS segment (`linux`/`macos`/`windows`) — no need to hand-split `MCPP_TARGET` |
-| `MCPP_TARGET_ARCH` | `mcpp::target_arch()` | the target's arch segment (GNU spelling: `x86_64`, `aarch64`, …) |
-| `MCPP_TARGET_ENV` | `mcpp::target_env()` | the target's env segment (`gnu`/`musl`/`msvc`); empty string when the triple has none (macOS) |
+| `MCPP_TARGET_OS` *(0.0.100+)* | `mcpp::target_os()` | the target's OS segment (`linux`/`macos`/`windows`) — no need to hand-split `MCPP_TARGET` |
+| `MCPP_TARGET_ARCH` *(0.0.100+)* | `mcpp::target_arch()` | the target's arch segment (GNU spelling: `x86_64`, `aarch64`, …) |
+| `MCPP_TARGET_ENV` *(0.0.100+)* | `mcpp::target_env()` | the target's env segment (`gnu`/`musl`/`msvc`); empty string when the triple has none (macOS) |
 | `MCPP_HOST` | `mcpp::host()` | the host triple |
 | `MCPP_PROFILE` | `mcpp::profile()` | effective profile name (`dev`/`release`/…) |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | a writable scratch/output dir owned by mcpp |
 | `MCPP_MANIFEST_DIR` | `mcpp::manifest_dir()` | the package root (= CWD) |
 | `MCPP_FEATURE_<NAME>` | `mcpp::has_feature("name")` | set to `1` per active feature (same `<NAME>` sanitization as the `MCPP_FEATURE_` compile macro) |
 | `MCPP_FEATURES` | — | comma-separated active feature list |
-| `MCPP_DEP_<NAME>_DIR` | `mcpp::dep_dir("name")` | the resolved install dir of each declared dependency (canonical **and** namespace-stripped name spellings; same `<NAME>` sanitization as `MCPP_FEATURE_`). Received by dependencies' build.mcpp **and** the root project's (the root runs after dependency resolution) |
+| `MCPP_DEP_<NAME>_DIR` | `mcpp::dep_dir("name")` | the resolved install dir of each declared dependency (canonical **and** namespace-stripped name spellings; same `<NAME>` sanitization as `MCPP_FEATURE_`). Received by dependencies' build.mcpp **and** the root project's (the root runs after dependency resolution, 0.0.100+) |
 
 These values are folded into the re-run key **unconditionally** — changing the
 target, profile, or feature set re-runs the program without any
@@ -147,7 +147,7 @@ directives and re-runs only when something it depends on changed:
 - the toolchain,
 - any file you declared with `rerun-if-changed`,
 - any env var you declared with `rerun-if-env-changed`,
-- (or a `generated` output went missing).
+- (or a `generated` output / `source=` selection went missing).
 
 So **declare your inputs**: if your program reads `config.h` or the `USE_FAST`
 variable, emit `mcpp:rerun-if-changed=config.h` / `mcpp:rerun-if-env-changed=USE_FAST`.

docs/zh/05-mcpp-toml.md

@@ -141,8 +141,8 @@ macos_deployment_target = "14.0"   # macOS 产物的最低支持系统版本(仅
 ```
 
 `include_dirs_after`(#249)列出**排在工具链系统目录之后**搜索的头文件目录
-(GCC/Clang 发射为 `-idirafter`;MSVC 方言无对应能力,退化为排在末尾的
-`/I`)。当目录是解压后的源码 tarball 根目录、且其中的文件名会与标准头冲突时,
+(GCC/Clang 发射为 `-idirafter`;MSVC 方言退化为排在末尾的 `/I`,NASM 汇编
+单元退化为普通 `-I`——两者都没有对应 flag,也都没有需要保护的系统头搜索链)。当目录是解压后的源码 tarball 根目录、且其中的文件名会与标准头冲突时,
 用它代替 `include_dirs` —— 例如 ffmpeg 根目录的 `VERSION` 文件在大小写不敏感
 的 macOS 文件系统上会把 libc++ 的 `<version>` 遮蔽(若该根目录挂在 `-I` 上)。
 使用 `include_dirs_after` 时系统头永远优先,而包自己的真实头文件

docs/zh/07-build-mcpp.md

@@ -46,9 +46,9 @@ mcpp build      # 编译 + 运行 build.mcpp,然后构建工程
 | `mcpp:link-search=<dir>`           | 增加库搜索目录(`-L`;相对路径按工程根目录解析) |
 | `mcpp:cfg=<name>`                  | 为 C 与 C++ 同时定义 `-D<name>` |
 | `mcpp:generated=<path>`            | 把生成的源码(相对工程根目录)加入构建 |
-| `mcpp:source=<path>`               | 把一份**既有**源文件选入构建(绝对路径,或相对包根)。下游效果与 `generated=` 相同;语义区别在于文件是程序*选中*的(tarball payload / vendored 源树)而非程序写出的——例如对大型源码包做 per-target 源选择 |
-| `mcpp:include-dir=<dir>`           | 为本包自身 TU 增加一个**私有** include 目录(`-I`;绝对路径或相对包根,自动规范化)。取代过去 `cxxflag=-I` + `cflag=-I` 的双重裸发 |
-| `mcpp:include-dir-after=<dir>`     | 同 `include-dir`,但排在系统目录**之后**搜索(`-idirafter`)——用于会遮蔽系统头的 payload 源树 |
+| `mcpp:source=<path>` *(0.0.100+)*  | 把一份**既有**源文件选入构建(绝对路径,或相对包根)。下游效果与 `generated=` 相同;语义区别在于文件是程序*选中*的(tarball payload / vendored 源树)而非程序写出的——例如对大型源码包做 per-target 源选择 |
+| `mcpp:include-dir=<dir>` *(0.0.100+)* | 为本包自身 TU 增加一个**私有** include 目录(`-I`;绝对路径或相对包根,自动规范化)。取代过去 `cxxflag=-I` + `cflag=-I` 的双重裸发 |
+| `mcpp:include-dir-after=<dir>` *(0.0.100+)* | 同 `include-dir`,但排在系统目录**之后**搜索(`-idirafter`)——用于会遮蔽系统头的 payload 源树 |
 | `mcpp:rerun-if-changed=<path>`     | 该文件变化时重跑 `build.mcpp` |
 | `mcpp:rerun-if-env-changed=<VAR>`  | 该环境变量变化时重跑 `build.mcpp` |
 
@@ -103,16 +103,16 @@ int main() {
 | 变量 | 类型化读取 | 值 |
 |---|---|---|
 | `MCPP_TARGET` | `mcpp::target()` | 解析后的 canonical 三元组(交叉构建下是 `--target` 三元组,原生构建是宿主) |
-| `MCPP_TARGET_OS` | `mcpp::target_os()` | 目标的 OS 段(`linux`/`macos`/`windows`)——不必再手撕 `MCPP_TARGET` |
-| `MCPP_TARGET_ARCH` | `mcpp::target_arch()` | 目标的 arch 段(GNU 拼写:`x86_64`、`aarch64`…) |
-| `MCPP_TARGET_ENV` | `mcpp::target_env()` | 目标的 env 段(`gnu`/`musl`/`msvc`);三元组无 env 段(macOS)时为空串 |
+| `MCPP_TARGET_OS` *(0.0.100+)* | `mcpp::target_os()` | 目标的 OS 段(`linux`/`macos`/`windows`)——不必再手撕 `MCPP_TARGET` |
+| `MCPP_TARGET_ARCH` *(0.0.100+)* | `mcpp::target_arch()` | 目标的 arch 段(GNU 拼写:`x86_64`、`aarch64`…) |
+| `MCPP_TARGET_ENV` *(0.0.100+)* | `mcpp::target_env()` | 目标的 env 段(`gnu`/`musl`/`msvc`);三元组无 env 段(macOS)时为空串 |
 | `MCPP_HOST` | `mcpp::host()` | 宿主三元组 |
 | `MCPP_PROFILE` | `mcpp::profile()` | 生效 profile 名(`dev`/`release`/…) |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | mcpp 提供的可写输出/暂存目录 |
 | `MCPP_MANIFEST_DIR` | `mcpp::manifest_dir()` | 包根(= CWD) |
 | `MCPP_FEATURE_<NAME>` | `mcpp::has_feature("name")` | 每个活跃 feature 置 `1`(`<NAME>` 消毒规则与 `MCPP_FEATURE_` 编译宏一致) |
 | `MCPP_FEATURES` | — | 活跃 feature 逗号列表 |
-| `MCPP_DEP_<NAME>_DIR` | `mcpp::dep_dir("name")` | 每个已声明依赖解析后的安装目录(canonical 名与去命名空间短名两种拼写都可用;`<NAME>` 消毒规则同 `MCPP_FEATURE_`)。依赖包的 build.mcpp **和**根工程的 build.mcpp 都能拿到(根工程的 build.mcpp 在依赖解析之后运行) |
+| `MCPP_DEP_<NAME>_DIR` | `mcpp::dep_dir("name")` | 每个已声明依赖解析后的安装目录(canonical 名与去命名空间短名两种拼写都可用;`<NAME>` 消毒规则同 `MCPP_FEATURE_`)。依赖包的 build.mcpp **和**根工程的 build.mcpp 都能拿到(根工程的 build.mcpp 在依赖解析之后运行,0.0.100+) |
 
 这些契约值**无条件**折入重跑键——换 target、换 profile、开关 feature 都会触发重跑,
 不需要任何 `rerun-if-env-changed` 声明。
@@ -135,7 +135,7 @@ mcpp **不会**每次构建都重跑 `build.mcpp`。它会缓存程序产出的
 - 工具链,
 - 任何用 `rerun-if-changed` 声明的文件,
 - 任何用 `rerun-if-env-changed` 声明的环境变量,
-- (或某个 `generated` 产物丢失了)。
+- (或某个 `generated` 产物 / `source=` 选中的文件丢失了)。
 
 所以请**声明你的输入**:如果程序读了 `config.h` 或 `USE_FAST` 变量,就分别 emit
 `mcpp:rerun-if-changed=config.h` / `mcpp:rerun-if-env-changed=USE_FAST`。这用一份明确的

src/build/ninja_backend.cppm

@@ -60,7 +60,15 @@ namespace {
 std::string escape_ninja_path(const std::filesystem::path& p) {
     // Ninja escapes: $ → $$, : → $:, space → $ (with leading space).
     // For simplicity we wrap in case-by-case.
-    std::string s = p.string();
+    //
+    // generic_string(): ninja node names must be forward-slash even on
+    // Windows (#247). rspfile_content = $in copies node names verbatim into
+    // a response file that gcc/clang/GNU ar tokenize GNU-style, where
+    // backslash is an ESCAPE character — `obj\cli.o` would arrive as
+    // `objcli.o`. Every Windows consumer of these strings (CreateProcess
+    // path resolution, cl.exe/link.exe, PowerShell Copy-Item, ninja itself)
+    // accepts forward slashes; POSIX output is byte-identical.
+    std::string s = p.generic_string();
     std::string out;
     for (char c : s) {
         if (c == '$')
@@ -87,8 +95,12 @@ std::string escape_flag_path(const std::filesystem::path& p) {
     return out;
 }
 
-std::string local_include_flags(const CompileUnit& cu, bool msvcDialect,
-                                bool nasmUnit) {
+bool is_nasm_source(const std::filesystem::path& src) {
+    return src.extension() == ".asm";
+}
+
+std::string local_include_flags(const CompileUnit& cu, bool msvcDialect) {
+    const bool nasmUnit = is_nasm_source(cu.source);
     std::string flags;
     for (auto const& inc : cu.localIncludeDirs) {
         flags += " -I";
@@ -197,10 +209,6 @@ bool is_gas_source(const std::filesystem::path& src) {
     return ext == ".S" || ext == ".s";
 }
 
-bool is_nasm_source(const std::filesystem::path& src) {
-    return src.extension() == ".asm";
-}
-
 // TUs the P1689 module scan must skip: C-family and assembly units cannot
 // contain `import`/`module` declarations, and feeding them to the scanner
 // would route them through the C++ frontend.
@@ -580,39 +588,25 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     }
 
     // Link/archive/shared: driver-style (g++/clang++ are the linker) vs the
-    // msvc dialect's separate link.exe/lib.exe. The msvc commands go through
-    // response files — object lists exceed cmd.exe's 8191-char limit fast.
-    if (separateLinker) {
-        append("rule cxx_link\n");
-        append("  command = $ld /nologo /OUT:$out @$out.rsp $ldflags $unit_ldflags\n");
-        append("  rspfile = $out.rsp\n");
-        append("  rspfile_content = $in\n");
-        append("  description = LINK $out\n\n");
-
-        append("rule cxx_archive\n");
-        append("  command = $ar /nologo /OUT:$out @$out.rsp\n");
-        append("  rspfile = $out.rsp\n");
-        append("  rspfile_content = $in\n");
-        append("  description = AR $out\n\n");
-
-        append("rule cxx_shared\n");
-        append("  command = $ld /nologo /DLL /OUT:$out /IMPLIB:$out.lib "
-               "@$out.rsp $ldflags $unit_ldflags\n");
-        append("  rspfile = $out.rsp\n");
-        append("  rspfile_content = $in\n");
-        append("  description = SHARED $out\n\n");
-    } else {
-        // Driver-style toolchains (g++/clang++ as the link driver). On
-        // Windows these still spawn through CreateProcess (32 KiB command
-        // line ceiling), and large source packages (ffmpeg/opencv-class)
-        // link thousands of objects — an inlined $in overflows it (#247).
-        // gcc/clang drivers and GNU/llvm ar all accept @rspfile, so route
-        // $in through one there. POSIX keeps the inline form byte-identical:
-        // ARG_MAX is ample and the plain command is easier to reproduce.
-        auto driver_rule = [&](std::string_view name, std::string cmd,
-                               std::string_view desc) {
+    // msvc dialect's separate link.exe/lib.exe. One emitter owns the rule
+    // shape; `useRsp` decides whether $in is inlined or routed through a
+    // response file (`$in → @$out.rsp` — the only `$i…` variable in any
+    // link/archive command; revisit the first-match replace if a dialect
+    // ever grows another).
+    //
+    // rsp is used when the command spawns through CreateProcess (32 KiB
+    // command-line ceiling): always for the separate-linker msvc dialect,
+    // and on Windows for driver-style too (#247 — ffmpeg/opencv-class
+    // packages link thousands of objects; clang/gcc drivers and GNU/llvm ar
+    // all accept @rspfile). POSIX driver-style keeps the inline form
+    // byte-identical: ARG_MAX is ample and the plain command is easier to
+    // reproduce by hand.
+    {
+        const bool useRsp = separateLinker || mcpp::platform::is_windows;
+        auto link_rule = [&](std::string_view name, std::string cmd,
+                             std::string_view desc) {
             append(std::format("rule {}\n", name));
-            if constexpr (mcpp::platform::is_windows) {
+            if (useRsp) {
                 if (auto pos = cmd.find("$in"); pos != std::string::npos)
                     cmd.replace(pos, 3, "@$out.rsp");
                 append(std::format("  command = {}\n", cmd));
@@ -623,12 +617,23 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             }
             append(std::format("  description = {} $out\n\n", desc));
         };
-        driver_rule("cxx_link",
-                    "$cxx $in -o $out $ldflags $unit_ldflags", "LINK");
-        driver_rule("cxx_archive", std::string(dial.archiveCmd), "AR");
-        driver_rule("cxx_shared",
-                    "$cxx -shared $in -o $out $ldflags $soname_flag $unit_ldflags",
-                    "SHARED");
+        if (separateLinker) {
+            link_rule("cxx_link",
+                      "$ld /nologo /OUT:$out $in $ldflags $unit_ldflags",
+                      "LINK");
+            link_rule("cxx_archive", std::string(dial.archiveCmd), "AR");
+            link_rule("cxx_shared",
+                      "$ld /nologo /DLL /OUT:$out /IMPLIB:$out.lib "
+                      "$in $ldflags $unit_ldflags",
+                      "SHARED");
+        } else {
+            link_rule("cxx_link",
+                      "$cxx $in -o $out $ldflags $unit_ldflags", "LINK");
+            link_rule("cxx_archive", std::string(dial.archiveCmd), "AR");
+            link_rule("cxx_shared",
+                      "$cxx -shared $in -o $out $ldflags $soname_flag $unit_ldflags",
+                      "SHARED");
+        }
     }
 
     append("rule runtime_alias\n");
@@ -750,7 +755,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             append(std::format("build {} : cxx_scan {}\n", escape_ninja_path(ddi),
                                escape_ninja_path(cu.source)));
             append(std::format("  compile_target = {}\n", escape_ninja_path(cu.object)));
-            if (auto includes = local_include_flags(cu, msvcDeps, is_nasm_source(cu.source)); !includes.empty())
+            if (auto includes = local_include_flags(cu, msvcDeps); !includes.empty())
                 append(std::format("  local_includes ={}\n", includes));
             if (auto flags = join_flags(cu.packageCxxflags); !flags.empty())
                 append(std::format("  unit_cxxflags ={}\n", flags));
@@ -829,7 +834,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             } else {
                 out_line += "\n";
             }
-            if (auto includes = local_include_flags(cu, msvcDeps, is_nasm_source(cu.source)); !includes.empty())
+            if (auto includes = local_include_flags(cu, msvcDeps); !includes.empty())
                 out_line += "  local_includes =" + includes + "\n";
             if (is_gas_source(cu.source) || is_nasm_source(cu.source)) {
                 if (auto flags = join_flags(asm_unit_flags(cu)); !flags.empty())
@@ -879,7 +884,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             if (!implicit.empty())
                 out_line += " |" + implicit;
             out_line += "\n";
-            if (auto includes = local_include_flags(cu, msvcDeps, is_nasm_source(cu.source)); !includes.empty())
+            if (auto includes = local_include_flags(cu, msvcDeps); !includes.empty())
                 out_line += "  local_includes =" + includes + "\n";
             if (is_gas_source(cu.source) || is_nasm_source(cu.source)) {
                 if (auto flags = join_flags(asm_unit_flags(cu)); !flags.empty())

src/build/plan.cppm

@@ -280,7 +280,7 @@ local_include_dirs_after_for_manifest(const std::filesystem::path& root,
 {
     std::vector<std::filesystem::path> dirs;
     for (auto const& inc : manifest.buildConfig.includeDirsAfter) {
-        for (auto& d : expand_manifest_include_entry(root, std::filesystem::path(inc)))
+        for (auto& d : expand_manifest_include_entry(root, inc))
             dirs.push_back(std::move(d));
     }
     return dirs;