操作

每夜版 · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7
提供用于创建操作的函数的模块。使用 ctx.actions 访问此模块。

成员

args

Args actions.args()

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

declare_directory

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

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

参数

参数 说明
filename 字符串； 必需
如果未提供“同级”目录，则为新目录的路径（相对于当前软件包）。否则，为文件的基本名称（“同级”定义目录）。
sibling 文件；或 None； 默认值为 None
与新声明的目录位于同一目录中的文件。文件必须位于当前软件包中。

declare_file

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

声明规则或方面会创建具有指定文件名的文件。如果未指定 sibling，则文件名相对于软件包目录，否则该文件与 sibling 位于同一目录中。无法在当前软件包之外创建文件。

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

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

参数

参数 说明
filename 字符串； 必需
如果未提供“同级”文件，则新文件的路径（相对于当前软件包）。否则，为文件的基本名称（“同级”确定目录）。
sibling 文件；或 None； 默认值为 None
与新创建的文件位于同一目录中的文件。文件必须位于当前软件包中。 

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

声明规则或方面在当前软件包中创建具有指定名称的符号链接。您必须创建一个生成此符号链接的操作。Bazel 绝不会取消引用此符号链接，而是会将其原封不动地转移到沙盒或远程执行器。目前不支持树状制品中的符号链接。

参数

参数 说明
filename 字符串； 必需
如果未提供“同级”项，则为新符号链接的路径（相对于当前软件包）。否则，为文件的基本名称（“同级”定义目录）。
sibling 文件；或 None； 默认值为 None
与新声明的符号链接位于同一目录中的文件。

do_nothing

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

创建一个既不执行命令也不产生任何输出的空操作，但可用于插入“额外操作”。

参数

参数 说明
mnemonic 字符串； 必需
对操作的单字描述，例如 CppCompile 或 GoLink。
inputs 文件的序列；或 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 dict；默认值为 {}
展开模板时要进行的替换。
is_executable bool； 默认值为 False
输出文件是否应可执行。
computed_substitutions TemplateDict；默认值为 unbound
扩展模板时要进行的替换。

map_directory

None actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation)

根据一个或多个输入目录中的文件创建多个操作，以输出一个或多个输出目录。

参数

参数 说明
input_directories 文件的字典；必需
一个将字符串映射到输入目录的字典，如 ctx.actions.declare_directory() 所声明（此处只允许将目录作为值）。这些值指定了我们希望展开的目录，以便在实现函数中访问其文件。键（字符串）充当标识符，以便在实现函数中轻松引用特定目录。
additional_inputs dict；默认值为 {}
一个字典，用于将字符串映射到其他输入（此处仅允许使用文件、FilesToRunProvider 和 Depset）。这些值用于指定我们希望通过实现函数创建的操作访问的任何其他输入。键（字符串）充当标识符，以便在实现函数中轻松引用特定输入。
output_directories File 的 dict；必需
一个将字符串映射到输出目录的字典，如 ctx.actions.declare_directory() 所声明。这些值指定了我们希望通过实现函数创建的操作生成的输出目录。键（字符串）充当标识符，以便从实现函数中轻松引用特定输出目录。
tools dict； 必需
一个将字符串映射到工具的字典（此处仅允许使用文件、FilesToRunProvider 和 Depset）。这些值用于指定我们希望通过实现函数创建的操作访问的工具。这些键（字符串）充当标识符，以便在实现函数中轻松引用特定工具。
additional_params dict；默认值为 {}
一个将字符串映射到其他参数的字典（此处仅允许使用字符串、布尔值和整数值）。这些值用于指定我们希望实现函数能够访问的任何其他参数，这些参数可用于影响实现函数的行为。键（字符串）充当标识符，以便从实现函数中轻松引用特定参数。
execution_requirements dict；或 None； 默认值为 None
用于安排所创建操作的信息。如需了解实用键，请参阅标记。
exec_group 字符串；或 None； 默认值为 None
在给定执行组的执行平台上运行创建的操作。如果未指定，则使用目标的默认执行平台。
toolchain 标签；或字符串；或 None； 默认值为 None

所创建操作使用的可执行文件或工具的工具链类型。

如果可执行文件和工具不是来自工具链，请将此参数设置为 None。

如果可执行文件和工具来自工具链，则必须设置工具链类型，以便创建的操作在正确的执行平台上执行。

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

如果同时设置了 toolchain 和 exec_group 参数，则系统会使用 exec_group。如果 exec_group 未指定相同的工具链，则会引发错误。
use_default_shell_env bool； 默认值为 False
创建的操作是否应使用默认 shell 环境，该环境包含一些与操作系统相关的变量以及通过 --action_env 设置的变量。

如果 use_default_shell_env 和 env 都设置为 True，则 env 中设置的值将覆盖默认的 shell 环境。

env dict；或 None； 默认值为 None
设置环境变量字典。

如果 use_default_shell_env 和 env 都设置为 True，则 env 中设置的值将覆盖默认的 shell 环境。

mnemonic 字符串；或 None； 默认值为 None
对所创建操作的单字描述，例如 CppCompile 或 GoLink。
implementation 函数； 必需
在构建输入目录后调用的 Starlark 函数，用于生成将文件输出到指定输出目录的操作。此函数会传递以下实参：
  • template_ctx（位置实参）：一个 template_ctx 对象，可用于创建操作。
  • input_directories（仅限关键字）：一个字典，用于将 actions.map_directory() 的 input_directories 实参的字符串键映射到其值的相应 ExpandedDirectory 对象。
  • output_directories（仅限关键字实参）：actions.map_directory() 的 output_directories 实参的值；一个从字符串到输出目录的映射字典。
  • additional_inputs（仅限关键字实参）：actions.map_directory() 的 additional_inputs 实参的值；一个从字符串到输入文件的字典映射。
  • tools（仅限关键字）：actions.map_directory() 的 tools 实参的值；一个从字符串到工具的映射字典。
  • additional_params（仅限关键字）：actions.map_directory() 的 additional_params 实参的值；一个从字符串到字符串、布尔值或整数的字典映射。
此函数必须是顶级函数，即不允许使用 lambda 和嵌套函数。

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)

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

参数

参数 说明
outputs 文件的序列；必需属性
操作的输出文件列表。
inputs 文件的序列；或 depset； 默认值为 []
操作的输入文件的列表或 depset。
unused_inputs_list 文件；或 None； 默认值为 None
包含操作未使用的输入列表的文件。

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

executable 文件；或字符串；或 FilesToRunProvider；必需
操作要调用的可执行文件。
tools 序列；或 depset； 默认值为 unbound
操作所需的任何工具的列表或 depset。工具是可执行的输入，可能具有自己的运行文件，这些文件会自动提供给操作。

如果提供的是列表，则可以是以下各项的异构集合：

  • File 秒
  • FilesToRunProvider 个实例
  • depsets 的 Files
来自 ctx.executable 的 File 和直接位于列表中的 FilesToRunProvider 将自动添加其 runfile。所有工具都会隐式添加为输入。

arguments 序列；默认值为 []
操作的命令行实参。必须是字符串列表或 actions.args() 对象。
mnemonic 字符串；或 None； 默认值为 None
操作的单字说明，例如 CppCompile 或 GoLink。
progress_message 字符串；或 None； 默认值为 None
在 build 期间向用户显示的进度消息，例如“正在编译 foo.cc 以创建 foo.o”。消息可以包含 %{label}、%{input} 或 %{output} 格式，这些格式分别替换为标签字符串、第一个输入或输出的路径。最好使用模式而不是静态字符串，因为前者更高效。
use_default_shell_env bool； 默认值为 False
操作是否应使用默认 shell 环境，该环境包含一些与操作系统相关的变量以及通过 --action_env 设置的变量。

如果 use_default_shell_env 和 env 都设置为 True，则 env 中设置的值将覆盖默认的 shell 环境。

env dict；或 None； 默认值为 None
设置环境变量字典。

如果 use_default_shell_env 和 env 都设置为 True，则 env 中设置的值将覆盖默认的 shell 环境。

execution_requirements dict；或 None； 默认值为 None
用于安排操作的信息。如需了解实用键，请参阅标记。
input_manifests 序列；或 None； 默认值为 None
旧版实参。已忽略。
exec_group 字符串；或 None； 默认值为 None
在给定执行组的执行平台上运行操作。如果未指定，则使用目标的默认执行平台。
shadowed_action 操作；默认值为 None
使用添加到操作的输入列表和环境中的给定影子操作的输入和环境来运行操作。操作环境可以覆盖任何被遮盖的操作的环境变量。如果为 None，则仅使用操作的输入和给定的环境。
resource_set 可调用对象；或 None； 默认值为 None
一个回调函数，用于返回资源集字典，以在本地运行此操作时估计执行时的资源使用情况。

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

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

如果此参数设置为 None，则使用默认值。

回调必须是顶级回调（不允许使用 lambda 和嵌套函数）。

toolchain 标签；或字符串；或 None； 默认值为 unbound

相应操作中使用的可执行文件或工具的工具链类型。

如果可执行文件和工具不是来自工具链，请将此参数设置为“None”。

如果可执行文件和工具来自工具链，则必须设置工具链类型，以便操作在正确的执行平台上执行。

请注意，创建此操作的规则需要在其“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=unbound)

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

参数

参数 说明
outputs 文件的序列；必需属性
操作的输出文件列表。
inputs 文件的序列；或 depset； 默认值为 []
操作的输入文件的列表或 depset。
tools File 的序列；或 depset； 默认值为 unbound
操作所需的任何工具的列表或 depset。工具是可执行的输入，可能具有自己的运行文件，这些文件会自动提供给操作。

如果提供的是列表，则可以是以下各项的异构集合：

  • File 秒
  • FilesToRunProvider 个实例
  • depsets 的 Files
来自 ctx.executable 的 File 和直接位于列表中的 FilesToRunProvider 将自动添加其 runfile。所有工具都会隐式添加为输入。

arguments 序列；默认值为 []
操作的命令行实参。必须是字符串列表或 actions.args() 对象列表。

Bazel 会将此属性中的元素作为实参传递给命令。命令可以使用 shell 变量替换（例如 $1、$2 等）来访问这些实参。请注意，由于 Args 对象在编制索引之前会进行扁平化处理，因此如果存在大小未知的 Args 对象，则所有后续字符串都将位于不可预测的索引处。将 $@（用于检索所有实参）与大小不确定的 Args 对象搭配使用可能很有用。

如果 command 是字符串列表，则可能无法使用此形参。

mnemonic 字符串；或 None； 默认值为 None
操作的单字说明，例如 CppCompile 或 GoLink。
command 字符串；或字符串的序列；必需
要执行的 shell 命令。可以是字符串（首选）或字符串序列（已弃用）。

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

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

Bazel 使用与 genrule 相同的 shell 来执行命令。

progress_message 字符串；或 None； 默认值为 None
在 build 期间向用户显示的进度消息，例如“正在编译 foo.cc 以创建 foo.o”。消息可以包含 %{label}、%{input} 或 %{output} 格式，这些格式分别替换为标签字符串、第一个输入或输出的路径。最好使用模式而不是静态字符串，因为前者更高效。
use_default_shell_env bool； 默认值为 False
操作是否应使用默认 shell 环境，该环境包含一些与操作系统相关的变量以及通过 --action_env 设置的变量。

如果 use_default_shell_env 和 env 都设置为 True，则 env 中设置的值将覆盖默认的 shell 环境。

env dict；或 None； 默认值为 None
设置环境变量字典。

如果 use_default_shell_env 和 env 都设置为 True，则 env 中设置的值将覆盖默认的 shell 环境。

execution_requirements dict；或 None； 默认值为 None
用于安排操作的信息。如需了解实用键，请参阅标记。
input_manifests 序列；或 None； 默认值为 None
旧版实参。已忽略。
exec_group 字符串；或 None； 默认值为 None
在给定执行组的执行平台上运行操作。如果未指定，则使用目标的默认执行平台。
shadowed_action 操作；默认值为 None
使用添加到操作输入列表中的给定影子操作的已发现输入运行操作。如果未指定，则仅使用操作的输入。
resource_set 可调用对象；或 None；默认值为 None
用于在本地运行时估计资源使用情况的回调函数。请参阅 ctx.actions.run()。
toolchain 标签；或字符串；或 None； 默认值为 unbound

相应操作中使用的可执行文件或工具的工具链类型。

如果可执行文件和工具不是来自工具链，请将此参数设置为“None”。

如果可执行文件和工具来自工具链，则必须设置工具链类型，以便操作在正确的执行平台上执行。

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

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

 

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

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

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

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

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

参数

参数 说明
output 文件；必需
相应操作的输出。
target_file 文件；或 None； 默认值为 None
输出符号链接将指向的文件。
target_path 字符串；或 None； 默认值为 None
输出符号链接将指向的确切路径。不应用任何归一化或其他处理。
target_type 字符串；或 None； 默认值为 None
只能与 target_path 搭配使用，不能与 target_file 搭配使用。如果指定了该属性，其值必须为“file”或“directory”，表示目标路径的预期类型。

在 Windows 上，此属性用于确定要创建的文件系统对象的类型（目录的联接点，文件的符号链接）。对其他操作系统没有影响。

is_executable 布尔值； 默认值为 False
只能与 target_file 搭配使用，不能与 target_path 搭配使用。如果为 true，则在执行操作时，系统会检查 target_file 的路径以确认其是否可执行，如果不可执行，则会报告错误。将 is_executable 设置为 False 并不意味着目标不可执行，只是不进行验证。

此功能不适用于 target_path，因为悬空符号链接可能在 build 时不存在。
progress_message 字符串；或 None； 默认值为 None
在 build 期间向用户显示的进度消息。

template_dict

TemplateDict actions.template_dict()

返回一个 TemplateDict 对象，用于以节省内存的方式展开模板。

write

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

创建文件写入操作。执行该操作时，它会将指定内容写入文件。此参数用于使用分析阶段中提供的信息生成文件。如果文件较大且包含大量静态内容，请考虑使用 expand_template。

参数

参数 说明
output 文件；必需
输出文件。
content 字符串；或 Args；必需
文件的内容。可以是字符串，也可以是 actions.args() 对象。
is_executable bool； 默认值为 False
输出文件是否应可执行。
mnemonic 字符串；或 None； 默认值为 None
操作的单字说明，例如 CppCompile 或 GoLink。