Module providing functions to create actions. Access this module using ctx.actions
.
Members
- args
- declare_directory
- declare_file
- declare_symlink
- do_nothing
- expand_template
- run
- run_shell
- symlink
- template_dict
- write
args
Args actions.args()
declare_directory
File actions.declare_directory(filename, *, sibling=None)
Args.add_all()
. Only regular files and directories can be in the expanded contents of a declare_directory.
Parameters
Parameter | Description |
---|---|
filename
|
string;
required 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; or None ;
default is None A file that lives in the same directory as the newly declared directory. The file must be in the current package. |
declare_file
File actions.declare_file(filename, *, sibling=None)
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;
required 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; or None ;
default is None 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)
Parameters
Parameter | Description |
---|---|
filename
|
string;
required 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
|
File; or None ;
default is None A file that lives in the same directory as the newly declared symlink. |
do_nothing
None
actions.do_nothing(mnemonic, inputs=[])
Parameters
Parameter | Description |
---|---|
mnemonic
|
string;
required A one-word description of the action, for example, CppCompile or GoLink. |
inputs
|
sequence of Files; or depset;
default is [] List of the input files of the action. |
expand_template
None
actions.expand_template(template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)
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;
required The template file, which is a UTF-8 encoded text file. |
output
|
File;
required The output file, which is a UTF-8 encoded text file. |
substitutions
|
dict;
default is {} Substitutions to make when expanding the template. |
is_executable
|
bool;
default is False Whether the output file should be executable. |
computed_substitutions
|
TemplateDict;
default is unbound Substitutions to make when expanding the template. |
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, shadowed_action=None, resource_set=None, toolchain=unbound)
Parameters
Parameter | Description |
---|---|
outputs
|
sequence of Files;
required List of the output files of the action. |
inputs
|
sequence of Files; or depset;
default is [] List or depset of the input files of the action. |
unused_inputs_list
|
File; or None ;
default is None 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
|
File; or string; or FilesToRunProvider;
required The executable file to be called by the action. |
tools
|
sequence; or depset;
default is unbound List or depset of any tools needed by the action. Tools are inputs with additional runfiles that are automatically made available to the action. When a list is provided, it can be a heterogenous collection of Files, FilesToRunProvider instances, or depsets of Files. Files which are directly in the list and come from ctx.executable will have their runfiles automatically added. When a depset is provided, it must contain only Files. In both cases, files within depsets are not cross-referenced with ctx.executable for runfiles. |
arguments
|
sequence;
default is [] Command line arguments of the action. Must be a list of strings or actions.args() objects.
|
mnemonic
|
string; or None ;
default is None A one-word description of the action, for example, CppCompile or GoLink. |
progress_message
|
string; or None ;
default is None Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label} , %{input} , or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient.
|
use_default_shell_env
|
bool;
default is False Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via --action_env .If both |
env
|
dict; or None ;
default is None Sets the dictionary of environment variables. If both |
execution_requirements
|
dict; or None ;
default is None Information for scheduling the action. See tags for useful keys. |
input_manifests
|
sequence; or None ;
default is None Legacy argument. Ignored. |
exec_group
|
string; or None ;
default is None Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. |
shadowed_action
|
Action;
default is None Runs the action using the given shadowed action's inputs and environment added to the action's inputs list and environment. The action environment can overwrite any of the shadowed action's environment variables. If none, uses only the action's inputs and given environment. |
resource_set
|
callable; or None ;
default is None A callback function that returns a resource set dictionary, used to estimate resource usage at execution time if this action is run locally. The function accepts two positional arguments: a string representing an OS name (e.g. "osx"), and an integer representing the number of inputs to the action. The returned dictionary may contain the following entries, each of which may be a float or an int:
If this parameter is set to The callback must be top-level (lambda and nested functions aren't allowed). |
toolchain
|
Label; or string; or None ;
default is unbound Toolchain type of the executable or tools used in this action. If executable and tools are not coming from a toolchain, set this parameter to `None`. If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform. Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function. When `toolchain` and `exec_group` parameters are both set, `exec_group` will be used. An error is raised in case the `exec_group` doesn't specify the same toolchain. |
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, shadowed_action=None, resource_set=None, toolchain=unbound)
Parameters
Parameter | Description |
---|---|
outputs
|
sequence of Files;
required List of the output files of the action. |
inputs
|
sequence of Files; or depset;
default is [] List or depset of the input files of the action. |
tools
|
sequence of Files; or depset;
default is unbound 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
|
sequence;
default is [] 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 In the case where |
mnemonic
|
string; or None ;
default is None A one-word description of the action, for example, CppCompile or GoLink. |
command
|
string; or sequence of strings;
required 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
|
string; or None ;
default is None Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label} , %{input} , or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient.
|
use_default_shell_env
|
bool;
default is False Whether the action should use the default shell environment, which consists of a few OS-dependent variables as well as variables set via --action_env .If both |
env
|
dict; or None ;
default is None Sets the dictionary of environment variables. If both |
execution_requirements
|
dict; or None ;
default is None Information for scheduling the action. See tags for useful keys. |
input_manifests
|
sequence; or None ;
default is None Legacy argument. Ignored. |
exec_group
|
string; or None ;
default is None Runs the action on the given exec group's execution platform. If none, uses the target's default execution platform. |
shadowed_action
|
Action;
default is None Runs the action using the given shadowed action's discovered inputs added to the action's inputs list. If none, uses only the action's inputs. |
resource_set
|
callable; or None ;
default is None A callback function for estimating resource usage if run locally. See ctx.actions.run() .
|
toolchain
|
Label; or string; or None ;
default is unbound Toolchain type of the executable or tools used in this action. If executable and tools are not coming from a toolchain, set this parameter to `None`. If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform. Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function. When `toolchain` and `exec_group` parameters are both set, `exec_group` will be used. An error is raised in case the `exec_group` doesn't specify the same toolchain. |
symlink
None
actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)
This function must be called with exactly one of target_file
or target_path
specified.
When you use target_file
, declare output
with declare_file()
or declare_directory()
and match the type of target_file
. This makes the symlink point to target_file
. Bazel invalidates the output of this action whenever the target of the symlink or its contents change.
Otherwise, when you use target_path
, declare output
with declare_symlink()
). In this case, the symlink points to target_path
. Bazel never resolves the symlink and the output of this action is invalidated only when the text contents of the symlink (that is, the value of readlink()
) changes. In particular, this can be used to create a dangling symlink.
Parameters
Parameter | Description |
---|---|
output
|
File;
required The output of this action. |
target_file
|
File; or None ;
default is None The File that the output symlink will point to. |
target_path
|
string; or None ;
default is None The exact path that the output symlink will point to. No normalization or other processing is applied. |
is_executable
|
bool;
default is False May only be used with target_file , not target_path . If true, when the action is executed, the target_file 's path is checked to confirm that it is executable, and an error is reported if it is not. Setting is_executable to False does not mean the target is not executable, just that no verification is done.This feature does not make sense for |
progress_message
|
string; or None ;
default is None Progress message to show to the user during the build. |
template_dict
TemplateDict actions.template_dict()
write
None
actions.write(output, content, is_executable=False)
expand_template
.
Parameters
Parameter | Description |
---|---|
output
|
File;
required The output file. |
content
|
string; or Args;
required the contents of the file. May be a either a string or an actions.args() object.
|
is_executable
|
bool;
default is False Whether the output file should be executable. |