一种对象，用于以节省内存的方式封装构建部分或全部命令行所需的数据。
通常，操作需要一个大型命令行，其中包含通过传递依赖项累积的值。例如，链接器命令行可以列出所有要链接的库需要的每个对象文件。最佳做法是将此类传递数据存储在 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
|
必需 如果传递了两个位置参数，该参数会被解释为参数名称。参数名称在值前面添加，不进行任何处理。如果只传递一个位置参数，则会被解释为 value（请参阅下文）。
|
value
|
默认值为 unbound要附加的对象。它将使用上述标准转换转换为字符串。由于此函数没有 map_each 参数，因此 value 应为字符串或 File。列表、元组、depset 或目录 File 必须传递给 add_all() 或 add_joined()，而不是此方法。
|
format
|
string;或 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（默认值）的情况之外，指定参数名称和terminate_with会分别作为第一个和最后一个参数插入。
参数
| 参数 | 说明 |
|---|---|
arg_name_or_values
|
必需 如果传递了两个位置参数，该参数会被解释为参数名称。参数名称作为单独的参数添加到 values 之前，不进行任何处理。如果 omit_if_empty 为 true（默认值），并且未附加任何其他项（比如 values 为空或其所有项都被滤除），则不会添加此参数名称。如果只传递一个位置参数，则会被解释为 values（请参阅下文）。
|
values
|
sequence；或 depset；
默认值为 unbound要附加其项的列表、元组或 depset。 |
map_each
|
Callable；或 None；
默认值为 None用于将每一项转换为零个或多个字符串的函数，这些字符串可以在附加之前进行进一步处理。如果未提供此参数，则使用标准转化。 系统会向该函数传递一个或两个位置参数：要转换的项后跟可选的 返回值的类型取决于要为相应项生成的参数数量：
None 的效果与分别返回长度为 1 或长度为 0 的列表的效果相同。不过，这样做更高效、可读性更强，避免在不需要时创建列表。通常，在设置 为避免将大型分析阶段数据结构意外保留到执行阶段，必须由顶级 警告：在调用 |
format_each
|
string;或 None；
默认值为 None可选的格式字符串模式，应用于 map_each 函数返回的每个字符串。格式字符串必须且只能包含一个“%s”占位符。
|
before_each
|
string;或 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
|
string;或 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
|
Callable；或 None；
默认值为 None与 add_all 相同。
|
format_each
|
string;或 None；
默认值为 None与 add_all 相同。
|
format_joined
|
string;或 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 可能会选择在执行期间省略将 params 文件写入输出树。如果您要调试操作并想要检查参数文件，请将 --materialize_param_files 传递给 build。
参数
| 参数 | 说明 |
|---|---|
param_file_arg
|
必需 包含单个“%s”的格式字符串。如果参数被溢出到 params 文件中，则会替换为由这个字符串（采用 params 文件路径格式）构成的参数。 例如，如果参数泄露到参数文件“params.txt”，则指定“--file=%s”会导致操作命令行包含“--file=params.txt”。 |
use_always
|
默认值为 False是否始终将参数溢出到参数文件中。如果为 false，bazel 将根据系统和参数长度决定是否需要溢出参数。 |