build.ninja 是静态依赖图描述文件，非脚本语言，不支持循环/条件/变量计算；所有规则、目标和依赖在启动时解析为DAG，仅执行拓扑排序与命令。
build.ninja 文件本质是静态的依赖图描述
它不是脚本语言，不支持循环、条件判断或变量计算；所有规则、构建目标和依赖关系在 Ninja 启动时就被一次性解析成 DAG（有向无环图），之后只做拓扑排序和命令执行。这意味着：build.ninja 里写的每一条 build 语句，都对应一个明确的输出文件及其输入、所用规则。
- 修改
build.ninja后必须重新生成（比如通过 CMake 或 Meson 输出），Ninja 自己不会“重写自己” - 没有
include机制，但可通过subninja引入其他.ninja文件——注意路径是相对于当前文件，不是工作目录 - 变量名（如
cc）只在声明作用域内有效，且不能覆盖内置变量（如rspfile、depfile）
rule 和 build 的参数决定编译行为是否正确
rule 定义命令模板，build 实例化具体构建动作。常见错误是把需要 shell 展开的逻辑（如 $(CC) -o $out $in）误写成字面量，或漏掉关键 flag。
-
command中的$in和$out是 Ninja 内置变量，自动展开为输入/输出文件列表；但$in_newline、$out_newline才真正按行分割，用于避免 shell 参数过长 - 若编译器需响应文件（如 MSVC 的
@response.rsp），必须配rspfile和rspfile_content，否则命令行截断导致静默失败 - 增量编译依赖
depfile（通常是.d文件），它必须由编译器生成（如gcc -MMD -MF $out.d），且depfile值要和实际生成路径一致，否则 Ninja 不知道头文件变更
示例片段：
rule cxx command = $cxx -MMD -MF $out.d -c $in -o $out depfile = $out.d description = CXX $out build obj/main.o: cxx src/main.cpp
Windows 上路径分隔符和换行符容易引发 silent failure
Ninja 在 Windows 下默认使用 作路径分隔符，但 build.ninja 文件本身必须用 Unix 风格换行（LF），哪怕你在 Windows 上编辑。CR+LF 会导致解析失败，且 Ninja 很少报错，只是跳过某条 build 规则。
立即学习“C++免费学习笔记（深入）”；
- 所有路径（
build行中的src/main.cpp、rule中的command）推荐统一用/，Ninja 会自动转换，避免\转义混乱 - 如果用 PowerShell 或批处理生成
build.ninja，务必确认输出编码为 UTF-8 without BOM，且换行是 LF -
pool限制并发数时（如consolepool），Windows 控制台输出可能乱序，但这不影响构建正确性，只是日志难读
C++ 项目中 build.ninja 通常不手写，而是由高层工具生成
直接手写 build.ninja 维护成本极高：C++ 头文件依赖、宏定义传递、多配置（Debug/Release）、链接顺序、导出符号等都难以手工建模。真实项目几乎全靠 CMake（-G Ninja）、Meson 或 Buck 输出。
- CMake 生成的
build.ninja里大量使用subninja和自定义rule，比如__CMAKE_开头的 rule，不要手动修改它们 - 想调试 Ninja 行为？用
ninja -t graph | dot -Tpng > graph.png看依赖图，比读文本快得多 - 修改构建逻辑时，优先改 CMakeLists.txt 或 meson.build，而不是反向 patch
build.ninja——后者下次 regen 就被覆盖
真正需要懂 build.ninja 语法的地方，是写自定义构建规则（比如打包资源、生成 IDL 代码），或排查 Ninja 报错时看懂它提示的哪一行、哪个变量没定义。
