mohitmishra786/low-level-dev-skills / skills/build-systems/ninja
ninja
VerifiedNinja 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| references/cheatsheet.md | markdown | 5.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |