实参

报告问题 查看源代码 每夜 build · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

通常，某个操作需要包含从传递依赖项累积的值的大型命令行。例如，链接器命令行可以列出所有要链接的库需要的每个对象文件。最佳实践是将此类传递数据存储在 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 值。
• 所有其他类型都会以未指定的方式转换为字符串。因此，您应避免将非字符串或 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
• add_all
• add_joined
• set_param_file_format
• use_param_file

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	字符串；或 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)

向此命令行附加多个参数。这些项会在执行阶段延迟处理。

大部分处理操作都是针对要附加的参数列表进行的，具体如下：

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

请注意，空字符串是有效参数，需要遵循所有这些处理步骤。

参数

参数	说明
arg_name_or_values	required 如果传递了两个位置参数，系统会将其解释为参数名称。实参名称会作为单独的实参添加到 values 之前，而无需进行任何处理。如果 omit_if_empty 为 true（默认值），并且未附加任何其他项（如果 values 为空或其所有项都被滤除，就会发生这种情况），则系统不会添加此参数名称。如果仅传递一个位置参数，系统会将其解读为 values（见下文）。
values	sequence；或 depset； 默认为 unbound 要附加项的列表、元组或 depset。
map_each	可调用函数；或 None； 默认为 None 一个函数，用于将每个项转换为零个或多个字符串，这些字符串可能会在附加之前进行进一步处理。如果未提供此参数，则使用标准转换。 系统会向该函数传递一个或两个位置参数：要转换的项后跟可选的 DirectoryExpander。只有当所提供的函数是用户定义的（而非内置函数）且声明了多个参数时，才会传递第二个参数。 返回值的类型取决于要为相应项生成的参数数量： 在每项都转换为一个字符串的常见情况下，该函数应返回该字符串。 如果要完全滤除相应项，该函数应返回 None。 如果项转换为多个字符串，该函数会返回这些字符串的列表。 返回单个字符串或 None 与返回长度为 1 或 0 的列表具有相同的效果。不过，避免在不需要时创建列表，可以提高效率并提高可读性。 通常，在设置 expand_directories=True 后，目录项会自动展开到其内容。不过，这不会展开其他值中包含的目录，例如，当项是将目录作为字段的结构体时。在这种情况下，可以应用 DirectoryExpander 参数来手动获取给定目录的文件。 为避免在执行阶段意外保留分析阶段的大型数据结构，map_each 函数必须通过顶级 def 语句声明；默认情况下，它可能不是嵌套函数闭包。 警告：在调用 map_each 期间执行的 print() 语句不会产生任何可见的输出。
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	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	可调用对象；或 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	必需 必须为以下各项之一： “multiline”：每一项（参数名称或值）都会一字不差地写入参数文件，并且其后有一个换行符。 “shell”：与“multiline”相同，但项目采用 shell 引用 “flag_per_line”：与“multiline”相同，但 (1) 只有标志（以“--”开头）会写入 param 文件，并且 (2) 标志的值（如果有）会写入同一行，并以“=”分隔。这是 Abseil 标志库所需的格式。 如果未调用，格式默认为“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 将根据系统和参数长度决定是否需要溢出参数。