# Extra Actions Rules

{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} {% dynamic setvar version "8.3.0" %} {% dynamic setvar original_path "/reference/be/extra-actions" %} {% include "_buttons.html" %}

## Rules

- action_listener
- extra_action

## action_listener

View rule sourceopen_in_new

    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_action`s 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_action`s 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 sourceopen_in_new

    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_action`s.

The `extra_action`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 `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; 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 `exec`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.