actions
Module providing functions to create actions. Access this module usingctx.actions
.
Members
args
Args actions.args()Returns an Args object that can be used to build memory-efficient command lines.
declare_directory
File actions.declare_directory(filename, *, sibling=None)Declares that the rule or aspect creates a directory with the given name, in the current package. You must create an action that generates the directory. The contents of the directory are not directly accessible from Starlark, but can be expanded in an action command with
Args.add_all()
.
Parameters
Parameter | Description |
---|---|
filename
|
If no 'sibling' provided, path of the new directory, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). |
sibling
|
A file that lives in the same directory as the newly declared directory. |
declare_file
File actions.declare_file(filename, *, sibling=None)Declares that the rule or aspect creates a file with the given filename. If
sibling
is not specified, the file name is relative to the package directory, otherwise the file is in the same directory as sibling
. Files cannot be created outside of the current package.Remember that in addition to declaring a file, you must separately create an action that emits the file. Creating that action will require passing the returned File
object to the action's construction function.
Note that predeclared output files do not need to be (and cannot be) declared using this function. You can obtain their File
objects from ctx.outputs
instead. See example of use.
Parameters
Parameter | Description |
---|---|
filename
|
If no 'sibling' provided, path of the new file, relative to the current package. Otherwise a base name for a file ('sibling' determines a directory). |
sibling
|
A file that lives in the same directory as the newly created file. The file must be in the current package. |
declare_symlink
File actions.declare_symlink(filename, *, sibling=None)
Experimental. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting --experimental_allow_unresolved_symlinks
Declares that the rule or aspect creates a symlink with the given name in the current package. You must create an action that generates this symlink. Bazel will never dereference this symlink and will transfer it verbatim to sandboxes or remote executors.
Parameters
Parameter | Description |
---|---|
filename
|
If no 'sibling' provided, path of the new symlink, relative to the current package. Otherwise a base name for a file ('sibling' defines a directory). |
sibling
|
A file that lives in the same directory as the newly declared symlink. |
do_nothing
None actions.do_nothing(mnemonic, inputs=[])Creates an empty action that neither executes a command nor produces any output, but that is useful for inserting 'extra actions'.
Parameters
Parameter | Description |
---|---|
mnemonic
|
A one-word description of the action, for example, CppCompile or GoLink. |
inputs
|
List of the input files of the action. |
expand_template
None actions.expand_template(template, output, substitutions, is_executable=False)Creates a template expansion action. When the action is executed, it will generate a file based on a template. Parts of the template will be replaced using the
substitutions
dictionary, in the order the substitutions are specified. Whenever a key of the dictionary appears in the template (or a result of a previous substitution), it is replaced with the associated value. There is no special syntax for the keys. You may, for example, use curly braces to avoid conflicts (for example, {KEY}
). See example of use.
Parameters
Parameter | Description |
---|---|
template
|
The template file, which is a UTF-8 encoded text file. |
output
|
The output file, which is a UTF-8 encoded text file. |
substitutions
|
Substitutions to make when expanding the template. |
is_executable
|
Whether the output file should be executable. |
run
None actions.run(outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None)Creates an action that runs an executable. See example of use.
Parameters
Parameter | Description |
---|---|
outputs
|
List of the output files of the action. |
inputs
|
List or depset of the input files of the action. |
unused_inputs_list
|
File containing list of inputs unused by the action. The content of this file (generally one of the outputs of the action) corresponds to the list of input files that were not used during the whole action execution. Any change in those files must not affect in any way the outputs of the action. |
executable
|
The executable file to be called by the action. |
tools
|
List or depset of any tools needed by the action. Tools are inputs with additional runfiles that are automatically made available to the action. |
arguments
|
Command line arguments of the action. Must be a list of strings or |
mnemonic
|
A one-word description of the action, for example, CppCompile or GoLink. |
progress_message
|
Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". |
use_default_shell_env
|
Whether the action should use the built in shell environment or not. |
env
|
Sets the dictionary of environment variables. |
execution_requirements
|
Information for scheduling the action. See tags for useful keys. |
input_manifests
|
(Experimental) sets the input runfiles metadata; they are typically generated by resolve_command. |
exec_group
|
Experimental. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting |
run_shell
None actions.run_shell(outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None)Creates an action that runs a shell command. See example of use.
Parameters
Parameter | Description |
---|---|
outputs
|
List of the output files of the action. |
inputs
|
List or depset of the input files of the action. |
tools
|
List or depset of any tools needed by the action. Tools are inputs with additional runfiles that are automatically made available to the action. The list can contain Files or FilesToRunProvider instances. |
arguments
|
Command line arguments of the action. Must be a list of strings or Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as In the case where |
mnemonic
|
A one-word description of the action, for example, CppCompile or GoLink. |
command
|
Shell command to execute. This may either be a string (preferred) or a sequence of strings (deprecated). If (Deprecated) If Bazel uses the same shell to execute the command as it does for genrules. |
progress_message
|
Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". |
use_default_shell_env
|
Whether the action should use the built in shell environment or not. |
env
|
Sets the dictionary of environment variables. |
execution_requirements
|
Information for scheduling the action. See tags for useful keys. |
input_manifests
|
(Experimental) sets the input runfiles metadata; they are typically generated by resolve_command. |
exec_group
|
Experimental. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting |
symlink
None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)Creates an action that writes a symlink in the file system.
This function must be called with exactly one of target_file
and target_path
specified.
If target_file
is used, then output
must be declared as a regular file (such as by using declare_file()
). It will actually be created as a symlink that points to the path of target_file
.
If target_path
is used instead, then output
must be declared as a symlink (such as by using declare_symlink()
). In this case, the symlink will point to whatever the content of target_path
is. This can be used to create a dangling symlink.
Parameters
Parameter | Description |
---|---|
output
|
The output of this action. |
target_file
|
The File that the output symlink will point to. |
target_path
|
(Experimental) The exact path that the output symlink will point to. No normalization or other processing is applied. Access to this feature requires setting |
is_executable
|
May only be used with This feature does not make sense for |
progress_message
|
Progress message to show to the user during the build. |
write
None actions.write(output, content, is_executable=False)Creates a file write action. When the action is executed, it will write the given content to a file. This is used to generate files using information available in the analysis phase. If the file is large and with a lot of static content, consider using
expand_template
.
Parameters
Parameter | Description |
---|---|
output
|
The output file. |
content
|
the contents of the file. May be a either a string or an |
is_executable
|
Whether the output file should be executable. |