ninja

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ninja

Purpose

用途

Guide agents through Ninja as a build executor: diagnosing failures, controlling parallelism, generating from CMake, and understanding the

.ninja

file format when needed.

指导开发者使用Ninja作为构建执行器：诊断构建失败、控制并行性、通过CMake生成构建文件，以及在需要时理解.ninja文件格式。

Triggers

触发场景

"Ninja is failing — how do I get more output?"
"How do I use Ninja with CMake?"
"How many parallel jobs does Ninja use?"
"How do I add a custom build step in Ninja?"
"What is a
```
build.ninja
```
file?"

"Ninja构建失败了——如何获取更多输出信息？"
"如何将Ninja与CMake配合使用？"
"Ninja会使用多少个并行任务？"
"如何在Ninja中添加自定义构建步骤？"
"什么是
```
build.ninja
```
文件？"

Workflow

工作流程

1. Ninja as a CMake generator

1. Ninja作为CMake生成器

The most common use of Ninja is as the build executor for CMake:

bash

undefined

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

bash

undefined

Configure with Ninja

用Ninja配置项目

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

cmake -S . -B build -G Ninja cmake --build build # 内部调用ninja

Or invoke ninja directly

或者直接调用ninja

cd build && ninja

Specify parallelism

指定并行任务数

ninja -j4 ninja -j$(nproc)

Build specific target

构建特定目标

ninja myapp ninja install


CMake also supports `Ninja Multi-Config`:

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

ninja myapp ninja install


CMake还支持`Ninja Multi-Config`：

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

2. Verbose output and diagnostics

2. 详细输出与诊断

bash

undefined

bash

undefined

Show full commands (not just [CC] foo.c)

显示完整命令（而非仅[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)

依赖关系图（graphviz格式）

ninja -t graph myapp | dot -Tsvg -o deps.svg

undefined

ninja -t graph myapp | dot -Tsvg -o deps.svg

undefined

3. Common Ninja flags

3. 常用Ninja参数

Flag	Effect
`-j N`	Parallel jobs (default: CPUs + 2)
`-l N`	Don't start new jobs if load average > N
`-k N`	Keep going after N failures (default 1)
`-v`	Verbose: show full command lines
`-n`	Dry run
`-C dir`	Change to `dir` before doing anything
`-t tool`	Run a sub-tool ( `clean` , `query` , `targets` , `graph` , `compdb` )

参数	作用
`-j N`	并行任务数（默认：CPU数量 + 2）
`-l N`	当系统负载平均值大于N时，不启动新任务
`-k N`	出现N次失败后继续执行（默认值为1）
`-v`	详细模式：显示完整命令行
`-n`	空运行
`-C dir`	执行操作前切换到指定目录 `dir`
`-t tool`	运行子工具（ `clean` 、 `query` 、 `targets` 、 `graph` 、 `compdb` ）

4. Cleaning

4. 清理构建产物

bash

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

Or via CMake:

bash

cmake --build build --target clean

bash

ninja -t clean          # 删除构建输出文件
ninja -t clean -g       # 同时删除生成的文件

或者通过CMake执行：

bash

cmake --build build --target clean

5. compile_commands.json

Ninja (via CMake) can generate a

compile_commands.json

for IDE integration and

clang-tidy

bash

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

Ninja（通过CMake）可以生成

compile_commands.json

，用于IDE集成和

clang-tidy

工具：

bash

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

6. build.ninja format (reference)

6. build.ninja格式（参考）

Rarely hand-written, but useful to understand for debugging:

ninja

undefined

该文件很少手动编写，但理解其格式对调试很有帮助：

ninja

undefined

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


Key concepts:

- `rule`: defines how to produce outputs from inputs
- `build`: instantiates a rule with specific files
- `$in` / `$out`: automatic variables for inputs/outputs
- `phony`: a target that is always considered out of date (like `.PHONY` in make)

default all


核心概念：

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

7. Ninja sub-tools

7. Ninja子工具

bash

undefined

bash

undefined

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)

生成compile_commands.json（如果生成器支持）

ninja -t compdb cc cxx > compile_commands.json

List rules

列出所有规则

ninja -t rules

undefined

ninja -t rules

undefined

8. Common issues

8. 常见问题

Issue	Cause	Fix
`ninja: error: 'foo.o', needed by 'prog', missing and no known rule to make it`	Missing build rule	Regenerate with CMake; check `add_executable` source list
Build not picking up changes	Stale `build.ninja`	Re-run `cmake -S . -B build`
Very slow parallel build	`-j` too high for I/O-bound build	Use `-l$(nproc)` to limit by load
Circular dependency	Rule depends on itself	Check CMake target dependencies

For the full Ninja command reference,

build.ninja

format details, and CMake integration patterns, see references/cheatsheet.md.

问题	原因	解决方法
`ninja: error: 'foo.o', needed by 'prog', missing and no known rule to make it`	缺少构建规则	使用CMake重新生成构建文件；检查 `add_executable` 的源文件列表
构建未检测到代码变更	`build.ninja` 文件过期	重新运行 `cmake -S . -B build`
并行构建速度极慢	`-j` 参数设置过高，导致I/O瓶颈	使用 `-l$(nproc)` 根据系统负载限制并行任务数
循环依赖	规则存在自依赖	检查CMake目标的依赖关系

如需获取完整的Ninja命令参考、

build.ninja

格式细节以及CMake集成模式，请查看references/cheatsheet.md。

ninja

Original

Translation

Ninja

Ninja

Purpose

用途

Triggers

触发场景

Workflow

工作流程

1. Ninja as a CMake generator

1. Ninja作为CMake生成器

Configure with Ninja

用Ninja配置项目

Or invoke ninja directly

或者直接调用ninja

Specify parallelism

指定并行任务数

Build specific target

构建特定目标

2. Verbose output and diagnostics

2. 详细输出与诊断

Show full commands (not just [CC] foo.c)

显示完整命令（而非仅[CC] foo.c）

Dry run (show what would be built)

空运行（显示将要执行的构建操作）

Show why a target needs rebuilding

显示目标需要重新构建的原因

Print all targets

打印所有目标

Print targets grouped by rule

按规则分组打印目标

Dependency graph (graphviz)

依赖关系图（graphviz格式）

3. Common Ninja flags

3. 常用Ninja参数

4. Cleaning

4. 清理构建产物

5. compile_commands.json

5. compile_commands.json

6. build.ninja format (reference)

6. build.ninja格式（参考）

Variable

变量

Rule

规则

Build edge

构建边

Phony target

伪目标

Default target

默认目标

7. Ninja sub-tools

7. Ninja子工具

List all build targets

列出所有构建目标

Query dependencies of a target

查询目标的依赖关系

Clean (already mentioned)

清理（前文已提及）

Generate compile_commands.json (if supported by generator)

生成compile_commands.json（如果生成器支持）

List rules

列出所有规则

8. Common issues

8. 常见问题

Related skills

相关技能