Extra Actions Rules

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

Rules

action_listener

View rule source 
action_listener(name, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, extra_actions, features, licenses, mnemonics, restricted_to, tags, target_compatible_with, testonly, visibility)

WARNING: Extra actions are deprecated. Use aspects instead.

An action_listener rule doesn't produce any output itself. Instead, it allows tool developers to insert extra_actions into the build system, by providing a mapping from action to extra_action .

This rule's arguments map action mnemonics to extra_action rules.

By specifying the option --experimental_action_listener=<label>, the build will use the specified action_listener to insert extra_actions into the build graph.

Example

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)",
)

Arguments

Attributes
name

Name; required

A unique name for this target.
extra_actions

List of labels; required

A list of extra_action targets this action_listener should add to the build graph. E.g. [ "//my/tools:analyzer" ].
mnemonics

List of strings; required

A list of action mnemonics this action_listener should listen for, e.g. [ "Javac" ].

Mnemonics are not a public interface. There's no guarantee that the mnemonics and their actions don't change.

extra_action

View rule source 
extra_action(name, data, cmd, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, out_templates, requires_action_output, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

WARNING: Extra actions are deprecated. Use aspects instead.

An extra_action 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.

See action_listener for details on how to enable extra_actions.

The extra_actions 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 extra_actions_base.proto for details on the data stored inside the protocol buffer. Each proto file contains an ExtraActionInfo message.

Just like all other actions, extra actions are sandboxed, and should be designed to handle that.

Arguments

Attributes
name

Name; required

A unique name for this target.

You may refer to this rule by label in the extra_actions argument of action_listener rules.
cmd

String; required

The command to run.

Like genrule cmd attribute with the following differences:

  1. No heuristic label expansion. Only labels using $(location ...) are expanded.

  2. An additional pass is applied to the string to replace all occurrences of the outputs created from the out_templates attribute. All occurrences of $(output out_template) are replaced with the path to the file denoted by label.

    E.g. out_template $(ACTION_ID).analysis can be matched with $(output $(ACTION_ID).analysis).

    In effect, this is the same substitution as $(location) but with a different scope.

out_templates

List of strings; default is []

A list of templates for files generated by the extra_action command.

The template can use the following variables:

  • $(ACTION_ID), an id uniquely identifying this extra_action. Used to generate a unique output file.

requires_action_output

Boolean; default is False

Indicates this extra_action requires the output of the original action to be present as input to this extra_action.

When true (default false), the extra_action can assume that the original action outputs are available as part of its inputs.

tools

List of labels; default is []

A list of tool dependencies for this rule.

See the definition of dependencies for more information.

The build system ensures these prerequisites are built before running the extra_action command; they are built using the execconfiguration, since they must run as a tool during the build itself. The path of an individual tools target //x:y can be obtained using $(location //x:y).

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.