构建文件

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7
BUILD 文件中提供的方法。另请参阅 Build 百科全书，了解可在 BUILD 文件中使用的其他 函数 和 build 规则。

成员

depset

depset depset(direct=None, order="default", *, transitive=None)

创建 depset。direct 参数是 depset 的直接元素列表，transitive 参数是 depset 列表，其元素将成为所创建 depset 的间接元素。当 depset 转换为列表时，元素的返回顺序由 order 参数指定。如需了解详情，请参阅 Depsets 概览。

depset 的所有元素（直接和间接）都必须是同一类型，如表达式 type(x) 所示。

由于系统在迭代期间使用基于哈希的集合来消除重复项，因此 depset 的所有元素都应该是可哈希的。不过，目前并非所有构造函数都会始终检查此不变量。使用 --incompatible_always_check_depset_elements 标志可启用一致性检查；这将是未来版本中的默认行为；请参阅 问题 10313。

此外，元素目前必须是不可变的，不过此限制将在未来放宽。

所创建 depset 的顺序应与其 transitive depset 的顺序兼容。"default" 顺序与任何其他顺序兼容，所有其他顺序仅与自身兼容。

参数

参数 说明
direct 序列；或 None； 默认值为 None
depset 的直接元素列表。
order 默认值为 "default"
新 depset 的遍历策略。如需了解可能的值，请点击此处。
transitive depset 序列；或 ； 默认值为 depset 列表，其元素将成为 depset 的间接元素。NoneNone

existing_rule

unknown existing_rule(name)

返回一个不可变的类字典对象，用于描述在此线程的软件包中实例化的规则的属性；如果不存在该名称的规则实例，则返回 None。

在此，不可变的类字典对象是指深度不可变的对象 x，它支持类字典迭代、len(x)、name in x、x[name]、x.get(name)、x.items()、x.keys() 和 x.values()。

如果设置了 --noincompatible_existing_rules_immutable_view 标志，则改为返回具有相同内容的新可变字典。

结果包含每个属性的条目，但私有属性（名称不以字母开头）和一些无法表示的旧版属性类型除外。此外，该字典还包含规则实例的 name 和 kind（例如 'cc_binary'）的条目。

结果的值表示属性值，如下所示：

  • 类型为 str、int 和 bool 的属性按原样表示。
  • 对于同一软件包中的目标，标签会转换为 ':foo' 形式的字符串；对于不同软件包中的目标，标签会转换为 '//pkg:name' 形式的字符串。
  • 列表表示为元组，字典转换为新的可变字典。其元素以相同的方式递归转换。
  • select 值会返回，其内容会按上述方式转换。
  • 在规则实例化期间未指定值且默认值是计算得出的属性将从结果中排除。（计算出的默认值在分析阶段之前无法计算。）。

如果可能，请避免使用此函数。它会使 BUILD 文件变得脆弱且依赖于顺序。此外，请注意，它与将规则属性值从内部形式转换为 Starlark 的其他两种转换略有不同：一种由计算出的默认值使用，另一种由 ctx.attr.foo 使用。

参数

参数 说明
name 必需
目标的名称。

existing_rules

unknown existing_rules()

返回一个不可变的类字典对象，用于描述在此线程的软件包中迄今为止实例化的规则。类字典对象的每个条目都会将规则实例的名称映射到 existing_rule(name) 将返回的结果。

在此，不可变的类字典对象是指深度不可变的对象 x，它支持类字典迭代、len(x)、name in x、x[name]、x.get(name)、x.items()、x.keys() 和 x.values()。

如果设置了 --noincompatible_existing_rules_immutable_view 标志，则改为返回具有相同内容的新可变字典。

注意：如果可能，请避免使用此函数。它会使 BUILD 文件变得脆弱且依赖于顺序。此外，如果设置了 --noincompatible_existing_rules_immutable_view 标志，此函数的开销可能会非常高，尤其是在循环内调用时。

exports_files

None exports_files(srcs, visibility=None, licenses=None)

指定属于此软件包且导出到其他软件包的文件列表。

参数

参数 说明
srcs 字符串序列； 必需
要导出的文件列表。
visibility 序列；或 None； 默认值为 None
可以指定可见性声明。这些文件将对指定的目标可见。如果未指定可见性，这些文件将对每个软件包可见。
licenses 字符串序列；或 None； 默认值为 None
要指定的许可。

glob

sequence glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)

Glob 会返回当前软件包中每个文件的新可变排序列表，这些文件：
  • 与 include 中的至少一种模式匹配。
  • 与 exclude 中的任何模式都不匹配（默认值为 []）。
如果启用了 exclude_directories 实参（设置为 1），则结果中将省略目录类型的文件（默认值为 1）。

参数

参数 说明
include 字符串序列； 默认值为 []
要包含的 glob 模式列表。
exclude 字符串序列； 默认值为 []
要排除的 glob 模式列表。
exclude_directories 默认值为 1
一个标志，用于指示是否排除目录。
allow_empty 默认值为 unbound
是否允许 glob 模式不匹配任何内容。如果 `allow_empty` 为 False，则每个单独的 include 模式都必须匹配某些内容，并且最终结果也必须为非空（在排除 `exclude` 模式的匹配项之后）。

module_name

string module_name()

与此软件包所在的代码库关联的 Bazel 模块的名称。如果此软件包来自在 WORKSPACE 而非 MODULE.bazel 中定义的代码库，则此值为空。对于由模块扩展生成的代码库，这是托管该扩展的模块的名称。它与 module.name 字段相同，如 module_ctx.modules 中所示。 可能会返回 None。

module_version

string module_version()

与此软件包所在的代码库关联的 Bazel 模块的版本。如果此软件包来自在 WORKSPACE 而非 MODULE.bazel 中定义的代码库，则此值为空。对于由模块扩展生成的代码库，这是托管该扩展的模块的版本。它与 module.version 字段相同，如 module_ctx.modules 中所示。 可能会返回 None。

package_group

None package_group(name, packages=[], includes=[])

此函数定义一组软件包，并为该组分配标签。该标签可在 visibility 属性中引用。

参数

参数 说明
name 必需
此规则的唯一名称。
packages 字符串序列； 默认值为 []
此组中软件包的完整枚举。
includes 字符串序列；字符串s； 默认值为 []
包含在此组中的其他软件包组。

package_name

string package_name()

正在评估的软件包的名称，不包含代码库名称。例如，在 BUILD 文件 some/package/BUILD 中，其值将为 some/package。如果 BUILD 文件调用在 .bzl 文件中定义的函数，则 package_name() 将与调用方 BUILD 文件软件包匹配。

package_relative_label

Label package_relative_label(input)

在当前正在初始化的软件包（即当前宏正在执行的 BUILD 文件）的上下文中，将输入字符串转换为 Label 对象。如果输入已是 Label，则会原封不动地返回。

此函数只能在评估 BUILD 文件及其直接或间接调用的宏时调用；它不能在（例如）规则实现函数中调用。

此函数的结果与将给定字符串传递给 BUILD 文件中声明的目标的标签值属性所产生的 Label 值相同。

使用说明： 此函数与 Label() 的区别在于，Label() 使用调用它的 .bzl 文件的软件包的上下文，而不是 BUILD 文件的软件包的上下文。当您需要引用硬编码到宏中的固定目标（例如编译器）时，请使用 Label()。当您需要将 BUILD 文件提供的标签字符串规范化为 Label 对象时，请使用 package_relative_label()。（在 BUILD 文件或调用 .bzl 文件以外的软件包的上下文中，无法将字符串转换为 Label。因此，外部宏应始终首选将 Label 对象传递给内部宏，而不是标签字符串。）

参数

参数 说明
input 字符串；或 Label； 必需
输入标签字符串或 Label 对象。如果传递了 Label 对象，则会原封不动地返回。

repo_name

string repo_name()

包含当前正在评估的软件包的代码库的规范名称，不带前导 @ 符号。

repository_name

string repository_name()

实验性。此 API 处于实验阶段，可能会随时更改。请勿依赖此功能。您可以通过设置 --+incompatible_enable_deprecated_label_apis
已废弃 。建议改用 repo_name，它不包含虚假的前导 @ 符号，但在其他方面行为相同。

包含当前正在评估的软件包的代码库的规范名称，带单个前缀 @ 符号 (@)。例如，在由 WORKSPACE 节 local_repository(name='local', path=...) 调用而存在的软件包中，它将设置为 @local。在主代码库中的软件包中，它将设置为 @.

select

unknown select(x, no_match_error='')

select() 是使规则属性 可配置的辅助函数。如需了解详情，请参阅 build 百科全书。

参数

参数 说明
x 必需
将配置条件映射到值的字典。每个键都是一个 Label 或标签字符串，用于标识 config_setting 或 constraint_value 实例。如需了解何时使用 Label 而不是字符串，请参阅宏文档。
no_match_error 默认值为 ''
如果没有任何条件匹配，则报告可选的自定义错误。

subpackages

sequence subpackages(include, exclude=[], allow_empty=False)

返回当前软件包的每个直接子软件包的新可变列表，无论文件系统目录深度如何。返回的列表已排序，并且包含相对于当前软件包的子软件包的名称。建议首选使用 bazel_skylib.subpackages 模块中的方法，而不是直接调用此函数。

参数

参数 说明
include 字符串序列； 必需
要在子软件包扫描中包含的 glob 模式列表。
exclude 字符串序列； 默认值为 []
要从子软件包扫描中排除的 glob 模式列表。
allow_empty 默认值为 False
如果调用返回空列表，是否失败。默认情况下，空列表表示对 subpackages() 的调用是多余的，这可能会导致 BUILD 文件中出现错误。设置为 true 可让此函数在这种情况下成功运行。