The Ninja build system

Where other build systems are high-level languages, Ninja aims to be an assembler.

Build systems get slow when they need to make decisions. When you are in a edit-compile cycle you want it to be as fast as possible — you want the build system to do the minimum work necessary to figure out what needs to be built immediately.

Ninja contains the barest functionality necessary to describe arbitrary dependency graphs. Its lack of syntax makes it impossible to express complex decisions.

Instead, Ninja is intended to be used with a separate program generating its input files. The generator program (like the ./configure found in autotools projects) can analyze system dependencies and make as many decisions as possible up front so that incremental builds stay fast. Going beyond autotools, even build-time decisions like "which compiler flags should I use?" or "should I build a debug or release-mode binary?" belong in the .ninja file generator.

Here are the design goals of Ninja:

Some explicit non-goals:

To restate, Ninja is faster than other build systems because it is painfully simple. You must tell Ninja exactly what to do when you create your project’s .ninja files.

Ninja is closest in spirit and functionality to Make, relying on simple dependencies between file timestamps.

But fundamentally, make has a lot of features: suffix rules, functions, built-in rules that e.g. search for RCS files when building source. Make’s language was designed to be written by humans. Many projects find make alone adequate for their build problems.

In contrast, Ninja has almost no features; just those necessary to get builds correct while punting most complexity to generation of the ninja input files. Ninja by itself is unlikely to be useful for most projects.

Here are some of the features Ninja adds to Make. (These sorts of features can often be implemented using more complicated Makefiles, but they are not part of make itself.)

Run ninja. By default, it looks for a file named build.ninja in the current directory and builds all out-of-date targets. You can specify which targets (files) to build as command line arguments.

There is also a special syntax target^ for specifying a target as the first output of some rule containing the source you put in the command line, if one exists. For example, if you specify target as foo.c^ then foo.o will get built (assuming you have those targets in your build files).

ninja -h prints help output. Many of Ninja’s flags intentionally match those of Make; e.g ninja -C build -j 20 changes into the build directory and runs 20 build commands in parallel. (Note that Ninja defaults to running commands in parallel anyway, so typically you don’t need to pass -j.)

Ninja supports one environment variable to control its behavior: NINJA_STATUS, the progress status printed before the rule being run.

Several placeholders are available:

The default progress status is "[%f/%t] " (note the trailing space to separate from the build rule). Another example of possible progress status could be "[%u/%r/%f] ".

The -t flag on the Ninja command line runs some tools that we have found useful during Ninja’s development. The current tools are:

Ninja evaluates a graph of dependencies between files, and runs whichever commands are necessary to make your build target up to date as determined by file modification times. If you are familiar with Make, Ninja is very similar.

A build file (default name: build.ninja) provides a list of rules — short names for longer commands, like how to run the compiler — along with a list of build statements saying how to build files using the rules — which rule to apply to which inputs to produce which outputs.

Conceptually, build statements describe the dependency graph of your project, while rule statements describe how to generate the files along a given edge of the graph.

Here’s a basic .ninja file that demonstrates most of the syntax. It will be used as an example for the following sections.

Despite the non-goal of being convenient to write by hand, to keep build files readable (debuggable), Ninja supports declaring shorter reusable names for strings. A declaration like the following

can be used on the right side of an equals sign, dereferencing it with a dollar sign, like this:

Variables can also be referenced using curly braces like ${in}.

Variables might better be called "bindings", in that a given variable cannot be changed, only shadowed. There is more on how shadowing works later in this document.

Rules declare a short name for a command line. They begin with a line consisting of the rule keyword and a name for the rule. Then follows an indented set of variable = value lines.

The basic example above declares a new rule named cc, along with the command to run. In the context of a rule, the command variable defines the command to run, $in expands to the list of input files (foo.c), and $out to the output files (foo.o) for the command. A full list of special variables is provided in the reference.

Build statements declare a relationship between input and output files. They begin with the build keyword, and have the format build outputs: rulename inputs. Such a declaration says that all of the output files are derived from the input files. When the output files are missing or when the inputs change, Ninja will run the rule to regenerate the outputs.

The basic example above describes how to build foo.o, using the cc rule.

In the scope of a build block (including in the evaluation of its associated rule), the variable $in is the list of inputs and the variable $out is the list of outputs.

A build statement may be followed by an indented set of key = value pairs, much like a rule. These variables will shadow any variables when evaluating the variables in the command. For example:

For more discussion of how scoping works, consult the reference.

If you need more complicated information passed from the build statement to the rule (for example, if the rule needs "the file extension of the first input"), pass that through as an extra variable, like how cflags is passed above.

If the top-level Ninja file is specified as an output of any build statement and it is out of date, Ninja will rebuild and reload it before building the targets requested by the user.

misc/ninja_syntax.py in the Ninja distribution is a tiny Python module to facilitate generating Ninja files. It allows you to make Python calls like ninja.rule(name='foo', command='bar', depfile='$out.d') and it will generate the appropriate syntax. Feel free to just inline it into your project’s build system if it’s useful.

The special rule name phony can be used to create aliases for other targets. For example:

This makes ninja foo build the longer path. Semantically, the phony rule is equivalent to a plain rule where the command does nothing, but phony rules are handled specially in that they aren’t printed when run, logged (see below), nor do they contribute to the command count printed as part of the build process.

phony can also be used to create dummy targets for files which may not exist at build time. If a phony build statement is written without any dependencies, the target will be considered out of date if it does not exist. Without a phony build statement, Ninja will report an error if the file does not exist and is required by the build.

By default, if no targets are specified on the command line, Ninja will build every output that is not named as an input elsewhere. You can override this behavior using a default target statement. A default target statement causes Ninja to build only a given subset of output files if none are specified on the command line.

Default target statements begin with the default keyword, and have the format default targets. A default target statement must appear after the build statement that declares the target as an output file. They are cumulative, so multiple statements may be used to extend the list of default targets. For example:

This causes Ninja to build the foo, bar and baz targets by default.

For each built file, Ninja keeps a log of the command used to build it. Using this log Ninja can know when an existing output was built with a different command line than the build files specify (i.e., the command line changed) and knows to rebuild the file.

The log file is kept in the build root in a file called .ninja_log. If you provide a variable named builddir in the outermost scope, .ninja_log will be kept in that directory instead.

Available since Ninja 1.2.

Ninja version labels follow the standard major.minor.patch format, where the major version is increased on backwards-incompatible syntax/behavioral changes and the minor version is increased on new behaviors. Your build.ninja may declare a variable named ninja_required_version that asserts the minimum Ninja version required to use the generated file. For example,

declares that the build file relies on some feature that was introduced in Ninja 1.1 (perhaps the pool syntax), and that Ninja 1.1 or greater must be used to build. Unlike other Ninja variables, this version requirement is checked immediately when the variable is encountered in parsing, so it’s best to put it at the top of the build file.

Ninja always warns if the major versions of Ninja and the ninja_required_version don’t match; a major version change hasn’t come up yet so it’s difficult to predict what behavior might be required.

To get C/C++ header dependencies (or any other build dependency that works in a similar way) correct Ninja has some extra functionality.

The problem with headers is that the full list of files that a given source file depends on can only be discovered by the compiler: different preprocessor defines and include paths cause different files to be used. Some compilers can emit this information while building, and Ninja can use that to get its dependencies perfect.

Consider: if the file has never been compiled, it must be built anyway, generating the header dependencies as a side effect. If any file is later modified (even in a way that changes which headers it depends on) the modification will cause a rebuild as well, keeping the dependencies up to date.

When loading these special dependencies, Ninja implicitly adds extra build edges such that it is not an error if the listed dependency is missing. This allows you to delete a header file and rebuild without the build aborting due to a missing input.

Available since Ninja 1.1.

Pools allow you to allocate one or more rules or edges a finite number of concurrent jobs which is more tightly restricted than the default parallelism.

This can be useful, for example, to restrict a particular expensive rule (like link steps for huge executables), or to restrict particular build statements which you know perform poorly when run concurrently.

Each pool has a depth variable which is specified in the build file. The pool is then referred to with the pool variable on either a rule or a build statement.

No matter what pools you specify, ninja will never run more concurrent jobs than the default parallelism, or the number of jobs specified on the command line (with -j).

Ninja is mostly encoding agnostic, as long as the bytes Ninja cares about (like slashes in paths) are ASCII. This means e.g. UTF-8 or ISO-8859-1 input files ought to work.

Comments begin with # and extend to the end of the line.

Newlines are significant. Statements like build foo bar are a set of space-separated tokens that end at the newline. Newlines and spaces within a token must be escaped.

There is only one escape character, $, and it has the following behaviors:

A build or default statement is first parsed as a space-separated list of filenames and then each name is expanded. This means that spaces within a variable will result in spaces in the expanded filename.

In a name = value statement, whitespace at the beginning of a value is always stripped. Whitespace at the beginning of a line after a line continuation is also stripped.

Other whitespace is only significant if it’s at the beginning of a line. If a line is indented more than the previous one, it’s considered part of its parent’s scope; if it is indented less than the previous one, it closes the previous scope.

Two variables are significant when declared in the outermost file scope.

A rule block contains a list of key = value declarations that affect the processing of the rule. Here is a full list of special keys.

There are two types of build outputs which are subtly different.

There are three types of build dependencies which are subtly different.

File paths are compared as is, which means that an absolute path and a relative path, pointing to the same file, are considered different by Ninja.

Variables are expanded in paths (in a build or default statement) and on the right side of a name = value statement.

When a name = value statement is evaluated, its right-hand side is expanded immediately (according to the below scoping rules), and from then on $name expands to the static string as the result of the expansion. It is never the case that you’ll need to "double-escape" a value to prevent it from getting expanded twice.

All variables are expanded immediately as they’re encountered in parsing, with one important exception: variables in rule blocks are expanded when the rule is used, not when it is declared. In the following example, the demo rule prints "this is a demo of bar".

Top-level variable declarations are scoped to the file they occur in.

Rule declarations are also scoped to the file they occur in. (Available since Ninja 1.6)

The subninja keyword, used to include another .ninja file, introduces a new scope. The included subninja file may use the variables and rules from the parent file, and shadow their values for the file’s scope, but it won’t affect values of the variables in the parent.

To include another .ninja file in the current scope, much like a C #include statement, use include instead of subninja.

Variable declarations indented in a build block are scoped to the build block. The full lookup order for a variable expanded in a build block (or the rule is uses) is: