Extra Actions Rules

Rules

action_listener
extra_action

action_listener

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)

DISCLAIMER: This is an experimental feature, expect breaking changes when implementing an action_listener/extra_action.

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

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.

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

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)

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: No heuristic label expansion. Only labels using $(location ...) are expanded. 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; optional` 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; optional; 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; optional` 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 `host`configuration, 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.