3 Evan Martin <martine@danga.com>
9 Ninja is yet another build system. It takes as input the
10 interdependencies of files (typically source code and output
11 executables) and orchestrates building them, _quickly_.
13 Ninja joins a sea of other build systems. Its distinguishing goal is
14 to be fast. It is born from my work on the Chromium browser project,
15 which has over 30,000 source files and whose other build systems
16 (including one built from custom non-recursive Makefiles) can take ten
17 seconds to start building after changing one file. Ninja is under a
21 Philosophical overview
22 ~~~~~~~~~~~~~~~~~~~~~~
24 Build systems get slow when they need to make decisions. When you are
25 in a edit-compile cycle you want it to be as fast as possible -- you
26 want the build system to do the minimum work necessary to figure out
27 what needs to be built immediately.
29 Ninja contains the barest functionality necessary to describe
30 arbitrary dependency graphs. Its lack of syntax makes it impossible
31 to express complex decisions. Instead, Ninja is intended to be used
32 with a separate program generating its input files. The generator
33 program (like the `./configure` found in autotools projects) can
34 analyze system dependencies and make as many decisions as possible up
35 front so that incremental builds stay fast. Going beyond autotools,
36 even build-time decisions like "which compiler flags should I use?"
37 or "should I build a debug or release-mode binary?" belong in the
38 `.ninja` file generator.
43 Ninja evaluates a graph of dependencies between files, and runs
44 whichever commands are necessary to make your build target up to date.
45 If you are familiar with Make, Ninja is very similar.
47 A build file (default name: `build.ninja`) provides a list of _rules_
48 -- short names for longer commands, like how to run the compiler --
49 along with a list of _build_ statements saying how to build files
50 using the rules -- which rule to apply to which inputs to produce
53 Conceptually, `build` statements describe the dependency graph of your
54 project, while `rule` statements describe how to generate the files
55 along a given edge of the graph.
60 Here are some of the design goals of Ninja:
62 * very fast (i.e., instant) incremental builds, even for very large
65 * very little policy about how code is built; "explicit is better than
68 * get dependencies correct, and in particular situations that are
69 difficult to get right with Makefiles (e.g. outputs need an implicit
70 dependency on the command line used to generate them; to build C
71 source code you need to use gcc's `-M` flags for header
74 * when convenience and speed are in conflict, prefer speed.
76 Some explicit _non-goals_:
78 * convenient syntax for writing build files by hand. _You should
79 generate your ninja files using another program_. This is how we
80 can sidestep many policy decisions.
82 * built-in rules. _Out of the box, Ninja has no rules for
83 e.g. compiling C code._
85 * build-time customization of the build. _Options belong in
86 the program that generates the ninja files_.
88 * build-time decision-making ability such as conditionals or search
89 paths. _Making decisions is slow._
91 To restate, Ninja is faster than other build systems because it is
92 painfully simple. You must tell Ninja exactly what to do when you
93 create your project's `.ninja` files.
95 Comparison to GNU make
96 ~~~~~~~~~~~~~~~~~~~~~~
98 Ninja is closest in spirit and functionality to make. But
99 fundamentally, make has a lot of _features_: suffix rules, functions,
100 built-in rules that e.g. search for RCS files when building source.
101 Many projects find make alone adequate for their build problems. In
102 contrast, Ninja has almost no features; just those necessary to get
103 builds correct while punting most complexity to generation of the
104 ninja input files. Ninja by itself is unlikely to be useful for most
107 Here are some of the features ninja adds to make. (These sorts of
108 features can often be implemented using more complicated Makefiles,
109 but they are not part of make itself.)
111 * A Ninja rule may point at a path for extra implicit dependency
112 information. This makes it easy to get header dependencies correct
115 * A build edge may have multiple outputs.
117 * Outputs implicitly depend on the command line that was used to generate
118 them, which means that changing e.g. compilation flags will cause
119 the outputs to rebuild.
121 * Output directories are always implicitly created before running the
122 command that relies on them.
124 * Rules can provide shorter descriptions of the command being run, so
125 you can print e.g. `CC foo.o` instead of a long command line while
128 * Command output is always buffered. This means commands running in
129 parallel don't interleave their output, and when a command fails we
130 can print its failure output next to the full command line that
131 produced the failure.
137 Start by downloading the code from
138 https://github.com/martine/ninja[the github repo].
140 The included `bootstrap.sh` should hopefully produce a working `ninja`
141 binary, by first blindly compiling all non-test files together then
142 re-building Ninja using itself.
144 Usage is currently just
150 where `target` is a known output described by `build.ninja` in the
153 There is no installation step; the only files of interest to a user
154 are the resulting binary and this manual.
157 Creating .ninja files
158 ---------------------
159 Here's a basic `.ninja` file that demonstrates most of the syntax.
160 It will be used as an example for the following sections.
162 ---------------------------------
166 command = gcc $cflags -c $in -o $out
168 build foo.o: cc foo.c
169 ---------------------------------
173 Despite the non-goal of being convenient to write by hand, to keep
174 build files readable (debuggable), Ninja supports declaring shorter
175 reusable names for strings. A declaration like the following
181 can be used on the right side of an equals sign, dereferencing it with
182 a dollar sign, like this:
186 command = gcc $cflags -c $in -o $out
189 Variables can also be referenced using curly braces like `${in}`.
191 Variables might better be called "bindings", in that a given variable
192 cannot be changed, only shadowed. There is more on how shadowing works
193 later in this document.
198 Rules declare a short name for a command line. They begin with a line
199 consisting of the `rule` keyword and a name for the rule. Then
200 follows an indented set of `variable = value` lines.
202 The basic example above declares a new rule named `cc`, along with the
203 command to run. (In the context of a rule, the `command` variable is
204 special and defines the command to run. A full list of special
205 variables is provided in <<ref_rule,the reference>>.)
207 Within the context of a rule, two additional special variables are
208 available: `$in` expands to the list of input files (`foo.c`) and
209 `$out` to the output file (`foo.o`) for the command.
215 Build statements declare a relationship between input and output
216 files. They begin with the `build` keyword, and have the format
217 +build _outputs_: _rulename_ _inputs_+. Such a declaration says that
218 all of the output files are derived from the input files. When the
219 output files are missing or when the inputs change, Ninja will run the
220 rule to regenerate the outputs.
222 The basic example above describes how to build `foo.o`, using the `cc`
225 In the scope of a `build` block (including in the evaluation of its
226 associated `rule`), the variable `$in` is the list of inputs and the
227 variable `$out` is the list of outputs.
229 A build statement may be followed by an indented set of `key = value`
230 pairs, much like a rule. These variables will shadow any variables
231 when evaluating the variables in the command. For example:
234 cflags = -Wall -Werror
236 command = gcc $cflags -c $in -o $out
238 # If left unspecified, builds get the outer $cflags.
239 build foo.o: cc foo.c
241 # But you can can shadow variables like cflags for a particular build.
242 build special.o: cc special.c
245 # The variable was only shadowed for the scope of special.o;
246 # Subsequent build lines get the outer (original) cflags.
247 build bar.o: cc bar.c
251 For more discussion of how scoping works, consult <<ref_scope,the
254 If you need more complicated information passed from the build
255 statement to the rule (for example, if the rule needs "the file
256 extension of the first input"), pass that through as an extra
257 variable, like how `cflags` is passed above.
259 If the top-level Ninja file is specified as an output of any build
260 statement and it is out of date, Ninja will rebuild and reload it
261 before building the targets requested by the user.
267 The special rule name `phony` can be used to create aliases for other
268 targets. For example:
271 build foo: phony some/file/in/a/faraway/subdir/foo
274 This makes `ninja foo` build the longer path. Semantically, the
275 `phony` rule is equivalent to a plain rule where the `command` does
276 nothing, but phony rules are handled specially in that they aren't
277 printed when run, logged (see below), nor do they contribute to the
278 command count printed as part of the build process.
280 `phony' can also be used to create dummy targets for files which
281 may not exist at build time. If a phony build statement is written
282 without any dependencies, the target will be considered out of date if
283 it does not exist. Without a phony build statement, Ninja will report
284 an error if the file does not exist and is required by the build.
287 Default target statements
288 ~~~~~~~~~~~~~~~~~~~~~~~~~
290 By default, if no targets are specified on the command line, Ninja
291 will build every output that is not named as an input elsewhere.
292 You can override this behavior using a default target statement.
293 A default target statement causes Ninja to build only a given subset
294 of output files if none are specified on the command line.
296 Default target statements begin with the `default` keyword, and have
297 the format +default _targets_+. A default target statement must appear
298 after the build statement that declares the target as an output file.
299 They are cumulative, so multiple statements may be used to extend
300 the list of default targets. For example:
307 This causes Ninja to build the `foo`, `bar` and `baz` targets by
314 For each built file, Ninja keeps a log of the command used to build
315 it. Using this log Ninja can know when an existing output was built
316 with a different command line than the build files specify (i.e., the
317 command line changed) and knows to rebuild the file.
319 The log file is kept in the build root in a file called `.ninja_log`.
320 If you provide a variable named `builddir` in the outermost scope,
321 `.ninja_log` will be kept in that directory instead.
324 Generating Ninja files
325 ----------------------
327 The Ninja distribution includes a tiny (<100 line) Python module to
328 facilitate generating Ninja files. It allows you to make Python calls
329 like `ninja.rule(name='foo', command='bar', depfile='$out.d')` and
330 it will generate the appropriate syntax.
332 Integration with other build systems
333 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
335 *gyp*. http://gyp.googlecode.com[gyp, the system used to generate build
336 files for the Chromium browser] can generate ninja files for Linux.
337 See http://code.google.com/p/chromium/wiki/NinjaBuild[the Chromium
338 Ninja documentation] for details.
340 *CMake*. Various people have worked on generating Ninja files from
341 CMake. Currently, it sounds like
342 https://github.com/pcc/CMake/tree/ninja-generator[pcc's branch] is the
345 *Autotools*. In theory, you could coax Automake into producing
346 .ninja files as well, but I haven't tried it. It may very well be the
347 case that most projects use too much Makefile syntax in their `.am`
348 files for this to work.
353 The `-t` flag on the Ninja command line runs some tools that I have
354 found useful during Ninja's development. The current tools are:
356 `query`:: dump the inputs and outputs of a given target.
358 `browse`:: browse the dependency graph in a web browser. Clicking a
359 file focuses the view on that file, showing inputs and outputs. This
360 feature requires a Python installation.
362 `graph`:: output a file in the syntax used by `graphviz`, a automatic
363 graph layout tool. Use it like: +ninja -t graph _target_ | dot -Tpng
364 -ograph.png /dev/stdin+ . In the Ninja source tree, `ninja graph`
365 generates an image for Ninja itself. If no target is given generate a
366 graph for all root targets.
368 `targets`:: output a list of targets either by rule or by depth. If used
369 like this +ninja -t targets rule _name_+ it prints the list of targets
370 using the given rule to be built. If no rule is given, it prints the source
371 files (the leaves of the graph). If used like this
372 +ninja -t targets depth _digit_+ it
373 prints the list of targets in a depth-first manner starting by the root
374 targets (the ones with no outputs). Indentation is used to mark dependencies.
375 If the depth is zero it prints all targets. If no arguments are provided
376 +ninja -t targets depth 1+ is assumed. In this mode targets may be listed
377 several times. If used like this +ninja -t targets all+ it
378 prints all the targets available without indentation and it is way faster
379 than the _depth_ mode. It returns non-zero if an error occurs.
381 `rules`:: output the list of all rules with their description if they have
382 one. It can be used to know which rule name to pass to
383 +ninja -t targets rule _name_+.
385 `clean`:: remove built files. If used like this +ninja -t clean+ it
386 removes all the built files. If used like this
387 +ninja -t clean _targets..._+ or like this
388 +ninja -t clean target _targets..._+ it removes the given targets and
389 recursively all files built for it. If used like this
390 +ninja -t clean rule _rules_+ it removes all files built using the given
391 rules. The depfiles are not removed. Files created but not referenced in
392 the graph are not removed. This tool takes in account the +-v+ and the
393 +-n+ options (note that +-n+ implies +-v+). It returns non-zero if an
399 A file is a series of declarations. A declaration can be one of:
401 1. A rule declaration, which begins with +rule _rulename_+, and
402 then has a series of indented lines defining variables.
404 2. A build edge, which looks like +build _output1_ _output2_:
405 _rulename_ _input1_ _input2_+. +
406 Implicit dependencies may be tacked on the end with +|
407 _dependency1_ _dependency2_+. +
408 Order-only dependencies may be tacked on the end with +||
409 _dependency1_ _dependency2_+. (See <<ref_dependencies,the reference on
412 3. Variable declarations, which look like +_variable_ = _value_+.
414 4. Default target statements, which look like +default _target1_ _target2_+.
416 5. References to more files, which look like +subninja _path_+ or
417 +include _path_+. The difference between these is explained below
418 <<ref_scope,in the discussion about scoping>>.
420 Comments begin with `#` and extend to the end of the line.
422 Newlines are significant, but they can be escaped by putting a `$`
423 before them. To produce a literal `$` in a path or variable value use
426 Other whitespace is only significant if it's at the beginning of a
427 line. If a line is intended more than the previous one, it's
428 considered part of its parent's scope; if it is indented less than the
429 previous one, it closes the previous scope.
435 A `rule` block contains a list of `key = value` declarations that
436 affect the processing of the rule. Here is a full list of special
439 `command` (_required_):: the command line to run. This string (after
440 $variables are expanded) is passed directly to `sh -c` without
441 interpretation by Ninja.
443 `depfile`:: path to an optional `Makefile` that contains extra
444 _implicit dependencies_ (see <<ref_dependencies,the reference on
445 dependency types>>). This is explicitly to support `gcc` and its `-M`
446 family of flags, which output the list of headers a given `.c` file
449 Use it like in the following example:
454 command = gcc -MMD -MF $out.d [other gcc flags here]
457 When loading a `depfile`, Ninja implicitly adds edges such that it is
458 not an error if the listed dependency is missing. This allows you to
459 delete a depfile-discovered header file and rebuild, without the build
460 aborting due to a missing input.
462 `description`:: a short description of the command, used to pretty-print
463 the command as it's running. The `-v` flag controls whether to print
464 the full command or its description; if a command fails, the full command
465 line will always be printed before the command's output.
467 Additionally, the special `$in` and `$out` variables expand to the
468 space-separated list of files provided to the `build` line referencing
475 There are three types of build dependencies which are subtly different.
477 1. _Explicit dependencies_, as listed in a build line. These are
478 available as the `$in` variable in the rule. Changes in these files
479 cause the output to be rebuilt; if these file are missing and
480 Ninja doesn't know how to build them, the build is aborted.
482 This is the standard form of dependency to be used for e.g. the
483 source file of a compile command.
485 2. _Implicit dependencies_, either as picked up from
486 a `depfile` attribute on a rule or from the syntax +| _dep1_
487 _dep2_+ on the end of a build line. The semantics are identical to
488 explicit dependencies, the only difference is that implicit dependencies
489 don't show up in the `$in` variable.
491 This is for expressing dependencies that don't show up on the
492 command line of the command; for example, for a rule that runs a
493 script, the script itself should be an implicit dependency, as
494 changes to the script should cause the output to rebuild.
496 Note that dependencies as loaded through depfiles have slightly different
497 semantics, as described in the <<ref_rule,rule reference>>.
499 3. _Order-only dependencies_, expressed with the syntax +|| _dep1_
500 _dep2_+ on the end of a build line. When these are missing, the
501 output is not rebuilt until they are built, but once they are
502 available further changes to the files do not affect the output.
504 Order-only dependencies can be useful for bootstrapping dependencies
505 that are only discovered during build time: for example, to generate a
506 header file before starting a subsequent compilation step. (Once the
507 header is used in compilation, a generated dependency file will then
508 express the implicit dependency.)
510 Evaluation and scoping
511 ~~~~~~~~~~~~~~~~~~~~~~
514 Top-level variable declarations are scoped to the file they occur in.
516 The `subninja` keyword, used to include another `.ninja` file,
517 introduces a new scope. The included `subninja` file may use the
518 variables from the parent file, and shadow their values for the file's
519 scope, but it won't affect values of the variables in the parent.
521 To include another `.ninja` file in the current scope, much like a C
522 `#include` statement, use `include` instead of `subninja`.
524 Variable declarations indented in a `build` block are scoped to the
525 `build` block. This scope is inherited by the `rule`. The full
526 lookup order for a variable referenced in a rule is:
528 1. Rule-level variables (i.e. `$in`, `$command`).
530 2. Build-level variables from the `build` that references this rule.
532 3. File-level variables from the file that the `build` line was in.
534 4. Variables from the file that included that file using the
540 Variables are expanded in three cases: in the right side of a `name =
541 value` statement, in paths in a `build` statement and in paths in
542 a `default` statement.
544 When a `name = value` statement is evaluated, its right-hand side is
545 expanded once (according to the above scoping rules) immediately, and
546 from then on `$name` expands to the static string as the result of the
547 expansion. It is never the case that you'll need to "double-escape" a
548 variable with some syntax like `$$foo`.
550 A `build` or `default` statement is first parsed as a space-separated
551 list of filenames and then each name is expanded. This means that
552 spaces within a variable will result in spaces in the expanded
557 build $spaced/baz other: ...
558 # The above build line has two outputs: "foo bar/baz" and "other".
561 In a `name = value` statement, whitespace at the beginning of a value
562 is always stripped. Whitespace at the beginning of a line after a
563 line continuation is also stripped.
566 two_words_with_one_space = foo $
568 one_word_with_no_space = foo$
576 Some pieces I'd like to add:
578 _inotify_. I had originally intended to make Ninja be memory-resident
579 and to use `inotify` to keep the build state hot at all times. But
580 upon writing the code I found it was fast enough to run from scratch
581 each time. Perhaps a slower computer would still benefit from
582 inotify; the data structures are set up such that using inotify
585 _build estimation and analysis_. As part of build correctness, Ninja
586 keeps a log of the time spent on each build statement. This log
587 format could be adjusted to instead store timing information across
588 multiple runs. From that, the total time necessary to build could be
589 estimated, allowing Ninja to print status like "3 minutes until
590 complete" when building. Additionally, a tool could output which
591 commands are the slowest or which directories take the most time
594 _many others_. See the `todo` file included in the distribution.