ninja

Ninja

用途

引导 Agent 将 Ninja 用作构建执行器：诊断失败、控制并行度、通过 CMake 生成构建文件，并在需要时了解 .ninja 文件格式。

触发条件

• “Ninja 构建失败了——如何查看更多输出？”
• “如何在 CMake 中使用 Ninja？”
• “Ninja 会使用多少个并行任务？”
• “如何在 Ninja 中添加自定义构建步骤？”
• “什么是 build.ninja 文件？”

工作流

1. 将 Ninja 用作 CMake 生成器

Ninja 最常见的用途是作为 CMake 的构建执行器：

# Configure with Ninja
cmake -S . -B build -G Ninja
cmake --build build                    # uses ninja internally

# Or invoke ninja directly
cd build && ninja

# Specify parallelism
ninja -j4
ninja -j$(nproc)

# Build specific target
ninja myapp
ninja install

CMake 也支持 Ninja Multi-Config：

cmake -S . -B build -G "Ninja Multi-Config"
cmake --build build --config Release
cmake --build build --config Debug

2. 详细输出和诊断

# Show full commands (not just [CC] foo.c)
ninja -v

# Dry run (show what would be built)
ninja -n

# Show why a target needs rebuilding
ninja -d explain myapp

# Print all targets
ninja -t targets all

# Print targets grouped by rule
ninja -t targets rule cc

# Dependency graph (graphviz)
ninja -t graph myapp | dot -Tsvg -o deps.svg

3. 常用 Ninja 标志

标志	效果
-j N	并行任务数（默认值：CPU 数量 + 2）
-l N	若平均负载 > N，则不启动新任务
-k N	发生 N 次失败后继续（默认值：1）
-v	详细模式：显示完整命令行
-n	试运行
-C dir	执行任何操作前先切换到 dir
-t tool	运行子工具（clean、query、targets、graph、compdb）

4. 清理

ninja -t clean          # remove build outputs
ninja -t clean -g       # also remove generated files

也可以通过 CMake 执行：

cmake --build build --target clean

5. compile_commands.json

Ninja（通过 CMake）可以生成 compile_commands.json，用于 IDE 集成和 clang-tidy：

cmake -S . -B build -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
ln -sf build/compile_commands.json .

6. build.ninja 格式（参考）

通常不会手动编写，但了解其格式有助于调试：

# Variable
cflags = -Wall -O2

# Rule
rule cc
  command = gcc $cflags -c $in -o $out
  description = CC $in

# Build edge
build foo.o: cc foo.c

# Phony target
build all: phony foo.o

# Default target
default all

核心概念：

• rule：定义如何根据输入生成输出
• build：使用特定文件实例化一条规则
• $in / $out：输入/输出的自动变量
• phony：始终被视为过期的目标（类似于 make 中的 .PHONY）

7. Ninja 子工具

# List all build targets
ninja -t targets

# Query dependencies of a target
ninja -t query myapp

# Clean (already mentioned)
ninja -t clean

# Generate compile_commands.json (if supported by generator)
ninja -t compdb cc cxx > compile_commands.json

# List rules
ninja -t rules

8. 常见问题

问题	原因	解决方法
ninja: error: 'foo.o', needed by 'prog', missing and no known rule to make it	缺少构建规则	使用 CMake 重新生成；检查 add_executable 的源文件列表
构建未检测到更改	build.ninja 已过期	重新运行 cmake -S . -B build
并行构建非常慢	对于受 I/O 限制的构建，-j 设置过高	使用 -l$(nproc) 根据负载进行限制
循环依赖	规则依赖于自身	检查 CMake 目标依赖

如需查看完整的 Ninja 命令参考、build.ninja 格式详情和 CMake 集成模式，请参阅 references/cheatsheet.md。

相关技能

• 使用 skills/build-systems/cmake 配置 CMake 以生成 Ninja 文件
• 使用 skills/build-systems/make 处理基于 Make 的项目