BazelCon 2024 报名现已开放！

此页面由 Cloud Translation API 翻译。

操作

报告问题查看源代码每夜 build · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

成员

args
declare_directory
declare_file
declare_symlink
do_nothing
expand_template
run
run_shell
symlink
template_dict
write

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` 与新创建的文件位于同一目录中的文件。该文件必须位于当前软件包中。

declare_symlink

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；默认为 `[]` action 的输入文件列表。

expand_template

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

创建模板展开操作。执行操作时，它会根据模板生成文件。系统将使用 substitutions 字典替换模板的部分内容，并遵循指定的替换顺序。每当模板中出现字典的键（或之前替换项的结果）时，系统都会将其替换为关联的值。键没有特殊语法。例如，您可以使用大括号来避免冲突（例如 {KEY}）。请参阅使用示例。

参数

参数	说明
`template`	必需模板文件，即 UTF-8 编码的文本文件。
`output`	必需输出文件，即 UTF-8 编码的文本文件。
`substitutions`	默认值为 `{}` 在展开模板时要进行的替换。
`is_executable`	默认值为 `False` 输出文件是否应可执行。
`computed_substitutions`	TemplateDict；默认值为 `unbound` 在展开模板时要进行的替换。

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`	文件的序列；或依赖项集；默认为 `[]` 操作的输入文件的列表或依赖项集。
`unused_inputs_list`	文件；或 `None`；默认为 `None` 包含操作未使用的输入列表的文件。此文件的内容（通常是操作的输出之一）对应于整个操作执行期间未使用的输入文件列表。这些文件中的任何更改都不得以任何方式影响操作的输出。
`executable`	文件；或字符串；或 FilesToRunProvider；必需要由操作调用的可执行文件。
`tools`	sequence；或 depset；默认为 `unbound` 操作所需的所有工具的列表或 depset。工具是包含额外运行文件的输入，这些运行文件会自动提供给相应操作。提供列表时，该列表可以是 Files、FilesToRunProvider 实例或 Files 的 depset 的异构集合。列表中直接来自 ctx.executable 的文件将自动添加其 runfile。提供 depset 时，其中必须仅包含文件。在这两种情况下，对于 runfile，depset 中的文件不会与 ctx.executable 进行交叉引用。
`arguments`	sequence；默认为 `[]` ，即操作的命令行参数。必须是字符串或 `actions.args()` 对象的列表。
`mnemonic`	字符串；或 `None`；默认为 `None` 对操作的单字描述，例如 CppCompile 或 GoLink。
`progress_message`	字符串；或 `None`；默认为 `None` 在构建期间向用户显示的进度消息，例如“正在编译 foo.cc 以创建 foo.o”。消息可能包含 `%{label}`、`%{input}` 或 `%{output}` 模式，这些模式分别会替换为标签字符串、第一个输入或输出的路径。尽量使用模式，而不是静态字符串，因为前者效率更高。
`use_default_shell_env`	默认值为 `False` 确定操作是否应使用默认 shell 环境，该环境由一些与操作系统相关的变量以及通过 `--action_env` 设置的变量组成。如果 `use_default_shell_env` 和 `env` 都设置为 `True`，则如果 `--incompatible_merge_fixed_and_default_shell_env` 处于启用状态（默认），`env` 中设置的值将覆盖默认的 Shell 环境。如果未启用该标志，系统会忽略 `env`。
`env`	字典；或 `None`；默认为 `None` 设置环境变量的字典。如果 `use_default_shell_env` 和 `env` 都设置为 `True`，则如果 `--incompatible_merge_fixed_and_default_shell_env` 处于启用状态（默认），`env` 中设置的值将覆盖默认的 Shell 环境。如果未启用该标志，系统会忽略 `env`。
`execution_requirements`	字典；或 `None`；默认为 `None` 用于安排操作的信息。如需了解实用键，请参阅标记。
`input_manifests`	sequence；或 `None`；默认为 `None` （实验性）设置输入 runfile 元数据；这些元数据通常由 resolve_command 生成。
`exec_group`	字符串；或 `None`；默认为 `None` 在给定执行组的执行平台上运行操作。如果未指定，则使用目标的默认执行平台。
`shadowed_action`	操作；默认为 `None` 使用添加到操作的输入列表和环境中的给定阴影操作的输入和环境运行操作。操作环境可以覆盖被阴影操作的任何环境变量。如果为 null，则仅使用操作的输入和给定环境。
`resource_set`	可调用函数；或 `None`；默认为 `None` 用于返回资源集字典的回调函数，如果此操作在本地运行，则用于估算执行时的资源用量。该函数接受两个位置参数：一个表示操作系统名称（例如“osx”）的字符串，以及一个表示操作的输入数量的整数。返回的字典可能包含以下条目，每个条目都可能是浮点数或整数： “cpu”：CPU 数量；默认值为 1 “memory”：以 MB 为单位；默认值为 250 “local_test”：本地测试的数量；默认值为 1 如果此参数设置为 `None` 或 `--experimental_action_resource_set` 为 false，则系统会使用默认值。回调必须是顶级函数（不允许使用 lambda 和嵌套函数）。
`toolchain`	标签；或字符串；或 `None`；默认值为 `unbound` 此操作中使用的可执行文件或工具的工具链类型。必须设置此参数，以便操作在正确的执行平台上执行。目前，此变量没有任何操作，但我们建议在使用工具链时设置此变量，因为未来的 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=unbound)

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

参数

参数	说明
`outputs`	文件的序列；必需操作的输出文件列表。
`inputs`	文件的序列；或依赖项集；默认为 `[]` 操作的输入文件的列表或依赖项集。
`tools`	文件的序列；或 depset；默认值为 `unbound` 操作所需的所有工具的列表或 depset。工具是包含额外运行文件的输入，这些运行文件会自动提供给相应操作。该列表可以包含 Files 或 FilesToRunProvider 实例。
`arguments`	sequence；默认为 `[]` ，即操作的命令行参数。必须是字符串或 `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 对象中的各个字符串。请注意，如果作为 `arguments` 的一部分传递大小未知的 Args 对象，则字符串将位于未知索引处；在这种情况下，`$@` shell 替换（检索所有参数）可能很有用。（已废弃）如果 `command` 是字符串序列，则第一个项是要运行的可执行文件，其余项是其参数。如果使用此形式，则不得提供 `arguments` 参数。请注意，此表单已被弃用，很快就会被移除。使用 `--incompatible_run_shell_command_string` 会停用此功能。请使用此标志验证您的代码是否兼容。 Bazel 使用与 genrule 相同的 shell 来执行命令。
`progress_message`	字符串；或 `None`；默认为 `None` 在构建期间向用户显示的进度消息，例如“正在编译 foo.cc 以创建 foo.o”。消息可能包含 `%{label}`、`%{input}` 或 `%{output}` 模式，这些模式分别会替换为标签字符串、第一个输入或输出的路径。尽量使用模式，而不是静态字符串，因为前者效率更高。
`use_default_shell_env`	默认值为 `False` 确定操作是否应使用默认 shell 环境，该环境由一些与操作系统相关的变量以及通过 `--action_env` 设置的变量组成。如果 `use_default_shell_env` 和 `env` 都设置为 `True`，则如果 `--incompatible_merge_fixed_and_default_shell_env` 处于启用状态（默认），`env` 中设置的值将覆盖默认的 Shell 环境。如果未启用该标志，系统会忽略 `env`。
`env`	字典；或 `None`；默认为 `None` 设置环境变量的字典。如果 `use_default_shell_env` 和 `env` 都设置为 `True`，则如果 `--incompatible_merge_fixed_and_default_shell_env` 处于启用状态（默认），`env` 中设置的值将覆盖默认的 Shell 环境。如果未启用该标志，系统会忽略 `env`。
`execution_requirements`	字典；或 `None`；默认为 `None` 用于安排操作的信息。如需了解实用键，请参阅标记。
`input_manifests`	sequence；或 `None`；默认为 `None` （实验性）设置输入 runfile 元数据；这些元数据通常由 resolve_command 生成。
`exec_group`	字符串；或 `None`；默认为 `None` 在给定执行组的执行平台上运行操作。如果未指定，则使用目标的默认执行平台。
`shadowed_action`	操作；默认为 `None` 使用添加到操作的输入列表中的给定阴影操作的已发现输入运行操作。如果没有，则仅使用操作的输入。
`resource_set`	可调用函数；或 `None`；默认为 `None` 如果在本地运行，则用于估算资源用量的回调函数。请参阅 `ctx.actions.run()`。
`toolchain`	标签；或字符串；或 `None`；默认值为 `unbound` 此操作中使用的可执行文件或工具的工具链类型。必须设置此参数，以便操作在正确的执行平台上执行。目前，此变量没有任何操作，但我们建议在使用工具链时设置此变量，因为未来的 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`	文件；或 `None`；默认为 `None` 输出符号链接将指向的文件。
`target_path`	字符串；或 `None`；默认为 `None` 输出符号链接将指向的确切路径。不会应用任何标准化或其他处理。
`is_executable`	默认值为 `False` 只能与 `target_file` 搭配使用，不能与 `target_path` 搭配使用。如果为 true，则在执行操作时，系统会检查 `target_file` 的路径，以确认其是否可执行；如果不可执行，则会报告错误。将 `is_executable` 设为 False 并不意味着目标不可执行，而只是表示未执行任何验证。此功能对 `target_path` 没有意义，因为悬空符号链接在构建时可能不存在。
`progress_message`	string；或 `None`；默认为 `None` 在构建期间向用户显示的进度消息。

template_dict

TemplateDict actions.template_dict()

返回一个 TemplateDict 对象，以实现高效的内存模板展开。

write

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

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

参数

参数	说明
`output`	必需输出文件。
`content`	字符串；或实参；必需文件的内容。可以是字符串或 `actions.args()` 对象。
`is_executable`	默认值为 `False` 输出文件是否应可执行。