From 94588c2ceebca3328d3b84566306c91a8600fae6 Mon Sep 17 00:00:00 2001
From: Googler <noreply@google.com>
Date: Thu, 12 Mar 2015 16:50:49 +0000
Subject: BazelExtraActionRule is documented.

--
MOS_MIGRATED_REVID=88449349
---
 .../bazel/rules/common/BazelExtraActionRule.java   | 102 +++++++++++++++++++++
 1 file changed, 102 insertions(+)

(limited to 'src/main/java/com/google/devtools/build')

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java
index fa73f9308e..efc4e4630e 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java
@@ -37,13 +37,115 @@ import com.google.devtools.build.lib.rules.extra.ExtraActionFactory;
 public final class BazelExtraActionRule implements RuleDefinition {
   @Override
   public RuleClass build(Builder builder, RuleDefinitionEnvironment environment) {
+    /*<!-- #BLAZE_RULE(extra_action).NAME -->
+    You may refer to this rule by <code>label</code> in the <code>extra_actions</code> argument
+    of <a href="#action_listener"><code> action_listener</code></a> rules.
+    <!-- #END_BLAZE_RULE.NAME -->*/
     return builder
+        /*<!-- #BLAZE_RULE(extra_action).ATTRIBUTE(tools) -->
+        A list of <code>tool</code> dependencies for this rule.
+        ${SYNOPSIS}
+        <p>
+          See the definition of <a href="build-ref.html#deps">dependencies</a> for more information.
+        </p>
+        <p>
+          The build system ensures these prerequisites are built before running the
+          <code>extra_action</code> command; they are built using the
+          <a href='bazel-user-manual.html#configurations'><code>host</code>configuration</a>, since
+          they must run as a tool during the build itself. The path of an individual
+          <code>tools</code> target <code>//x:y</code> can be obtained using
+          <code>$(location //x:y)</code>.
+        </p>
+        <p>
+          All tools and their data dependencies are consolidated into a single tree
+          within which the command can use relative paths. The working directory will
+          be the root of that unified tree.
+        </p>
+        <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
         .add(attr("tools", LABEL_LIST).cfg(HOST).allowedFileTypes().exec())
+        /*<!-- #BLAZE_RULE(extra_action).ATTRIBUTE(out_templates) -->
+         A list of templates for files generated by the <code>extra_action</code> command.
+         ${SYNOPSIS}
+         <p>
+           The template can use the following variables:
+           <ul>
+             <li>
+               $(ACTION_ID), an id uniquely identifying this <code>extra_action</code>.
+               Used to generate a unique output file.
+             </li>
+           </ul>
+         </p>
+         <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
         .add(attr("out_templates", STRING_LIST))
+        /*<!-- #BLAZE_RULE(extra_action).ATTRIBUTE(cmd) -->
+         The command to run.
+         ${SYNOPSIS}
+         <p>
+           Like <a href="#genrule.cmd">genrule cmd attribute</a> with the following differences:
+         </p>
+         <ol>
+           <li>
+             <p>
+               No heuristic label expansion. Only labels using $(location ...) are expanded.
+             </p>
+           </li>
+           <li>
+             <p>
+               An additional pass is applied to the string to replace all
+               occurrences of the outputs created from the <code>out_templates</code>
+               attribute. All occurrences of <code>$(output <i>out_template</i>)</code>
+               are replaced with the path to the file denoted by <code>label</code>.
+             </p>
+             <p>
+               E.g. out_template <code>$(ACTION_ID).analysis</code>
+               can be matched with <code>$(output $(ACTION_ID).analysis)</code>.
+             </p>
+             <p>
+               In effect, this is the same substitution as <code>$(location)</code>
+               but with a different scope.
+             </p>
+           </li>
+         </ol>
+         <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
         .add(attr("cmd", STRING).mandatory())
+        /*<!-- #BLAZE_RULE(extra_action).ATTRIBUTE(requires_action_output) -->
+         Indicates this <code>extra_action</code> requires the output of the
+         original action to be present as input to this <code>extra_action</code>.
+         ${SYNOPSIS}
+         <p>
+           When true (default false), the extra_action can assume that the
+           original action outputs are available as part of its inputs.
+         </p>
+         <!-- #END_BLAZE_RULE.ATTRIBUTE -->*/
         .add(attr("requires_action_output", BOOLEAN))
         .removeAttribute("deps")
         .removeAttribute(":action_listener")
         .build();
   }
 }
+
+/*<!-- #BLAZE_RULE (NAME = extra_action, TYPE = LIBRARY, FAMILY = Extra Actions)[GENERIC_RULE] -->
+
+${ATTRIBUTE_SIGNATURE}
+
+<p>
+  An <code>extra_action</code> rule doesn't produce any meaningful output
+  when specified as a regular build target. Instead, it allows tool developers
+  to insert additional actions into the build graph that shadow existing actions.
+</p>
+
+<p>
+  See <a href="#action_listener"><code>action_listener</code></a> for details
+  on how to enable <code>extra_action</code>s in Bazel.
+</p>
+
+<p>
+  The <code>extra_action</code>s run as a command-line. The command-line tool gets
+  access to a file containing a protocol buffer as $(EXTRA_ACTION_FILE)
+  with detailed information on the original action it is shadowing.
+  It also has access to all the input files the original action has access to.
+</p>
+
+${ATTRIBUTE_DEFINITION}
+
+<!-- #END_BLAZE_RULE -->*/
-- 
cgit v1.2.3