Ninja

mohitmishra786/low-level-dev-skills/skills/build-systems/ninja

by mohitmishra786bdc58472fa9fNo license253 starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 3 months ago

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.

Instructions onlySoftware Development DevOps & Cloud

AI-generated overview

Guides agents through Ninja build executor usage, diagnostics, parallelism, and build.ninja files.

What it does: This skill provides guidance on using Ninja as a low-level build executor, typically generated by CMake. It covers configuring builds with CMake's Ninja generator, verbose and dry-run output, parallelism flags, cleaning, compile_commands.json generation, and the build.ninja file format. It also lists common Ninja sub-tools and a table of frequent build errors with causes and fixes, and points to a cheatsheet reference for fuller command details.
When to use it: Use it when diagnosing Ninja build failures, interpreting Ninja output, or tuning Ninja parallelism. It also fits questions about using Ninja with CMake, the Ninja Multi-Config generator, or the build.ninja file format.
Requirements: No scripts or packages are required; it is instructions only. The described workflows assume Ninja and CMake are installed, and some commands optionally use graphviz (dot) or clang-tidy.

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:

bash

# 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

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

bash

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

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

2. Verbose output and diagnostics

bash

# 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

# 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

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

4. Cleaning

bash

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

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

Or via CMake:

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=ONln -sf build/compile_commands.json .

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:

ninja

# 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

# 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

bash

# 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

# 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

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 [blocked].

Related skills

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

Source and attribution

Source:mohitmishra786/low-level-dev-skillsinskills/build-systems/ninjaat commitbdc5847

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Ninja

Ninja

Purpose

Triggers

Workflow

1. Ninja as a CMake generator

2. Verbose output and diagnostics

3. Common Ninja flags

4. Cleaning

5. compile_commands.json

6. build.ninja format (reference)

7. Ninja sub-tools

8. Common issues

Related skills

Source and attribution

More from mohitmishra786/low-level-dev-skills

Zig Debugging

Simd Intrinsics

Zig Cross

Rustc Basics

Zig Cinterop

Zig Build System

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices