ninja: Usage, Options & Common CI Errors

ninja runs builds described by a generated build.ninja file, fast and in parallel.

ninja is the speed-focused backend CMake and Meson generate for. You rarely hand-write build.ninja; you run ninja in a build directory a generator produced. In CI the gotchas are running it in the wrong directory and over-parallelizing memory-hungry C++ links.

What it does

ninja executes builds defined by a build.ninja manifest, which is typically emitted by a meta build system (CMake with -G Ninja, Meson, gn). It is designed for speed: minimal logic, aggressive parallelism, and fast incremental rebuilds.

Common usage

Terminal

cmake -G Ninja -S . -B build && ninja -C build
ninja                              # build default targets here
ninja -C build -j4                 # limit parallel jobs
ninja -C build install
ninja -t clean                     # clean built outputs

Options

Flag	What it does
-C <dir>	Change to dir (where build.ninja lives)
-j <N>	Run N jobs in parallel (default: CPUs+2)
-v	Print full command lines
-t <tool>	Subtool: clean, graph, query, deps
-n	Dry run (show, do not execute)

Common errors in CI

"ninja: error: loading ‘build.ninja’: No such file or directory" means you are not in the generated build directory - run the generator first or use ninja -C build. "ninja: error: unknown target ‘X’" - the target name does not exist; ninja -t targets lists them. By default ninja uses CPUs+2 jobs, which can OOM-kill heavy C++ links on memory-limited runners ("ninja: build stopped: subcommand failed" after a g++ kill) - cap with -j to fit memory.