summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2015-07-13 19:25:50 (GMT)
committerBrad King <brad.king@kitware.com>2016-02-03 14:37:17 (GMT)
commitcc39240a10fb040fca80bf3669245f2f2d5736c5 (patch)
tree0b26230a0dd1dde9514dbbe7d6f06a3402c6e8b3 /doc
parentf1f3f494f5f67a4cd64b0cddaad472b070f6db07 (diff)
downloadNinja-cc39240a10fb040fca80bf3669245f2f2d5736c5.zip
Ninja-cc39240a10fb040fca80bf3669245f2f2d5736c5.tar.gz
Ninja-cc39240a10fb040fca80bf3669245f2f2d5736c5.tar.bz2
Add support for build statement implicit outputs
Some build rules produce outputs that are not mentioned on the command line but that should be part of the build graph. Such outputs should not be named in the `$out` variable. Extend the build statement syntax to support specification of implicit outputs using the syntax `| out1 out2` after the explicit outputs and before the `:`. For example, compilation of a Fortran source file `foo.f90` that defines `MODULE FOO` may now be specified as: rule fc command = f95 -c $in -o $out build foo.o | foo.mod: fc foo.f90 The `foo.mod` file is an implicit output generated by the compiler based on the content of the source file and not mentioned on the command line.
Diffstat (limited to 'doc')
-rw-r--r--doc/manual.asciidoc27
1 files changed, 26 insertions, 1 deletions
diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc
index ab5c945..4e73df3 100644
--- a/doc/manual.asciidoc
+++ b/doc/manual.asciidoc
@@ -689,6 +689,10 @@ 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>>.)
++
+Implicit outputs _(available since Ninja 1.7)_ may be added before
+the `:` with +| _output1_ _output2_+ and do not appear in `$out`.
+(See <<ref_outputs,the reference on output types>>.)
3. Variable declarations, which look like +_variable_ = _value_+.
@@ -872,6 +876,27 @@ interpretation of the command (such as the use of `&&` to chain
multiple commands), make the command execute the Windows shell by
prefixing the command with `cmd /c`.
+[[ref_outputs]]
+Build outputs
+~~~~~~~~~~~~~
+
+There are two types of build outputs which are subtly different.
+
+1. _Explicit outputs_, as listed in a build line. These are
+ available as the `$out` variable in the rule.
++
+This is the standard form of output to be used for e.g. the
+object file of a compile command.
+
+2. _Implicit outputs_, as listed in a build line with the syntax +|
+ _out1_ _out2_+ + before the `:` of a build line _(available since
+ Ninja 1.7)_. The semantics are identical to explicit outputs,
+ the only difference is that implicit outputs don't show up in the
+ `$out` variable.
++
+This is for expressing outputs that don't show up on the
+command line of the command.
+
[[ref_dependencies]]
Build dependencies
~~~~~~~~~~~~~~~~~~
@@ -883,7 +908,7 @@ There are three types of build dependencies which are subtly different.
cause the output to be rebuilt; if these file are missing and
Ninja doesn't know how to build them, the build is aborted.
+
-This is the standard form of dependency to be used for e.g. the
+This is the standard form of dependency to be used e.g. for the
source file of a compile command.
2. _Implicit dependencies_, either as picked up from