docs/versions/7.3.0/reference/be/extra-actions.mdx
{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} {% dynamic setvar version "7.3.0" %} {% dynamic setvar original_path "/reference/be/extra-actions" %} {% include "_buttons.html" %}
<h2>Rules</h2> <ul> <li> <a href="#action_listener"> action_listener </a> </li> <li> <a href="#extra_action"> extra_action </a> </li> </ul> <h2 id="action_listener"> action_listener </h2> <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java" target="_blank"> View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> </a> <pre class="rule-signature">action_listener(<a href="#action_listener.name">name</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#action_listener.extra_actions">extra_actions</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#action_listener.mnemonics">mnemonics</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> <p> <b>WARNING:</b> Extra actions are deprecated. Use <a href="https://bazel.build/versions/7.3.0/rules/aspects">aspects</a> instead. </p> <p> An <code>action_listener</code> rule doesn't produce any output itself. Instead, it allows tool developers to insert <a href="/versions/7.3.0/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a>s into the build system, by providing a mapping from action to <a href="/versions/7.3.0/reference/be/extra-actions.html#extra_action"><code>extra_action</code> </a>. </p> <p> This rule's arguments map action mnemonics to <a href="/versions/7.3.0/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a> rules. </p> <p> By specifying the option <a href="/versions/7.3.0/docs/user-manual#flag--experimental_action_listener"> <code>--experimental_action_listener=<label></code></a>, the build will use the specified <code>action_listener</code> to insert <a href="/versions/7.3.0/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a>s into the build graph. </p> <h4 id="action_listener_example">Example</h4> <pre> action_listener( name = "index_all_languages", mnemonics = [ "Javac", "CppCompile", "Python", ], extra_actions = [":indexer"], )action_listener( name = "index_java", mnemonics = ["Javac"], extra_actions = [":indexer"], )
extra_action( name = "indexer", tools = ["//my/tools:indexer"], cmd = "$(location //my/tools:indexer)" + "--extra_action_file=$(EXTRA_ACTION_FILE)", ) </pre>
<h3 id="action_listener_args">Arguments</h3> <table class="table table-condensed table-bordered table-params"> <colgroup> <col class="col-param" /> <col class="param-description" /> </colgroup> <thead> <tr> <th colspan="2">Attributes</th> </tr> </thead> <tbody> <tr> <td id="action_listener.name"><code>name</code></td> <td> <p><a href="/versions/7.3.0/concepts/labels#target-names">Name</a>; required</p> <p>A unique name for this target.</p> </td>
</tr>
<tr>
<td id="action_listener.extra_actions">
<code>extra_actions</code>
</td>
<td>
<p>List of <a href="/versions/7.3.0/concepts/labels">labels</a>; required</p>
A list of <code><a href="/versions/7.3.0/reference/be/extra-actions.html#extra_action">extra_action</a></code> targets
this <code>action_listener</code> should add to the build graph.
E.g. <code>[ "//my/tools:analyzer" ]</code>.
</td>
</tr>
<tr>
<td id="action_listener.mnemonics">
<code>mnemonics</code>
</td>
<td>
<p>List of strings; required</p>
A list of action mnemonics this <code>action_listener</code> should listen
for, e.g. <code>[ "Javac" ]</code>.
<p>
Mnemonics are not a public interface.
There's no guarantee that the mnemonics and their actions don't change.
</p>
</td>
</tr>
</tbody>
</td>
</tr>
<tr>
<td id="extra_action.cmd">
<code>cmd</code>
</td>
<td>
<p>String; required</p>
The command to run.
<p>
Like <a href="/versions/7.3.0/reference/be/general.html#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>
</td>
</tr>
<tr>
<td id="extra_action.out_templates">
<code>out_templates</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
A list of templates for files generated by the <code>extra_action</code> command.
<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>
</td>
</tr>
<tr>
<td id="extra_action.requires_action_output">
<code>requires_action_output</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
Indicates this <code>extra_action</code> requires the output of the
original action to be present as input to this <code>extra_action</code>.
<p>
When true (default false), the extra_action can assume that the
original action outputs are available as part of its inputs.
</p>
</td>
</tr>
<tr>
<td id="extra_action.tools">
<code>tools</code>
</td>
<td>
<p>List of <a href="/versions/7.3.0/concepts/labels">labels</a>; default is <code>[]</code></p>
A list of <code>tool</code> dependencies for this rule.
<p>
See the definition of <a href="/versions/7.3.0/concepts/build-ref#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='/versions/7.3.0/docs/user-manual#configurations'><code>exec</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>
</td>
</tr>
</tbody>