操作

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
提供用于创建操作函数的模块。使用 ctx.actions 访问此模块。

成员

args

Args actions.args()

返回可用于构建内存高效命令行的 Args 对象。

声明目录

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

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

参数

参数 说明
filename 必需
如果未提供 &s33;sibling',则为新目录(相对于当前软件包)的路径。否则,该文件的基名(“'sibling'”定义一个目录)。
sibling File; or None; default = None
与新声明的目录位于同一目录中的文件。文件必须位于当前的软件包中。

声明文件

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

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

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

请注意,无需使用此函数声明(且无法)声明预先声明的输出文件。您可以改为从 ctx.outputs 获取其 File 对象。查看使用示例

参数

参数 说明
filename 必需
如果未提供“同级”,则为新文件相对于当前文件文件的路径。否则,文件的基本名称(由“同级”决定目录)。
sibling File; or None;默认值为 None
与新创建的文件位于同一目录中的文件。文件必须位于当前的软件包中。

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

实验性。此参数是实验性参数,随时都可能更改。请勿依赖它。可以通过设置 --experimental_allow_unresolved_symlinks 在实验中进行启用

声明规则或方面在当前软件包中创建具有给定名称的符号链接。您必须创建生成此符号链接的操作。Bazel 绝不会引用此符号链接,而是将其逐字转移到沙盒或远程执行程序。

参数

参数 说明
filename 必需
如果未提供 'sibling',则为新符号链接的路径(相对于当前软件包)。否则,该文件的基名(“'sibling'”定义一个目录)。
sibling File; or None;默认值为 None
与新声明的符号链接位于同一目录中的文件。

什么也不做

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

创建一个空操作,该操作既不会执行命令也不会产生任何输出,但对插入“额外操作”非常有用。

参数

参数 说明
mnemonic 必需操作
用一个字词描述的操作,例如:CppCompile 或 GoLink。
inputs sequence of Files; or depset;默认值为 []
操作的输入文件列表。

展开模板

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)

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

参数

参数 说明
outputs sequence of Files;必需
操作输出文件的列表。
inputs sequence of Files; or depset;默认值为 []
列出操作输入文件。
unused_inputs_list File; or None;默认值 = None
包含操作未使用的输入列表的文件。

此文件的内容(通常是某个操作的输出之一)对应于在整个操作执行期间未使用的输入文件列表。这些文件中的任何更改都不得对操作的输出产生任何影响。

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

此函数接受两个位置参数:表示操作系统名称的字符串(例如 "osx")和表示操作输入数量的整数。返回的字典可能包含以下条目,每个条目可以是浮点数或整数:

  • "CPU”:CPU 数量;默认值为 1
  • "memory":以 MB 为单位;默认值为 250
  • "local_test":本地测试数量;默认值为 1

如果此参数设置为 None--experimental_action_resource_set 为 false,则使用默认值。

该回调必须是顶级函数(不允许使用 lambda 和嵌套函数)。

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)

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

参数

参数 说明
outputs sequence of Files;必需
操作输出文件的列表。
inputs sequence of Files; or depset;默认值为 []
列出操作输入文件。
tools sequence of Files; or depset;默认值 = unbound
列出操作所需的任何工具或显示其设置。工具是指具有可自动提供给操作的附加运行文件的输入。该列表可以包含 Files 或 FilesToRunProvider 实例。
arguments sequence;默认值 = []
操作的命令行参数。必须是字符串或 actions.args() 对象列表。

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

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

mnemonic string; or None;默认值 = 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 与 genrule 一样,使用相同的 shell 来执行该命令。

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

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

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

只有在指定 target_filetarget_path 之一时才能调用此函数。

如果使用 target_file,则必须通过 declare_file()declare_directory() 声明 output,并且匹配 target_file 的类型。在本例中,output 是一个内容为 target_file 路径的符号链接。

否则,如果使用 target_path,则必须使用 declare_symlink() 声明 output。在这种情况下,output 将是一个内容为 target_path 的符号链接。它可用于创建悬空的符号链接。

参数

参数 说明
output 必需
此操作的输出。
target_file File; or None;默认值为默认值 None
输出符号链接所指向的文件。
target_path string; or None;默认值为 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; default = None
在构建期间向用户显示的进度消息。

模板字典

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
输出文件是否可执行。