actions

Module providing functions to create actions. Access this module using ctx.actions.

Methods

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 rule or aspect create a directory with the given name, in the current package. You must create an action that generates the directory.

Parameters

Parameter Description
filename

string

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

File

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

string

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

File

A file that lives in the same directory as the newly created file. The file must be in the current package.

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

string

A one-word description of the action, for example, CppCompile or GoLink.
inputs

sequence of Files; or depset of Files

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

File

The template file, which is a UTF-8 encoded text file.
output

File

The output file, which is a UTF-8 encoded text file.
substitutions

dict

Substitutions to make when expanding the template.
is_executable

bool

Whether the output file should be executable.

run

None actions.run(outputs, inputs=[], executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None)

Creates an action that runs an executable. See example of use.

Parameters

Parameter Description
outputs

sequence of Files

List of the output files of the action.
inputs

sequence of Files; or depset of Files

List or depset of the input files of the action.
executable

File; or string

The executable file to be called by the action.
tools

sequence of Files; or depset of Files

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

sequence

Command line arguments of the action. Must be a list of strings or actions.args() objects.
mnemonic

string

A one-word description of the action, for example, CppCompile or GoLink.
progress_message

string

Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o".
use_default_shell_env

bool

Whether the action should use the built in shell environment or not.
env

dict

Sets the dictionary of environment variables.
execution_requirements

dict

Information for scheduling the action. See tags for useful keys.
input_manifests

sequence

(Experimental) sets the input runfiles metadata; they are typically generated by resolve_command.

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)

Creates an action that runs a shell command. See example of use.

Parameters

Parameter Description
outputs

sequence of Files

List of the output files of the action.
inputs

sequence of Files; or depset of Files

List or depset of the input files of the action.
tools

sequence of Files; or depset of Files

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

sequence

Command line arguments of the action. Must be a list of strings or actions.args() objects.

Bazel passes the elements in this attribute as arguments to the command.The command can access these arguments using shell variable substitutions such as $1, $2, etc. Note that since Args objects are flattened before indexing, if there is an Args object of unknown size then all subsequent strings will be at unpredictable indices. It may be useful to use $@ (to retrieve all arguments) in conjunction with Args objects of indeterminate size.

In the case where command is a list of strings, this parameter may not be used.
mnemonic

string

A one-word description of the action, for example, CppCompile or GoLink.
command

string; or sequence of strings

Shell command to execute. This may either be a string (preferred) or a sequence of strings (deprecated).

If command is a string, then it is executed as if by sh -c <command> "" <arguments> -- that is, the elements in arguments are made available to the command as $1, $2, etc. If arguments contains any actions.args() objects, their contents are appended one by one to the command line, so $i can refer to individual strings within an Args object. Note that if an Args object of unknown size is passed as part of arguments, then the strings will be at unknown indices; in this case the $@ shell substitution (retrieve all arguments) may be useful.

(Deprecated) If command is a sequence of strings, the first item is the executable to run and the remaining items are its arguments. If this form is used, the arguments parameter must not be supplied.

Bazel uses the same shell to execute the command as it does for genrules.
progress_message

string

Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o".
use_default_shell_env

bool

Whether the action should use the built in shell environment or not.
env

dict

Sets the dictionary of environment variables.
execution_requirements

dict

Information for scheduling the action. See tags for useful keys.
input_manifests

sequence

(Experimental) sets the input runfiles metadata; they are typically generated by resolve_command.

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

File

The output file.
content

string; or Args

the contents of the file. May be a either a string or an actions.args() object.
is_executable

bool

Whether the output file should be executable.