Add validation nodes to ninja

A common problem in the Android build is inserting rules that perform
some sort of error checking that doesn't produce any artifacts needed
by the build, for example static analysis tools.  There are a few
patterns currently used, both of which have downsides.

The first is to have a rule that depends on all of the static analysis
results.  This ensures they run, but requires running static analysis
over everything, and not just the active parts of the build graph.

The second is to insert the static analysis rule into the build graph
between the artifact producing rule and anything that depends on it,
often copying the artifact as the output of the static analysis rule.
This increases the critical path of the build, often reducing
parallelism.  In the case of copying the artifact, it also wastes
disk space.

This patch adds "validation nodes" to edges in Ninja.  A build
statement can specify validation nodes using "|@" in the edge
inputs.  The validation nodes are not used as an input to the edge
(the edge can run before the validation node is ready), but are
added to the initial nodes of the build graph whenever the edge
is part of the build graph.  The edge that outputs the validation
node can depend on the output of the edge that is being validated
if desired.

Test: ninja_test
Change-Id: Ife27086c50c1b257a26509373199664680b2b247

1 files changed, 27 insertions, 0 deletions

diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc
index 2b948b9..bdfa99b 100644
--- a/doc/manual.asciidoc
+++ b/doc/manual.asciidoc
@@ -748,6 +748,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`.
@@ -1006,6 +1008,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
 ~~~~~~~~~~~~~~~~~~