ninja

Build software projects quickly

TLDR

Build in the current directory

$ ninja

Build in the current directory, executing 4 jobs at a time in parallel

$ ninja -j [4]

Build a program in a given directory

$ ninja -C [path/to/directory]

Show targets (e.g. install and uninstall)

$ ninja -t targets

Display help

$ ninja -h

    Change to the given directory before doing anything else.

-f
    Specify the build file; defaults to build.ninja.

-t
    Run a built-in tool. Valid values include 'targets', 'commands', 'graph', 'query', 'browse', 'recompact', 'restat', 'clean'.

-v
    Show all command lines while building.

-n
    Dry run (don't run commands).

-j
    Run N jobs in parallel; infinite by default.

-k
    Keep going until N jobs fail (0 means infinity).

-l
    Do not start new jobs if the load average is above load.

-d
    Enable debugging; valid values include 'md5sum', 'keepdepfile', 'explain'.

-w
    Adjust warning behavior; valid values include 'err', 'warn', 'quiet'.

--version
    Print ninja version.

-h
    Display this help message.

DESCRIPTION

Ninja is a small build system designed for speed. It reads build descriptions written by a higher-level build generator and executes them as quickly as possible. Ninja focuses on doing one thing well: build fast. It is often used in conjunction with meta-build systems like CMake, Meson, or GN (Generate Ninja) which are responsible for generating the actual build files that Ninja then executes.

Unlike Make, Ninja is not recursive. It creates a dependency graph from the build files and schedules operations so as to maximize parallelism. This enables Ninja to achieve significantly faster build times, especially on large projects. Ninja is well-suited to projects where build speed is critical, allowing developers to iterate and test changes rapidly.

CAVEATS

Ninja requires a build file (typically `build.ninja`) generated by another tool like CMake or Meson. It does not handle dependency resolution or build file generation itself. Errors in the generated `build.ninja` file may lead to unexpected behavior or build failures.

TARGET SPECIFICATION

If no target is specified, Ninja builds the 'default' target(s) specified in the build file. Otherwise, Ninja builds the specified targets. A target is typically the name of an output file.

TOOLS

The `-t` option gives you access to various sub-tools for inspecting or manipulating Ninja's internal state. For example, `ninja -t targets` lists all available targets in the build file. `ninja -t clean` removes files built by ninja.

HISTORY

Ninja was created by Evan Martin at Google, initially released in 2011. It was designed to be a faster replacement for Make, addressing the performance limitations observed in large-scale projects. It quickly gained popularity due to its focus on speed and efficient scheduling of build operations. It has become a popular tool for building software across a variety of platforms and projects, and used by many development teams that prioritize faster iteration cycles.