<html devsite>
<head>
  <meta name="project_path" value="/_project.yaml">
  <meta name="book_path" value="/versions/6.2.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>



<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>

  <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/6.2.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/6.2.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/6.2.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/6.2.0/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a> rules.
</p>

<p>
  By specifying the option <a href="/versions/6.2.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/6.2.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><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; required</code></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><code>List of <a href="/versions/6.2.0/concepts/labels">labels</a>; required</code></p>
                            A list of <code><a href="/versions/6.2.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><code>List of strings; required</code></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>

  <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/6.2.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/6.2.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><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; required</code></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/6.2.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><code>String; required</code></p>
                            The command to run.
        <p>
          Like <a href="/versions/6.2.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><code>List of strings; optional</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><code>Boolean; optional; default is 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><code>List of <a href="/versions/6.2.0/concepts/labels">labels</a>; optional</code></p>
                            A list of <code>tool</code> dependencies for this rule.
        <p>
          See the definition of <a href="/versions/6.2.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/6.2.0/docs/user-manual#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>

        </td>
      </tr>
                        </tbody>
  </table>

<!-- Generated footer -->

</body>
</html>
