1. 为什么我建议你认真了解Ninja这个构建系统如果你编译过一个上千源文件的C项目很可能经历过这样的场景在执行make -j8之后终端里飞驰过无数条编译命令但只要改动一个头文件整个工程就像失忆一样把一半的文件重新编译一遍。最开始我会以为这是Make的正常表现后来才发现真正的问题出在依赖跟踪和构建调度的粒度上。后来我把项目切到Ninja同样的增量改动重建时间从几十秒降到几秒。Ninja不是一个更好用的Make而是一个完全从构建速度这个目标倒推出来的低层构建系统。Ninja的定位简单说就是执行速度快到几乎感知不到的构建工具。它不提供复杂的宏语言没有Make那么丰富的函数和隐式规则也不打算让你直接拿它编写大型项目的完整构建逻辑。它的构建文件通常由CMake、Meson、GN这样的元构建系统生成。你可以把它理解为构建界的汇编语言上层的高级语言负责生成最优化、最直白的指令Ninja负责把这些指令以极快的速度执行完。Google的Chromium项目是这个系统最早的深度用户也正是因为需要在几十个模块、数万个源文件的规模下保持可接受的构建速度Ninja才被设计和开源出来。什么人适合马上接触Ninja第一类是使用CMake或Meson的开发者你只需要加一个-G Ninja参数就能在大多数场景下体验到构建速度的提升。第二类是受够了Makefile隐式规则玄学的人Ninja的构建文件非常直白每个命令、每条依赖都摆在明面上。第三类是对构建原理感兴趣的人Ninja的增量判断逻辑和调度方式可以当成一个非常好的学习范本。即使你不是专业做构建基础设施的花半天时间把Ninja跑通后面能省下的时间绝对值得。需要说明的是我在这篇文章里会把Ninja当作一个独立的构建系统来讲不假设你已经用过它。我会从设计思路、构建文件语法、与CMake等工具的配合、增量构建原理、性能调优与踩坑经验这几个角度把我在实际项目里用出来的心得都写出来。Ninja的官方文档很精炼但很多为什么和实际项目中怎么办不是文档里能查到的这些才是本文的重点。2. 设计哲学Ninja为何刻意做得比Make 笨2.1 从Makefile的复杂说起想理解Ninja先理解它讨厌什么。GNU Make发展了几十年语法已经非常丰富变量、函数、模式规则、隐式规则、VPATH、include、条件判断甚至还能定义自己的函数。丰富的语法让Makefile几乎成为一种编程语言但这是有代价的。Make在执行前必须先读取整个Makefile展开所有变量和规则分析隐式规则链才能确定哪些目标需要重建。在小型项目里这个解析时间忽略不计但在几万条规则的项目里解析和评估本身就可能花上好几秒而且增量构建时还得重复这个过程。更麻烦的是Make的隐式规则经常让开发者意外你觉得某个文件应该被重建但它没有或者反过来一个无关的变量赋值让所有规则都重新触发。Ninja从根上就不打算做这些事。它的作者Evan Martin在开发Chromium构建系统时发现底层构建工具最需要的不是功能强大而是调度快速、执行准确。于是Ninja被设计成只包含最小的功能集rule定义命令build声明输出和输入再加上变量和几个特殊字段仅此而已。没有函数没有模式规则没有自动推导。所有的复杂计算都放到上层生成器里完成Ninja只负责把生成器告诉它的依赖关系和时间戳信息高效地组织起来。2.2 Ninja构建文件的最小骨架Ninja的构建文件默认叫build.ninja也支持通过-f指定其他文件。它的基础结构如下rule cc command gcc -c $in -o $out description CC $out build hello.o: cc hello.c build app: cc hello.o default app这个例子里rule cc定义了一条编译规则command是实际执行的命令行$in和$out分别代表输入文件和输出文件。build hello.o: cc hello.c声明了一个构建目标hello.o由规则cc作用于输入hello.c生成。build app: cc hello.o同理虽然规则名也叫cc但这里我们是用gcc直接链接只是为了演示规则可以复用。default app指定了如果不带参数执行ninja时默认构建的目标。看起来跟Makefile很像对吗但注意没有clean、install这样的内建目标没有变量自动展开的隐式规则。你可以定义自己的变量比如cflags -Wall然后在command里用$cflags引用。你必须把每一条依赖关系都显式写出来Ninja不会因为你有一个hello.c就自动推导出hello.o。这看起来是退化却是Ninja能够快速判断哪些目标需要重建的关键依赖图是静态的、扁平的加载后直接变成内存里的哈希表和邻接表不需要任何动态计算。2.3 为什么这种笨反而更快官方有个很形象的描述Ninja的目标是让增量构建的速度接近于只运行必要编译命令的时间。它做了三件非常务实的事情构建文件解析极快。文件结构简单没有需要解释执行的函数读进来就能构建图。依赖判断极简。对每个输出记录其输入的时间戳当输入比输出新就重建。由于不依赖隐式规则它能精确知道哪些文件需要重编。并行调度高效。Ninja内部用拓扑排序和就绪队列调度任务在-j指定的并发数内能最快开始运行可并行的任务。所以在同等条件下使用同样的编译命令Make可能需要几百毫秒来做判断要构建什么Ninja可能只需要几毫秒。全量构建时两者的编译时间本身差不多但在一次次小改动触发增量构建时Ninja的优势会积累得非常可观。另外因为规则都是显式的Ninja不会出现Make那种多执行了某个模式规则或者漏掉某个隐式依赖的问题——前提是上层生成器生成的依赖足够准确。3. 手写一个真实可用的Ninja构建文件3.1 带头文件依赖的完整示例只看最小骨架是跑不起来实际项目的因为C/C项目最大的麻烦在于头文件依赖。Ninja本身不会去扫描#include它必须依赖外部机制来了解头文件的变化。最常见的做法是让编译器输出依赖文件再通过depfile字段把这些依赖纳入构建图。假设有这样一个项目结构. ├── include/ │ └── util.h ├── src/ │ ├── main.c │ └── util.c └── build.ninjabuild.ninja可以这么写ninja_required_version 1.10 cflags -Wall -Iinclude rule cc command gcc $cflags -MMD -MF $out.d -c $in -o $out depfile $out.d deps gcc description CC $out rule link command gcc $in -o $out description LINK $out build src/main.o: cc src/main.c build src/util.o: cc src/util.c build app: link src/main.o src/util.o default app这里的关键是gcc -MMD -MF $out.d让编译器在编译时额外生成一个$out.d文件里面记录了这个.o文件所包含的头文件依赖。depfile $out.d告诉Ninja去读取这个文件把其中的头文件也加入依赖图。deps gcc是让Ninja用专用的解析器读取GCC格式的依赖文件这样读取速度更快而且不需要保留.d文件其实默认会把依赖信息存到.ninja_deps文件里。如果你用的是Clang同样可以这样处理。执行ninja第一次会编译两个源文件并链接成app。接着修改include/util.h再执行ninja你会发现只有包含了这个头文件的util.o和app会被重新构建main.o如果确实没有包含util.h就不会动。这比Makefile里常见的把所有头文件一股脑全列进变量要精确得多。3.2 构建文件里的变量作用域与常见写法Ninja的变量作用域和Make有类似之处但更严格。变量可以在文件顶部定义也可以在rule或build块内定义。rule里的变量相当于作用于该规则的所有实例而build块里定义的变量只对这条构建语句有效。变量的求值时机也很重要不同变量类型有不同的展开规则初学者最容易踩的坑是在rule里使用$in、$out、$depfile这几个特殊变量时必须放在command中才能正确展开。比如下面这种写法是合法的rule compile command $compiler -I$incdir -c $in -o $out description COMPILE $out compiler gcc incdir include build foo.o: compile foo.c如果$compiler在rule定义之后才赋值会影响command吗会。因为rule块内的变量都是延迟求值的只有到真正执行那条build时才展开。这个特性可以让你在文件末尾改变变量从而影响前面定义的规则。但要小心别为了炫技写出难以阅读的构建文件。我个人的习惯是所有基础变量放在文件顶部规则定义放在中间具体的build语句放在后面保持从上到下的阅读顺序。3.3 使用phony和default管理目标大型项目会有很多中间产物需要给它们起一些别名方便记忆phony就是这个用途。例如build tests: phony unit_tests integration_tests build all: phony app tests这里tests和all本身不产生文件只是依赖其他目标。执行ninja all就相当于说把所有东西都构建出来。不过phony虽然好用过度使用会让依赖图变得混乱。如果某个phony目标既被用作真实文件的输入又出现在依赖链里Ninja会按别名处理容易导致时间戳判断失效。建议只把phony用在明确的聚合目标上不要让它参与真正编译命令的输入。另外default语句如果存在那么不带参数执行ninja时会构建它指定的目标如果没有default默认就是构建文件里出现的所有目标。大多数由CMake生成的build.ninja会把all或实际目标设为默认这样ninja命令最省心。4. 与CMake/Meson配合一句话让整个项目提速4.1 CMake生成Ninja构建系统的用法对绝大多数项目来说手动维护build.ninja并不是好主意尤其是当项目规模变大你还需要处理平台差异、编译选项、条件编译、安装规则时。正确姿势是让CMake这类元构建系统去生成build.ninja。你只需要在配置阶段指定生成器cmake -S . -B build -G Ninja cmake --build build-G Ninja告诉CMake使用Ninja作为底层构建工具。CMake会自动生成内容庞杂的build.ninja里面包含所有编译规则、链接规则、依赖信息、自定义命令、生成文件规则等。你基本不需要去看它直接用cmake --build build即可也可以用cmake --build build -- -j16给Ninja传递并行参数。一个常见的误区是认为CMake Ninja只能用于C/C。实际上CMake在较新版本里也支持Fortran、CUDA、Swift等语言只要底层有对应编译器Ninja作为执行后端都是适用的。如果你的项目已经在用CMake从默认生成的Makefile切到Ninja几乎不需要改动CMakeLists.txt只需要在配置时多传一个-G参数风险非常低。4.2 Meson、GN等工具为何默认选择NinjaMeson这个构建系统从设计之初就把Ninja作为默认后端它的理念是让开发者用更高级、更可读的DSL描述构建而把底层执行细节交给Ninja。Meson的目标之一就是让构建系统用起来现代、快速且友好它选择的底层就是Ninja因为它不需要重新发明一套执行调度机制只要专注做好依赖分析和规则生成。GNGenerate Ninja则是Chromium团队专门设计的元构建系统主要用来生成Ninja文件。Chromium级别的项目有非常复杂的依赖关系、大量的平台配置和组件化需求GN生成的build.ninja精确到每个源文件的依赖配合Ninja的执行速度才能在合理的硬件上完成大规模开发循环。如果你不参与Chromium开发大概率不会直接接触到GN但了解这个背景能帮助你理解Ninja在Google内部乃至整个C/C生态中的位置。4.3 用好ninja -t compdb导出compile_commands.json对接编辑器是实际开发中的高频需求尤其是clangd、ccls这类基于编译数据库的C/C语言服务器。使用Makefile时要么手动配置CMake导出compile_commands.json要么靠bear等工具生成。切换到Ninja后一切都更简单执行ninja -C build -t compdb cxx cc compile_commands.json-t compdb命令会读取build.ninja里所有编译规则输出一个标准的JSON数组每条记录包含当前目录、编译命令和源文件路径。你可以把它保存为compile_commands.json然后让clangd打开项目时自动索引。这个文件对于代码跳转、自动补全、静态检查都至关重要。我遇到过不少同事项目还在用Makefile时为了生成compile_commands.json折腾半天切到Ninja后这个问题就消失了。因为CMake只要指定Ninja生成器在配置阶段就能直接输出compile_commands.json前提是开启CMAKE_EXPORT_COMPILE_COMMANDS。5. 增量构建原理与五种最实用的诊断命令5.1 时间戳逻辑与restat机制Ninja判断一个目标是否需要重建的逻辑非常直白如果存在输出文件且其时间戳比所有输入文件都新就认为目标是最新的否则就执行规则重建它。这个逻辑和Make基本一致但有个额外机制容易忽略restat。当一条命令执行后如果它的输出时间戳其实没有变化Ninja可以通过restat属性得知并向上更新状态避免传播无谓的重建。典型场景是脚本生成文件某个脚本每次运行都会更新生成文件的访问时间但文件内容可能没变。如果不用restat所有依赖这个生成文件的编译任务都会被触发用了restatNinja会在脚本执行完后再检查时间戳发现没有变化就认为该目标实际未更新从而让下游任务保持最新状态。实际项目中CMake生成的某些自定义命令会自动加上restat但手写build.ninja时如果碰到文件没变但每次都要重编下游的现象可以检查一下是不是缺少restat 1。这个字段虽小却能省下大量不必要的编译。5.2 用-d explain找出为什么又重编Ninja提供了一些调试选项其中-d explain是我最依赖的。当你不确定某个目标为什么总是被重建时运行ninja -d explainNinja会在重建前输出原因例如ninja explain: output build/foo.o older than most recent input build/foo.c ninja explain: output build/foo.o missing这种输出能立刻暴露问题所在可能是某个生成文件的时间戳总在变也可能是你的build.ninja里依赖写得不全。遇到全量重编的诡异现象先跑一遍-d explain大多数情况能定位到是哪个输入文件一直在变新。5.3ninja -t子命令实战-t是Ninja自带的诊断工具入口下面这些命令我几乎每天都会用ninja -t query target查看某个目标的具体依赖关系包括输入、输出、使用的规则适合快速确认依赖图是否符合预期。ninja -t targets列出构建文件里的所有目标后面加规则名可以过滤出使用该规则的目标。ninja -t commands target打印构建目标时会执行哪些命令不实际执行。切换构建系统后可以用它来确认最终编译命令是否包含了正确的宏定义和头文件路径。ninja -t graph target输出Graphviz格式的依赖图可以结合dot渲染成图片。当依赖关系复杂到肉眼无法追踪时这是最直观的排查方式。ninja -t deps target查看目标已记录的依赖文件列表确认depfile是否正确加载了头文件依赖。ninja -t clean target清理目标相关的输出。比手动删除文件靠谱。其中compdb在上一节已经提过。这些子命令都没有写进Ninja的默认帮助里但对排查构建问题价值极大。我之前遇到过一个问题某个头文件被修改后只有一半的源文件被重编另一半没有。看代码觉得所有文件都#include了它但实际重编了一半找不出原因。后来用ninja -t deps一查才发现没有重编的那些.o文件的依赖列表里根本没有那个头文件——因为它们在代码里用的是相对路径而编译器的-MMD输出和实际文件名大小写不一致导致依赖匹配失败。这种问题如果靠肉眼从构建日志里找会浪费很多时间。6. 性能调优与真实踩坑把Ninja用到极致6.1 并行度、状态输出和任务池Ninja默认会检测CPU核心数并设置一个适合并行编译的-j值但在实际项目中盲目拉满并行度并不总是最优。-j太大时大量编译进程同时跑起来可能耗尽内存或I/O带宽反而让总时间变长。如果发现编译时卡顿明显可以先用-j减半试一下。对于链接这类内存大户Ninja提供了pool机制来限制并发pool link_pool depth 1 rule link command g -o $out $in pool link_pool这样即使全局-j16同一时刻也只允许一条链接任务运行避免内存被多个链接进程打爆。在大型C项目里这个设置经常能避免链接阶段的内存抖动。另一个提升体验的小技巧是设置NINJA_STATUS环境变量让Ninja在执行过程中显示当前进度。例如export NINJA_STATUS[%f/%t %p] ninja%f表示已完成任务数%t表示总任务数%p是已完成百分比。相比默认输出这种进度显示从让人焦虑变成让人安心。它在CI日志里也很有用可以直观看到构建是否卡住。6.2 搭配ccache/distcc混合构建Ninja只负责调度不关心你实际运行的是什么编译器所以它可以轻松地和各种编译加速工具组合。最常见的组合是ccache# 在rule里把编译器包装成ccache rule cc command ccache gcc $cflags -MMD -MF $out.d -c $in -o $out也可以利用CCACHE_PREFIX、CCACHE_BASEDIR等环境变量控制缓存行为。使用CMake时可以通过CMAKE_CXX_COMPILER_LAUNCHERccache来设置让生成的构建命令自动带上ccache前缀无需手改规则。Ninja增量判断和ccache命中判断是两层Ninja发现输入时间戳变了会重新运行命令但命令落到ccache时可能直接命中缓存而秒回。这样即使某种原因导致依赖重编只要源文件内容没变编译过程仍然很快。如果你的团队有共享缓存服务也可以把ccache配置成分布式缓存效果更明显。distcc之类的分布式编译相对复杂但原理上一样只要命令能被包装Ninja就只是傻傻地执行它。需要注意的是分布式编译对增量依赖判断要求更高因为每台机器的头文件路径可能不同-MMD生成的依赖文件也会包含路径信息。在使用前一定要确认所有机器环境一致否则容易出现这边编译成功、那边编译失败的诡异问题。6.3 迁移到Ninja时最容易踩的五个坑从Makefile迁移或初次使用Ninja时有几个坑几乎是人人都会遇到的在这里集中说一下。第一个坑是忘记写depfile。手写build.ninja时如果只写了简单的command gcc -c $in -o $out没有-MMD -MF那么Ninja只追踪由build语句显式列出的输入文件头文件变化完全不会触发重建。这会导致改了头文件程序还是旧的的诡异现象。解决办法是接好depfile机制并且把依赖文件纳入版本控制之外因为它们是构建的临时产物。第二个坑是把输出文件放在源目录里。Ninja的增量判断完全基于文件路径和时间戳如果输出和输入混在一起清理起来会很麻烦还容易误删源码。建议所有输出都放到独立的构建目录CMake里的CMAKE_BINARY_DIR就是这个作用。也不要让某个build语句的输出路径和另一个build语句的输入路径存在大小写不一致的情况在Linux上没问题但在macOS的大小写不敏感文件系统上时间戳对比可能被干扰。第三个坑是盲目迁移所有自定义命令。Makefile里可以用$(shell ...)在解析阶段执行命令Ninja不允许。如果你原本的Makefile逻辑严重依赖shell函数、条件判断和宏直接手写等价build.ninja会非常痛苦。这个时候更好的做法是先迁移到CMake或Meson再让它们生成Ninja文件而不是尝试在Ninja里复刻Make的复杂逻辑。第四个坑是并行编译遇到命令名冲突。比如你在rule里写了cd subdir make这是把Make当作子进程调用如果subdir里的构建依赖没有正确记录在父级build.ninja中Ninja无法调度子Make内部的任务并行可能造成竞争。正确的做法是尽量不用嵌套构建工具所有编译动作都应该由Ninja直接调度。如果一定要调用外部脚本务必让脚本自身保证幂等和线程安全。第五个坑是忽视ninja -d explain的作用。遇到任何不该重编却重编的问题先别乱改代码先加-d explain看原因。很多时候是因为某个生成文件每次都被命令touch了或者依赖路径里包含了不稳定的时间戳文件。搞清楚原因再动手能省下大量排错时间。6.4 一个真实的迁移收益记录我用一个实际的例子来说明收益。一个中等规模的C项目约800个源文件使用CMake构建。原来用make -j8做增量构建改动一个核心头文件后通常需要重新编译200多个源文件并链接整个过程约1分20秒。后来只把生成器换成-G Ninja同样的改动场景编译耗时降到50秒左右。看起来差别不算巨大但改动一个.cpp文件时原Makefile可能因为某条隐式规则触发导致几十个文件重编Ninja在信息完备时只重编这一个文件和相应的链接步骤耗时不到20秒。为什么同样用CMake一个用Makefile后端一个用Ninja后端会有这个差别因为CMake为Makefile后端生成的规则和依赖追踪方式不如为Ninja后端生成的那么精确。CMake在Makefile后端里使用了make的$(MAKE)递归或某些批量规则而Ninja后端从最开始就为Ninja设计了一套干净、细粒度的构建图。当然首次全量构建时Ninja并不会比Make快很多因为瓶颈在编译器本身。但开发过程中迭代最频繁的其实是增量构建。一天下来几十次增量构建节省的时间累积起来非常可观。这也是我建议每个使用CMake/Meson的团队都尝试Ninja的原因。7. 什么时候不要用Ninja以及我的最后几条建议Ninja不是万金油。对于非常小的项目比如一个只有两三个源文件的课程作业或临时脚本直接一条gcc命令或者一个简单的Makefile反而更直观。Ninja的最小构建文件虽然简单但为了头文件依赖还得配depfile这个复杂度对小项目来说是多余的。另外如果你的项目严重依赖Make的隐式规则、多级条件分支、各种shell函数展开而且你暂时没有计划迁移到CMake/Meson那么不要硬改Ninja。强行用Ninja复刻Make的高级功能只会得到一份难维护的build.ninja。如果你决定上手我的建议路径是先用CMake的-G Ninja把它跑起来不要一开始就手写build.ninja。等到你确实需要定制一些CMake不好表达的规则时再去研究Ninja的rule、pool和restat。手写build.ninja的场景通常是嵌入式、特殊代码生成器或者自定义脚本链这时保持简单最重要规则尽量少变量尽量少每个build的输入输出都显式写出别让Ninja做任何“猜测”。最后分享一个我自己的小习惯在项目根目录放一个Makefile里面只写一行all: cmake -S . -B build -G Ninja cmake --build build这样既保留了大家熟悉的make入口又让真正的构建落到Ninja上。等团队成员慢慢体会到增量构建的速度差异后很多人会自动把ninja命令变成肌肉记忆。构建系统这件事工具本身重要但真正决定效率的是你愿不愿意花点时间理解背后的调度逻辑。Ninja的设计者把“快”做成了唯一目标而我们要做的就是把这个目标用在自己的项目里。 1. 为什么我建议你认真了解Ninja这个构建系统如果你编译过一个上千源文件的C项目很可能经历过这样的场景在执行make -j8之后终端里飞驰过无数条编译命令但只要改动一个头文件整个工程就像失忆一样把一半的文件重新编译一遍。最开始我会以为这是Make的正常表现后来才发现真正的问题出在依赖跟踪和构建调度的粒度上。后来我把项目切到Ninja同样的增量改动重建时间从几十秒降到几秒。Ninja不是一个更好用的Make而是一个完全从构建速度这个目标倒推出来的低层构建系统。Ninja的定位简单说就是执行速度快到几乎感知不到的构建工具。它不提供复杂的宏语言没有Make那么丰富的函数和隐式规则也不打算让你直接拿它编写大型项目的完整构建逻辑。它的构建文件通常由CMake、Meson、GN这样的元构建系统生成。你可以把它理解为构建界的汇编语言上层的高级语言负责生成最优化、最直白的指令Ninja负责把这些指令以极快的速度执行完。Google的Chromium项目是这个系统最早的深度用户也正是因为需要在几十个模块、数万个源文件的规模下保持可接受的构建速度Ninja才被设计和开源出来。什么人适合马上接触Ninja第一类是使用CMake或Meson的开发者你只需要加一个-G Ninja参数就能在大多数场景下体验到构建速度的提升。第二类是受够了Makefile隐式规则玄学的人Ninja的构建文件非常直白每个命令、每条依赖都摆在明面上。第三类是对构建原理感兴趣的人Ninja的增量判断逻辑和调度方式可以当成一个非常好的学习范本。即使你不是专业做构建基础设施的花半天时间把Ninja跑通后面能省下的时间绝对值得。需要说明的是我在这篇文章里会把Ninja当作一个独立的构建系统来讲不假设你已经用过它。我会从设计思路、构建文件语法、与CMake等工具的配合、增量构建原理、性能调优与踩坑经验这几个角度把我在实际项目里用出来的心得都写出来。Ninja的官方文档很精炼但很多为什么和实际项目中怎么办不是文档里能查到的这些才是本文的重点。2. 设计哲学Ninja为何刻意做得比Make 笨2.1 从Makefile的复杂说起想理解Ninja先理解它讨厌什么。GNU Make发展了几十年语法已经非常丰富变量、函数、模式规则、隐式规则、VPATH、include、条件判断甚至还能定义自己的函数。丰富的语法让Makefile几乎成为一种编程语言但这是有代价的。Make在执行前必须先读取整个Makefile展开所有变量和规则分析隐式规则链才能确定哪些目标需要重建。在小型项目里这个解析时间忽略不计但在几万条规则的项目里解析和评估本身就可能花上好几秒而且增量构建时还得重复这个过程。更麻烦的是Make的隐式规则经常让开发者意外你觉得某个文件应该被重建但它没有或者反过来一个无关的变量赋值让所有规则都重新触发。Ninja从根上就不打算做这些事。它的作者Evan Martin在开发Chromium构建系统时发现底层构建工具最需要的不是功能强大而是调度快速、执行准确。于是Ninja被设计成只包含最小的功能集rule定义命令build声明输出和输入再加上变量和几个特殊字段仅此而已。没有函数没有模式规则没有自动推导。所有的复杂计算都放到上层生成器里完成Ninja只负责把生成器告诉它的依赖关系和时间戳信息高效地组织起来。2.2 Ninja构建文件的最小骨架Ninja的构建文件默认叫build.ninja也支持通过-f指定其他文件。它的基础结构如下rule cc command gcc -c $in -o $out description CC $out build hello.o: cc hello.c build app: cc hello.o default app这个例子里rule cc定义了一条编译规则command是实际执行的命令行$in和$out分别代表输入文件和输出文件。build hello.o: cc hello.c声明了一个构建目标hello.o由规则cc作用于输入hello.c生成。build app: cc hello.o同理虽然规则名也叫cc但这里我们是用gcc直接链接只是为了演示规则可以复用。default app指定了如果不带参数执行ninja时默认构建的目标。看起来跟Makefile很像对吗但注意没有clean、install这样的内建目标没有变量自动展开的隐式规则。你可以定义自己的变量比如cflags -Wall然后在command里用$cflags引用。你必须把每一条依赖关系都显式写出来Ninja不会因为你有一个hello.c就自动推导出hello.o。这看起来是退化却是Ninja能够快速判断哪些目标需要重建的关键依赖图是静态的、扁平的加载后直接变成内存里的哈希表和邻接表不需要任何动态计算。2.3 为什么这种笨反而更快官方有个很形象的描述Ninja的目标是让增量构建的速度接近于只运行必要编译命令的时间。它做了三件非常务实的事情构建文件解析极快。文件结构简单没有需要解释执行的函数读进来就能构建图。依赖判断极简。对每个输出记录其输入的时间戳当输入比输出新就重建。由于不依赖隐式规则它能精确知道哪些文件需要重编。并行调度高效。Ninja内部用拓扑排序和就绪队列调度任务在-j指定的并发数内能最快开始运行可并行的任务。所以在同等条件下使用同样的编译命令Make可能需要几百毫秒来做判断要构建什么Ninja可能只需要几毫秒。全量构建时两者的编译时间本身差不多但在一次次小改动触发增量构建时Ninja的优势会积累得非常可观。另外因为规则都是显式的Ninja不会出现Make那种多执行了某个模式规则或者漏掉某个隐式依赖的问题——前提是上层生成器生成的依赖足够准确。3. 手写一个真实可用的Ninja构建文件3.1 带头文件依赖的完整示例只看最小骨架是跑不起来实际项目的因为C/C项目最大的麻烦在于头文件依赖。Ninja本身不会去扫描#include它必须依赖外部机制来了解头文件的变化。最常见的做法是让编译器输出依赖文件再通过depfile字段把这些依赖纳入构建图。假设有这样一个项目结构. ├── include/ │ └── util.h ├── src/ │ ├── main.c │ └── util.c └── build.ninjabuild.ninja可以这么写ninja_required_version 1.10 cflags -Wall -Iinclude rule cc command gcc $cflags -MMD -MF $out.d -c $in -o $out depfile $out.d deps gcc description CC $out rule link command gcc $in -o $out description LINK $out build src/main.o: cc src/main.c build src/util.o: cc src/util.c build app: link src/main.o src/util.o default app这里的关键是gcc -MMD -MF $out.d让编译器在编译时额外生成一个$out.d文件里面记录了这个.o文件所包含的头文件依赖。depfile $out.d告诉Ninja去读取这个文件把其中的头文件也加入依赖图。deps gcc是让Ninja用专用的解析器读取GCC格式的依赖文件这样读取速度更快而且不需要保留.d文件其实默认会把依赖信息存到.ninja_deps文件里。如果你用的是Clang同样可以这样处理。执行ninja第一次会编译两个源文件并链接成app。接着修改include/util.h再执行ninja你会发现只有包含了这个头文件的util.o和app会被重新构建main.o如果确实没有包含util.h就不会动。这比Makefile里常见的把所有头文件一股脑全列进变量要精确得多。3.2 构建文件里的变量作用域与常见写法Ninja的变量作用域和Make有类似之处但更严格。变量可以在文件顶部定义也可以在rule或build块内定义。rule里的变量相当于作用于该规则的所有实例而build块里定义的变量只对这条构建语句有效。变量的求值时机也很重要不同变量类型有不同的展开规则初学者最容易踩的坑是在rule里使用$in、$out、$depfile这几个特殊变量时必须放在command中才能正确展开。比如下面这种写法是合法的rule compile command $compiler -I$incdir -c $in -o $out description COMPILE $out compiler gcc incdir include build foo.o: compile foo.c如果$compiler在rule定义之后才赋值会影响command吗会。因为rule块内的变量都是延迟求值的只有到真正执行那条build时才展开。这个特性可以让你在文件末尾改变变量从而影响前面定义的规则。但要小心别为了炫技写出难以阅读的构建文件。我个人的习惯是所有基础变量放在文件顶部规则定义放在中间具体的build语句放在后面保持从上到下的阅读顺序。3.3 使用phony和default管理目标大型项目会有很多中间产物需要给它们起一些别名方便记忆phony就是这个用途。例如build tests: phony unit_tests integration_tests build all: phony app tests这里tests和all本身不产生文件只是依赖其他目标。执行ninja all就相当于说把所有东西都构建出来。不过phony虽然好用过度使用会让依赖图变得混乱。如果某个phony目标既被用作真实文件的输入又出现在依赖链里Ninja会按别名处理容易导致时间戳判断失效。建议只把phony用在明确的聚合目标上不要让它参与真正编译命令的输入。另外default语句如果存在那么不带参数执行ninja时会构建它指定的目标如果没有default默认就是构建文件里出现的所有目标。大多数由CMake生成的build.ninja会把all或实际目标设为默认这样ninja命令最省心。4. 与CMake/Meson配合一句话让整个项目提速4.1 CMake生成Ninja构建系统的用法对绝大多数项目来说手动维护build.ninja并不是好主意尤其是当项目规模变大你还需要处理平台差异、编译选项、条件编译、安装规则时。正确姿势是让CMake这类元构建系统去生成build.ninja。你只需要在配置阶段指定生成器cmake -S . -B build -G Ninja cmake --build build-G Ninja告诉CMake使用Ninja作为底层构建工具。CMake会自动生成内容庞杂的build.ninja里面包含所有编译规则、链接规则、依赖信息、自定义命令、生成文件规则等。你基本不需要去看它直接用cmake --build build即可也可以用cmake --build build -- -j16给Ninja传递并行参数。一个常见的误区是认为CMake Ninja只能用于C/C。实际上CMake在较新版本里也支持Fortran、CUDA、Swift等语言只要底层有对应编译器Ninja作为执行后端都是适用的。如果你的项目已经在用CMake从默认生成的Makefile切到Ninja几乎不需要改动CMakeLists.txt只需要在配置时多传一个-G参数风险非常低。4.2 Meson、GN等工具为何默认选择NinjaMeson这个构建系统从设计之初就把Ninja作为默认后端它的理念是让开发者用更高级、更可读的DSL描述构建而把底层执行细节交给Ninja。Meson的目标之一就是让构建系统用起来现代、快速且友好它选择的底层就是Ninja因为它不需要重新发明一套执行调度机制只要专注做好依赖分析和规则生成。GNGenerate Ninja则是Chromium团队专门设计的元构建系统主要用来生成Ninja文件。Chromium级别的项目有非常复杂的依赖关系、大量的平台配置和组件化需求GN生成的build.ninja精确到每个源文件的依赖配合Ninja的执行速度才能在合理的硬件上完成大规模开发循环。如果你不参与Chromium开发大概率不会直接接触到GN但了解这个背景能帮助你理解Ninja在Google内部乃至整个C/C生态中的位置。4.3 用好ninja -t compdb导出compile_commands.json对接编辑器是实际开发中的高频需求尤其是clangd、ccls这类基于编译数据库的C/C语言服务器。使用Makefile时要么手动配置CMake导出compile_commands.json要么靠bear等工具生成。切换到Ninja后一切都更简单执行ninja -C build -t compdb cxx cc compile_commands.json-t compdb命令会读取build.ninja里所有编译规则输出一个标准的JSON数组每条记录包含当前目录、编译命令和源文件路径。你可以把它保存为compile_commands.json然后让clangd打开项目时自动索引。这个文件对于代码跳转、自动补全、静态检查都至关重要。我遇到过不少同事项目还在用Makefile时为了生成compile_commands.json折腾半天切到Ninja后这个问题就消失了。因为CMake只要指定Ninja生成器在配置阶段就能直接输出compile_commands.json前提是开启CMAKE_EXPORT_COMPILE_COMMANDS。5. 增量构建原理与五种最实用的诊断命令5.1 时间戳逻辑与restat机制Ninja判断一个目标是否需要重建的逻辑非常直白如果存在输出文件且其时间戳比所有输入文件都新就认为目标是最新的否则就执行规则重建它。这个逻辑和Make基本一致但有个额外机制容易忽略restat。当一条命令执行后如果它的输出时间戳其实没有变化Ninja可以通过restat属性得知并向上更新状态避免传播无谓的重建。典型场景是脚本生成文件某个脚本每次运行都会更新生成文件的访问时间但文件内容可能没变。如果不用restat所有依赖这个生成文件的编译任务都会被触发用了restatNinja会在脚本执行完后再检查时间戳发现没有变化就认为该目标实际未更新从而让下游任务保持最新状态。实际项目中CMake生成的某些自定义命令会自动加上restat但手写build.ninja时如果碰到文件没变但每次都要重编下游的现象可以检查一下是不是缺少restat 1。这个字段虽小却能省下大量不必要的编译。5.2 用-d explain找出为什么又重编Ninja提供了一些调试选项其中-d explain是我最依赖的。当你不确定某个目标为什么总是被重建时运行ninja -d explainNinja会在重建前输出原因例如ninja explain: output build/foo.o older than most recent input build/foo.c ninja explain: output build/foo.o missing这种输出能立刻暴露问题所在可能是某个生成文件的时间戳总在变也可能是你的build.ninja里依赖写得不全。遇到全量重编的诡异现象先跑一遍-d explain大多数情况能定位到是哪个输入文件一直在变新。5.3ninja -t子命令实战-t是Ninja自带的诊断工具入口下面这些命令我几乎每天都会用ninja -t query target查看某个目标的具体依赖关系包括输入、输出、使用的规则适合快速确认依赖图是否符合预期。ninja -t targets列出构建文件里的所有目标后面加规则名可以过滤出使用该规则的目标。ninja -t commands target打印构建目标时会执行哪些命令不实际执行。切换构建系统后可以用它来确认最终编译命令是否包含了正确的宏定义和头文件路径。ninja -t graph target输出Graphviz格式的依赖图可以结合dot渲染成图片。当依赖关系复杂到肉眼无法追踪时这是最直观的排查方式。ninja -t deps target查看目标已记录的依赖文件列表确认depfile是否正确加载了头文件依赖。ninja -t clean target清理目标相关的输出。比手动删除文件靠谱。其中compdb在上一节已经提过。这些子命令都没有写进Ninja的默认帮助里但对排查构建问题价值极大。我之前遇到过一个问题某个头文件被修改后只有一半的源文件被重编另一半没有。看代码觉得所有文件都#include了它但实际重编了一半找不出原因。后来用ninja -t deps一查才发现没有重编的那些.o文件的依赖列表里根本没有那个头文件——因为它们在代码里用的是相对路径而编译器的-MMD输出和实际文件名大小写不一致导致依赖匹配失败。这种问题如果靠肉眼从构建日志里找会浪费很多时间。6. 性能调优与真实踩坑把Ninja用到极致6.1 并行度、状态输出和任务池Ninja默认会检测CPU核心数并设置一个适合并行编译的-j值但在实际项目中盲目拉满并行度并不总是最优。-j太大时大量编译进程同时跑起来可能耗尽内存或I/O带宽反而让总时间变长。如果发现编译时卡顿明显可以先用-j减半试一下。对于链接这类内存大户Ninja提供了pool机制来限制并发pool link_pool depth 1 rule link command g -o $out $in pool link_pool这样即使全局-j16同一时刻也只允许一条链接任务运行避免内存被多个链接进程打爆。在大型C项目里这个设置经常能避免链接阶段的内存抖动。另一个提升体验的小技巧是设置NINJA_STATUS环境变量让Ninja在执行过程中显示当前进度。例如export NINJA_STATUS[%f/%t %p] ninja%f表示已完成任务数%t表示总任务数%p是已完成百分比。相比默认输出这种进度显示从让人焦虑变成让人安心。它在CI日志里也很有用可以直观看到构建是否卡住。6.2 搭配ccache/distcc混合构建Ninja只负责调度不关心你实际运行的是什么编译器所以它可以轻松地和各种编译加速工具组合。最常见的组合是ccache# 在rule里把编译器包装成ccache rule cc command ccache gcc $cflags -MMD -MF $out.d -c $in -o $out也可以利用CCACHE_PREFIX、CCACHE_BASEDIR等环境变量控制缓存行为。使用CMake时可以通过CMAKE_CXX_COMPILER_LAUNCHERccache来设置让生成的构建命令自动带上ccache前缀无需手改规则。Ninja增量判断和ccache命中判断是两层Ninja发现输入时间戳变了会重新运行命令但命令落到ccache时可能直接命中缓存而秒回。这样即使某种原因导致依赖重编只要源文件内容没变编译过程仍然很快。如果你的团队有共享缓存服务也可以把ccache配置成分布式缓存效果更明显。distcc之类的分布式编译相对复杂但原理上一样只要命令能被包装Ninja就只是傻傻地执行它。需要注意的是分布式编译对增量依赖判断要求更高因为每台机器的头文件路径可能不同-MMD生成的依赖文件也会包含路径信息。在使用前一定要确认所有机器环境一致否则容易出现这边编译成功、那边编译失败的诡异问题。6.3 迁移到Ninja时最容易踩的五个坑从Makefile迁移或初次使用Ninja时有几个坑几乎是人人都会遇到的在这里集中说一下。第一个坑是忘记写depfile。手写build.ninja时如果只写了简单的command gcc -c $in -o $out没有-MMD -MF那么Ninja只追踪由build语句显式列出的输入文件头文件变化完全不会触发重建。这会导致改了头文件程序还是旧的的诡异现象。解决办法是接好depfile机制并且把依赖文件纳入版本控制之外因为它们是构建的临时产物。第二个坑是把输出文件放在源目录里。Ninja的增量判断完全基于文件路径和时间戳如果输出和输入混在一起清理起来会很麻烦还容易误删源码。建议所有输出都放到独立的构建目录CMake里的CMAKE_BINARY_DIR就是这个作用。也不要让某个build语句的输出路径和另一个build语句的输入路径存在大小写不一致的情况在Linux上没问题但在macOS的大小写不敏感文件系统上时间戳对比可能被干扰。第三个坑是盲目迁移所有自定义命令。Makefile里可以用$(shell ...)在解析阶段执行命令Ninja不允许。如果你原本的Makefile逻辑严重依赖shell函数、条件判断和宏直接手写等价build.ninja会非常痛苦。这个时候更好的做法是先迁移到CMake或Meson再让它们生成Ninja文件而不是尝试在Ninja里复刻Make的复杂逻辑。第四个坑是并行编译遇到命令名冲突。比如你在rule里写了cd subdir make这是把Make当作子进程调用如果subdir里的构建依赖没有正确记录在父级build.ninja中Ninja无法调度子Make内部的任务并行可能造成竞争。正确的做法是尽量不用嵌套构建工具所有编译动作都应该由Ninja直接调度。如果一定要调用外部脚本务必让脚本自身保证幂等和线程安全。第五个坑是忽视ninja -d explain的作用。遇到任何不该重编却重编的问题先别乱改代码先加-d explain看原因。很多时候是因为某个生成文件每次都被命令touch了或者依赖路径里包含了不稳定的时间戳文件。搞清楚原因再动手能省下大量排错时间。6.4 一个真实的迁移收益记录我用一个实际的例子来说明收益。一个中等规模的C项目约800个源文件使用CMake构建。原来用make -j8做增量构建改动一个核心头文件后通常需要重新编译200多个源文件并链接整个过程约1分20秒。后来只把生成器换成-G Ninja同样的改动场景编译耗时降到50秒左右。看起来差别不算巨大但改动一个.cpp文件时原Makefile可能因为某条隐式规则触发导致几十个文件重编Ninja在信息完备时只重编这一个文件和相应的链接步骤耗时不到20秒。为什么同样用CMake一个用Makefile后端一个用Ninja后端会有这个差别因为CMake为Makefile后端生成的规则和依赖追踪方式不如为Ninja后端生成的那么精确。CMake在Makefile后端里使用了make的$(MAKE)递归或某些批量规则而Ninja后端从最开始就为Ninja设计了一套干净、细粒度的构建图。当然首次全量构建时Ninja并不会比Make快很多因为瓶颈在编译器本身。但开发过程中迭代最频繁的其实是增量构建。一天下来几十次增量构建节省的时间累积起来非常可观。这也是我建议每个使用CMake/Meson的团队都尝试Ninja的原因。7. 什么时候不要用Ninja以及我的最后几条建议Ninja不是万金油。对于非常小的项目比如一个只有两三个源文件的课程作业或临时脚本直接一条gcc命令或者一个简单的Makefile反而更直观。Ninja的最小构建文件虽然简单但为了头文件依赖还得配depfile这个复杂度对小项目来说是多余的。另外如果你的项目严重依赖Make的隐式规则、多级条件分支、各种shell函数展开而且你暂时没有计划迁移到CMake/Meson那么不要硬改Ninja。强行用Ninja复刻Make的高级功能只会得到一份难维护的build.ninja。如果你决定上手我的建议路径是先用CMake的-G Ninja把它跑起来不要一开始就手写build.ninja。等到你确实需要定制一些CMake不好表达的规则时再去研究Ninja的rule、pool和restat。手写build.ninja的场景通常是嵌入式、特殊代码生成器或者自定义脚本链这时保持简单最重要规则尽量少变量尽量少每个build的输入输出都显式写出别让Ninja做任何“猜测”。最后分享一个我自己的小习惯在项目根目录放一个Makefile里面只写一行all: cmake -S . -B build -G Ninja cmake --build build这样既保留了大家熟悉的make入口又让真正的构建落到Ninja上。等团队成员慢慢体会到增量构建的速度差异后很多人会自动把ninja命令变成肌肉记忆。构建系统这件事工具本身重要但真正决定效率的是你愿不愿意花点时间理解背后的调度逻辑。Ninja的设计者把“快”做成了唯一目标而我们要做的就是把这个目标用在自己的项目里。