diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual.asciidoc | 52 |
1 files changed, 27 insertions, 25 deletions
diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc index 221df47..119ccfd 100644 --- a/doc/manual.asciidoc +++ b/doc/manual.asciidoc @@ -356,17 +356,11 @@ consisting of the `rule` keyword and a name for the rule. Then follows an indented set of `variable = value` lines. The basic example above declares a new rule named `cc`, along with the -command to run. (In the context of a rule, the `command` variable is -special and defines the command to run. A full list of special -variables is provided in <<ref_rule,the reference>>.) - -Within the context of a rule, three additional special variables are -available: `$in` expands to the list of input files (`foo.c`) and -`$out` to the output file (`foo.o`) for the command. For use with -`$rspfile_content`, there is also `$in_newline`, which is the same as -`$in`, except that multiple inputs are separated by `\n`, rather than -spaces. - +command to run. In the context of a rule, the `command` variable +defines the command to run, `$in` expands to the list of +input files (`foo.c`), and `$out` to the output files (`foo.o`) for the +command. A full list of special variables is provided in +<<ref_rule,the reference>>. Build statements ~~~~~~~~~~~~~~~~ @@ -422,9 +416,7 @@ before building the targets requested by the user. Pools ~~~~~ -*Note: pools were added as an experiment and may be removed in a future -version of Ninja. Are they useful for you? Let us know on the mailing -list.* +_Available since Ninja 1.1._ Pools allow you to allocate one or more rules or edges a finite number of concurrent jobs which is more tightly restricted than the default @@ -538,11 +530,10 @@ This causes Ninja to build the `foo`, `bar` and `baz` targets by default. +[[ref_log]] The Ninja log ~~~~~~~~~~~~~ -[[ref_log]] - For each built file, Ninja keeps a log of the command used to build it. Using this log Ninja can know when an existing output was built with a different command line than the build files specify (i.e., the @@ -553,10 +544,11 @@ If you provide a variable named `builddir` in the outermost scope, `.ninja_log` will be kept in that directory instead. +[[ref_versioning]] Version compatibility ~~~~~~~~~~~~~~~~~~~~~ -[[ref_versioning]] +_Available since Ninja 1.XXX._ Ninja version labels follow the standard major.minor.patch format, where the major version is increased on backwards-incompatible @@ -676,13 +668,13 @@ Two variables are significant when declared in the outermost file scope. discussion of the build log>>. (You can also store other build output in this directory.) -`ninja_required_version`:: the minimum verison of Ninja required to process +`ninja_required_version`:: the minimum version of Ninja required to process the build correctly. See <<ref_versioning,the discussion of versioning>>. +[[ref_rule]] Rule variables ~~~~~~~~~~~~~~ -[[ref_rule]] A `rule` block contains a list of `key = value` declarations that affect the processing of the rule. Here is a full list of special @@ -724,6 +716,20 @@ aborting due to a missing input. rebuilt if the command line changes; and secondly, they are not cleaned by default. +`in`:: the shell-quoted space-separated list of files provided as + inputs to the build line referencing this `rule`. (`$in` is provided + solely for convenience; if you need some subset or variant of this + list of files, just construct a new variable with that list and use + that instead.) + +`in_newline`:: the same as `$in` except that multiple inputs are + separated by newlines rather than spaces. (For use with + `$rspfile_content`; this works around a bug in the MSVC linker where + it uses a fixed-size buffer for processing input.) + +`out`:: the shell-quoted space-separated list of files provided as + outputs to the build line referencing this `rule`. + `restat`:: if present, causes Ninja to re-stat the command's outputs after execution of the command. Each output whose modification time the command did not change will be treated as though it had never @@ -750,13 +756,9 @@ rule link build myapp.exe: link a.obj b.obj [possibly many other .obj files] ---- -Finally, the special `$in` and `$out` variables expand to the -shell-quoted space-separated list of files provided to the `build` -line referencing this `rule`. - +[[ref_dependencies]] Build dependencies ~~~~~~~~~~~~~~~~~~ -[[ref_dependencies]] There are three types of build dependencies which are subtly different. @@ -818,9 +820,9 @@ build out: demo foo = bar ---- +[[ref_scope]] Evaluation and scoping ~~~~~~~~~~~~~~~~~~~~~~ -[[ref_scope]] Top-level variable declarations are scoped to the file they occur in. |