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 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 also supports Ninja Multi-Config:

cmake -S . -B build -G "Ninja Multi-Config"
cmake --build build --config Release
cmake --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 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. Common Ninja flags

4. Cleaning

ninja -t clean          # remove build outputs
ninja -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=ON
ln -sf build/compile_commands.json .

6. build.ninja format (reference)

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

# 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)

7. Ninja sub-tools

# 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. Common issues

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

Related skills

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

Ninja Cheatsheet

Source: <https://ninja-build.org/manual.html>

Table of Contents

1. Command line 2. Sub-tools (-t) 3. build.ninja format 4. Variables and rules 5. Integration with CMake 6. Troubleshooting

---

Command line

ninja                          # build default target
ninja myapp                    # build specific target
ninja install                  # run install target
ninja clean                    # remove outputs (via -t clean)

ninja -j4                      # exactly 4 parallel jobs
ninja -j$(nproc)               # all available CPUs
ninja -l4.0                    # don't start jobs if load > 4.0
ninja -k5                      # keep going after up to 5 failures
ninja -k0                      # keep going indefinitely

ninja -v                       # verbose: show full commands
ninja -n                       # dry run: show what would run
ninja -C build/                # change to build/ directory first

ninja -d explain myapp         # explain why target needs rebuild
ninja -d keepdepfile           # keep .d files after use
ninja -d keeprsp               # keep .rsp response files
ninja -d stats                 # print build statistics at end

---

Sub-tools (-t)

# List all targets
ninja -t targets
ninja -t targets all           # all targets (including intermediate)
ninja -t targets rule cc       # targets using rule 'cc'

# Clean build outputs
ninja -t clean                 # remove all built files
ninja -t clean myapp           # clean specific target only
ninja -t clean -g              # also remove generated files

# Query a target's dependencies
ninja -t query myapp

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

# Generate compile_commands.json (if rules support it)
ninja -t compdb cc cxx > compile_commands.json

# List all rules
ninja -t rules

# Browse (requires curses)
ninja -t browse --port=8080 myapp

---

build.ninja format

Ninja files are almost always generated by CMake or other tools. Understanding the format helps debug generated builds.

Minimal example

# Variable declaration
cc = gcc
cflags = -Wall -O2

# Rule: how to transform inputs to outputs
rule compile_c
  command = $cc $cflags -c $in -o $out
  description = CC $in
  depfile = $out.d
  deps = gcc             # tells ninja to read gcc-style .d files

rule link
  command = $cc -o $out $in
  description = LINK $out

# Build edges: instantiate rules with specific files
build src/foo.o: compile_c src/foo.c
build src/bar.o: compile_c src/bar.c

# Link
build myapp: link src/foo.o src/bar.o

# Phony: always out of date
build clean: phony
build all: phony myapp

# Default targets (built when none specified)
default all

Key concepts

---

Variables and rules

Special variables

Variable scoping

# Global variable
cflags = -O2

# Rule-level variable (overrides global inside the rule)
rule compile_c
  command = gcc $cflags -c $in -o $out
  cflags = -O0      # this shadows the global inside the rule

# Build-edge variable (overrides for this specific build edge)
build slow.o: compile_c slow.c
  cflags = -O0 -g   # only for this edge

Response files (for long command lines)

rule link
  command = gcc @$out.rsp -o $out
  rspfile = $out.rsp
  rspfile_content = $in $LINK_FLAGS

---

Integration with CMake

# Generate Ninja build files
cmake -S . -B build -G Ninja

# Build
cmake --build build
# Or: cd build && ninja

# Parallel build
cmake --build build -- -j$(nproc)

# Verbose (see actual commands)
cmake --build build -- -v
# Or: VERBOSE=1 ninja -C build

# Build a specific target
cmake --build build --target myapp

# Clean
cmake --build build --target clean

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

generate compile_commands.json

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

---

Troubleshooting

Debugging why a target rebuilds

ninja -d explain myapp 2>&1 | head -30

Output will show which dependency is newer than the target, triggering the rebuild.