ctx.actions
访问此模块。
会员
- 参数
- statement_directory
- statement_file
- statement_symlink [声明符号链接]
- do_nothing
- expand_template
- 运行
- run_shell
- 符号链接
- template_dict
- 写入
args
Args actions.args()返回可用于构建内存效率高的命令行的 Args 对象。
声明目录
File actions.declare_directory(filename, *, sibling=None)声明相应规则或宽高比会在当前软件包中创建包含指定名称的目录。您必须创建一个生成目录的操作。该目录的内容无法直接通过 Starlark 访问,但可以使用
Args.add_all()
在操作命令中展开。仅在声明和目录的扩展内容中放置常规文件和目录。
参数
参数 | 说明 |
---|---|
filename
|
必需 如果未提供“同级”,则是新目录相对于当前软件包的路径。否则,该文件的基名将定义一个目录。 |
sibling
|
File; or None ;
default = None与新声明的目录位于同一目录中的文件。文件必须位于当前的软件包中。 |
声明文件
File actions.declare_file(filename, *, sibling=None)声明该规则或方面会使用给定文件名创建文件。如果未指定
sibling
,则文件名是相对于软件包目录的名称,否则该文件将与 sibling
位于同一目录中。无法在当前软件包之外创建文件。请注意,除了声明文件之外,您还必须单独创建一个发出该文件的操作。创建该操作需要将返回的 File
对象传递给操作的构造函数。
请注意,无需使用此函数声明(也无法声明)预声明的输出文件。您可以改为从 ctx.outputs
获取其 File
对象。查看使用示例。
参数
参数 | 说明 |
---|---|
filename
|
必需 如果未提供“同级”,则为新文件的路径(相对于当前软件包)。否则,文件基名将决定目录。 |
sibling
|
File; or None ;
default = None与新创建的文件位于同一目录中的文件。文件必须位于当前的软件包中。 |
声明符号链接
File actions.declare_symlink(filename, *, sibling=None)
此参数是实验性参数,随时可能会更改。可通过设置 --noexperimental_allow_unresolved_symlinks
将其停用
声明该规则或宽高比会使用当前软件包中的指定名称创建符号链接。您必须创建一个生成此符号链接的操作。Bazel 绝不会对此符号链接取消引用,它会逐字传输至沙盒或远程执行程序。目前不支持树内工件中的符号链接。
参数
参数 | 说明 |
---|---|
filename
|
必需 如果未提供“同级”,则是新符号链接(相对于当前软件包)的路径。否则,该文件的基名将定义一个目录。 |
sibling
|
File; or None ;
default = None与新声明的符号链接位于同一目录的文件。 |
不执行任何操作
None actions.do_nothing(mnemonic, inputs=[])创建一个空操作,该操作既不执行命令,也不会生成任何输出,但对于插入“额外操作”非常有用。
参数
参数 | 说明 |
---|---|
mnemonic
|
必需 对某个字词的说明,例如 CppCompile 或 GoLink。 |
inputs
|
sequence of Files; or depset ;
default = []操作的输入文件列表。 |
展开模板
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 ;
default = 未绑定实验性。此参数是实验性参数,随时可能会更改。请勿依赖它。您可以设置 --+experimental_lazy_template_expansion 实验性功能:在展开模板时进行替换,以实验性方式启用该功能。 |
得分
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
|
sequence of Files ;必需操作的输出文件的列表。 |
inputs
|
sequence of Files; or depset ;
default = []操作输入文件的清单或依赖项。 |
unused_inputs_list
|
File; or None ;
default = None该文件包含操作未使用的输入列表。 此文件的内容(通常是操作的输出之一)对应于在整个操作执行期间未使用过的输入文件列表。这些文件中的任何更改都不得以任何方式影响操作的输出。 |
executable
|
File; or string; or FilesToRunProvider ;必需要由操作调用的可执行文件。 |
tools
|
sequence; or depset ;
default = unbound列出操作所需的任何工具或部署该操作。工具是输入,其中包含可自动提供给操作的其他运行文件。提供的列表可以是异构文件、FileToRunProvider 实例或文件的依赖项集合。直接位于列表中且来自 ctx.executable 的文件会自动添加其运行文件。提供偏移量时,它只能包含 文件。在这两种情况下,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} 模式,它们分别替换为标签字符串、First Input 或输出的路径。首选使用模式而不是静态字符串,因为前者更高效。
|
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(实验性)设置输入运行文件元数据;它们通常由 resolve_command 生成。 |
exec_group
|
string; or None ;
default = None在指定的执行组的执行平台上运行操作。如果未设置,则使用目标的默认执行平台。 |
shadowed_action
|
Action ;
default = None使用被添加到操作的输入列表和环境中的指定被覆盖操作的输入和环境运行操作。操作环境可以覆盖被覆盖的操作的任何环境变量。如果没有,则仅使用操作的输入和指定环境。 |
resource_set
|
callable; or None ;
default = None一个回调函数,用于返回资源集字典,用于估算本地执行时的资源使用情况(如果相应操作在本地运行)。 该函数接受两个位置参数:一个表示操作系统名称的字符串(例如“osx”),以及一个表示操作输入数量的整数。返回的字典可能包含以下条目,每个条目可以是浮点数或整数:
如果此参数设置为 回调必须是顶级(不允许 lambda 和嵌套函数)。 |
toolchain
|
Label; or string; or None ;默认值 = 未绑定此操作使用的可执行文件的类型或工具。必须设置该参数,以便操作可以在正确的执行平台上执行。 目前,它是一项空操作,但我们建议您在使用工具链时对其进行设置,因为在未来的 Bazel 版本中,您必须进行此操作。 请注意,创建此操作的规则需要在其“rule()”函数中定义此工具链。 如果同时设置了“toolchain”和“exec_group”参数,将使用“exec_group”。如果“exec_group”未指定,则会引发错误。 |
运行 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
|
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 变量替代项(例如 如果 |
mnemonic
|
string; or None ;
default = None对操作的单个字词说明,例如 CppCompile 或 GoLink。 |
command
|
string; or sequence of strings ;必需要执行的 Shell 命令。可以是字符串(首选)或字符串序列(已弃用)。 如果 (已弃用)如果 Bazel 使用与 genrule 相同的 shell 来执行该命令。 |
progress_message
|
string; or None ;
default = None在构建期间向用户显示的进度消息,例如“编译 foo.cc 以创建 foo.o”。该消息可能包含 %{label} 、%{input} 或 %{output} 模式,它们分别替换为标签字符串、First Input 或输出的路径。首选使用模式而不是静态字符串,因为前者更高效。
|
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(实验性)设置输入运行文件元数据;它们通常由 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 ;默认值 = 未绑定此操作使用的可执行文件的类型或工具。必须设置该参数,以便操作可以在正确的执行平台上执行。 目前,它是一项空操作,但我们建议您在使用工具链时对其进行设置,因为在未来的 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输出符号链接指向的确切路径。而不会进行标准化或其他处理。 |
is_executable
|
default = False 只能与 target_file 一起使用,不能与 target_path 一起使用。如果为 true,则系统会在执行操作时检查 target_file 的路径,以确认其可执行;如果不是,则会报告错误。将 is_executable 设置为 False 并不意味着目标不可执行,只是不进行任何验证。此功能对 |
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 输出文件是否可执行。 |