Ninja is yet another build system. It takes as input the interdependencies of files (typically source code and output executables) and orchestrates building them, quickly.
Ninja joins a sea of other build systems. Its distinguishing goal is to be fast. It is born from my work on the Chromium browser project, which has over 30,000 source files and whose other build systems (including one built from custom non-recursive Makefiles) can take ten seconds to start building after changing one file. Ninja is under a second.
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
Here are the design goals of Ninja:
very fast (i.e., instant) incremental builds, even for very large projects.
very little policy about how code is built. Different projects and higher-level build systems have different opinions about how code should be built; for example, should built objects live alongside the sources or should all build output go into a separate directory? Is there an "package" rule that builds a distributable package of the project? Sidestep these decisions by trying to allow either to be implemented, rather than choosing, even if that results in more verbosity.
get dependencies correct, and in particular situations that are difficult to get right with Makefiles (e.g. outputs need an implicit dependency on the command line used to generate them; to build C source code you need to use gcc’s
-Mflags for header dependencies).
when convenience and speed are in conflict, prefer speed.
Some explicit non-goals:
convenient syntax for writing build files by hand. You should generate your ninja files using another program. This is how we can sidestep many policy decisions.
built-in rules. Out of the box, Ninja has no rules for e.g. compiling C code.
build-time customization of the build. Options belong in the program that generates the ninja files.
build-time decision-making ability such as conditionals or search paths. Making decisions is slow.
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
Comparison to Make
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.)
A Ninja rule may point at a path for extra implicit dependency information. This makes it easy to get header dependencies correct for C/C++ code.
A build edge may have multiple outputs.
Outputs implicitly depend on the command line that was used to generate them, which means that changing e.g. compilation flags will cause the outputs to rebuild.
Output directories are always implicitly created before running the command that relies on them.
Rules can provide shorter descriptions of the command being run, so you can print e.g.
CC foo.oinstead of a long command line while building.
Builds are always run in parallel, based by default on the number of CPUs your system has. Underspecified build dependencies will result in incorrect builds.
Command output is always buffered. This means commands running in parallel don’t interleave their output, and when a command fails we can print its failure output next to the full command line that produced the failure.
Using Ninja for your project
Ninja currently works on Unix-like systems. It’s seen the most testing on Linux (and has the best performance there) but it runs fine on Mac OS X and FreeBSD. Ninja has some preliminary Windows support but the full details of the implementation — like how to get C header interdependencies correct and fast when using MSVC’s compiler — is not yet complete.
If your project is small, Ninja’s speed impact is likely unnoticeable. Some build timing numbers are included below. (However, even for small projects it sometimes turns out that Ninja’s limited syntax forces simpler build rules that result in faster builds.) Another way to say this is that if you’re happy with the edit-compile cycle time of your project already then Ninja won’t help.
There are many other build systems that are more user-friendly or featureful than Ninja itself. For some recommendations: the Ninja author found the tup build system influential in Ninja’s design, and thinks redo's design is quite clever.
Ninja’s benefit comes from using it in conjunction with a smarter meta-build system.
The meta-build system used to generate build files for Google Chrome. gyp can generate Ninja files for Linux and Mac and is used by many Chrome developers; support for Windows is in progress. See the Chromium Ninja documentation for more details. gyp is relatively unpopular outside of the Chrome and v8 world.
For Chrome (~30k source files), Ninja reduced no-op builds from around 15 seconds to under one second.
A Mozilla developer compares build systems: "While chromium’s full build is 2.15x slower than firefox’s, a nop build is 78.2x faster! That is really noticeable during development. No incremental build of firefox can be faster than 57.9s, which means that in practice almost all of them will be over a minute."
A widely used meta-build system that can generate Ninja files on Linux as of CMake version 2.8.8. (There is some Mac and Windows support — ReactOS uses Ninja on Windows for their buildbots, but those platforms are not yet officially supported by CMake as the full test suite doesn’t pass.)
For building Blender, one user reported "Single file rebuild is 0.97 sec, same on makefiles was 3.7sec."
For building LLVM on Windows, one user reported no-op build times: "ninja: 0.4s / MSBuild: 11s / jom: 53s".
Ninja ought to fit perfectly into other meta-build software like premake. If you do this work, please let us know!
ninja. By default, it looks for a file named
the current directory and builds all out-of-date targets. You can
specify which targets (files) to build as command line arguments.
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
Ninja supports one environment variable to control its behavior.
The progress status printed before the rule being run. Several placeholders are available:
%s: The number of started edges.
%t: The total number of edges that must be run to complete the build.
%r: The number of currently running edges.
%u: The number of remaining edges to start.
%f: The number of finished edges.
%o: Overall rate of finished edges per second
%c: Current rate of finished edges per second (average over builds specified by -j or its default)
%%: A plain
The default progress status is
"[%s/%t] "(note the trailing space to separate from the build rule). Another example of possible progress status could be
-t flag on the Ninja command line runs some tools that we have
found useful during Ninja’s development. The current tools are:
dump the inputs and outputs of a given target.
browse the dependency graph in a web browser. Clicking a file focuses the view on that file, showing inputs and outputs. This feature requires a Python installation.
output a file in the syntax used by
ninja -t graph mytarget | dot -Tpng -ograph.png
In the Ninja source tree,
output a list of targets either by rule or by depth. If used
output the list of all rules with their description if they have
one. It can be used to know which rule name to pass to
given a list of targets, print a list of commands which, if executed in order, may be used to rebuild those targets, assuming that all output files are out of date.
remove built files. By default it removes all built files
except for those created by the generator. Adding the
If used like
Files created but not referenced in the graph are not removed. This
tool takes in account the
Writing your own Ninja files
The remainder of this manual is only useful if you are constructing Ninja files yourself: for example, if you’re writing a meta-build system or supporting a new language.
Ninja evaluates a graph of dependencies between files, and runs whichever commands are necessary to make your build target up to date. 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
build statements describe the dependency graph of your
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.
cflags = -Wall rule cc command = gcc $cflags -c $in -o $out build foo.o: cc foo.c
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
cflags = -g
can be used on the right side of an equals sign, dereferencing it with a dollar sign, like this:
rule cc command = gcc $cflags -c $in -o $out
Variables can also be referenced using curly braces like
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 is
special and defines the command to run. A full list of special
variables is provided in the reference.)
Within the context of a rule, three additional special variables are
$in expands to the list of input files (
$out to the output file (
foo.o) for the command. For use with
$rspfile_content, there is also
$in_newline, which is the same as
$in, except that multiple inputs are separated by
\n, rather than
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
In the scope of a
build block (including in the evaluation of its
rule), the variable
$in is the list of inputs and the
$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:
cflags = -Wall -Werror rule 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 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 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.
Generating Ninja files from code
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
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
The special rule name
phony can be used to create aliases for other
targets. For example:
build foo: phony some/file/in/a/faraway/subdir/foo
ninja foo build the longer path. Semantically, the
phony rule is equivalent to a plain rule where the
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.
Default target statements
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
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:
default foo bar default baz
This causes Ninja to build the
baz targets by
The Ninja log
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
If you provide a variable named
builddir in the outermost scope,
.ninja_log will be kept in that directory instead.
Ninja file reference
A file is a series of declarations. A declaration can be one of:
A rule declaration, which begins with
rule rulename, and then has a series of indented lines defining variables.
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.)
Variable declarations, which look like
variable = value.
Default target statements, which look like
default target1 target2.
References to more files, which look like
include path. The difference between these is explained below in the discussion about scoping.
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. (To simplify some code, tabs and carriage returns are currently disallowed; this could be fixed if it really mattered to you.)
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
escape the newline (continue the current line across a line break).
a variable reference.
alternate syntax for
a space. (This is only necessary in lists of paths, where a space would otherwise separate filenames. See below.)
a colon. (This is only necessary in
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
spaced = foo bar build $spaced/baz other$ file: ... # The above build line has two outputs: "foo bar/baz" and "other file".
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.
two_words_with_one_space = foo $ bar one_word_with_no_space = foo$ bar
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.
rule block contains a list of
key = value declarations that
affect the processing of the rule. Here is a full list of special
the command line to run. This string (after $variables are expanded) is passed directly to
sh -cwithout interpretation by Ninja. Each
rulemay have only one
commanddeclaration. To specify multiple commands use
&&(or similar) to concatenate operations.
path to an optional
Makefilethat contains extra implicit dependencies (see the reference on dependency types). This is explicitly to support
-Mfamily of flags, which output the list of headers a given
.cfile depends on.
Use it like in the following example:
rule cc depfile = $out.d command = gcc -MMD -MF $out.d [other gcc flags here]
When loading a
depfile, Ninja implicitly adds edges such that it is not an error if the listed dependency is missing. This allows you to delete a depfile-discovered header file and rebuild, without the build aborting due to a missing input.
a short description of the command, used to pretty-print the command as it’s running. The
-vflag controls whether to print the full command or its description; if a command fails, the full command line will always be printed before the command’s output.
if present, specifies that this rule is used to re-invoke the generator program. Files built using
generatorrules are treated specially in two ways: firstly, they will not be rebuilt if the command line changes; and secondly, they are not cleaned by default.
if present, causes Ninja to re-stat the command’s outputs after execution of the command. Each output whose modification time the command did not change will be treated as though it had never needed to be built. This may cause the output’s reverse dependencies to be removed from the list of pending build actions.
if present (both), Ninja will use a response file for the given command, i.e. write the selected string (
rspfile_content) to the given file (
rspfile) before calling the command and delete the file after successful execution of the command.
This is particularly useful on Windows OS, where the maximal length of a command line is limited and response files must be used instead.
Use it like in the following example:
rule link command = link.exe /OUT$out [usual link flags here] @$out.rsp rspfile = $out.rsp rspfile_content = $in build myapp.exe: link a.obj b.obj [possibly many other .obj files]
Finally, the special
$out variables expand to the
shell-quoted space-separated list of files provided to the
line referencing this
There are three types of build dependencies which are subtly different.
Explicit dependencies, as listed in a build line. These are available as the
$invariable in the rule. Changes in these files cause the output to be rebuilt; if these file are missing and Ninja doesn’t know how to build them, the build is aborted.
This is the standard form of dependency to be used for e.g. the source file of a compile command.
Implicit dependencies, either as picked up from a
depfileattribute on a rule or from the syntax
| dep1 dep2on the end of a build line. The semantics are identical to explicit dependencies, the only difference is that implicit dependencies don’t show up in the
This is for expressing dependencies that don’t show up on the command line of the command; for example, for a rule that runs a script, the script itself should be an implicit dependency, as changes to the script should cause the output to rebuild.
Note that dependencies as loaded through depfiles have slightly different semantics, as described in the rule reference.
Order-only dependencies, expressed with the syntax
|| dep1 dep2on the end of a build line. When these are out of date, the output is not rebuilt until they are built, but changes in order-only dependencies alone do not cause the output to be rebuilt.
Order-only dependencies can be useful for bootstrapping dependencies that are only discovered during build time: for example, to generate a header file before starting a subsequent compilation step. (Once the header is used in compilation, a generated dependency file will then express the implicit dependency.)
Evaluation and scoping
Top-level variable declarations are scoped to the file they occur in.
subninja keyword, used to include another
introduces a new scope. The included
subninja file may use the
variables 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
Variable declarations indented in a
build block are scoped to the
build block. This scope is inherited by the
rule. The full
lookup order for a variable referenced in a rule is:
Rule-level variables (i.e.
Build-level variables from the
buildthat references this rule.
File-level variables from the file that the
buildline was in.
Variables from the file that included that file using the
Variables are expanded in paths (in a
and on the right side of a
name = value statement.
name = value statement is evaluated, its right-hand side is
expanded once (according to the above scoping rules) immediately, 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.