8 Ninja is yet another build system. It takes as input the
9 interdependencies of files (typically source code and output
10 executables) and orchestrates building them, _quickly_.
12 Ninja joins a sea of other build systems. Its distinguishing goal is
13 to be fast. It is born from
14 http://neugierig.org/software/chromium/notes/2011/02/ninja.html[my
15 work on the Chromium browser project], which has over 30,000 source
16 files and whose other build systems (including one built from custom
17 non-recursive Makefiles) would take ten seconds to start building
18 after changing one file. Ninja is under a second.
20 Philosophical overview
21 ~~~~~~~~~~~~~~~~~~~~~~
23 Where other build systems are high-level languages, Ninja aims to be
26 Build systems get slow when they need to make decisions. When you are
27 in a edit-compile cycle you want it to be as fast as possible -- you
28 want the build system to do the minimum work necessary to figure out
29 what needs to be built immediately.
31 Ninja contains the barest functionality necessary to describe
32 arbitrary dependency graphs. Its lack of syntax makes it impossible
33 to express complex decisions.
35 Instead, Ninja is intended to be used with a separate program
36 generating its input files. The generator program (like the
37 `./configure` found in autotools projects) can analyze system
38 dependencies and make as many decisions as possible up front so that
39 incremental builds stay fast. Going beyond autotools, even build-time
40 decisions like "which compiler flags should I use?" or "should I
41 build a debug or release-mode binary?" belong in the `.ninja` file
47 Here are the design goals of Ninja:
49 * very fast (i.e., instant) incremental builds, even for very large
52 * very little policy about how code is built. Different projects and
53 higher-level build systems have different opinions about how code
54 should be built; for example, should built objects live alongside
55 the sources or should all build output go into a separate directory?
56 Is there a "package" rule that builds a distributable package of
57 the project? Sidestep these decisions by trying to allow either to
58 be implemented, rather than choosing, even if that results in
61 * get dependencies correct, and in particular situations that are
62 difficult to get right with Makefiles (e.g. outputs need an implicit
63 dependency on the command line used to generate them; to build C
64 source code you need to use gcc's `-M` flags for header
67 * when convenience and speed are in conflict, prefer speed.
69 Some explicit _non-goals_:
71 * convenient syntax for writing build files by hand. _You should
72 generate your ninja files using another program_. This is how we
73 can sidestep many policy decisions.
75 * built-in rules. _Out of the box, Ninja has no rules for
76 e.g. compiling C code._
78 * build-time customization of the build. _Options belong in
79 the program that generates the ninja files_.
81 * build-time decision-making ability such as conditionals or search
82 paths. _Making decisions is slow._
84 To restate, Ninja is faster than other build systems because it is
85 painfully simple. You must tell Ninja exactly what to do when you
86 create your project's `.ninja` files.
91 Ninja is closest in spirit and functionality to Make, relying on
92 simple dependencies between file timestamps.
94 But fundamentally, make has a lot of _features_: suffix rules,
95 functions, built-in rules that e.g. search for RCS files when building
96 source. Make's language was designed to be written by humans. Many
97 projects find make alone adequate for their build problems.
99 In contrast, Ninja has almost no features; just those necessary to get
100 builds correct while punting most complexity to generation of the
101 ninja input files. Ninja by itself is unlikely to be useful for most
104 Here are some of the features Ninja adds to Make. (These sorts of
105 features can often be implemented using more complicated Makefiles,
106 but they are not part of make itself.)
108 * Ninja has special support for discovering extra dependencies at build
109 time, making it easy to get <<ref_headers,header dependencies>>
110 correct for C/C++ code.
112 * A build edge may have multiple outputs.
114 * Outputs implicitly depend on the command line that was used to generate
115 them, which means that changing e.g. compilation flags will cause
116 the outputs to rebuild.
118 * Output directories are always implicitly created before running the
119 command that relies on them.
121 * Rules can provide shorter descriptions of the command being run, so
122 you can print e.g. `CC foo.o` instead of a long command line while
125 * Builds are always run in parallel, based by default on the number of
126 CPUs your system has. Underspecified build dependencies will result
129 * Command output is always buffered. This means commands running in
130 parallel don't interleave their output, and when a command fails we
131 can print its failure output next to the full command line that
132 produced the failure.
135 Using Ninja for your project
136 ----------------------------
138 Ninja currently works on Unix-like systems and Windows. It's seen the
139 most testing on Linux (and has the best performance there) but it runs
140 fine on Mac OS X and FreeBSD.
142 If your project is small, Ninja's speed impact is likely unnoticeable.
143 (However, even for small projects it sometimes turns out that Ninja's
144 limited syntax forces simpler build rules that result in faster
145 builds.) Another way to say this is that if you're happy with the
146 edit-compile cycle time of your project already then Ninja won't help.
148 There are many other build systems that are more user-friendly or
149 featureful than Ninja itself. For some recommendations: the Ninja
150 author found http://gittup.org/tup/[the tup build system] influential
151 in Ninja's design, and thinks https://github.com/apenwarr/redo[redo]'s
152 design is quite clever.
154 Ninja's benefit comes from using it in conjunction with a smarter
157 http://code.google.com/p/gyp/[gyp]:: The meta-build system used to
158 generate build files for Google Chrome and related projects (v8,
159 node.js). gyp can generate Ninja files for all platforms supported by
161 https://chromium.googlesource.com/chromium/src/+/master/docs/ninja_build.md[Chromium Ninja documentation for more details].
163 https://cmake.org/[CMake]:: A widely used meta-build system that
164 can generate Ninja files on Linux as of CMake version 2.8.8. Newer versions
165 of CMake support generating Ninja files on Windows and Mac OS X too.
167 https://github.com/ninja-build/ninja/wiki/List-of-generators-producing-ninja-build-files[others]:: Ninja ought to fit perfectly into other meta-build software
168 like http://industriousone.com/premake[premake]. If you do this work,
174 Run `ninja`. By default, it looks for a file named `build.ninja` in
175 the current directory and builds all out-of-date targets. You can
176 specify which targets (files) to build as command line arguments.
178 There is also a special syntax `target^` for specifying a target
179 as the first output of some rule containing the source you put in
180 the command line, if one exists. For example, if you specify target as
181 `foo.c^` then `foo.o` will get built (assuming you have those targets
182 in your build files).
184 `ninja -h` prints help output. Many of Ninja's flags intentionally
185 match those of Make; e.g `ninja -C build -j 20` changes into the
186 `build` directory and runs 20 build commands in parallel. (Note that
187 Ninja defaults to running commands in parallel anyway, so typically
188 you don't need to pass `-j`.)
191 Environment variables
192 ~~~~~~~~~~~~~~~~~~~~~
194 Ninja supports one environment variable to control its behavior:
195 `NINJA_STATUS`, the progress status printed before the rule being run.
197 Several placeholders are available:
199 `%s`:: The number of started edges.
200 `%t`:: The total number of edges that must be run to complete the build.
201 `%p`:: The percentage of started edges.
202 `%r`:: The number of currently running edges.
203 `%u`:: The number of remaining edges to start.
204 `%f`:: The number of finished edges.
205 `%o`:: Overall rate of finished edges per second
206 `%c`:: Current rate of finished edges per second (average over builds
207 specified by `-j` or its default)
208 `%e`:: Elapsed time in seconds. _(Available since Ninja 1.2.)_
209 `%%`:: A plain `%` character.
211 The default progress status is `"[%s/%t] "` (note the trailing space
212 to separate from the build rule). Another example of possible progress status
213 could be `"[%u/%r/%f] "`.
218 The `-t` flag on the Ninja command line runs some tools that we have
219 found useful during Ninja's development. The current tools are:
222 `query`:: dump the inputs and outputs of a given target.
224 `browse`:: browse the dependency graph in a web browser. Clicking a
225 file focuses the view on that file, showing inputs and outputs. This
226 feature requires a Python installation. The `PORT` environment variable
227 can be used to override the default port number (8000).
229 `graph`:: output a file in the syntax used by `graphviz`, a automatic
230 graph layout tool. Use it like:
233 ninja -t graph mytarget | dot -Tpng -ograph.png
236 In the Ninja source tree, `ninja graph.png`
237 generates an image for Ninja itself. If no target is given generate a
238 graph for all root targets.
240 `targets`:: output a list of targets either by rule or by depth. If used
241 like +ninja -t targets rule _name_+ it prints the list of targets
242 using the given rule to be built. If no rule is given, it prints the source
243 files (the leaves of the graph). If used like
244 +ninja -t targets depth _digit_+ it
245 prints the list of targets in a depth-first manner starting by the root
246 targets (the ones with no outputs). Indentation is used to mark dependencies.
247 If the depth is zero it prints all targets. If no arguments are provided
248 +ninja -t targets depth 1+ is assumed. In this mode targets may be listed
249 several times. If used like this +ninja -t targets all+ it
250 prints all the targets available without indentation and it is faster
251 than the _depth_ mode.
253 `commands`:: given a list of targets, print a list of commands which, if
254 executed in order, may be used to rebuild those targets, assuming that all
255 output files are out of date.
257 `clean`:: remove built files. By default it removes all built files
258 except for those created by the generator. Adding the `-g` flag also
259 removes built files created by the generator (see <<ref_rule,the rule
260 reference for the +generator+ attribute>>). Additional arguments are
261 targets, which removes the given targets and recursively all files
264 If used like +ninja -t clean -r _rules_+ it removes all files built using
267 Files created but not referenced in the graph are not removed. This
268 tool takes in account the +-v+ and the +-n+ options (note that +-n+
271 `compdb`:: given a list of rules, each of which is expected to be a
272 C family language compiler rule whose first input is the name of the
273 source file, prints on standard output a compilation database in the
274 http://clang.llvm.org/docs/JSONCompilationDatabase.html[JSON format] expected
275 by the Clang tooling interface.
276 _Available since Ninja 1.2._
279 Writing your own Ninja files
280 ----------------------------
282 The remainder of this manual is only useful if you are constructing
283 Ninja files yourself: for example, if you're writing a meta-build
284 system or supporting a new language.
289 Ninja evaluates a graph of dependencies between files, and runs
290 whichever commands are necessary to make your build target up to date
291 as determined by file modification times. If you are familiar with
292 Make, Ninja is very similar.
294 A build file (default name: `build.ninja`) provides a list of _rules_
295 -- short names for longer commands, like how to run the compiler --
296 along with a list of _build_ statements saying how to build files
297 using the rules -- which rule to apply to which inputs to produce
300 Conceptually, `build` statements describe the dependency graph of your
301 project, while `rule` statements describe how to generate the files
302 along a given edge of the graph.
307 Here's a basic `.ninja` file that demonstrates most of the syntax.
308 It will be used as an example for the following sections.
310 ---------------------------------
314 command = gcc $cflags -c $in -o $out
316 build foo.o: cc foo.c
317 ---------------------------------
321 Despite the non-goal of being convenient to write by hand, to keep
322 build files readable (debuggable), Ninja supports declaring shorter
323 reusable names for strings. A declaration like the following
329 can be used on the right side of an equals sign, dereferencing it with
330 a dollar sign, like this:
334 command = gcc $cflags -c $in -o $out
337 Variables can also be referenced using curly braces like `${in}`.
339 Variables might better be called "bindings", in that a given variable
340 cannot be changed, only shadowed. There is more on how shadowing works
341 later in this document.
346 Rules declare a short name for a command line. They begin with a line
347 consisting of the `rule` keyword and a name for the rule. Then
348 follows an indented set of `variable = value` lines.
350 The basic example above declares a new rule named `cc`, along with the
351 command to run. In the context of a rule, the `command` variable
352 defines the command to run, `$in` expands to the list of
353 input files (`foo.c`), and `$out` to the output files (`foo.o`) for the
354 command. A full list of special variables is provided in
355 <<ref_rule,the reference>>.
360 Build statements declare a relationship between input and output
361 files. They begin with the `build` keyword, and have the format
362 +build _outputs_: _rulename_ _inputs_+. Such a declaration says that
363 all of the output files are derived from the input files. When the
364 output files are missing or when the inputs change, Ninja will run the
365 rule to regenerate the outputs.
367 The basic example above describes how to build `foo.o`, using the `cc`
370 In the scope of a `build` block (including in the evaluation of its
371 associated `rule`), the variable `$in` is the list of inputs and the
372 variable `$out` is the list of outputs.
374 A build statement may be followed by an indented set of `key = value`
375 pairs, much like a rule. These variables will shadow any variables
376 when evaluating the variables in the command. For example:
379 cflags = -Wall -Werror
381 command = gcc $cflags -c $in -o $out
383 # If left unspecified, builds get the outer $cflags.
384 build foo.o: cc foo.c
386 # But you can shadow variables like cflags for a particular build.
387 build special.o: cc special.c
390 # The variable was only shadowed for the scope of special.o;
391 # Subsequent build lines get the outer (original) cflags.
392 build bar.o: cc bar.c
396 For more discussion of how scoping works, consult <<ref_scope,the
399 If you need more complicated information passed from the build
400 statement to the rule (for example, if the rule needs "the file
401 extension of the first input"), pass that through as an extra
402 variable, like how `cflags` is passed above.
404 If the top-level Ninja file is specified as an output of any build
405 statement and it is out of date, Ninja will rebuild and reload it
406 before building the targets requested by the user.
408 Generating Ninja files from code
409 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
411 `misc/ninja_syntax.py` in the Ninja distribution is a tiny Python
412 module to facilitate generating Ninja files. It allows you to make
413 Python calls like `ninja.rule(name='foo', command='bar',
414 depfile='$out.d')` and it will generate the appropriate syntax. Feel
415 free to just inline it into your project's build system if it's
425 The special rule name `phony` can be used to create aliases for other
426 targets. For example:
429 build foo: phony some/file/in/a/faraway/subdir/foo
432 This makes `ninja foo` build the longer path. Semantically, the
433 `phony` rule is equivalent to a plain rule where the `command` does
434 nothing, but phony rules are handled specially in that they aren't
435 printed when run, logged (see below), nor do they contribute to the
436 command count printed as part of the build process.
438 `phony` can also be used to create dummy targets for files which
439 may not exist at build time. If a phony build statement is written
440 without any dependencies, the target will be considered out of date if
441 it does not exist. Without a phony build statement, Ninja will report
442 an error if the file does not exist and is required by the build.
445 Default target statements
446 ~~~~~~~~~~~~~~~~~~~~~~~~~
448 By default, if no targets are specified on the command line, Ninja
449 will build every output that is not named as an input elsewhere.
450 You can override this behavior using a default target statement.
451 A default target statement causes Ninja to build only a given subset
452 of output files if none are specified on the command line.
454 Default target statements begin with the `default` keyword, and have
455 the format +default _targets_+. A default target statement must appear
456 after the build statement that declares the target as an output file.
457 They are cumulative, so multiple statements may be used to extend
458 the list of default targets. For example:
465 This causes Ninja to build the `foo`, `bar` and `baz` targets by
473 For each built file, Ninja keeps a log of the command used to build
474 it. Using this log Ninja can know when an existing output was built
475 with a different command line than the build files specify (i.e., the
476 command line changed) and knows to rebuild the file.
478 The log file is kept in the build root in a file called `.ninja_log`.
479 If you provide a variable named `builddir` in the outermost scope,
480 `.ninja_log` will be kept in that directory instead.
484 Version compatibility
485 ~~~~~~~~~~~~~~~~~~~~~
487 _Available since Ninja 1.2._
489 Ninja version labels follow the standard major.minor.patch format,
490 where the major version is increased on backwards-incompatible
491 syntax/behavioral changes and the minor version is increased on new
492 behaviors. Your `build.ninja` may declare a variable named
493 `ninja_required_version` that asserts the minimum Ninja version
494 required to use the generated file. For example,
497 ninja_required_version = 1.1
500 declares that the build file relies on some feature that was
501 introduced in Ninja 1.1 (perhaps the `pool` syntax), and that
502 Ninja 1.1 or greater must be used to build. Unlike other Ninja
503 variables, this version requirement is checked immediately when
504 the variable is encountered in parsing, so it's best to put it
505 at the top of the build file.
507 Ninja always warns if the major versions of Ninja and the
508 `ninja_required_version` don't match; a major version change hasn't
509 come up yet so it's difficult to predict what behavior might be
513 C/C++ header dependencies
514 ~~~~~~~~~~~~~~~~~~~~~~~~~
516 To get C/C++ header dependencies (or any other build dependency that
517 works in a similar way) correct Ninja has some extra functionality.
519 The problem with headers is that the full list of files that a given
520 source file depends on can only be discovered by the compiler:
521 different preprocessor defines and include paths cause different files
522 to be used. Some compilers can emit this information while building,
523 and Ninja can use that to get its dependencies perfect.
525 Consider: if the file has never been compiled, it must be built anyway,
526 generating the header dependencies as a side effect. If any file is
527 later modified (even in a way that changes which headers it depends
528 on) the modification will cause a rebuild as well, keeping the
529 dependencies up to date.
531 When loading these special dependencies, Ninja implicitly adds extra
532 build edges such that it is not an error if the listed dependency is
533 missing. This allows you to delete a header file and rebuild without
534 the build aborting due to a missing input.
539 `gcc` (and other compilers like `clang`) support emitting dependency
540 information in the syntax of a Makefile. (Any command that can write
541 dependencies in this form can be used, not just `gcc`.)
543 To bring this information into Ninja requires cooperation. On the
544 Ninja side, the `depfile` attribute on the `build` must point to a
545 path where this data is written. (Ninja only supports the limited
546 subset of the Makefile syntax emitted by compilers.) Then the command
547 must know to write dependencies into the `depfile` path.
548 Use it like in the following example:
553 command = gcc -MMD -MF $out.d [other gcc flags here]
556 The `-MMD` flag to `gcc` tells it to output header dependencies, and
557 the `-MF` flag tells it where to write them.
562 _(Available since Ninja 1.3.)_
564 It turns out that for large projects (and particularly on Windows,
565 where the file system is slow) loading these dependency files on
568 Ninja 1.3 can instead process dependencies just after they're generated
569 and save a compacted form of the same information in a Ninja-internal
572 Ninja supports this processing in two forms.
574 1. `deps = gcc` specifies that the tool outputs `gcc`-style dependencies
575 in the form of Makefiles. Adding this to the above example will
576 cause Ninja to process the `depfile` immediately after the
577 compilation finishes, then delete the `.d` file (which is only used
580 2. `deps = msvc` specifies that the tool outputs header dependencies
581 in the form produced by Visual Studio's compiler's
582 http://msdn.microsoft.com/en-us/library/hdkef6tk(v=vs.90).aspx[`/showIncludes`
583 flag]. Briefly, this means the tool outputs specially-formatted lines
584 to its stdout. Ninja then filters these lines from the displayed
585 output. No `depfile` attribute is necessary, but the localized string
586 in front of the the header file path. For instance
587 `msvc_deps_prefix = Note: including file: `
588 for a English Visual Studio (the default). Should be globally defined.
591 msvc_deps_prefix = Note: including file:
594 command = cl /showIncludes -c $in /Fo$out
597 If the include directory directives are using absolute paths, your depfile
598 may result in a mixture of relative and absolute paths. Paths used by other
599 build rules need to match exactly. Therefore, it is recommended to use
600 relative paths in these cases.
606 _Available since Ninja 1.1._
608 Pools allow you to allocate one or more rules or edges a finite number
609 of concurrent jobs which is more tightly restricted than the default
612 This can be useful, for example, to restrict a particular expensive rule
613 (like link steps for huge executables), or to restrict particular build
614 statements which you know perform poorly when run concurrently.
616 Each pool has a `depth` variable which is specified in the build file.
617 The pool is then referred to with the `pool` variable on either a rule
618 or a build statement.
620 No matter what pools you specify, ninja will never run more concurrent jobs
621 than the default parallelism, or the number of jobs specified on the command
625 # No more than 4 links at a time.
629 # No more than 1 heavy object at a time.
630 pool heavy_object_pool
640 # The link_pool is used here. Only 4 links will run concurrently.
641 build foo.exe: link input.obj
643 # A build statement can be exempted from its rule's pool by setting an
644 # empty pool. This effectively puts the build statement back into the default
645 # pool, which has infinite depth.
646 build other.exe: link input.obj
649 # A build statement can specify a pool directly.
650 # Only one of these builds will run at a time.
651 build heavy_object1.obj: cc heavy_obj1.cc
652 pool = heavy_object_pool
653 build heavy_object2.obj: cc heavy_obj2.cc
654 pool = heavy_object_pool
661 _Available since Ninja 1.5._
663 There exists a pre-defined pool named `console` with a depth of 1. It has
664 the special property that any task in the pool has direct access to the
665 standard input, output and error streams provided to Ninja, which are
666 normally connected to the user's console (hence the name) but could be
667 redirected. This can be useful for interactive tasks or long-running tasks
668 which produce status updates on the console (such as test suites).
670 While a task in the `console` pool is running, Ninja's regular output (such
671 as progress status and output from concurrent tasks) is buffered until
677 A file is a series of declarations. A declaration can be one of:
679 1. A rule declaration, which begins with +rule _rulename_+, and
680 then has a series of indented lines defining variables.
682 2. A build edge, which looks like +build _output1_ _output2_:
683 _rulename_ _input1_ _input2_+. +
684 Implicit dependencies may be tacked on the end with +|
685 _dependency1_ _dependency2_+. +
686 Order-only dependencies may be tacked on the end with +||
687 _dependency1_ _dependency2_+. (See <<ref_dependencies,the reference on
690 Implicit outputs _(available since Ninja 1.7)_ may be added before
691 the `:` with +| _output1_ _output2_+ and do not appear in `$out`.
692 (See <<ref_outputs,the reference on output types>>.)
694 3. Variable declarations, which look like +_variable_ = _value_+.
696 4. Default target statements, which look like +default _target1_ _target2_+.
698 5. References to more files, which look like +subninja _path_+ or
699 +include _path_+. The difference between these is explained below
700 <<ref_scope,in the discussion about scoping>>.
702 6. A pool declaration, which looks like +pool _poolname_+. Pools are explained
703 <<ref_pool, in the section on pools>>.
708 Ninja is mostly encoding agnostic, as long as the bytes Ninja cares
709 about (like slashes in paths) are ASCII. This means e.g. UTF-8 or
710 ISO-8859-1 input files ought to work.
712 Comments begin with `#` and extend to the end of the line.
714 Newlines are significant. Statements like `build foo bar` are a set
715 of space-separated tokens that end at the newline. Newlines and
716 spaces within a token must be escaped.
718 There is only one escape character, `$`, and it has the following
721 `$` followed by a newline:: escape the newline (continue the current line
722 across a line break).
724 `$` followed by text:: a variable reference.
726 `${varname}`:: alternate syntax for `$varname`.
728 `$` followed by space:: a space. (This is only necessary in lists of
729 paths, where a space would otherwise separate filenames. See below.)
731 `$:` :: a colon. (This is only necessary in `build` lines, where a colon
732 would otherwise terminate the list of outputs.)
734 `$$`:: a literal `$`.
736 A `build` or `default` statement is first parsed as a space-separated
737 list of filenames and then each name is expanded. This means that
738 spaces within a variable will result in spaces in the expanded
743 build $spaced/baz other$ file: ...
744 # The above build line has two outputs: "foo bar/baz" and "other file".
747 In a `name = value` statement, whitespace at the beginning of a value
748 is always stripped. Whitespace at the beginning of a line after a
749 line continuation is also stripped.
752 two_words_with_one_space = foo $
754 one_word_with_no_space = foo$
758 Other whitespace is only significant if it's at the beginning of a
759 line. If a line is indented more than the previous one, it's
760 considered part of its parent's scope; if it is indented less than the
761 previous one, it closes the previous scope.
767 Two variables are significant when declared in the outermost file scope.
769 `builddir`:: a directory for some Ninja output files. See <<ref_log,the
770 discussion of the build log>>. (You can also store other build output
773 `ninja_required_version`:: the minimum version of Ninja required to process
774 the build correctly. See <<ref_versioning,the discussion of versioning>>.
781 A `rule` block contains a list of `key = value` declarations that
782 affect the processing of the rule. Here is a full list of special
785 `command` (_required_):: the command line to run. Each `rule` may
786 have only one `command` declaration. See <<ref_rule_command,the next
787 section>> for more details on quoting and executing multiple commands.
789 `depfile`:: path to an optional `Makefile` that contains extra
790 _implicit dependencies_ (see <<ref_dependencies,the reference on
791 dependency types>>). This is explicitly to support C/C++ header
792 dependencies; see <<ref_headers,the full discussion>>.
794 `deps`:: _(Available since Ninja 1.3.)_ if present, must be one of
795 `gcc` or `msvc` to specify special dependency processing. See
796 <<ref_headers,the full discussion>>. The generated database is
797 stored as `.ninja_deps` in the `builddir`, see <<ref_toplevel,the
798 discussion of `builddir`>>.
800 `msvc_deps_prefix`:: _(Available since Ninja 1.5.)_ defines the string
801 which should be stripped from msvc's /showIncludes output. Only
802 needed when `deps = msvc` and no English Visual Studio version is used.
804 `description`:: a short description of the command, used to pretty-print
805 the command as it's running. The `-v` flag controls whether to print
806 the full command or its description; if a command fails, the full command
807 line will always be printed before the command's output.
809 `generator`:: if present, specifies that this rule is used to
810 re-invoke the generator program. Files built using `generator`
811 rules are treated specially in two ways: firstly, they will not be
812 rebuilt if the command line changes; and secondly, they are not
815 `in`:: the space-separated list of files provided as inputs to the build line
816 referencing this `rule`, shell-quoted if it appears in commands. (`$in` is
817 provided solely for convenience; if you need some subset or variant of this
818 list of files, just construct a new variable with that list and use
821 `in_newline`:: the same as `$in` except that multiple inputs are
822 separated by newlines rather than spaces. (For use with
823 `$rspfile_content`; this works around a bug in the MSVC linker where
824 it uses a fixed-size buffer for processing input.)
826 `out`:: the space-separated list of files provided as outputs to the build line
827 referencing this `rule`, shell-quoted if it appears in commands.
829 `restat`:: if present, causes Ninja to re-stat the command's outputs
830 after execution of the command. Each output whose modification time
831 the command did not change will be treated as though it had never
832 needed to be built. This may cause the output's reverse
833 dependencies to be removed from the list of pending build actions.
835 `rspfile`, `rspfile_content`:: if present (both), Ninja will use a
836 response file for the given command, i.e. write the selected string
837 (`rspfile_content`) to the given file (`rspfile`) before calling the
838 command and delete the file after successful execution of the
841 This is particularly useful on Windows OS, where the maximal length of
842 a command line is limited and response files must be used instead.
844 Use it like in the following example:
848 command = link.exe /OUT$out [usual link flags here] @$out.rsp
850 rspfile_content = $in
852 build myapp.exe: link a.obj b.obj [possibly many other .obj files]
856 Interpretation of the `command` variable
857 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
858 Fundamentally, command lines behave differently on Unixes and Windows.
860 On Unixes, commands are arrays of arguments. The Ninja `command`
861 variable is passed directly to `sh -c`, which is then responsible for
862 interpreting that string into an argv array. Therefore the quoting
863 rules are those of the shell, and you can use all the normal shell
864 operators, like `&&` to chain multiple commands, or `VAR=value cmd` to
865 set environment variables.
867 On Windows, commands are strings, so Ninja passes the `command` string
868 directly to `CreateProcess`. (In the common case of simply executing
869 a compiler this means there is less overhead.) Consequently the
870 quoting rules are deterimined by the called program, which on Windows
871 are usually provided by the C library. If you need shell
872 interpretation of the command (such as the use of `&&` to chain
873 multiple commands), make the command execute the Windows shell by
874 prefixing the command with `cmd /c`.
880 There are two types of build outputs which are subtly different.
882 1. _Explicit outputs_, as listed in a build line. These are
883 available as the `$out` variable in the rule.
885 This is the standard form of output to be used for e.g. the
886 object file of a compile command.
888 2. _Implicit outputs_, as listed in a build line with the syntax +|
889 _out1_ _out2_+ + before the `:` of a build line _(available since
890 Ninja 1.7)_. The semantics are identical to explicit outputs,
891 the only difference is that implicit outputs don't show up in the
894 This is for expressing outputs that don't show up on the
895 command line of the command.
901 There are three types of build dependencies which are subtly different.
903 1. _Explicit dependencies_, as listed in a build line. These are
904 available as the `$in` variable in the rule. Changes in these files
905 cause the output to be rebuilt; if these file are missing and
906 Ninja doesn't know how to build them, the build is aborted.
908 This is the standard form of dependency to be used e.g. for the
909 source file of a compile command.
911 2. _Implicit dependencies_, either as picked up from
912 a `depfile` attribute on a rule or from the syntax +| _dep1_
913 _dep2_+ on the end of a build line. The semantics are identical to
914 explicit dependencies, the only difference is that implicit dependencies
915 don't show up in the `$in` variable.
917 This is for expressing dependencies that don't show up on the
918 command line of the command; for example, for a rule that runs a
919 script, the script itself should be an implicit dependency, as
920 changes to the script should cause the output to rebuild.
922 Note that dependencies as loaded through depfiles have slightly different
923 semantics, as described in the <<ref_rule,rule reference>>.
925 3. _Order-only dependencies_, expressed with the syntax +|| _dep1_
926 _dep2_+ on the end of a build line. When these are out of date, the
927 output is not rebuilt until they are built, but changes in order-only
928 dependencies alone do not cause the output to be rebuilt.
930 Order-only dependencies can be useful for bootstrapping dependencies
931 that are only discovered during build time: for example, to generate a
932 header file before starting a subsequent compilation step. (Once the
933 header is used in compilation, a generated dependency file will then
934 express the implicit dependency.)
936 File paths are compared as is, which means that an absolute path and a
937 relative path, pointing to the same file, are considered different by Ninja.
942 Variables are expanded in paths (in a `build` or `default` statement)
943 and on the right side of a `name = value` statement.
945 When a `name = value` statement is evaluated, its right-hand side is
946 expanded immediately (according to the below scoping rules), and
947 from then on `$name` expands to the static string as the result of the
948 expansion. It is never the case that you'll need to "double-escape" a
949 value to prevent it from getting expanded twice.
951 All variables are expanded immediately as they're encountered in parsing,
952 with one important exception: variables in `rule` blocks are expanded
953 when the rule is _used_, not when it is declared. In the following
954 example, the `demo` rule prints "this is a demo of bar".
958 command = echo "this is a demo of $foo"
965 Evaluation and scoping
966 ~~~~~~~~~~~~~~~~~~~~~~
968 Top-level variable declarations are scoped to the file they occur in.
970 Rule declarations are also scoped to the file they occur in.
971 _(Available since Ninja 1.6)_
973 The `subninja` keyword, used to include another `.ninja` file,
974 introduces a new scope. The included `subninja` file may use the
975 variables and rules from the parent file, and shadow their values for the file's
976 scope, but it won't affect values of the variables in the parent.
978 To include another `.ninja` file in the current scope, much like a C
979 `#include` statement, use `include` instead of `subninja`.
981 Variable declarations indented in a `build` block are scoped to the
982 `build` block. The full lookup order for a variable expanded in a
983 `build` block (or the `rule` is uses) is:
985 1. Special built-in variables (`$in`, `$out`).
987 2. Build-level variables from the `build` block.
989 3. Rule-level variables from the `rule` block (i.e. `$command`).
990 (Note from the above discussion on expansion that these are
991 expanded "late", and may make use of in-scope bindings like `$in`.)
993 4. File-level variables from the file that the `build` line was in.
995 5. Variables from the file that included that file using the
projects / platform / upstream / ninja.git / blob