构建文件

报告问题 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

BUILD 文件中可用的方法。另请参阅 Build 百科全书,了解可在 BUILD 文件中使用的其他函数和 build 规则。

成员

depset

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

创建 depsetdirect 参数是 depset 的直接元素列表,而 transitive 参数是 depset 的列表,这些 depset 的元素会成为所创建 depset 的间接元素。将 depset 转换为列表时,返回元素的顺序由 order 参数指定。如需了解详情,请参阅 Depset 概览

deps 的所有元素(直接和间接)必须具有相同的类型,如表达式 type(x) 所获得的那样。

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

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

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

参数

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

existing_rule

unknown existing_rule(name)

返回一个不可变的类字典对象,用于描述相应规则在相应线程的软件包中实例化时的属性;如果不存在具有相应名称的规则实例,则返回 None

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

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

结果的值表示属性值,如下所示:

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

如果可能,请仅在规则最终确定器符号宏的实现函数中使用此函数。不建议在其他上下文中使用此函数,并且在未来的 Bazel 版本中,此函数将被停用;它会使 BUILD 文件变得脆弱且依赖于顺序。另请注意,它与另外两种将规则属性值从内部形式转换为 Starlark 的转换略有不同:一种用于计算出的默认值,另一种用于 ctx.attr.foo

参数

参数 说明
name 字符串; 必需
目标的名称。

existing_rules

unknown existing_rules()

返回一个不可变的类字典对象,用于描述相应线程的软件包中目前已实例化的规则。类字典对象的每个条目都会将规则实例的名称映射到 existing_rule(name) 将返回的结果。

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

如果可能,请仅在规则最终确定器符号宏的实现函数中使用此函数。不建议在其他上下文中使用此函数,并且在未来的 Bazel 版本中,此函数将被停用;它会使 BUILD 文件变得脆弱且依赖于顺序。

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 int; 默认值为 1
一个标志,用于指示是否排除目录。
allow_empty 默认值为 unbound
是否允许 glob 模式不匹配任何内容。如果 `allow_empty` 为 False,则每个单独的包含模式都必须匹配某些内容,并且最终结果必须为非空(在排除 `exclude` 模式的匹配项之后)。

module_name

string module_name()

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

module_version

string module_version()

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

包裹

unknown package(**kwargs)

声明适用于软件包中每条规则的元数据。在软件包(BUILD 文件)中,此函数最多只能调用一次。如果调用,它应该是 BUILD 文件中的第一个调用,紧跟在 load() 语句之后。

参数

参数 说明
kwargs 必需
如需了解适用的实参,请参阅 Build Encyclopedia 中的 package() 函数。

package_default_visibility

List package_default_visibility()

返回正在评估的软件包的默认公开范围。这是 package()default_visibility 参数的值,扩展为包含软件包本身。

package_group

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

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

参数

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

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 string;或 Label;必需
输入标签字符串或 Label 对象。如果传递的是 Label 对象,则按原样返回。

repo_name

string repo_name()

包含当前正在评估的软件包的代码库的规范名称,不含开头的 @ 符号。

repository_name

string repository_name()

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

包含当前正在评估的软件包的仓库的规范名称,并以单个英文艾特符 (@) 为前缀。例如,在由 WORKSPACE stanza local_repository(name='local', path=...) 调用而创建的软件包中,它将设置为 @local。在主代码库中的软件包中,它将设置为 @

选择

unknown select(x, no_match_error='')

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

参数

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

子软件包

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

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

参数

参数 说明
include 字符串序列;必需
要在子软件包扫描中包含的 glob 模式列表。
exclude 字符串的序列;默认值为 []
要从子软件包扫描中排除的 glob 模式列表。
allow_empty bool; default is False
Whether we fail if the call returns an empty list. 默认情况下,空列表表示 BUILD 文件中可能存在错误,其中对 subpackages() 的调用是多余的。设置为 true 可让此函数在这种情况下成功运行。