diff options
author | 2015-03-12 16:50:49 +0000 | |
---|---|---|
committer | 2015-03-13 14:38:32 +0000 | |
commit | 94588c2ceebca3328d3b84566306c91a8600fae6 (patch) | |
tree | a7937c06cdd64dff20ad737be6f687352a3c7740 /src/main/java/com/google/devtools/build | |
parent | 4ebb2b1e97e6988c0a7bbdf0e8b01eec5f46483a (diff) |
BazelExtraActionRule is documented.
--
MOS_MIGRATED_REVID=88449349
Diffstat (limited to 'src/main/java/com/google/devtools/build')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java | 102 |
1 files changed, 102 insertions, 0 deletions
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 -->*/ |