Lines Matching +full:ninja +full:- +full:build
1 The Ninja build system
7 ------------
9 Ninja is yet another build system. It takes as input the
13 Ninja joins a sea of other build systems. Its distinguishing goal is
15 http://neugierig.org/software/chromium/notes/2011/02/ninja.html[my
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.
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
32 Ninja contains the barest functionality necessary to describe
36 Instead, Ninja is intended to be used with a separate program
40 incremental builds stay fast. Going beyond autotools, even build-time
42 build a debug or release-mode binary?" belong in the `.ninja` file
48 Here are the design goals of Ninja:
54 higher-level build systems have different opinions about how code
56 the sources or should all build output go into a separate directory?
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
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
76 * built-in rules. _Out of the box, Ninja has no rules for
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
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
96 functions, built-in rules that e.g. search for RCS files when building
98 projects find make alone adequate for their build problems.
100 In contrast, Ninja has almost no features; just those necessary to get
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
109 * Ninja has special support for discovering extra dependencies at build
113 * A build edge may have multiple outputs.
127 CPUs your system has. Underspecified build dependencies will result
136 Using Ninja for your project
137 ----------------------------
139 Ninja currently works on Unix-like systems and Windows. It's seen the
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
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
155 Ninja's benefit comes from using it in conjunction with a smarter
156 meta-build system.
158 https://gn.googlesource.com/gn/[gn]:: The meta-build system used to
159 generate build files for Google Chrome and related projects (v8,
160 node.js), as well as Google Fuchsia. gn can generate Ninja files for
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 …github.com/ninja-build/ninja/wiki/List-of-generators-producing-ninja-build-files[others]:: Ninja o…
171 Running Ninja
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.
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`.)
194 Ninja supports one environment variable to control its behavior:
200 `%t`:: The total number of edges that must be run to complete the build.
207 specified by `-j` or its default)
208 `%e`:: Elapsed time in seconds. _(Available since Ninja 1.2.)_
212 to separate from the build rule). Another example of possible progress status
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:
229 ----
230 ninja -t browse --port=8000 --no-browser mytarget
231 ----
236 ----
237 ninja -t graph mytarget | dot -Tpng -ograph.png
238 ----
240 In the Ninja source tree, `ninja graph.png`
241 generates an image for Ninja itself. If no target is given generate a
245 like +ninja -t targets rule _name_+ it prints the list of targets
248 +ninja -t targets depth _digit_+ it
249 prints the list of targets in a depth-first manner starting by the root
252 +ninja -t targets depth 1+ is assumed. In this mode targets may be listed
253 several times. If used like this +ninja -t targets all+ it
263 _Available since Ninja 1.11._
266 except for those created by the generator. Adding the `-g` flag also
272 If used like +ninja -t clean -r _rules_+ it removes all files built using
276 tool takes in account the +-v+ and the +-n+ options (note that +-n+
277 implies +-v+).
280 build file. _Available since Ninja 1.10._
287 _Available since Ninja 1.2._
290 target, show just the target's dependencies. _Available since Ninja 1.4._
294 on the generator. Such targets may cause build flakiness on clean builds.
298 of a generator-target) implicitly, but does not have an explicit or order-only
299 dependency path to the generator-target, is considered broken.
301 The tool's findings can be verified by trying to build the listed targets in
302 a clean outdir without building any other targets. The build should fail for
305 _Available since Ninja 1.11._
307 `recompact`:: recompact the `.ninja_deps` file. _Available since Ninja 1.4._
310 file. _Available since Ninja 1.10._
313 to pass to +ninja -t targets rule _name_+ or +ninja -t compdb+. Adding the `-d`
317 Helper tool to invoke the `cl.exe` compiler with a pre-defined set of
320 ----
321 ninja -t msvc -e ENVFILE -- cl.exe <arguments>
322 ----
325 for CreateProcessA() on Windows (i.e. a series of zero-terminated strings that
330 the `/showIncludes` flag is used, and generating a GCC-compatible depfile from it.
332 ---
333 ninja -t msvc -o DEPFILE [-p STRING] -- cl.exe /showIncludes <arguments>
334 --- l4subsection
337 When using this option, `-p STRING` can be used to pass the localized line prefix
338 that `cl.exe` uses to output dependency information. For English-speaking regions
342 Note that Ninja supports this natively now, with the use of `deps = msvc` and
343 `msvc_deps_prefix` in Ninja files. Native support also avoids launching an extra
347 `wincodepage`:: Available on Windows hosts (_since Ninja 1.11_).
348 Prints the Windows code page whose encoding is expected in the build file.
351 ----
352 Build file encoding: <codepage>
353 ----
355 Additional lines may be added in future versions of Ninja.
359 `UTF-8`::: Encode as UTF-8.
361 `ANSI`::: Encode to the system-wide ANSI code page.
363 Writing your own Ninja files
364 ----------------------------
367 Ninja files yourself: for example, if you're writing a meta-build
373 Ninja evaluates a graph of dependencies between files, and runs
374 whichever commands are necessary to make your build target up to date
376 Make, Ninja is very similar.
378 A build file (default name: `build.ninja`) provides a list of _rules_
379 -- short names for longer commands, like how to run the compiler --
380 along with a list of _build_ statements saying how to build files
381 using the rules -- which rule to apply to which inputs to produce
384 Conceptually, `build` statements describe the dependency graph of your
391 Here's a basic `.ninja` file that demonstrates most of the syntax.
394 ---------------------------------
395 cflags = -Wall
398 command = gcc $cflags -c $in -o $out
400 build foo.o: cc foo.c
401 ---------------------------------
405 Despite the non-goal of being convenient to write by hand, to keep
406 build files readable (debuggable), Ninja supports declaring shorter
409 ----------------
410 cflags = -g
411 ----------------
416 ----------------
418 command = gcc $cflags -c $in -o $out
419 ----------------
441 Build statements
444 Build statements declare a relationship between input and output
445 files. They begin with the `build` keyword, and have the format
446 +build _outputs_: _rulename_ _inputs_+. Such a declaration says that
448 output files are missing or when the inputs change, Ninja will run the
451 The basic example above describes how to build `foo.o`, using the `cc`
454 In the scope of a `build` block (including in the evaluation of its
458 A build statement may be followed by an indented set of `key = value`
462 ----------------
463 cflags = -Wall -Werror
465 command = gcc $cflags -c $in -o $out
468 build foo.o: cc foo.c
470 # But you can shadow variables like cflags for a particular build.
471 build special.o: cc special.c
472 cflags = -Wall
475 # Subsequent build lines get the outer (original) cflags.
476 build bar.o: cc bar.c
478 ----------------
483 If you need more complicated information passed from the build
488 If the top-level Ninja file is specified as an output of any build
489 statement and it is out of date, Ninja will rebuild and reload it
492 Generating Ninja files from code
495 `misc/ninja_syntax.py` in the Ninja distribution is a tiny Python
496 module to facilitate generating Ninja files. It allows you to make
497 Python calls like `ninja.rule(name='foo', command='bar',
499 free to just inline it into your project's build system if it's
504 ------------
512 ----------------
513 build foo: phony some/file/in/a/faraway/subdir/foo
514 ----------------
516 This makes `ninja foo` build the longer path. Semantically, the
520 command count printed as part of the build process.
522 When a `phony` target is used as an input to another build rule, the
523 other build rule will, semantically, consider the inputs of the
528 may not exist at build time. If a phony build statement is written
530 it does not exist. Without a phony build statement, Ninja will report
531 an error if the file does not exist and is required by the build.
533 To create a rule that never rebuilds, use a build rule without any input:
534 ----------------
537 build file_that_always_exists.dummy: touch
538 build dummy_target_to_follow_a_pattern: phony file_that_always_exists.dummy
539 ----------------
545 By default, if no targets are specified on the command line, Ninja
546 will build every output that is not named as an input elsewhere.
548 A default target statement causes Ninja to build only a given subset
553 after the build statement that declares the target as an output file.
557 ----------------
560 ----------------
562 This causes Ninja to build the `foo`, `bar` and `baz` targets by
567 The Ninja log
570 For each built file, Ninja keeps a log of the command used to build
571 it. Using this log Ninja can know when an existing output was built
572 with a different command line than the build files specify (i.e., the
575 The log file is kept in the build root in a file called `.ninja_log`.
584 _Available since Ninja 1.2._
586 Ninja version labels follow the standard major.minor.patch format,
587 where the major version is increased on backwards-incompatible
589 behaviors. Your `build.ninja` may declare a variable named
590 `ninja_required_version` that asserts the minimum Ninja version
593 -----
595 -----
597 declares that the build file relies on some feature that was
598 introduced in Ninja 1.1 (perhaps the `pool` syntax), and that
599 Ninja 1.1 or greater must be used to build. Unlike other Ninja
602 at the top of the build file.
604 Ninja always warns if the major versions of Ninja and the
613 To get C/C++ header dependencies (or any other build dependency that
614 works in a similar way) correct Ninja has some extra functionality.
620 and Ninja can use that to get its dependencies perfect.
628 When loading these special dependencies, Ninja implicitly adds extra
629 build edges such that it is not an error if the listed dependency is
631 the build aborting due to a missing input.
640 To bring this information into Ninja requires cooperation. On the
641 Ninja side, the `depfile` attribute on the `build` must point to a
642 path where this data is written. (Ninja only supports the limited
647 ----
650 command = gcc -MD -MF $out.d [other gcc flags here]
651 ----
653 The `-MD` flag to `gcc` tells it to output header dependencies, and
654 the `-MF` flag tells it where to write them.
659 _(Available since Ninja 1.3.)_
665 Ninja 1.3 can instead process dependencies just after they're generated
666 and save a compacted form of the same information in a Ninja-internal
669 Ninja supports this processing in two forms.
671 1. `deps = gcc` specifies that the tool outputs `gcc`-style dependencies
673 cause Ninja to process the `depfile` immediately after the
679 http://msdn.microsoft.com/en-us/library/hdkef6tk(v=vs.90).aspx[`/showIncludes`
680 flag]. Briefly, this means the tool outputs specially-formatted lines
681 to its stdout. Ninja then filters these lines from the displayed
687 ----
691 command = cl /showIncludes -c $in /Fo$out
692 ----
696 build rules need to match exactly. Therefore, it is recommended to use
703 _Available since Ninja 1.1._
710 (like link steps for huge executables), or to restrict particular build
713 Each pool has a `depth` variable which is specified in the build file.
715 or a build statement.
717 No matter what pools you specify, ninja will never run more concurrent jobs
719 line (with `-j`).
721 ----------------
738 build foo.exe: link input.obj
740 # A build statement can be exempted from its rule's pool by setting an
741 # empty pool. This effectively puts the build statement back into the default
743 build other.exe: link input.obj
746 # A build statement can specify a pool directly.
748 build heavy_object1.obj: cc heavy_obj1.cc
750 build heavy_object2.obj: cc heavy_obj2.cc
753 ----------------
758 _Available since Ninja 1.5._
760 There exists a pre-defined pool named `console` with a depth of 1. It has
762 standard input, output and error streams provided to Ninja, which are
764 redirected. This can be useful for interactive tasks or long-running tasks
767 While a task in the `console` pool is running, Ninja's regular output (such
772 Ninja file reference
773 --------------------
780 2. A build edge, which looks like +build _output1_ _output2_:
784 Order-only dependencies may be tacked on the end with +||
790 Implicit outputs _(available since Ninja 1.7)_ may be added before
809 Ninja is mostly encoding agnostic, as long as the bytes Ninja cares
810 about (like slashes in paths) are ASCII. This means e.g. UTF-8 or
811 ISO-8859-1 input files ought to work.
815 Newlines are significant. Statements like `build foo bar` are a set
816 of space-separated tokens that end at the newline. Newlines and
832 `$:` :: a colon. (This is only necessary in `build` lines, where a colon
837 A `build` or `default` statement is first parsed as a space-separated
842 ----
844 build $spaced/baz other$ file: ...
845 # The above build line has two outputs: "foo bar/baz" and "other file".
846 ----
852 ----
857 ----
865 Top-level variables
870 `builddir`:: a directory for some Ninja output files. See <<ref_log,the
871 discussion of the build log>>. (You can also store other build output
874 `ninja_required_version`:: the minimum version of Ninja required to process
875 the build correctly. See <<ref_versioning,the discussion of versioning>>.
895 `deps`:: _(Available since Ninja 1.3.)_ if present, must be one of
901 `msvc_deps_prefix`:: _(Available since Ninja 1.5.)_ defines the string
905 `description`:: a short description of the command, used to pretty-print
906 the command as it's running. The `-v` flag controls whether to print
910 `dyndep`:: _(Available since Ninja 1.10.)_ Used only on build statements.
911 If present, must name one of the build statement inputs. Dynamically
916 re-invoke the generator program. Files built using `generator`
921 `in`:: the space-separated list of files provided as inputs to the build line
922 referencing this `rule`, shell-quoted if it appears in commands. (`$in` is
930 it uses a fixed-size buffer for processing input.)
932 `out`:: the space-separated list of files provided as outputs to the build line
933 referencing this `rule`, shell-quoted if it appears in commands.
935 `restat`:: if present, causes Ninja to re-stat the command's outputs
939 dependencies to be removed from the list of pending build actions.
941 `rspfile`, `rspfile_content`:: if present (both), Ninja will use a
952 ----
958 build myapp.exe: link a.obj b.obj [possibly many other .obj files]
959 ----
966 On Unixes, commands are arrays of arguments. The Ninja `command`
967 variable is passed directly to `sh -c`, which is then responsible for
973 On Windows, commands are strings, so Ninja passes the `command` string
980 prefixing the command with `cmd /c`. Ninja may error with "invalid parameter"
984 Build outputs
987 There are two types of build outputs which are subtly different.
989 1. _Explicit outputs_, as listed in a build line. These are
995 2. _Implicit outputs_, as listed in a build line with the syntax +|
996 _out1_ _out2_+ + before the `:` of a build line _(available since
997 Ninja 1.7)_. The semantics are identical to explicit outputs,
1005 Build dependencies
1008 There are three types of build dependencies which are subtly different.
1010 1. _Explicit dependencies_, as listed in a build line. These are
1013 Ninja doesn't know how to build them, the build is aborted.
1020 _dep2_+ on the end of a build line. The semantics are identical to
1033 3. _Order-only dependencies_, expressed with the syntax +|| _dep1_
1034 _dep2_+ on the end of a build line. When these are out of date, the
1035 output is not rebuilt until they are built, but changes in order-only
1038 Order-only dependencies can be useful for bootstrapping dependencies
1039 that are only discovered during build time: for example, to generate a
1045 relative path, pointing to the same file, are considered different by Ninja.
1050 Validations listed on the build line cause the specified files to be
1051 added to the top level of the build graph (as if they were specified
1052 on the Ninja command line) whenever the build line is a transitive
1056 Validations are added to the build graph regardless of whether the output
1057 files of the build statement are dirty are not, and the dirty state of
1058 the build statement that outputs the file being used as a validation
1059 has no effect on the dirty state of the build statement that requested it.
1061 A build edge can list another build edge as a validation even if the second
1065 don't produce any artifacts needed by the build, for example static
1067 of the main build rule of the source files or of the rules that depend
1068 on the main build rule would slow down the critical path of the build,
1069 but using a validation would allow the build to proceed in parallel with
1070 the static analysis rule once the main build rule is complete.
1075 Variables are expanded in paths (in a `build` or `default` statement)
1078 When a `name = value` statement is evaluated, its right-hand side is
1081 expansion. It is never the case that you'll need to "double-escape" a
1089 ----
1093 build out: demo
1095 ----
1101 Top-level variable declarations are scoped to the file they occur in.
1104 _(Available since Ninja 1.6)_
1106 The `subninja` keyword, used to include another `.ninja` file,
1111 To include another `.ninja` file in the current scope, much like a C
1114 Variable declarations indented in a `build` block are scoped to the
1115 `build` block. The full lookup order for a variable expanded in a
1116 `build` block (or the `rule` is uses) is:
1118 1. Special built-in variables (`$in`, `$out`).
1120 2. Build-level variables from the `build` block.
1122 3. Rule-level variables from the `rule` block (i.e. `$command`).
1124 expanded "late", and may make use of in-scope bindings like `$in`.)
1126 4. File-level variables from the file that the `build` line was in.
1133 --------------------
1135 _Available since Ninja 1.10._
1138 discovered from source file content _during the build_ in order to build
1141 second run and later to rebuild correctly. A build statement may have a
1145 ----
1146 build out: ... || foo
1148 build foo: ...
1149 ----
1152 the build statement for `out` can never be executed before `foo` is built.
1153 As soon as `foo` is finished Ninja will read it to load dynamically
1155 implicit inputs and/or outputs. Ninja will update the build graph
1156 accordingly and the build will proceed as if the information was known
1163 as <<ref_ninja_file,ninja build files>> and have the following layout.
1167 ----
1169 ----
1174 2. One or more build statements of the form:
1176 ----
1177 build out | imp-outs... : dyndep | imp-ins...
1178 ----
1181 the rule name `dyndep`. The `| imp-outs...` and `| imp-ins...` portions
1184 3. An optional `restat` <<ref_rule,variable binding>> on each build statement.
1186 The build statements in a dyndep file must have a one-to-one correspondence
1187 to build statements in the <<ref_ninja_file,ninja build file>> that name the
1188 dyndep file in a `dyndep` binding. No dyndep build statement may be omitted
1189 and no extra build statements may be specified.
1205 ----
1207 command = f95 -o $out -c $in
1209 command = fscan -o $out $in
1211 build foobar.dd: fscan foo.f90 bar.f90
1213 build foo.o: f95 foo.f90 || foobar.dd
1215 build bar.o: f95 bar.f90 || foobar.dd
1217 ----
1219 In this example the order-only dependencies ensure that `foobar.dd` is
1224 ----
1226 build foo.o | foo.mod: dyndep
1227 build bar.o: dyndep | foo.mod
1228 ----
1230 Ninja will load this file to add `foo.mod` as an implicit output of
1240 the tarball changes, but we also would like to re-extract if any of the
1242 of the tarball and cannot be spelled out explicitly in the ninja build file.
1245 ----
1249 command = scantar --stamp=$stamp --dd=$out $in
1250 build foo.tar.dd: scantar foo.tar
1252 build foo.tar.stamp: untar foo.tar || foo.tar.dd
1254 ----
1256 In this example the order-only dependency ensures that `foo.tar.dd` is
1261 ----
1263 build foo.tar.stamp | file1.txt file2.txt : dyndep
1265 ----
1267 Ninja will load this file to add `file1.txt` and `file2.txt` as implicit
1268 outputs of `foo.tar.stamp`, and to mark the build statement for `restat`.
1270 extracted again. The `restat` binding tells Ninja to tolerate the fact
1272 the tarball itself (avoiding re-extraction on every build).