操作

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

成员

args

Args actions.args()

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

declare_directory

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

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

参数

参数 说明
filename 必需
如果没有“同级”提供的新目录路径(相对于当前软件包)。否则,为文件指定基名(“同级”定义目录)。
sibling File; or None; 默认值 = 无
与新声明的目录位于同一目录的文件。该文件必须位于当前软件包中。

declare_file

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

声明规则或方面会创建一个使用给定文件名的文件。如果未指定 sibling,则文件名相对于软件包目录;否则,文件位于 sibling 所在的目录中。无法在当前软件包之外创建文件。

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

请注意,预声明的输出文件不需要(也不能)使用此函数声明。您可以改为从 ctx.outputs 获取它们的 File 对象。查看使用示例

参数

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

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

实验性。此参数目前处于实验阶段,随时可能发生变化。请勿依赖此功能。您可以通过设置 --experimental_allow_unresolved_symlinks 来实验性启用该功能

声明该规则或切面会在当前软件包中创建具有给定名称的符号链接。您必须创建一个用于生成此符号链接的操作。Bazel 绝不会解引用此符号链接,并会将其原样转移到沙盒或远程执行器。

参数

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

do_nothing

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

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

参数

参数 说明
mnemonic 必需
对相应操作的简短说明,例如 CppCompile 或 GoLink。
inputs sequence of Files; or depset; 默认值 = []
操作的输入文件列表。

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

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

参数

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

此文件的内容(通常是操作的一个输出)与在整个操作执行过程中未使用的输入文件列表相对应。这些文件中的任何更改都不得以任何方式影响操作的输出。

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

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

  • "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; 默认值 = []
列出或弃用操作的输入文件。
tools sequence of Files; or depset; 默认 = 未绑定
列出或弃用操作所需的所有工具。工具是包含其他 runfile 的输入,可自动提供给操作使用。该列表可以包含 Files 或 FilesToRunProvider 实例。
arguments sequence; 默认值 = []
操作的命令行参数。必须是字符串或 actions.args() 对象的列表。

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

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

mnemonic string; or 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; 默认值 = 无
构建期间向用户显示的进度消息,例如“编译 foo.cc 以创建 foo.o”。该消息可能包含 %{label}%{input}%{output} 模式,这些模式分别替换为标签字符串、首次输入或输出的路径。尽量使用模式,而不是静态字符串,因为前者效率更高。
use_default_shell_env 默认值 = False
操作是否应使用内置的 shell 环境。
env dict; or None; 默认值 = 无
设置环境变量字典。
execution_requirements dict; or None; 默认值为 None
用于安排操作的信息。如需了解实用键,请参阅标记
input_manifests sequence; or None; 默认值 = 无
(实验性)设置输入 Runfile 元数据;它们通常由 resolve_command 生成。
exec_group string; or None; 默认值 = 无
在指定执行组的执行平台上运行操作。如果没有,则使用目标的默认执行平台。
shadowed_action Action; 默认值 = 无
使用添加到操作的输入列表中的指定被覆盖操作的已发现输入来运行操作。如果没有,则仅使用操作的输入。
resource_set callable; or None; 默认值 = 无
用于估算资源使用情况的回调函数(如果在本地运行)。请参阅 ctx.actions.run()
toolchain Label; or string; or 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_filetarget_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; 默认值 = 无
输出符号链接将指向的文件。
target_path string; or None; 默认值为 None
(实验性)输出符号链接将指向的确切路径。系统不会应用任何标准化或其他处理。要使用此功能,必须设置 --experimental_allow_unresolved_symlinks
is_executable 默认值 = False
只能与 target_file 一起使用,而不能与 target_path 一起使用。如果为 true,则在执行操作时,系统会检查 target_file 的路径,以确认其是否可执行;如果不可执行,则会报告错误。将 is_executable 设为 False 并不意味着目标不可执行,而只是表示未执行任何验证。

此功能对 target_path 没有意义,因为在构建时可能不存在悬空符号链接。

progress_message string; or 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
输出文件是否应可执行。