Lines Matching +full:windows +full:- +full:build +full:- +full:rules
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
17 files and whose other build systems (including one built from custom
18 non-recursive Makefiles) would take ten seconds to start building
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 an 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
40 incremental builds stay fast. Going beyond autotools, even build-time
42 build a debug or release-mode binary?" belong in the `.ninja` file
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
76 * built-in rules. _Out of the box, Ninja has no rules for
79 * build-time customization of the build. _Options belong in
82 * build-time decision-making ability such as conditionals or search
85 To restate, Ninja is faster than other build systems because it is
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
98 projects find make alone adequate for their build problems.
109 * Ninja has special support for discovering extra dependencies at build
113 * A build edge may have multiple outputs.
122 * Rules can provide shorter descriptions of the command being run, so
127 CPUs your system has. Underspecified build dependencies will result
137 ----------------------------
139 Ninja currently works on Unix-like systems and Windows. It's seen the
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
151 author found http://gittup.org/tup/[the tup build system] influential
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,
163 https://cmake.org/[CMake]:: A widely used meta-build system that
165 of CMake support generating Ninja files on Windows and Mac OS X too.
167 …thub.com/ninja-build/ninja/wiki/List-of-generators-producing-ninja-build-files[others]:: Ninja oug…
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
188 you don't need to pass `-j`.)
200 `%t`:: The total number of edges that must be run to complete the build.
207 specified by `-j` or its default)
216 to separate from the build rule). Another example of possible progress status
222 The `-t` flag on the Ninja command line runs some tools that we have
233 ----
234 ninja -t browse --port=8000 --no-browser mytarget
235 ----
240 ----
241 ninja -t graph mytarget | dot -Tpng -ograph.png
242 ----
249 like +ninja -t targets rule _name_+ it prints the list of targets
252 +ninja -t targets depth _digit_+ it
253 prints the list of targets in a depth-first manner starting by the root
256 +ninja -t targets depth 1+ is assumed. In this mode targets may be listed
257 several times. If used like this +ninja -t targets all+ it
270 except for those created by the generator. Adding the `-g` flag also
276 If used like +ninja -t clean -r _rules_+ it removes all files built using
277 the given rules.
280 tool takes in account the +-v+ and the +-n+ options (note that +-n+
281 implies +-v+).
284 build file. _Available since Ninja 1.10._
286 `compdb`:: given a list of rules, each of which is expected to be a
298 on the generator. Such targets may cause build flakiness on clean builds.
302 of a generator-target) implicitly, but does not have an explicit or order-only
303 dependency path to the generator-target, is considered broken.
305 The tool's findings can be verified by trying to build the listed targets in
306 a clean outdir without building any other targets. The build should fail for
316 `rules`:: output the list of all rules. It can be used to know which rule name
317 to pass to +ninja -t targets rule _name_+ or +ninja -t compdb+. Adding the `-d`
318 flag also prints the description of the rules.
320 `msvc`:: Available on Windows hosts only.
321 Helper tool to invoke the `cl.exe` compiler with a pre-defined set of
324 ----
325 ninja -t msvc -e ENVFILE -- cl.exe <arguments>
326 ----
329 for CreateProcessA() on Windows (i.e. a series of zero-terminated strings that
334 the `/showIncludes` flag is used, and generating a GCC-compatible depfile from it:
336 ----
337 ninja -t msvc -o DEPFILE [-p STRING] -- cl.exe /showIncludes <arguments>
338 ----
340 When using this option, `-p STRING` can be used to pass the localized line prefix
341 that `cl.exe` uses to output dependency information. For English-speaking regions
348 noticeably on Windows.
350 `wincodepage`:: Available on Windows hosts (_since Ninja 1.11_).
351 Prints the Windows code page whose encoding is expected in the build file.
354 ----
355 Build file encoding: <codepage>
356 ----
362 `UTF-8`::: Encode as UTF-8.
364 `ANSI`::: Encode to the system-wide ANSI code page.
367 ----------------------------
370 Ninja files yourself: for example, if you're writing a meta-build
377 whichever commands are necessary to make your build target up to date
381 A build file (default name: `build.ninja`) provides a list of _rules_
382 -- short names for longer commands, like how to run the compiler --
383 along with a list of _build_ statements saying how to build files
384 using the rules -- which rule to apply to which inputs to produce
387 Conceptually, `build` statements describe the dependency graph of your
397 ---------------------------------
398 cflags = -Wall
401 command = gcc $cflags -c $in -o $out
403 build foo.o: cc foo.c
404 ---------------------------------
408 Despite the non-goal of being convenient to write by hand, to keep
409 build files readable (debuggable), Ninja supports declaring shorter
412 ----------------
413 cflags = -g
414 ----------------
419 ----------------
421 command = gcc $cflags -c $in -o $out
422 ----------------
430 Rules subsection
433 Rules declare a short name for a command line. They begin with a line
444 Build statements
447 Build statements declare a relationship between input and output
448 files. They begin with the `build` keyword, and have the format
449 +build _outputs_: _rulename_ _inputs_+. Such a declaration says that
454 The basic example above describes how to build `foo.o`, using the `cc`
457 In the scope of a `build` block (including in the evaluation of its
461 A build statement may be followed by an indented set of `key = value`
465 ----------------
466 cflags = -Wall -Werror
468 command = gcc $cflags -c $in -o $out
471 build foo.o: cc foo.c
473 # But you can shadow variables like cflags for a particular build.
474 build special.o: cc special.c
475 cflags = -Wall
478 # Subsequent build lines get the outer (original) cflags.
479 build bar.o: cc bar.c
481 ----------------
486 If you need more complicated information passed from the build
491 If the top-level Ninja file is specified as an output of any build
502 free to just inline it into your project's build system if it's
507 ------------
515 ----------------
516 build foo: phony some/file/in/a/faraway/subdir/foo
517 ----------------
519 This makes `ninja foo` build the longer path. Semantically, the
521 nothing, but phony rules are handled specially in that they aren't
523 command count printed as part of the build process.
525 When a `phony` target is used as an input to another build rule, the
526 other build rule will, semantically, consider the inputs of the
527 `phony` rule as its own. Therefore, `phony` rules can be used to group
531 may not exist at build time. If a phony build statement is written
533 it does not exist. Without a phony build statement, Ninja will report
534 an error if the file does not exist and is required by the build.
536 To create a rule that never rebuilds, use a build rule without any input:
537 ----------------
540 build file_that_always_exists.dummy: touch
541 build dummy_target_to_follow_a_pattern: phony file_that_always_exists.dummy
542 ----------------
549 will build every output that is not named as an input elsewhere.
551 A default target statement causes Ninja to build only a given subset
556 after the build statement that declares the target as an output file.
560 ----------------
563 ----------------
565 This causes Ninja to build the `foo`, `bar` and `baz` targets by
573 For each built file, Ninja keeps a log of the command used to build
575 with a different command line than the build files specify (i.e., the
578 The log file is kept in the build root in a file called `.ninja_log`.
590 where the major version is increased on backwards-incompatible
592 behaviors. Your `build.ninja` may declare a variable named
596 -----
598 -----
600 declares that the build file relies on some feature that was
602 Ninja 1.1 or greater must be used to build. Unlike other Ninja
605 at the top of the build file.
616 To get C/C++ header dependencies (or any other build dependency that
632 build edges such that it is not an error if the listed dependency is
634 the build aborting due to a missing input.
644 Ninja side, the `depfile` attribute on the `build` must point to a
650 ----
653 command = gcc -MD -MF $out.d [other gcc flags here]
654 ----
656 The `-MD` flag to `gcc` tells it to output header dependencies, and
657 the `-MF` flag tells it where to write them.
664 It turns out that for large projects (and particularly on Windows,
669 and save a compacted form of the same information in a Ninja-internal
674 1. `deps = gcc` specifies that the tool outputs `gcc`-style dependencies
682 http://msdn.microsoft.com/en-us/library/hdkef6tk(v=vs.90).aspx[`/showIncludes`
683 flag]. Briefly, this means the tool outputs specially-formatted lines
690 ----
694 command = cl /showIncludes -c $in /Fo$out
695 ----
699 build rules need to match exactly. Therefore, it is recommended to use
708 Pools allow you to allocate one or more rules or edges a finite number
713 (like link steps for huge executables), or to restrict particular build
716 Each pool has a `depth` variable which is specified in the build file.
718 or a build statement.
722 line (with `-j`).
724 ----------------
741 build foo.exe: link input.obj
743 # A build statement can be exempted from its rule's pool by setting an
744 # empty pool. This effectively puts the build statement back into the default
746 build other.exe: link input.obj
749 # A build statement can specify a pool directly.
751 build heavy_object1.obj: cc heavy_obj1.cc
753 build heavy_object2.obj: cc heavy_obj2.cc
756 ----------------
763 There exists a pre-defined pool named `console` with a depth of 1. It has
767 redirected. This can be useful for interactive tasks or long-running tasks
776 --------------------
783 2. A build edge, which looks like +build _output1_ _output2_:
787 Order-only dependencies may be tacked on the end with +||
813 about (like slashes in paths) are ASCII. This means e.g. UTF-8 or
814 ISO-8859-1 input files ought to work.
818 Newlines are significant. Statements like `build foo bar` are a set
819 of space-separated tokens that end at the newline. Newlines and
835 `$:` :: a colon. (This is only necessary in `build` lines, where a colon
840 A `build` or `default` statement is first parsed as a space-separated
845 ----
847 build $spaced/baz other$ file: ...
848 # The above build line has two outputs: "foo bar/baz" and "other file".
849 ----
855 ----
860 ----
868 Top-level variables
874 discussion of the build log>>. (You can also store other build output
878 the build correctly. See <<ref_versioning,the discussion of versioning>>.
908 `description`:: a short description of the command, used to pretty-print
909 the command as it's running. The `-v` flag controls whether to print
913 `dyndep`:: _(Available since Ninja 1.10.)_ Used only on build statements.
914 If present, must name one of the build statement inputs. Dynamically
919 re-invoke the generator program. Files built using `generator`
920 rules are treated specially in two ways: firstly, they will not be
924 `in`:: the space-separated list of files provided as inputs to the build line
925 referencing this `rule`, shell-quoted if it appears in commands. (`$in` is
933 it uses a fixed-size buffer for processing input.)
935 `out`:: the space-separated list of files provided as outputs to the build line
936 referencing this `rule`, shell-quoted if it appears in commands.
938 `restat`:: if present, causes Ninja to re-stat the command's outputs
942 dependencies to be removed from the list of pending build actions.
950 This is particularly useful on Windows OS, where the maximal length of
955 ----
961 build myapp.exe: link a.obj b.obj [possibly many other .obj files]
962 ----
967 Fundamentally, command lines behave differently on Unixes and Windows.
970 variable is passed directly to `sh -c`, which is then responsible for
972 rules are those of the shell, and you can use all the normal shell
976 On Windows, commands are strings, so Ninja passes the `command` string
979 quoting rules are determined by the called program, which on Windows
982 multiple commands), make the command execute the Windows shell by
987 Build outputs
990 There are two types of build outputs which are subtly different.
992 1. _Explicit outputs_, as listed in a build line. These are
998 2. _Implicit outputs_, as listed in a build line with the syntax +|
999 _out1_ _out2_+ + before the `:` of a build line _(available since
1008 Build dependencies
1011 There are three types of build dependencies which are subtly different.
1013 1. _Explicit dependencies_, as listed in a build line. These are
1016 Ninja doesn't know how to build them, the build is aborted.
1023 _dep2_+ on the end of a build line. The semantics are identical to
1036 3. _Order-only dependencies_, expressed with the syntax +|| _dep1_
1037 _dep2_+ on the end of a build line. When these are out of date, the
1038 output is not rebuilt until they are built, but changes in order-only
1041 Order-only dependencies can be useful for bootstrapping dependencies
1042 that are only discovered during build time: for example, to generate a
1056 Validations listed on the build line cause the specified files to be
1057 added to the top level of the build graph (as if they were specified
1058 on the Ninja command line) whenever the build line is a transitive
1062 Validations are added to the build graph regardless of whether the output
1063 files of the build statement are dirty are not, and the dirty state of
1064 the build statement that outputs the file being used as a validation
1065 has no effect on the dirty state of the build statement that requested it.
1067 A build edge can list another build edge as a validation even if the second
1070 Validations are designed to handle rules that perform error checking but
1071 don't produce any artifacts needed by the build, for example, static
1073 of the main build rule of the source files or of the rules that depend
1074 on the main build rule would slow down the critical path of the build,
1075 but using a validation would allow the build to proceed in parallel with
1076 the static analysis rule once the main build rule is complete.
1081 Variables are expanded in paths (in a `build` or `default` statement)
1084 When a `name = value` statement is evaluated, its right-hand side is
1085 expanded immediately (according to the below scoping rules), and
1087 expansion. It is never the case that you'll need to "double-escape" a
1095 ----
1099 build out: demo
1101 ----
1107 Top-level variable declarations are scoped to the file they occur in.
1114 variables and rules from the parent file, and shadow their values for the file's
1120 Variable declarations indented in a `build` block are scoped to the
1121 `build` block. The full lookup order for a variable expanded in a
1122 `build` block (or the `rule` is uses) is:
1124 1. Special built-in variables (`$in`, `$out`).
1126 2. Build-level variables from the `build` block.
1128 3. Rule-level variables from the `rule` block (i.e. `$command`).
1130 expanded "late", and may make use of in-scope bindings like `$in`.)
1132 4. File-level variables from the file that the `build` line was in.
1139 --------------------
1144 discovered from source file content _during the build_ in order to build
1147 second run and later to rebuild correctly. A build statement may have a
1151 ----
1152 build out: ... || foo
1154 build foo: ...
1155 ----
1158 the build statement for `out` can never be executed before `foo` is built.
1161 implicit inputs and/or outputs. Ninja will update the build graph
1162 accordingly and the build will proceed as if the information was known
1169 as <<ref_ninja_file,ninja build files>> and have the following layout.
1173 ----
1175 ----
1180 2. One or more build statements of the form:
1182 ----
1183 build out | imp-outs... : dyndep | imp-ins...
1184 ----
1187 the rule name `dyndep`. The `| imp-outs...` and `| imp-ins...` portions
1190 3. An optional `restat` <<ref_rule,variable binding>> on each build statement.
1192 The build statements in a dyndep file must have a one-to-one correspondence
1193 to build statements in the <<ref_ninja_file,ninja build file>> that name the
1194 dyndep file in a `dyndep` binding. No dyndep build statement may be omitted
1195 and no extra build statements may be specified.
1211 ----
1213 command = f95 -o $out -c $in
1215 command = fscan -o $out $in
1217 build foobar.dd: fscan foo.f90 bar.f90
1219 build foo.o: f95 foo.f90 || foobar.dd
1221 build bar.o: f95 bar.f90 || foobar.dd
1223 ----
1225 In this example the order-only dependencies ensure that `foobar.dd` is
1230 ----
1232 build foo.o | foo.mod: dyndep
1233 build bar.o: dyndep | foo.mod
1234 ----
1246 the tarball changes, but we also would like to re-extract if any of the
1248 of the tarball and cannot be spelled out explicitly in the ninja build file.
1251 ----
1255 command = scantar --stamp=$stamp --dd=$out $in
1256 build foo.tar.dd: scantar foo.tar
1258 build foo.tar.stamp: untar foo.tar || foo.tar.dd
1260 ----
1262 In this example the order-only dependency ensures that `foo.tar.dd` is
1267 ----
1269 build foo.tar.stamp | file1.txt file2.txt : dyndep
1271 ----
1274 outputs of `foo.tar.stamp`, and to mark the build statement for `restat`.
1278 the tarball itself (avoiding re-extraction on every build).