The Ninja build system (2024)

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

Build systems get slow when they need to make decisions. When you arein an edit-compile cycle you want it to be as fast as possible — youwant the build system to do the minimum work necessary to figure outwhat needs to be built immediately.

Ninja contains the barest functionality necessary to describearbitrary dependency graphs. Its lack of syntax makes it impossibleto express complex decisions.

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

Here are the design goals of Ninja:

Some explicit non-goals:

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

Ninja is closest in spirit and functionality to Make, relying onsimple 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 buildingsource. Make’s language was designed to be written by humans. Manyprojects find make alone adequate for their build problems.

In contrast, Ninja has almost no features; just those necessary to getbuilds correct while punting most complexity to generation of theninja input files. Ninja by itself is unlikely to be useful for mostprojects.

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

gn

The meta-build system used togenerate build files for Google Chrome and related projects (v8,node.js), as well as Google Fuchsia. gn can generate Ninja files forall platforms supported by Chrome.

CMake

A widely used meta-build system thatcan generate Ninja files on Linux as of CMake version 2.8.8. Newer versionsof CMake support generating Ninja files on Windows and Mac OS X too.

others

Ninja ought to fit perfectly into other meta-build softwarelike premake. If you do this work,please let us know!

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

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

ninja -h prints help output. Many of Ninja’s flags intentionallymatch those of Make; e.g ninja -C build -j 20 changes into thebuild directory and runs 20 build commands in parallel. (Note thatNinja defaults to running commands in parallel anyway, so typicallyyou 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 spaceto separate from the build rule). Another example of possible progress statuscould be "[%u/%r/%f] ".

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

ninja -t browse --port=8000 --no-browser mytarget

ninja -t graph mytarget | dot -Tpng -ograph.png

ninja -t msvc -e ENVFILE -- cl.exe <arguments>

ninja -t msvc -o DEPFILE [-p STRING] -- cl.exe /showIncludes <arguments>

Build file encoding: <codepage>

Ninja evaluates a graph of dependencies between files, and runswhichever commands are necessary to make your build target up to dateas determined by file modification times. If you are familiar withMake, 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 filesusing the rules — which rule to apply to which inputs to producewhich outputs.

Conceptually, build statements describe the dependency graph of yourproject, while rule statements describe how to generate the filesalong 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.

cflags = -Wallrule cc command = gcc $cflags -c $in -o $outbuild foo.o: cc foo.c

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

cflags = -g

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

rule cc command = gcc $cflags -c $in -o $out

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

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

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

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

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

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

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

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

cflags = -Wall -Werrorrule cc command = gcc $cflags -c $in -o $out# If left unspecified, builds get the outer $cflags.build foo.o: cc foo.c# But you can shadow variables like cflags for a particular build.build special.o: cc special.c cflags = -Wall# The variable was only shadowed for the scope of special.o;# Subsequent build lines get the outer (original) cflags.build bar.o: cc bar.c

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

If you need more complicated information passed from the buildstatement to the rule (for example, if the rule needs "the fileextension of the first input"), pass that through as an extravariable, like how cflags is passed above.

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

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

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

build foo: phony some/file/in/a/faraway/subdir/foo

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

When a phony target is used as an input to another build rule, theother build rule will, semantically, consider the inputs of thephony rule as its own. Therefore, phony rules can be used to groupinputs, e.g. header files.

phony can also be used to create dummy targets for files whichmay not exist at build time. If a phony build statement is writtenwithout any dependencies, the target will be considered out of date ifit does not exist. Without a phony build statement, Ninja will reportan error if the file does not exist and is required by the build.

To create a rule that never rebuilds, use a build rule without any input:

rule touch command = touch $outbuild file_that_always_exists.dummy: touchbuild dummy_target_to_follow_a_pattern: phony file_that_always_exists.dummy

By default, if no targets are specified on the command line, Ninjawill 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 subsetof output files if none are specified on the command line.

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

default foo bardefault baz

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

For each built file, Ninja keeps a log of the command used to buildit. Using this log Ninja can know when an existing output was builtwith a different command line than the build files specify (i.e., thecommand 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-incompatiblesyntax/behavioral changes and the minor version is increased on newbehaviors. Your build.ninja may declare a variable namedninja_required_version that asserts the minimum Ninja versionrequired to use the generated file. For example,

ninja_required_version = 1.1

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

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

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

The problem with headers is that the full list of files that a givensource file depends on can only be discovered by the compiler:different preprocessor defines and include paths cause different filesto 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 islater modified (even in a way that changes which headers it dependson) the modification will cause a rebuild as well, keeping thedependencies up to date.

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

rule cc depfile = $out.d command = gcc -MD -MF $out.d [other gcc flags here]

Available since Ninja 1.1.

Pools allow you to allocate one or more rules or edges a finite numberof concurrent jobs which is more tightly restricted than the defaultparallelism.

This can be useful, for example, to restrict a particular expensive rule(like link steps for huge executables), or to restrict particular buildstatements 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 ruleor a build statement.

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

# No more than 4 links at a time.pool link_pool depth = 4# No more than 1 heavy object at a time.pool heavy_object_pool depth = 1rule link ... pool = link_poolrule cc ...# The link_pool is used here. Only 4 links will run concurrently.build foo.exe: link input.obj# A build statement can be exempted from its rule's pool by setting an# empty pool. This effectively puts the build statement back into the default# pool, which has infinite depth.build other.exe: link input.obj pool =# A build statement can specify a pool directly.# Only one of these builds will run at a time.build heavy_object1.obj: cc heavy_obj1.cc pool = heavy_object_poolbuild heavy_object2.obj: cc heavy_obj2.cc pool = heavy_object_pool

1. A rule declaration, which begins with rule rulename, and then has a series of indented lines defining variables.

2. A build edge, which looks like build output1 output2: rulename input1 input2. Implicit dependencies may be tacked on the end with | dependency1 dependency2. Order-only dependencies may be tacked on the end with || dependency1 dependency2. (See the reference on dependency types.) Validations may be taked on the end with |@ validation1 validation2. (See the reference on validations.)

   Implicit outputs (available since Ninja 1.7) may be added beforethe : with | output1 output2 and do not appear in $out.(See the reference on output types.)

3. Variable declarations, which look like variable = value.
4. Default target statements, which look like default target1 target2.
5. References to more files, which look like subninja path or include path. The difference between these is explained below in the discussion about scoping.
6. A pool declaration, which looks like pool poolname. Pools are explained in the section on pools.

Ninja is mostly encoding agnostic, as long as the bytes Ninja caresabout (like slashes in paths) are ASCII. This means e.g. UTF-8 orISO-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 setof space-separated tokens that end at the newline. Newlines andspaces within a token must be escaped.

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

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

spaced = foo barbuild $spaced/baz other$ file: ...# The above build line has two outputs: "foo bar/baz" and "other file".

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

two_words_with_one_space = foo $ barone_word_with_no_space = foo$ bar

Other whitespace is only significant if it’s at the beginning of aline. If a line is indented more than the previous one, it’sconsidered part of its parent’s scope; if it is indented less than theprevious 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 thataffect the processing of the rule. Here is a full list of specialkeys.

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 arelative path, pointing to the same file, are considered different by Ninja.

Available since Ninja 1.11.

Validations listed on the build line cause the specified files to beadded to the top level of the build graph (as if they were specifiedon the Ninja command line) whenever the build line is a transitivedependency of one of the targets specified on the command line or adefault target.

Validations are added to the build graph regardless of whether the outputfiles of the build statement are dirty are not, and the dirty state ofthe build statement that outputs the file being used as a validationhas no effect on the dirty state of the build statement that requested it.

A build edge can list another build edge as a validation even if the secondedge depends on the first.

Validations are designed to handle rules that perform error checking butdon’t produce any artifacts needed by the build, for example, staticanalysis tools. Marking the static analysis rule as an implicit inputof the main build rule of the source files or of the rules that dependon the main build rule would slow down the critical path of the build,but using a validation would allow the build to proceed in parallel withthe static analysis rule once the main build rule is complete.

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 isexpanded immediately (according to the below scoping rules), andfrom then on $name expands to the static string as the result of theexpansion. It is never the case that you’ll need to "double-escape" avalue 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 expandedwhen the rule is used, not when it is declared. In the followingexample, the demo rule prints "this is a demo of bar".

rule demo command = echo "this is a demo of $foo"build out: demo foo = 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 thevariables and rules from the parent file, and shadow their values for the file’sscope, 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 thebuild block. The full lookup order for a variable expanded in abuild block (or the rule is uses) is:

Files specified by dyndep bindings use the same lexical syntaxas ninja build files and have the following layout.

The build statements in a dyndep file must have a one-to-one correspondenceto build statements in the ninja build file that name thedyndep file in a dyndep binding. No dyndep build statement may be omittedand no extra build statements may be specified.