Ninja

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.

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?"

Workflow

1. Ninja as a CMake generator

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

# Configure with Ninjacmake -S . -B build -G Ninjacmake --build build                    # uses ninja internally
# Or invoke ninja directlycd build && ninja
# Specify parallelismninja -j4ninja -j$(nproc)
# Build specific targetninja myappninja install

CMake also supports Ninja Multi-Config:

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

2. Verbose output and diagnostics

# Show full commands (not just [CC] foo.c)ninja -v
# Dry run (show what would be built)ninja -n
# Show why a target needs rebuildingninja -d explain myapp
# Print all targetsninja -t targets all
# Print targets grouped by ruleninja -t targets rule cc
# Dependency graph (graphviz)ninja -t graph myapp | dot -Tsvg -o deps.svg

3. Common Ninja flags

4. Cleaning

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

Or via CMake:

cmake --build build --target clean

5. compile_commands.json

Ninja (via CMake) can generate a compile_commands.json for IDE integration and clang-tidy:

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

6. build.ninja format (reference)

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

# Variablecflags = -Wall -O2
# Rulerule cc  command = gcc $cflags -c $in -o $out  description = CC $in
# Build edgebuild foo.o: cc foo.c
# Phony targetbuild all: phony foo.o
# Default targetdefault 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)

7. Ninja sub-tools

# List all build targetsninja -t targets
# Query dependencies of a targetninja -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 rulesninja -t rules

8. Common issues

For the full Ninja command reference, build.ninja format details, and CMake integration patterns, see references/cheatsheet.md [blocked].

Related skills

• Use skills/build-systems/cmake for CMake configuration that generates Ninja files
• Use skills/build-systems/make for Make-based projects