通常,操作需要一个大型命令行,其中包含从传递依赖项累积的值。例如,链接器命令行可能会列出所有链接的库所需的所有对象文件。最佳做法是将此类传递数据存储在 depset
中,以便多个目标共享。不过,如果规则作者必须将这些依赖项转换为字符串列表才能构建操作命令行,则会破坏此内存共享优化。
因此,除了字符串之外,操作构造函数还接受 Args
对象。每个 Args
对象代表一个字符串和依赖项的串联,以及用于操控数据的可选转换。在执行阶段之前,Args
对象不会处理它们封装的依赖项。这有助于将所有费用高昂的复制操作延迟到分析阶段结束后。如需了解详情,请参阅优化性能页面。
Args
通过调用 ctx.actions.args()
进行构建。它们可以作为 ctx.actions.run()
或 ctx.actions.run_shell()
的 arguments
参数传递。Args
对象的每次变更都会将值附加到最终命令行。
借助 map_each
功能,您可以自定义如何将项转换为字符串。如果您未提供 map_each
函数,标准转换将如下所示:
- 已是字符串的值将保持不变。
File
对象会转换为其File.path
值。- 所有其他类型都以未指定的方式转换为字符串。因此,您应避免将非字符串或
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
|
必需 如果传递了两个位置参数,则会被解释为参数名称。参数名称会在值之前添加,不会进行任何处理。如果仅传递一个位置参数,则会被解释为 value (见下文)。
|
value
|
default = unbound 要附加的对象。它将使用上述标准转换将其转换为字符串。由于此函数没有 map_each 参数,因此 value 应为字符串或 File 。必须将列表、元组、偏移量或目录 File 传递给 add_all() 或 add_joined() ,而不是该方法。
|
format
|
string; or None ;
default = None一种格式字符串模式,应用于 value 的字符串化版本。
|
添加全部
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(默认值)之外,参数名称和terminate_with
会分别作为第一个和最后一个参数插入(如果被提供)。
参数
参数 | 说明 |
---|---|
arg_name_or_values
|
必需 如果传递了两个位置参数,则会被解释为参数名称。将参数名称作为单独的参数添加到 values 之前,无需进行任何处理。如果 omit_if_empty 为 true(默认值),并且未附加任何其他项(例如,如果 values 为空或所有项均被滤除,则系统不会添加此参数名称)。如果仅传递一个位置参数,则会被解释为 values (见下文)。
|
values
|
sequence; or depset ;
default = unbound将要附加其项的列表、元组或依赖项。 |
map_each
|
callable; or None ;
default = None用于将每个项目转换为零个或多个字符串的函数,可能会在附加之前进一步处理。如果未提供此参数,系统会使用标准转换。 系统会向该函数传递一个或两个位置参数:要转换的项,后跟可选的 返回值的类型取决于要为该项生成的参数数量:
None 的效果与分别返回长度 1 或长度 0 的效果相同。不过,避免创建不必要的列表,可以提高效率和可读性。通常,设置 为了避免将大型分析阶段数据结构意外保留到执行阶段, 警告:在调用 |
format_each
|
string; or None ;
default = None可选格式字符串模式,应用于 map_each 函数返回的每个字符串。格式字符串必须正好有一个“%s”占位符。 |
before_each
|
string; or None ;
default = None在附加派生自 values 的每个参数之前要附加的可选参数。
|
omit_if_empty
|
default = True 如果为 true,如果没有要附加的来自 values 的参数,则禁止所有进一步处理,命令行保持不变。如果为 false,则无论是否存在其他参数,参数名称和 terminate_with (如果提供)仍会被附加。 |
uniquify
|
default = False 如果为 true,则派生自 values 的重复参数。系统只会保留每个参数的第一次出现位置。通常不需要此功能,因为依赖项已经省略了重复项,但如果 map_each 为多个项发出相同的字符串,则会非常有用。 |
expand_directories
|
default = True 如果为 true, values 中的任何目录都将展开为平面文件列表。在应用 map_each 之前,会发生这种情况。 |
terminate_with
|
string; or None ;
default = None可选参数,在所有其他参数后面附加。如果 omit_if_empty 为 true(默认值),并且未附加任何其他项(例如,如果 values 为空或所有项均被滤除,则不会添加此参数)。
|
allow_closure
|
default = False 如果为 true,则允许在 map_each 等函数参数中使用闭包。通常没有必要这样做,这样做可能会导致在执行阶段保留较大的分析阶段数据结构。 |
已添加联接
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; or depset ;
default = unbound将要联接的项的列表、元组或依赖项。 |
join_with
|
必需 用于将通过应用 map_each 和 format_each 获取的字符串组合在一起的分隔符字符串,方式与 string.join() 相同。
|
map_each
|
callable; or None ;默认值 = None与 add_all 相同。 |
format_each
|
string; or None ;默认值 = None与 add_all 相同。 |
format_joined
|
string; or None ;
default = None一个可选格式字符串模式,应用于联接的字符串。格式字符串必须正好有一个“%s”占位符。 |
omit_if_empty
|
default = True 如果为 true,如果没有要联接的字符串(因为 values 为空或其所有项都被过滤),则抑制所有进一步处理并且命令行保持不变。如果为 false,即使没有要连接的字符串,也将附加两个参数:参数名称后跟一个空字符串(零字符串的逻辑联接)。
|
uniquify
|
default = False 与 add_all 相同。 |
expand_directories
|
default = True 与 add_all 相同。 |
allow_closure
|
default = False 与 add_all 相同。 |
set_param_file_format
Args Args.set_param_file_format(format)设置参数文件的格式(如果使用的话)
参数
参数 | 说明 |
---|---|
format
|
必需 必须为以下项之一:
如果未调用,则格式默认为“shell”。 |
使用参数_file
Args Args.use_param_file(param_file_arg, *, use_always=False)将参数溢出至参数文件,将其替换为指向参数文件的指针。如果您的参数可能超出系统的命令长度限制,请使用此选项。
为了提高效率,Bazel 可能会选择省略执行参数时将输出文件写入输出树。如果您要调试操作并想检查参数文件,请将 --materialize_param_files
传递给您的 build。
参数
参数 | 说明 |
---|---|
param_file_arg
|
必需 包含单个“%s”的格式字符串。如果参数溢出到参数文件中,则参数会被替换为由此字符串和 params 文件的路径设置的字符串。 例如,如果参数溢出到参数文件“params.txt”,则指定“--file=%s”会导致操作命令行包含“--file=params.txt”。 |
use_always
|
default = False 是否始终将参数溢出到参数文件中。如果值为 false,则 Bazel 会根据您的系统和参数长度来判断参数是否需要溢出。 |