ContextQMD
Back to Bazel

Extra Actions

docs/versions/6.1.0/reference/be/extra-actions.mdx

9.1.012.1 KB
Original Source
<html devsite> <head> <meta name="project_path" value="/_project.yaml"> <meta name="book_path" value="/versions/6.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> <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.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/6.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/6.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/6.1.0/reference/be/extra-actions.html#extra_action"><code>extra_action</code></a> rules. </p> <p> By specifying the option <a href="/versions/6.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/6.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><code><a href="/versions/6.1.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.1.0/concepts/labels">labels</a>; required</code></p>
                        A list of <code><a href="/versions/6.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><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.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/6.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><code><a href="/versions/6.1.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.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><code>String; required</code></p>
                        The command to run.
    <p>
      Like <a href="/versions/6.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><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.1.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.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/6.1.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>