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
15 http://neugierig.org/software/chromium/notes/2011/02/ninja.html[my
16 work on the Chromium browser project], which has over 30,000 source
17 files and whose other build systems (including one built from custom
18 non-recursive Makefiles) would take ten seconds to start building
19 after changing one file. Ninja is under a second.
21 Philosophical overview
22 ~~~~~~~~~~~~~~~~~~~~~~
24 Where other build systems are high-level languages, Ninja aims to be
27 Build systems get slow when they need to make decisions. When you are
28 in a edit-compile cycle you want it to be as fast as possible -- you
29 want the build system to do the minimum work necessary to figure out
30 what needs to be built immediately.
32 Ninja contains the barest functionality necessary to describe
33 arbitrary dependency graphs. Its lack of syntax makes it impossible
34 to express complex decisions.
36 Instead, Ninja is intended to be used with a separate program
37 generating its input files. The generator program (like the
38 `./configure` found in autotools projects) can analyze system
39 dependencies and make as many decisions as possible up front so that
40 incremental builds stay fast. Going beyond autotools, even build-time
41 decisions like "which compiler flags should I use?" or "should I
42 build a debug or release-mode binary?" belong in the `.ninja` file
48 Here are the design goals of Ninja:
50 * very fast (i.e., instant) incremental builds, even for very large
53 * very little policy about how code is built. Different projects and
54 higher-level build systems have different opinions about how code
55 should be built; for example, should built objects live alongside
56 the sources or should all build output go into a separate directory?
57 Is there an "package" rule that builds a distributable package of
58 the project? Sidestep these decisions by trying to allow either to
59 be implemented, rather than choosing, even if that results in
62 * get dependencies correct, and in particular situations that are
63 difficult to get right with Makefiles (e.g. outputs need an implicit
64 dependency on the command line used to generate them; to build C
65 source code you need to use gcc's `-M` flags for header
68 * when convenience and speed are in conflict, prefer speed.
70 Some explicit _non-goals_:
72 * convenient syntax for writing build files by hand. _You should
73 generate your ninja files using another program_. This is how we
74 can sidestep many policy decisions.
76 * built-in rules. _Out of the box, Ninja has no rules for
77 e.g. compiling C code._
79 * build-time customization of the build. _Options belong in
80 the program that generates the ninja files_.
82 * build-time decision-making ability such as conditionals or search
83 paths. _Making decisions is slow._
85 To restate, Ninja is faster than other build systems because it is
86 painfully simple. You must tell Ninja exactly what to do when you
87 create your project's `.ninja` files.
92 Ninja is closest in spirit and functionality to Make, relying on
93 simple dependencies between file timestamps.
95 But fundamentally, make has a lot of _features_: suffix rules,
96 functions, built-in rules that e.g. search for RCS files when building
97 source. Make's language was designed to be written by humans. Many
98 projects find make alone adequate for their build problems.
100 In contrast, Ninja has almost no features; just those necessary to get
101 builds correct while punting most complexity to generation of the
102 ninja input files. Ninja by itself is unlikely to be useful for most
105 Here are some of the features Ninja adds to Make. (These sorts of
106 features can often be implemented using more complicated Makefiles,
107 but they are not part of make itself.)
109 * Ninja has special support for discovering extra dependencies at build
110 time, making it easy to get <<ref_headers,header dependencies>>
111 correct for C/C++ code.
113 * A build edge may have multiple outputs.
115 * Outputs implicitly depend on the command line that was used to generate
116 them, which means that changing e.g. compilation flags will cause
117 the outputs to rebuild.
119 * Output directories are always implicitly created before running the
120 command that relies on them.
122 * Rules can provide shorter descriptions of the command being run, so
123 you can print e.g. `CC foo.o` instead of a long command line while
126 * Builds are always run in parallel, based by default on the number of
127 CPUs your system has. Underspecified build dependencies will result
130 * Command output is always buffered. This means commands running in
131 parallel don't interleave their output, and when a command fails we
132 can print its failure output next to the full command line that
133 produced the failure.
136 Using Ninja for your project
137 ----------------------------
139 Ninja currently works on Unix-like systems and Windows. It's seen the
140 most testing on Linux (and has the best performance there) but it runs
141 fine on Mac OS X and FreeBSD.
143 If your project is small, Ninja's speed impact is likely unnoticeable.
144 (However, even for small projects it sometimes turns out that Ninja's
145 limited syntax forces simpler build rules that result in faster
146 builds.) Another way to say this is that if you're happy with the
147 edit-compile cycle time of your project already then Ninja won't help.
149 There are many other build systems that are more user-friendly or
150 featureful than Ninja itself. For some recommendations: the Ninja
151 author found http://gittup.org/tup/[the tup build system] influential
152 in Ninja's design, and thinks https://github.com/apenwarr/redo[redo]'s
153 design is quite clever.
155 Ninja's benefit comes from using it in conjunction with a smarter
158 http://code.google.com/p/gyp/[gyp]:: The meta-build system used to
159 generate build files for Google Chrome and related projects (v8,
160 node.js). gyp can generate Ninja files for all platforms supported by
162 http://code.google.com/p/chromium/wiki/NinjaBuild[Chromium Ninja
163 documentation for more details].
165 http://www.cmake.org/[CMake]:: A widely used meta-build system that
166 can generate Ninja files on Linux as of CMake version 2.8.8. (There
167 is some Mac and Windows support -- http://www.reactos.org[ReactOS]
168 uses Ninja on Windows for their buildbots, but those platforms are not
169 yet officially supported by CMake as the full test suite doesn't
172 others:: Ninja ought to fit perfectly into other meta-build software
173 like http://industriousone.com/premake[premake]. If you do this work,
179 Run `ninja`. By default, it looks for a file named `build.ninja` in
180 the current directory and builds all out-of-date targets. You can
181 specify which targets (files) to build as command line arguments.
183 `ninja -h` prints help output. Many of Ninja's flags intentionally
184 match those of Make; e.g `ninja -C build -j 20` changes into the
185 `build` directory and runs 20 build commands in parallel. (Note that
186 Ninja defaults to running commands in parallel anyway, so typically
187 you don't need to pass `-j`.)
190 Environment variables
191 ~~~~~~~~~~~~~~~~~~~~~
193 Ninja supports one environment variable to control its behavior:
194 `NINJA_STATUS`, the progress status printed before the rule being run.
196 Several placeholders are available:
198 `%s`:: The number of started edges.
199 `%t`:: The total number of edges that must be run to complete the build.
200 `%p`:: The percentage of started edges.
201 `%r`:: The number of currently running edges.
202 `%u`:: The number of remaining edges to start.
203 `%f`:: The number of finished edges.
204 `%o`:: Overall rate of finished edges per second
205 `%c`:: Current rate of finished edges per second (average over builds
206 specified by `-j` or its default)
207 `%e`:: Elapsed time in seconds. _(Available since Ninja 1.2.)_
208 `%%`:: A plain `%` character.
210 The default progress status is `"[%s/%t] "` (note the trailing space
211 to separate from the build rule). Another example of possible progress status
212 could be `"[%u/%r/%f] "`.
217 The `-t` flag on the Ninja command line runs some tools that we have
218 found useful during Ninja's development. The current tools are:
221 `query`:: dump the inputs and outputs of a given target.
223 `browse`:: browse the dependency graph in a web browser. Clicking a
224 file focuses the view on that file, showing inputs and outputs. This
225 feature requires a Python installation.
227 `graph`:: output a file in the syntax used by `graphviz`, a automatic
228 graph layout tool. Use it like:
231 ninja -t graph mytarget | dot -Tpng -ograph.png
234 In the Ninja source tree, `ninja graph.png`
235 generates an image for Ninja itself. If no target is given generate a
236 graph for all root targets.
238 `targets`:: output a list of targets either by rule or by depth. If used
239 like +ninja -t targets rule _name_+ it prints the list of targets
240 using the given rule to be built. If no rule is given, it prints the source
241 files (the leaves of the graph). If used like
242 +ninja -t targets depth _digit_+ it
243 prints the list of targets in a depth-first manner starting by the root
244 targets (the ones with no outputs). Indentation is used to mark dependencies.
245 If the depth is zero it prints all targets. If no arguments are provided
246 +ninja -t targets depth 1+ is assumed. In this mode targets may be listed
247 several times. If used like this +ninja -t targets all+ it
248 prints all the targets available without indentation and it is faster
249 than the _depth_ mode.
251 `commands`:: given a list of targets, print a list of commands which, if
252 executed in order, may be used to rebuild those targets, assuming that all
253 output files are out of date.
255 `clean`:: remove built files. By default it removes all built files
256 except for those created by the generator. Adding the `-g` flag also
257 removes built files created by the generator (see <<ref_rule,the rule
258 reference for the +generator+ attribute>>). Additional arguments are
259 targets, which removes the given targets and recursively all files
262 If used like +ninja -t clean -r _rules_+ it removes all files built using
265 Files created but not referenced in the graph are not removed. This
266 tool takes in account the +-v+ and the +-n+ options (note that +-n+
269 `compdb`:: given a list of rules, each of which is expected to be a
270 C family language compiler rule whose first input is the name of the
271 source file, prints on standard output a compilation database in the
272 http://clang.llvm.org/docs/JSONCompilationDatabase.html[JSON format] expected
273 by the Clang tooling interface.
274 _Available since Ninja 1.2._
277 Writing your own Ninja files
278 ----------------------------
280 The remainder of this manual is only useful if you are constructing
281 Ninja files yourself: for example, if you're writing a meta-build
282 system or supporting a new language.
287 Ninja evaluates a graph of dependencies between files, and runs
288 whichever commands are necessary to make your build target up to date
289 as determined by file modification times. If you are familiar with
290 Make, Ninja is very similar.
292 A build file (default name: `build.ninja`) provides a list of _rules_
293 -- short names for longer commands, like how to run the compiler --
294 along with a list of _build_ statements saying how to build files
295 using the rules -- which rule to apply to which inputs to produce
298 Conceptually, `build` statements describe the dependency graph of your
299 project, while `rule` statements describe how to generate the files
300 along a given edge of the graph.
305 Here's a basic `.ninja` file that demonstrates most of the syntax.
306 It will be used as an example for the following sections.
308 ---------------------------------
312 command = gcc $cflags -c $in -o $out
314 build foo.o: cc foo.c
315 ---------------------------------
319 Despite the non-goal of being convenient to write by hand, to keep
320 build files readable (debuggable), Ninja supports declaring shorter
321 reusable names for strings. A declaration like the following
327 can be used on the right side of an equals sign, dereferencing it with
328 a dollar sign, like this:
332 command = gcc $cflags -c $in -o $out
335 Variables can also be referenced using curly braces like `${in}`.
337 Variables might better be called "bindings", in that a given variable
338 cannot be changed, only shadowed. There is more on how shadowing works
339 later in this document.
344 Rules declare a short name for a command line. They begin with a line
345 consisting of the `rule` keyword and a name for the rule. Then
346 follows an indented set of `variable = value` lines.
348 The basic example above declares a new rule named `cc`, along with the
349 command to run. In the context of a rule, the `command` variable
350 defines the command to run, `$in` expands to the list of
351 input files (`foo.c`), and `$out` to the output files (`foo.o`) for the
352 command. A full list of special variables is provided in
353 <<ref_rule,the reference>>.
358 Build statements declare a relationship between input and output
359 files. They begin with the `build` keyword, and have the format
360 +build _outputs_: _rulename_ _inputs_+. Such a declaration says that
361 all of the output files are derived from the input files. When the
362 output files are missing or when the inputs change, Ninja will run the
363 rule to regenerate the outputs.
365 The basic example above describes how to build `foo.o`, using the `cc`
368 In the scope of a `build` block (including in the evaluation of its
369 associated `rule`), the variable `$in` is the list of inputs and the
370 variable `$out` is the list of outputs.
372 A build statement may be followed by an indented set of `key = value`
373 pairs, much like a rule. These variables will shadow any variables
374 when evaluating the variables in the command. For example:
377 cflags = -Wall -Werror
379 command = gcc $cflags -c $in -o $out
381 # If left unspecified, builds get the outer $cflags.
382 build foo.o: cc foo.c
384 # But you can shadow variables like cflags for a particular build.
385 build special.o: cc special.c
388 # The variable was only shadowed for the scope of special.o;
389 # Subsequent build lines get the outer (original) cflags.
390 build bar.o: cc bar.c
394 For more discussion of how scoping works, consult <<ref_scope,the
397 If you need more complicated information passed from the build
398 statement to the rule (for example, if the rule needs "the file
399 extension of the first input"), pass that through as an extra
400 variable, like how `cflags` is passed above.
402 If the top-level Ninja file is specified as an output of any build
403 statement and it is out of date, Ninja will rebuild and reload it
404 before building the targets requested by the user.
409 _Available since Ninja 1.1._
411 Pools allow you to allocate one or more rules or edges a finite number
412 of concurrent jobs which is more tightly restricted than the default
415 This can be useful, for example, to restrict a particular expensive rule
416 (like link steps for huge executables), or to restrict particular build
417 statements which you know perform poorly when run concurrently.
419 Each pool has a `depth` variable which is specified in the build file.
420 The pool is then referred to with the `pool` variable on either a rule
421 or a build statement.
423 No matter what pools you specify, ninja will never run more concurrent jobs
424 than the default parallelism, or the number of jobs specified on the command
428 # No more than 4 links at a time.
432 # No more than 1 heavy object at a time.
433 pool heavy_object_pool
443 # The link_pool is used here. Only 4 links will run concurrently.
444 build foo.exe: link input.obj
446 # A build statement can be exempted from its rule's pool by setting an
447 # empty pool. This effectively puts the build statement back into the default
448 # pool, which has infinite depth.
449 build other.exe: link input.obj
452 # A build statement can specify a pool directly.
453 # Only one of these builds will run at a time.
454 build heavy_object1.obj: cc heavy_obj1.cc
455 pool = heavy_object_pool
456 build heavy_object2.obj: cc heavy_obj2.cc
457 pool = heavy_object_pool
462 Generating Ninja files from code
463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
465 `misc/ninja_syntax.py` in the Ninja distribution is a tiny Python
466 module to facilitate generating Ninja files. It allows you to make
467 Python calls like `ninja.rule(name='foo', command='bar',
468 depfile='$out.d')` and it will generate the appropriate syntax. Feel
469 free to just inline it into your project's build system if it's
479 The special rule name `phony` can be used to create aliases for other
480 targets. For example:
483 build foo: phony some/file/in/a/faraway/subdir/foo
486 This makes `ninja foo` build the longer path. Semantically, the
487 `phony` rule is equivalent to a plain rule where the `command` does
488 nothing, but phony rules are handled specially in that they aren't
489 printed when run, logged (see below), nor do they contribute to the
490 command count printed as part of the build process.
492 `phony` can also be used to create dummy targets for files which
493 may not exist at build time. If a phony build statement is written
494 without any dependencies, the target will be considered out of date if
495 it does not exist. Without a phony build statement, Ninja will report
496 an error if the file does not exist and is required by the build.
499 Default target statements
500 ~~~~~~~~~~~~~~~~~~~~~~~~~
502 By default, if no targets are specified on the command line, Ninja
503 will build every output that is not named as an input elsewhere.
504 You can override this behavior using a default target statement.
505 A default target statement causes Ninja to build only a given subset
506 of output files if none are specified on the command line.
508 Default target statements begin with the `default` keyword, and have
509 the format +default _targets_+. A default target statement must appear
510 after the build statement that declares the target as an output file.
511 They are cumulative, so multiple statements may be used to extend
512 the list of default targets. For example:
519 This causes Ninja to build the `foo`, `bar` and `baz` targets by
527 For each built file, Ninja keeps a log of the command used to build
528 it. Using this log Ninja can know when an existing output was built
529 with a different command line than the build files specify (i.e., the
530 command line changed) and knows to rebuild the file.
532 The log file is kept in the build root in a file called `.ninja_log`.
533 If you provide a variable named `builddir` in the outermost scope,
534 `.ninja_log` will be kept in that directory instead.
538 Version compatibility
539 ~~~~~~~~~~~~~~~~~~~~~
541 _Available since Ninja 1.2._
543 Ninja version labels follow the standard major.minor.patch format,
544 where the major version is increased on backwards-incompatible
545 syntax/behavioral changes and the minor version is increased on new
546 behaviors. Your `build.ninja` may declare a variable named
547 `ninja_required_version` that asserts the minimum Ninja version
548 required to use the generated file. For example,
551 ninja_required_version = 1.1
554 declares that the build file relies on some feature that was
555 introduced in Ninja 1.1 (perhaps the `pool` syntax), and that
556 Ninja 1.1 or greater must be used to build. Unlike other Ninja
557 variables, this version requirement is checked immediately when
558 the variable is encountered in parsing, so it's best to put it
559 at the top of the build file.
561 Ninja always warns if the major versions of Ninja and the
562 `ninja_required_version` don't match; a major version change hasn't
563 come up yet so it's difficult to predict what behavior might be
567 C/C++ header dependencies
568 ~~~~~~~~~~~~~~~~~~~~~~~~~
570 To get C/C++ header dependencies (or any other build dependency that
571 works in a similar way) correct Ninja has some extra functionality.
573 The problem with headers is that the full list of files that a given
574 source file depends on can only be discovered by the compiler:
575 different preprocessor defines and include paths cause different files
576 to be used. Some compilers can emit this information while building,
577 and Ninja can use that to get its dependencies perfect.
579 Consider: if the file has never been compiled, it must be built anyway,
580 generating the header dependencies as a side effect. If any file is
581 later modified (even in a way that changes which headers it depends
582 on) the modification will cause a rebuild as well, keeping the
583 dependencies up to date.
585 When loading these special dependencies, Ninja implicitly adds extra
586 build edges such that it is not an error if the listed dependency is
587 missing. This allows you to delete a header file and rebuild without
588 the build aborting due to a missing input.
593 `gcc` (and other compilers like `clang`) support emitting dependency
594 information in the syntax of a Makefile. (Any command that can write
595 dependencies in this form can be used, not just `gcc`.)
597 To bring this information into Ninja requires cooperation. On the
598 Ninja side, the `depfile` attribute on the `build` must point to a
599 path where this data is written. (Ninja only supports the limited
600 subset of the Makefile syntax emitted by compilers.) Then the command
601 must know to write dependencies into the `depfile` path.
602 Use it like in the following example:
607 command = gcc -MMD -MF $out.d [other gcc flags here]
610 The `-MMD` flag to `gcc` tells it to output header dependencies, and
611 the `-MF` flag tells it where to write them.
616 _(Available since Ninja 1.3.)_
618 It turns out that for large projects (and particularly on Windows,
619 where the file system is slow) loading these dependency files on
622 Ninja 1.3 can instead process dependencies just after they're generated
623 and save a compacted form of the same information in a Ninja-internal
626 Ninja supports this processing in two forms.
628 1. `deps = gcc` specifies that the tool outputs `gcc`-style dependencies
629 in the form of Makefiles. Adding this to the above example will
630 cause Ninja to process the `depfile` immediately after the
631 compilation finishes, then delete the `.d` file (which is only used
634 2. `deps = msvc` specifies that the tool outputs header dependencies
635 in the form produced by Visual Studio's compiler's
636 http://msdn.microsoft.com/en-us/library/hdkef6tk(v=vs.90).aspx[`/showIncludes`
637 flag]. Briefly, this means the tool outputs specially-formatted lines
638 to its stdout. Ninja then filters these lines from the displayed
639 output. No `depfile` attribute is necessary.
644 command = cl /showIncludes -c $in /Fo$out
651 A file is a series of declarations. A declaration can be one of:
653 1. A rule declaration, which begins with +rule _rulename_+, and
654 then has a series of indented lines defining variables.
656 2. A build edge, which looks like +build _output1_ _output2_:
657 _rulename_ _input1_ _input2_+. +
658 Implicit dependencies may be tacked on the end with +|
659 _dependency1_ _dependency2_+. +
660 Order-only dependencies may be tacked on the end with +||
661 _dependency1_ _dependency2_+. (See <<ref_dependencies,the reference on
664 3. Variable declarations, which look like +_variable_ = _value_+.
666 4. Default target statements, which look like +default _target1_ _target2_+.
668 5. References to more files, which look like +subninja _path_+ or
669 +include _path_+. The difference between these is explained below
670 <<ref_scope,in the discussion about scoping>>.
675 Ninja is mostly encoding agnostic, as long as the bytes Ninja cares
676 about (like slashes in paths) are ASCII. This means e.g. UTF-8 or
677 ISO-8859-1 input files ought to work. (To simplify some code, tabs
678 and carriage returns are currently disallowed; this could be fixed if
679 it really mattered to you.)
681 Comments begin with `#` and extend to the end of the line.
683 Newlines are significant. Statements like `build foo bar` are a set
684 of space-separated tokens that end at the newline. Newlines and
685 spaces within a token must be escaped.
687 There is only one escape character, `$`, and it has the following
691 `$` followed by a newline:: escape the newline (continue the current line
692 across a line break).
694 `$` followed by text:: a variable reference.
696 `${varname}`:: alternate syntax for `$varname`.
698 `$` followed by space:: a space. (This is only necessary in lists of
699 paths, where a space would otherwise separate filenames. See below.)
701 `$:` :: a colon. (This is only necessary in `build` lines, where a colon
702 would otherwise terminate the list of outputs.)
704 `$$`:: a literal `$`.
706 A `build` or `default` statement is first parsed as a space-separated
707 list of filenames and then each name is expanded. This means that
708 spaces within a variable will result in spaces in the expanded
713 build $spaced/baz other$ file: ...
714 # The above build line has two outputs: "foo bar/baz" and "other file".
717 In a `name = value` statement, whitespace at the beginning of a value
718 is always stripped. Whitespace at the beginning of a line after a
719 line continuation is also stripped.
722 two_words_with_one_space = foo $
724 one_word_with_no_space = foo$
728 Other whitespace is only significant if it's at the beginning of a
729 line. If a line is indented more than the previous one, it's
730 considered part of its parent's scope; if it is indented less than the
731 previous one, it closes the previous scope.
737 Two variables are significant when declared in the outermost file scope.
739 `builddir`:: a directory for some Ninja output files. See <<ref_log,the
740 discussion of the build log>>. (You can also store other build output
743 `ninja_required_version`:: the minimum version of Ninja required to process
744 the build correctly. See <<ref_versioning,the discussion of versioning>>.
751 A `rule` block contains a list of `key = value` declarations that
752 affect the processing of the rule. Here is a full list of special
755 `command` (_required_):: the command line to run. This string (after
756 $variables are expanded) is passed directly to `sh -c` without
757 interpretation by Ninja. Each `rule` may have only one `command`
758 declaration. To specify multiple commands use `&&` (or similar) to
759 concatenate operations.
761 `depfile`:: path to an optional `Makefile` that contains extra
762 _implicit dependencies_ (see <<ref_dependencies,the reference on
763 dependency types>>). This is explicitly to support C/C++ header
764 dependencies; see <<ref_headers,the full discussion>>.
766 `deps`:: _(Available since Ninja 1.3.)_ if present, must be one of
767 `gcc` or `msvc` to specify special dependency processing. See
768 <<ref_headers,the full discussion>>. The generated database is
769 stored as `.ninja_deps` in the `builddir`, see <<ref_toplevel,the
770 discussion of `builddir`>>.
772 `description`:: a short description of the command, used to pretty-print
773 the command as it's running. The `-v` flag controls whether to print
774 the full command or its description; if a command fails, the full command
775 line will always be printed before the command's output.
777 `generator`:: if present, specifies that this rule is used to
778 re-invoke the generator program. Files built using `generator`
779 rules are treated specially in two ways: firstly, they will not be
780 rebuilt if the command line changes; and secondly, they are not
783 `in`:: the shell-quoted space-separated list of files provided as
784 inputs to the build line referencing this `rule`. (`$in` is provided
785 solely for convenience; if you need some subset or variant of this
786 list of files, just construct a new variable with that list and use
789 `in_newline`:: the same as `$in` except that multiple inputs are
790 separated by newlines rather than spaces. (For use with
791 `$rspfile_content`; this works around a bug in the MSVC linker where
792 it uses a fixed-size buffer for processing input.)
794 `out`:: the shell-quoted space-separated list of files provided as
795 outputs to the build line referencing this `rule`.
797 `restat`:: if present, causes Ninja to re-stat the command's outputs
798 after execution of the command. Each output whose modification time
799 the command did not change will be treated as though it had never
800 needed to be built. This may cause the output's reverse
801 dependencies to be removed from the list of pending build actions.
803 `rspfile`, `rspfile_content`:: if present (both), Ninja will use a
804 response file for the given command, i.e. write the selected string
805 (`rspfile_content`) to the given file (`rspfile`) before calling the
806 command and delete the file after successful execution of the
809 This is particularly useful on Windows OS, where the maximal length of
810 a command line is limited and response files must be used instead.
812 Use it like in the following example:
816 command = link.exe /OUT$out [usual link flags here] @$out.rsp
818 rspfile_content = $in
820 build myapp.exe: link a.obj b.obj [possibly many other .obj files]
827 There are three types of build dependencies which are subtly different.
829 1. _Explicit dependencies_, as listed in a build line. These are
830 available as the `$in` variable in the rule. Changes in these files
831 cause the output to be rebuilt; if these file are missing and
832 Ninja doesn't know how to build them, the build is aborted.
834 This is the standard form of dependency to be used for e.g. the
835 source file of a compile command.
837 2. _Implicit dependencies_, either as picked up from
838 a `depfile` attribute on a rule or from the syntax +| _dep1_
839 _dep2_+ on the end of a build line. The semantics are identical to
840 explicit dependencies, the only difference is that implicit dependencies
841 don't show up in the `$in` variable.
843 This is for expressing dependencies that don't show up on the
844 command line of the command; for example, for a rule that runs a
845 script, the script itself should be an implicit dependency, as
846 changes to the script should cause the output to rebuild.
848 Note that dependencies as loaded through depfiles have slightly different
849 semantics, as described in the <<ref_rule,rule reference>>.
851 3. _Order-only dependencies_, expressed with the syntax +|| _dep1_
852 _dep2_+ on the end of a build line. When these are out of date, the
853 output is not rebuilt until they are built, but changes in order-only
854 dependencies alone do not cause the output to be rebuilt.
856 Order-only dependencies can be useful for bootstrapping dependencies
857 that are only discovered during build time: for example, to generate a
858 header file before starting a subsequent compilation step. (Once the
859 header is used in compilation, a generated dependency file will then
860 express the implicit dependency.)
865 Variables are expanded in paths (in a `build` or `default` statement)
866 and on the right side of a `name = value` statement.
868 When a `name = value` statement is evaluated, its right-hand side is
869 expanded immediately (according to the below scoping rules), and
870 from then on `$name` expands to the static string as the result of the
871 expansion. It is never the case that you'll need to "double-escape" a
872 value to prevent it from getting expanded twice.
874 All variables are expanded immediately as they're encountered in parsing,
875 with one important exception: variables in `rule` blocks are expanded
876 when the rule is _used_, not when it is declared. In the following
877 example, the `demo` rule prints "this is a demo of bar".
881 command = echo "this is a demo of $foo"
888 Evaluation and scoping
889 ~~~~~~~~~~~~~~~~~~~~~~
891 Top-level variable declarations are scoped to the file they occur in.
893 The `subninja` keyword, used to include another `.ninja` file,
894 introduces a new scope. The included `subninja` file may use the
895 variables from the parent file, and shadow their values for the file's
896 scope, but it won't affect values of the variables in the parent.
898 To include another `.ninja` file in the current scope, much like a C
899 `#include` statement, use `include` instead of `subninja`.
901 Variable declarations indented in a `build` block are scoped to the
902 `build` block. The full lookup order for a variable expanded in a
903 `build` block (or the `rule` is uses) is:
905 1. Special built-in variables (`$in`, `$out`).
907 2. Build-level variables from the `build` block.
909 3. Rule-level variables from the `rule` block (i.e. `$command`).
910 (Note from the above discussion on expansion that these are
911 expanded "late", and may make use of in-scope bindings like `$in`.)
913 4. File-level variables from the file that the `build` line was in.
915 5. Variables from the file that included that file using the