|
| 1 | +--- |
| 2 | +title: 'Extra Actions Rules' |
| 3 | +--- |
| 4 | + |
| 5 | + |
| 6 | +## Rules |
| 7 | + |
| 8 | +* [action\_listener](#action_listener) |
| 9 | +* [extra\_action](#extra_action) |
| 10 | + |
| 11 | +## action\_listener |
| 12 | + |
| 13 | +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ActionListenerRule.java) |
| 14 | + |
| 15 | +``` |
| 16 | +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) |
| 17 | +``` |
| 18 | + |
| 19 | +**WARNING:** Extra actions are deprecated. Use |
| 20 | +[aspects](https://bazel.build/rules/aspects) |
| 21 | +instead. |
| 22 | + |
| 23 | +An `action_listener` rule doesn't produce any output itself. |
| 24 | +Instead, it allows tool developers to insert |
| 25 | +[`extra_action`](/reference/be/extra-actions#extra_action)s into the build system, |
| 26 | +by providing a mapping from action to [`extra_action`](/reference/be/extra-actions#extra_action). |
| 27 | + |
| 28 | +This rule's arguments map action mnemonics to |
| 29 | +[`extra_action`](/reference/be/extra-actions#extra_action) rules. |
| 30 | + |
| 31 | +By specifying the option [`--experimental_action_listener=<label>`](/docs/user-manual#flag--experimental_action_listener), |
| 32 | +the build will use the specified `action_listener` to insert |
| 33 | +[`extra_action`](/reference/be/extra-actions#extra_action)s into the build graph. |
| 34 | + |
| 35 | +#### Example |
| 36 | + |
| 37 | +``` |
| 38 | +action_listener( |
| 39 | + name = "index_all_languages", |
| 40 | + mnemonics = [ |
| 41 | + "Javac", |
| 42 | + "CppCompile", |
| 43 | + "Python", |
| 44 | + ], |
| 45 | + extra_actions = [":indexer"], |
| 46 | +) |
| 47 | +
|
| 48 | +action_listener( |
| 49 | + name = "index_java", |
| 50 | + mnemonics = ["Javac"], |
| 51 | + extra_actions = [":indexer"], |
| 52 | +) |
| 53 | +
|
| 54 | +extra_action( |
| 55 | + name = "indexer", |
| 56 | + tools = ["//my/tools:indexer"], |
| 57 | + cmd = "$(location //my/tools:indexer)" + |
| 58 | + "--extra_action_file=$(EXTRA_ACTION_FILE)", |
| 59 | +) |
| 60 | +``` |
| 61 | + |
| 62 | +### Arguments |
| 63 | + |
| 64 | +| Attributes | | |
| 65 | +| --- | --- | |
| 66 | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. | |
| 67 | +| `extra_actions` | List of [labels](/concepts/labels); required A list of `extra_action` targets this `action_listener` should add to the build graph. E.g. `[ "//my/tools:analyzer" ]`. | |
| 68 | +| `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. | |
| 69 | + |
| 70 | +## extra\_action |
| 71 | + |
| 72 | +[View rule sourceopen\_in\_new](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/extra/ExtraActionRule.java) |
| 73 | + |
| 74 | +``` |
| 75 | +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) |
| 76 | +``` |
| 77 | + |
| 78 | +**WARNING:** Extra actions are deprecated. Use |
| 79 | +[aspects](https://bazel.build/rules/aspects) |
| 80 | +instead. |
| 81 | + |
| 82 | +An `extra_action` rule doesn't produce any meaningful output |
| 83 | +when specified as a regular build target. Instead, it allows tool developers |
| 84 | +to insert additional actions into the build graph that shadow existing actions. |
| 85 | + |
| 86 | +See [`action_listener`](/reference/be/extra-actions#action_listener) for details |
| 87 | +on how to enable `extra_action`s. |
| 88 | + |
| 89 | +The `extra_action`s run as a command-line. The command-line tool gets |
| 90 | +access to a file containing a protocol buffer as $(EXTRA\_ACTION\_FILE) |
| 91 | +with detailed information on the original action it is shadowing. |
| 92 | +It also has access to all the input files the original action has access to. |
| 93 | +See extra\_actions\_base.proto |
| 94 | +for details on the data stored inside the protocol buffer. Each proto file |
| 95 | +contains an ExtraActionInfo message. |
| 96 | + |
| 97 | +Just like all other actions, extra actions are sandboxed, and should be designed to handle that. |
| 98 | + |
| 99 | +### Arguments |
| 100 | + |
| 101 | +| Attributes | | |
| 102 | +| --- | --- | |
| 103 | +| `name` | [Name](/concepts/labels#target-names); required A unique name for this target. You may refer to this rule by `label` in the `extra_actions` argument of [`action_listener`](/reference/be/extra-actions#action_listener) rules. | |
| 104 | +| `cmd` | String; required The command to run. Like [genrule cmd attribute](/reference/be/general#genrule.cmd) 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. | |
| 105 | +| `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. | |
| 106 | +| `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. | |
| 107 | +| `tools` | List of [labels](/concepts/labels); default is `[]` A list of `tool` dependencies for this rule. See the definition of [dependencies](/concepts/build-ref#deps) for more information. The build system ensures these prerequisites are built before running the `extra_action` command; they are built using the [`exec`configuration](/docs/user-manual#configurations), 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. | |
0 commit comments