Skip to content

protagonist-fy/low-level-dev-skills / skills/build-systems/ninja

Ninja build system skill. Use when diagnosing Ninja build failures, understanding Ninja's role as a low-level build executor generated by CMake or other meta-build systems, tuning parallelism, interpreting Ninja output, or working with build.ninja files. Activates on queries about ninja errors, ninja parallelism, ninja verbose output, build.ninja format, or ninja as a CMake generator.

FileKindSize
SKILL.mdskill md4.3 KB
references/cheatsheet.mdmarkdown5.8 KB

references/cheatsheet.md

View on GitHub
# Ninja Cheatsheet

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

## Table of Contents

1. [Command line](#command-line)
2. [Sub-tools (-t)](#sub-tools--t)
3. [build.ninja format](#buildninja-format)
4. [Variables and rules](#variables-and-rules)
5. [Integration with CMake](#integration-with-cmake)
6. [Troubleshooting](#troubleshooting)

---

## Command line

```bash
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)

```bash
# 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

```ninja
# 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

| Concept | Description |
|---------|-------------|
| `rule` | Defines a build command template |
| `build` | Instantiates a rule with specific files |
| `$in` | Space-separated list of input files |
| `$out` | Space-separated list of output files |
| `$depfile` | Path to a Makefile-style dependency file (`.d`) |
| `deps = gcc` | Tells ninja to parse gcc-style depfiles and manage them |
| `deps = msvc` | Parse MSVC-style `/showIncludes` output |
| `phony` | Pseudo-target; always considered out of date |
| `default` | Targets built when none specified on command line |

---

## Variables and rules

### Special variables

| Variable | When it expands |
|----------|----------------|
| `$in` | Input files for the build edge |
| `$out` | Output files for the build edge |
| `$depfile` | The dependency file path |

### Variable scoping

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

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

---

## Integration with CMake

```bash
# 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

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

---

## Troubleshooting

| Problem | Cause | Fix |
|---------|-------|-----|
| `ninja: error: 'foo.o', needed by 'prog', missing and no known rule` | File missing / rule not generated | Re-run cmake; check `add_executable` sources |
| Stale build, not picking up changes | `build.ninja` outdated | Re-run `cmake -S . -B build` |
| `ninja: build stopped: subcommand failed` | A compile/link failed | Read the error above this line; use `-v` for full command |
| Parallel build produces race output | Many jobs writing stdout | Use `ninja -j1` to serialize; or add `pool console` |
| Circular dependency | Target depends on itself indirectly | Check CMake `target_link_libraries` for cycles |
| Extremely slow incremental build | Too many redundant edges | Check if globs or generated files are causing unnecessary rebuilds |

### Debugging why a target rebuilds

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

Output will show which dependency is newer than the target, triggering the rebuild.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall