Google Git
Sign in
bazel/bazel/a640dc240f79ef811fb4089436f1ba6d84ea6bc9/./docs/versions/8.1.0/reference/be/extra-actions.mdx
blob: 0c9cd3784ada6e84f9da8589d409daa861b321e9 [file]
<html devsite>
<head>
<meta name="project_path" value="/_project.yaml">
<meta name="book_path" value="/versions/8.1.0/_book.yaml">
</head>
<body>
<!--
This document is synchronized with Bazel releases.
To edit, submit changes to the Bazel source code.
-->
<!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip -->
<html>
<body>
<h1 class="page-title">Extra Actions Rules</h1>
{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %}
{% dynamic setvar version "8.1.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/8.1.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/8.1.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/8.1.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/8.1.0/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a> rules.
</p>
<p>
By specifying the option <a href="/versions/8.1.0/docs/user-manual#flag--experimental_action_listener">
<code>--experimental_action_listener=&lt;label&gt;</code></a>,
the build will use the specified <code>action_listener</code> to insert
<a href="/versions/8.1.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/8.1.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/8.1.0/concepts/labels">labels</a>; required</p>
A list of <code><a href="/versions/8.1.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>
</table>
<h2 id="extra_action">
extra_action
</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/ExtraActionRule.java" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">extra_action(<a href="#extra_action.name">name</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#extra_action.cmd">cmd</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="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#extra_action.out_templates">out_templates</a>, <a href="#extra_action.requires_action_output">requires_action_output</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.toolchains">toolchains</a>, <a href="#extra_action.tools">tools</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/8.1.0/rules/aspects">aspects</a>
instead.
</p>
<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="/versions/8.1.0/reference/be/extra-actions.html#action_listener"><code>action_listener</code></a> for details
on how to enable <code>extra_action</code>s.
</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.
See <tt>extra_actions_base.proto</tt>
for details on the data stored inside the protocol buffer. Each proto file
contains an ExtraActionInfo message.
</p>
<p>
Just like all other actions, extra actions are sandboxed, and should be designed to handle that.
</p>
<h3 id="extra_action_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="extra_action.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
You may refer to this rule by <code>label</code> in the <code>extra_actions</code> argument
of <a href="/versions/8.1.0/reference/be/extra-actions.html#action_listener"><code> action_listener</code></a> rules.
</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/8.1.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/8.1.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/8.1.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/8.1.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>
</table>
<!-- Generated footer -->
</body>
</html>