diff options
Diffstat (limited to 'doc/manual.asciidoc')
| -rw-r--r-- | doc/manual.asciidoc | 44 |
1 files changed, 40 insertions, 4 deletions
diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc index a5012b4..9e2bec5 100644 --- a/doc/manual.asciidoc +++ b/doc/manual.asciidoc @@ -257,6 +257,10 @@ than the _depth_ mode. executed in order, may be used to rebuild those targets, assuming that all output files are out of date. +`inputs`:: given a list of targets, print a list of all inputs which are used +to rebuild those targets. +_Available since Ninja 1.11._ + `clean`:: remove built files. By default it removes all built files except for those created by the generator. Adding the `-g` flag also removes built files created by the generator (see <<ref_rule,the rule @@ -294,7 +298,7 @@ of a generator-target) implicitly, but does not have an explicit or order-only dependency path to the generator-target, is considered broken. + The tool's findings can be verified by trying to build the listed targets in -a clean outdir without buidling any other targets. The build should fail for +a clean outdir without building any other targets. The build should fail for each of them with a missing include error or equivalent pointing to the generated file. _Available since Ninja 1.11._ @@ -304,9 +308,9 @@ _Available since Ninja 1.11._ `restat`:: updates all recorded file modification timestamps in the `.ninja_log` file. _Available since Ninja 1.10._ -`rules`:: output the list of all rules (eventually with their description -if they have one). It can be used to know which rule name to pass to -+ninja -t targets rule _name_+ or +ninja -t compdb+. +`rules`:: output the list of all rules. It can be used to know which rule name +to pass to +ninja -t targets rule _name_+ or +ninja -t compdb+. Adding the `-d` +flag also prints the description of the rules. `wincodepage`:: Available on Windows hosts (_since Ninja 1.11_). Prints the Windows code page whose encoding is expected in the build file. @@ -483,6 +487,11 @@ nothing, but phony rules are handled specially in that they aren't printed when run, logged (see below), nor do they contribute to the command count printed as part of the build process. +When a `phony` target is used as an input to another build rule, the +other build rule will, semantically, consider the inputs of the +`phony` rule as its own. Therefore, `phony` rules can be used to group +inputs, e.g. header files. + `phony` can also be used to create dummy targets for files which may not exist at build time. If a phony build statement is written without any dependencies, the target will be considered out of date if @@ -743,6 +752,8 @@ A file is a series of declarations. A declaration can be one of: Order-only dependencies may be tacked on the end with +|| _dependency1_ _dependency2_+. (See <<ref_dependencies,the reference on dependency types>>.) + Validations may be taked on the end with +|@ _validation1_ _validation2_+. + (See <<validations,the reference on validations>>.) + Implicit outputs _(available since Ninja 1.7)_ may be added before the `:` with +| _output1_ _output2_+ and do not appear in `$out`. @@ -1001,6 +1012,31 @@ express the implicit dependency.) File paths are compared as is, which means that an absolute path and a relative path, pointing to the same file, are considered different by Ninja. +[[validations]] +Validations +~~~~~~~~~~~ +Validations listed on the build line cause the specified files to be +added to the top level of the build graph (as if they were specified +on the Ninja command line) whenever the build line is a transitive +dependency of one of the targets specified on the command line or a +default target. + +Validations are added to the build graph regardless of whether the output +files of the build statement are dirty are not, and the dirty state of +the build statement that outputs the file being used as a validation +has no effect on the dirty state of the build statement that requested it. + +A build edge can list another build edge as a validation even if the second +edge depends on the first. + +Validations are designed to handle rules that perform error checking but +don't produce any artifacts needed by the build, for example static +analysis tools. Marking the static analysis rule as an implicit input +of the main build rule of the source files or of the rules that depend +on the main build rule would slow down the critical path of the build, +but using a validation would allow the build to proceed in parallel with +the static analysis rule once the main build rule is complete. + Variable expansion ~~~~~~~~~~~~~~~~~~ |