实参

一种对象，用于以节省内存的方式封装构建命令行部分或全部所需的数据。

通常，某个操作需要包含从传递依赖项累积的值的大型命令行。例如，链接器命令行可能会列出要链接的所有库所需的每个对象文件。最佳实践是将此类传递数据存储在 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

# 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
• add_all
• add_joined
• set_param_file_format
• use_param_file

add

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

参数

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)

大多数处理都发生在要附加的参数列表上，具体步骤如下：

1. 每个目录 File 项都会被该目录中递归包含的所有 File 替换。
2. 如果指定了 map_each，系统会将其应用于每个项，并将生成的字符串列表串联起来，以形成初始参数列表。否则，初始参数列表是将标准转换应用于每个项的结果。
3. 列表中的每个实参均采用 format_each 格式（如果有）。
4. 如果 uniquify 为 true，系统会移除重复的参数。第一个出现的值会保留。
5. 如果指定了 before_each 字符串，系统会将其作为新参数插入到列表中每个现有参数之前。这实际上会将此时要附加的参数数量翻倍。
6. 除非列表为空且 omit_if_empty 为 true（默认值），否则 arg 名称和 terminate_with（如果已指定）会分别作为第一个和最后一个参数插入。

参数

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，则联接的字符串将为空字符串。

参数

set_param_file_format

Args Args.set_param_file_format(format)

参数

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

为了提高效率，Bazel 可能会选择在执行期间省略将参数文件写入输出树。如果您正在调试操作并希望检查 param 文件，请将 --materialize_param_files 传递给 build。

参数