操作

提供用于创建操作的函数的模块。请使用 ctx.actions 访问此模块。

成员

args

Args actions.args()

返回一个 Args 对象，该对象可用于构建节省内存的命令行。

declare_directory

File actions.declare_directory(filename, *, sibling=None)

声明规则或切面在当前软件包中创建具有指定名称的目录。您必须创建一个生成目录的操作。您无法直接从 Starlark 访问该目录的内容，但可以使用 Args.add_all() 在操作命令中展开该目录。

参数

参数 说明
filename required
如果未提供“同级”，则为新目录的路径（相对于当前软件包）。否则，为文件的基本名称（“同级”定义目录）。
sibling File; or None; default = None
与新声明的目录位于同一目录中的文件。该文件必须位于当前软件包中。

declare_file

File actions.declare_file(filename, *, sibling=None)

声明规则或切面使用给定文件名创建文件。如果未指定 sibling，则文件名将相对于软件包目录，否则文件将与 sibling 位于同一目录中。无法在当前软件包之外创建文件。

请注意，除了声明文件之外，您还必须单独创建一个发出该文件的操作。创建该操作需要将返回的 File 对象传递给操作的构建函数。

请注意，您不需要（也无法）使用此函数声明预声明的输出文件。您可以改为从 ctx.outputs 获取其 File 对象。查看使用示例。

参数

参数 说明
filename required
如果未提供“同级”，则为新文件相对于当前软件包的路径。否则，使用文件的基名（“同级”决定目录）。
sibling File; or None; default = None
与新创建的文件位于同一目录中的文件。该文件必须位于当前软件包中。 

File actions.declare_symlink(filename, *, sibling=None)

实验性。此参数尚处于实验阶段，随时可能发生变化。请不要依赖它。可以通过设置 --experimental_allow_unresolved_symlinks 进行实验性启用

声明规则或切面在当前软件包中创建具有指定名称的符号链接。您必须创建一个生成此符号链接的操作。Bazel 绝不会取消对此符号链接的引用，而是将其逐字传送到沙盒或远程执行程序。

参数

参数 说明
filename required
如果未提供“同级”，则为新符号链接的路径（相对于当前软件包）。否则，为文件的基本名称（“同级”定义目录）。
sibling File; or None; default = None
与新声明的符号链接位于同一目录中的文件。

do_nothing

None actions.do_nothing(mnemonic, inputs=[])

创建既不会执行命令也不会生成任何输出的空操作，但这对于插入“额外操作”很有用。

参数

参数 说明
mnemonic 必需
操作的单字说明，例如 CppCompile 或 GoLink。
inputs sequence of Files; or depset； default = []
操作的输入文件列表。

expand_template

None actions.expand_template(template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)

创建模板展开操作。执行操作时，系统将根据模板生成一个文件。系统将按照指定替换项的顺序使用 substitutions 字典替换模板的某些部分。每当字典的键出现在模板中（或之前替换的结果）中时，它都会替换为关联的值。这些键没有特殊语法。例如，您可以使用大括号以避免冲突（例如，{KEY}）。查看使用示例。

参数

参数 说明
template 必需
模板文件，它是一个 UTF-8 编码的文本文件。
output 必需
输出文件，即一个 UTF-8 编码的文本文件。
substitutions default = {}
展开模板时要执行的替换。
is_executable default = False
输出文件是否应为可执行文件。
computed_substitutions TemplateDict；默认 = 未绑定
实验性。此参数尚处于实验阶段，随时可能发生变化。请不要依赖它。可以通过设置 --+experimental_lazy_template_expansion
实验性功能：在展开模板时要替换的内容来启用实验性功能。

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=None)

创建用于运行可执行文件的操作。查看使用示例。

参数

参数 说明
outputs sequence of Files；必需
操作的输出文件列表。
inputs sequence of Files; or depset; default = []
操作的输入文件的列表或偏移量。
unused_inputs_list File; or None； 默认设置为 None
包含操作未使用的输入源列表的文件。

此文件的内容（通常是操作的输出之一）对应于整个操作执行期间未使用的输入文件的列表。对这些文件所做的任何更改都不得以任何方式影响该操作的输出。

executable File; or string; or FilesToRunProvider；必需
操作要调用的可执行文件。
tools sequence; or depset； default = unbound
操作所需的所有工具的列表或依赖项。工具是自动为操作提供的附加运行文件的输入。如果提供列表，列表可以是文件、FilesToRunProvider 实例的异构集合，或文件视频的依赖项。系统会自动添加位于列表中且来自 ctx.executable 的文件的 runfile。如果提供了 depset，其中只能包含“文件”。在这两种情况下，不会将 depset 中的文件与 runfiles 的 ctx.executable 交叉引用。
arguments sequence; default = []
操作的命令行参数。必须是字符串列表或 actions.args() 对象列表。
mnemonic string; or None; default = None
操作的单字说明，例如 CppCompile 或 GoLink。
progress_message string; or None； default = None
在构建期间向用户显示的进度消息，例如“正在编译 foo.cc 以创建 foo.o”。消息可能包含 %{label}、%{input} 或 %{output} 模式，它们分别替换为标签字符串、第一个输入或输出的路径。首选使用模式而非静态字符串，因为前者的效率更高。
use_default_shell_env default = False
操作是否应使用内置的 shell 环境。
env dict; or None; default = None
设置环境变量的字典。
execution_requirements dict; or None； default = None
有关安排操作的信息。如需了解实用键，请参阅标记。
input_manifests sequence; or None； default = None
（实验性）设置输入 runfiles 元数据；它们通常由 resolve_command 生成。
exec_group string; or None; default = None
在给定执行组的执行平台上运行操作。如果没有，则使用目标的默认执行平台。
shadowed_action Action; default = None
使用被覆盖的指定操作的输入和环境（添加到操作的输入列表和环境）运行操作。操作环境可以覆盖被覆盖的操作的任何环境变量。如果没有任何值，则仅使用操作的输入和给定的环境。
resource_set callable; or None； default = None
一个返回资源集字典的回调函数，用于在本地运行此操作时估算执行时的资源使用量。

该函数接受两个位置参数：表示操作系统名称的字符串（例如“osx”）和表示操作的输入数量的整数。返回的字典可能包含以下条目，其中每个条目可能是浮点数或 int：

  • "cpu"：CPU 数量；默认值为 1
  • “memory”：以 MB 为单位；默认值为 250
  • “local_test”：本地测试数；默认值为 1

如果此参数设置为 None 或 --experimental_action_resource_set 为 false，系统将使用默认值。

回调必须是顶级（不允许使用 lambda 和嵌套函数）。
toolchain Label; or string; or None；默认值 = None

此操作中使用的可执行文件或工具的工具链类型。必须设置该参数，以便操作在正确的执行平台上执行。

它目前是一项空操作，但我们建议您在使用工具链时设置它，因为未来的 Bazel 版本中会用到它。

请注意，创建此操作的规则需要在其“rule()”函数中定义此工具链。

如果“toolchain”和“exec_group”参数均已设置，系统将使用“exec_group”。如果“exec_group”未指定相同的值，则会引发错误。

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=None)

创建用于运行 shell 命令的操作。查看使用示例。

参数

参数 说明
outputs sequence of Files；必需
操作的输出文件列表。
inputs sequence of Files; or depset; default = []
操作的输入文件的列表或偏移量。
tools sequence of Files; or depset； default = unbound
操作所需的所有工具的列表或依赖项。工具是自动为操作提供的附加运行文件的输入。该列表可以包含 Files 或 FilesToRunProvider 实例。
arguments sequence; default = []
操作的命令行参数。必须是字符串列表或 actions.args() 对象列表。

Bazel 会将此属性中的元素作为参数传递给命令。该命令可以使用 shell 变量替代项（例如 $1、$2 等）访问这些参数。请注意，由于 Args 对象在编入索引之前会展平，因此如果存在大小未知的 Args 对象，则所有后续字符串都将采用不可预测的索引。将 $@（检索所有参数）与大小不确定的 Args 对象结合使用可能会很有用。

如果 command 是字符串列表，则不可使用此参数。

mnemonic string; or None; default = None
操作的单字说明，例如 CppCompile 或 GoLink。
command string; or sequence of strings；必需
要执行的 Shell 命令。它可以是一个字符串（首选）或一系列字符串（已弃用）。

如果 command 是一个字符串，则该函数会像 sh -c <command> "" <arguments> 一样执行。也就是说，arguments 中的元素作为 $1、$2（如果使用 Windows 批处理，则为 %1、%2）等提供给命令使用。如果 arguments 包含任何 actions.args() 对象，其内容会逐一附加到命令行中，以便 $i 可以引用 Args 对象中的各个字符串。请注意，如果将大小未知的 Args 对象作为 arguments 的一部分进行传递，字符串将位于未知索引；在这种情况下，$@ shell 替换（检索所有参数）可能会很有用。

（已弃用）如果 command 是一系列字符串，则第一项是要运行的可执行文件，其余项是它的参数。如果使用此表单，则不得提供 arguments 参数。请注意，此表单已被弃用，很快就会被移除。可通过“--incompatible_run_shell_command_string”来停用该功能。请使用此标记验证您的代码是否兼容。

Bazel 使用与 genrules 相同的 shell 执行命令。
progress_message string; or None； default = None
在构建期间向用户显示的进度消息，例如“正在编译 foo.cc 以创建 foo.o”。消息可能包含 %{label}、%{input} 或 %{output} 模式，它们分别替换为标签字符串、第一个输入或输出的路径。首选使用模式而非静态字符串，因为前者的效率更高。
use_default_shell_env default = False
操作是否应使用内置的 shell 环境。
env dict; or None; default = None
设置环境变量的字典。
execution_requirements dict; or None； default = None
有关安排操作的信息。如需了解实用键，请参阅标记。
input_manifests sequence; or None； default = None
（实验性）设置输入 runfiles 元数据；它们通常由 resolve_command 生成。
exec_group string; or None; default = None
在给定执行组的执行平台上运行操作。如果没有，则使用目标的默认执行平台。
shadowed_action Action; default = None
使用指定的被覆盖操作发现的添加到操作输入列表的输入运行操作。如果没有设置，则仅使用操作的输入。
resource_set callable; or None； default = None
在本地运行时，用于估算资源使用情况的回调函数。请参阅 ctx.actions.run()。
toolchain Label; or string; or None；默认值 = None

此操作中使用的可执行文件或工具的工具链类型。必须设置该参数，以便操作在正确的执行平台上执行。

它目前是一项空操作，但我们建议您在使用工具链时设置它，因为未来的 Bazel 版本中会用到它。

请注意，创建此操作的规则需要在其“rule()”函数中定义此工具链。

如果“toolchain”和“exec_group”参数均已设置，系统将使用“exec_group”。如果“exec_group”未指定相同的工具链，则会引发错误。

 

None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)

创建在文件系统中写入符号链接的操作。

调用此函数时必须明确指定 target_file 或 target_path 中的一个。

使用 target_file 时，请使用 declare_file() 或 declare_directory() 声明 output，并匹配 target_file 的类型。这会使符号链接指向 target_file。每当符号链接的目标或其内容发生变化时，Bazel 都会使此操作的输出失效。

否则，当您使用 target_path 时，请使用 declare_symlink() 声明 output。在本例中，符号链接指向 target_path。Bazel 绝不会解析符号链接，并且只有在符号链接的文本内容（即 readlink() 的值）发生更改时，此操作的输出才会失效。特别是，这可用于创建悬挂的符号链接。

参数

参数 说明
output 必需
此操作的输出。
target_file File; or None; default = None
输出符号链接将指向的文件。
target_path string; or None； default = None
（实验性）输出符号链接将指向的确切路径。不会进行标准化或其他处理。如需使用此功能，需要设置 --experimental_allow_unresolved_symlinks。
is_executable default = False
只能与 target_file 一起使用，不能与 target_path 一起使用。如果为 true，则在执行操作时，会检查 target_file 的路径以确认其是否可执行，否则将报告错误。将 is_executable 设为 False 并不意味着目标不可执行，只表示不会完成任何验证。

此功能对 target_path 没有意义，因为在构建时可能不存在悬挂的符号链接。
progress_message string; or None； 默认值 = None
在构建期间向用户显示的进度消息。

template_dict

TemplateDict actions.template_dict()

实验性。此 API 目前处于实验阶段，随时可能更改。请不要依赖它。可以通过设置 --+experimental_lazy_template_expansion
实验性功能来实验性启用该功能：返回 TemplateDict 对象，实现节省内存的模板扩展。

write

None actions.write(output, content, is_executable=False)

创建文件写入操作。执行该操作时，它会将指定的内容写入文件。这是为了使用分析阶段可用的信息生成文件。如果文件很大并且包含大量静态内容，请考虑使用 expand_template。

参数

参数 说明
output 必需
输出文件。
content string; or Args；必需
文件内容。可以是字符串或 actions.args() 对象。
is_executable default = False
输出文件是否应为可执行文件。