一种对象,用于以节省内存的方式封装构建命令行部分或全部所需的数据。
通常,操作需要一个大型命令行,其中包含通过传递依赖项累积的值。例如,链接器命令行可能会列出要链接的所有库所需的每个对象文件。最佳做法是将此类传递数据存储在 depset
中,以便多个目标共享。不过,如果规则作者必须将这些 depset 转换为字符串列表,以构建操作命令行,则会破坏这种内存共享优化。
因此,操作构造函数除了接受字符串之外,还接受 Args
对象。每个 Args
对象都表示字符串和 depset 的串联,并包含用于处理数据的可选转换。Args
对象不会处理它们封装的 depset,直到执行阶段需要计算命令行时才会处理。这有助于将任何开销较高的复制操作推迟到分析阶段完成之后。如需了解详情,请参阅优化性能页面。
Args
是通过调用 ctx.actions.args()
构造的。它们可以作为 ctx.actions.run()
或 ctx.actions.run_shell()
的 arguments
参数传递。对 Args
对象的每次更改都会将值附加到最终的命令行。
借助 map_each
功能,您可以自定义将项转换为字符串的方式。如果您未提供 map_each
函数,标准转换如下所示:
- 已经是字符串的值将保留原样。
File
对象会转换为其File.path
值。Label
对象会转换为字符串表示形式,在主仓库上下文中解析时会解析回同一对象。如果可能,字符串表示法会使用代码库的显式名称,而不是代码库的规范名称,这使得此表示法适合在 BUILD 文件中使用。虽然无法保证表示形式的确切形式,但典型示例包括//foo:bar
、@repo//foo:bar
和@@canonical_name~//foo:bar.bzl
。- 所有其他类型都会以未指定的方式转换为字符串。因此,您应避免将非字符串或
File
类型的值传递给add()
,如果您将这些值传递给add_all()
或add_joined()
,则应提供map_each
函数。
使用字符串格式设置(add*()
方法的 format
、format_each
和 format_joined
参数)时,格式模板的解读方式与对字符串进行 %
替换的方式相同,但模板必须只有一个替换占位符,且该占位符必须为 %s
。百分比字面量可以转义为 %%
。格式设置会在值转换为字符串后应用,如上所示。
每个 add*()
方法都有一个替代形式,该形式接受一个额外的位置参数,即要插入在其余参数之前的“实参名称”字符串。对于 add_all
和 add_joined
,如果序列为空,系统将不会添加额外的字符串。例如,相同的用法可以在命令行中添加 --foo val1 val2 val3 --bar
或仅添加 --bar
,具体取决于给定序列是包含 val1..val3
还是为空。
如果命令行的大小会超出系统允许的大小上限,则参数可以溢出到参数文件中。请参阅 use_param_file()
和 set_param_file_format()
。
示例:假设我们想要生成以下命令行:
--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
Args
对象:# foo_deps and bar_deps are depsets containing # File objects for the foo and bar .txt files. args = ctx.actions.args() args.add_all("--foo", foo_deps) args.add_joined("--bar", bar_deps, join_with=",") args.add("--baz") ctx.actions.run( ... arguments = [args], ... )
成员
add
Args Args.add(arg_name_or_value, value=unbound, *, format=None)
参数
参数 | 说明 |
---|---|
arg_name_or_value
|
required 如果传递了两个位置参数,系统会将其解释为参数名称。参数名称在值前面添加,不进行任何处理。如果只传递一个位置参数,则会被解释为 value (请参阅下文)。
|
value
|
默认值为 unbound 要附加的对象。系统会使用上述标准转换将其转换为字符串。由于此函数没有 map_each 参数,因此 value 应为字符串或 File 。必须将列表、元组、depset 或目录 File 传递给 add_all() 或 add_joined() ,而不是此方法。
|
format
|
字符串;或 None ;
默认为 None 格式字符串模式,将应用于 value 的字符串化版本。
|
add_all
Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)
大多数处理都发生在要附加的参数列表上,具体步骤如下:
- 每个目录
File
项都会被该目录中递归包含的所有File
替换。 - 如果指定了
map_each
,则会将其应用于各项,并将生成的字符串列表串联起来以形成初始参数列表。否则,初始参数列表是将标准转换应用于每个项的结果。 - 列表中的每个参数都采用
format_each
格式(如果存在)。 - 如果
uniquify
为 true,系统会移除重复的参数。第一次出现的情况是留下的数据。 - 如果指定了
before_each
字符串,系统会将其作为新参数插入到列表中每个现有参数之前。这实际上会将此时要附加的参数数量翻倍。 - 除非列表为空且
omit_if_empty
为 true(默认值),否则 arg 名称和terminate_with
(如果已指定)会分别作为第一个和最后一个实参插入。
参数
参数 | 说明 |
---|---|
arg_name_or_values
|
必需 如果传递两个位置参数,则此参数会被解读为实参名称。参数名称作为单独的参数添加到 values 之前,不进行任何处理。如果 omit_if_empty 为 true(默认值),并且未附加任何其他项(如果 values 为空或其所有项都被滤除,就会发生这种情况),则系统不会添加此参数名称。如果仅传递一个位置参数,系统会将其解读为 values (见下文)。
|
values
|
sequence;或 depset;
默认为 unbound 要附加项的列表、元组或 depset。 |
map_each
|
可调用函数;或 None ;
默认为 None 一个函数,用于将每个项转换为零个或多个字符串,这些字符串可能会在附加之前进行进一步处理。如果未提供此参数,则使用标准转换。 系统会向该函数传递一个或两个位置参数:要转换的项后跟可选的 返回值的类型取决于要为相应项生成的参数数量:
None 与返回长度为 1 或 0 的列表具有相同的效果。不过,避免在不需要时创建列表,可以提高效率并提高可读性。通常,设置 为避免在执行阶段意外保留分析阶段的大型数据结构, 警告:在调用 |
format_each
|
字符串;或 None ;
默认为 None 可选的格式字符串模式,应用于 map_each 函数返回的每个字符串。格式字符串中必须只有一个“%s”占位符。
|
before_each
|
字符串;或 None ;
默认为 None 在附加从 values 派生的每个参数之前附加的可选参数。
|
omit_if_empty
|
默认值为 True 如果为 true,并且没有从 values 派生的参数要附加,则会抑制所有后续处理,并且命令行将保持不变。如果为 false,则无论是否存在其他参数,系统仍会附加参数名称和 terminate_with (如果已提供)。
|
uniquify
|
默认值为 False 如果值为 true,将省略推导自 values 的重复参数。系统只会保留每个参数的首次出现。通常不需要此功能,因为 depset 已省略重复项,但如果 map_each 为多个项发出了相同的字符串,则此功能会很有用。
|
expand_directories
|
默认为 True 如果为 true, values 中的任何目录都将展开为文件的平面列表。这发生在应用 map_each 之前。
|
terminate_with
|
字符串;或 None ;
默认为 None 在所有其他参数后附加的可选参数。如果 omit_if_empty 为 true(默认值)且未附加任何其他项(如果 values 为空或其所有项均被滤除,就会发生这种情况),则系统不会添加此参数。
|
allow_closure
|
默认值为 False 如果为 true,则允许在函数参数(如 map_each )中使用闭包。通常情况下,这并不必要,并且可能会导致在执行阶段保留分析阶段的大型数据结构。
|
add_joined
Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)
处理方式与 add_all()
类似,但从 values
派生的参数列表会合并为一个参数(就像使用 join_with.join(...)
一样),然后使用给定的 format_joined
字符串模板设置格式。与 add_all()
不同,此方法不支持 before_each
或 terminate_with
参数,因为当项组合为单个参数时,这些参数通常没有用。
如果过滤后没有字符串可联接到参数,并且 omit_if_empty
为 true(默认值),则不执行任何处理。否则,如果没有要联接的字符串,但 omit_if_empty
为 false,则联接的字符串将为空字符串。
参数
参数 | 说明 |
---|---|
arg_name_or_values
|
必需 如果传递两个位置参数,则此参数会被解读为实参名称。参数名称会添加到 values 之前,且不进行任何处理。如果 omit_if_empty 为 true(默认值),并且没有从 values 派生的字符串要联接在一起(当 values 为空或其所有项都被滤除),则不会添加此参数。如果仅传递一个位置参数,系统会将其解读为 values (见下文)。
|
values
|
sequence;或 depset;默认值为 unbound 要联接其项的列表、元组或 depset。 |
join_with
|
必需 用于将通过应用 map_each 和 format_each 获得的字符串联接在一起的分隔符字符串,方法与 string.join() 相同。
|
map_each
|
可调用对象;或 None ;
默认为 None 与 add_all 相同。
|
format_each
|
string;或 None ;默认值为 None 与 add_all 相同。
|
format_joined
|
字符串;或 None ;
默认为 None 应用于连接字符串的可选格式字符串模式。格式字符串中必须只有一个“%s”占位符。 |
omit_if_empty
|
默认值为 True 如果为 true,并且没有要联接的字符串(因为 values 为空或其所有项都被滤除),则会抑制所有后续处理,并且命令行将保持不变。如果为 false,则即使没有要联接的字符串,系统也会附加两个参数:参数名称后跟一个空字符串(即零个字符串的逻辑联接)。
|
uniquify
|
默认值为 False 与 add_all 相同。
|
expand_directories
|
默认值为 True 与 add_all 相同。
|
allow_closure
|
默认值为 False 与 add_all 相同。
|
set_param_file_format
Args Args.set_param_file_format(format)
参数
参数 | 说明 |
---|---|
format
|
必需 必须为以下各项之一:
如果未调用,格式默认为“shell”。 |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)
为了提高效率,Bazel 可能会选择在执行期间省略将参数文件写入输出树。如果您正在调试操作并希望检查 param 文件,请将 --materialize_param_files
传递给 build。
参数
参数 | 说明 |
---|---|
param_file_arg
|
必需 包含单个“%s”的格式字符串。如果参数被溢出到参数文件,则会被替换为一个参数,该参数由使用参数文件路径格式化的此字符串组成。 例如,如果参数溢出到参数文件“params.txt”,则指定“--file=%s”会导致操作命令行包含“--file=params.txt”。 |
use_always
|
默认为 False 是否始终将参数溢出到参数文件。如果为 false,则 bazel 会根据您的系统和参数长度决定是否需要溢出参数。 |