构建文件

报告问题

BUILD 文件中提供的方法。另请参阅“构建百科全书”,了解同样可以在 BUILD 文件中使用的其他函数和构建规则。

成员

废弃

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

创建一个 depsetdirect 形参是 depset 的直接元素列表,而 transitive 形参是一系列 depset,其元素会成为已创建的依赖项的间接元素。将偏移量转换为列表时,返回元素的顺序由 order 参数指定。如需了解详情,请参阅依赖项概览

偏移的所有元素(直接和间接)都必须属于同一类型,如表达式 type(x) 所获取的类型。

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

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

创建的依赖项的顺序应与其 transitive 依赖项的顺序兼容"default" 订单与任何其他订单兼容,其他所有订单仅与其自身兼容。

参数

参数 说明
direct sequence;或 None;默认值为 None
偏移量的直接元素列表。
order 默认值为 "default"
新依赖项的遍历策略。如需了解可能的值,请参阅此处
transitive depsetsequence;或 None;默认值为 None
一系列 depset,其元素将成为该 depset 的间接元素。

existing_rule

unknown existing_rule(name)

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

这里,类似字典的对象是指高度不可变的对象 x,支持类似字典的迭代,即 len(x)name in xx[name]x.get(name)x.items()x.keys()x.values()

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

结果包含每个属性对应的条目,但私有属性(名称不以字母开头)和一些不可表示的旧版属性类型除外。此外,字典包含规则实例的 namekind 的条目(例如 '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 xx[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 序列(共 strings); 必填
要导出的文件列表。
visibility sequence; 或 None;默认值为 None
可以指定可见性声明。这些文件将对指定的目标可见。如果未指定可见性,则文件将对每个软件包可见。
licenses string 组成的序列;或 None;默认为 None
要指定的许可。

glob

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

Glob 会返回一个可变且经过排序的新列表,其中包含当前软件包中符合以下条件的每个文件:
  • 至少与 include 中的一个模式匹配。
  • 与“exclude”中的任何模式都不匹配(默认为 [])。
如果 exclude_directories 参数已启用(设置为 1),结果中将不会包含目录类型的文件(默认为 1)。

参数

参数 说明
include string序列;默认值为 []
要包含的 glob 模式列表。
exclude string序列;默认值为 []
要排除的 glob 模式列表。
exclude_directories 默认值为 1
一个标志,用于指示是否排除目录。
allow_empty 默认值为 unbound
我们是否允许 glob 模式不匹配任何内容。如果“allow_empty”为 False,则每个包含模式都必须匹配某些内容,并且最终结果必须非空(在排除“excluded”模式的匹配项之后)。

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

package_group

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

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

参数

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

package_name

string package_name()

要评估的软件包的名称。例如,在 BUILD 文件 some/package/BUILD 中,其值为 some/package。如果 BUILD 文件调用 .bzl 文件中定义的函数,package_name() 将与调用方 BUILD 文件软件包匹配。此函数相当于已废弃的变量 PACKAGE_NAME

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。因此,外部宏应始终优先将标签对象传递给内部宏,而不是标记字符串。)

参数

参数 说明
input string;或标签;必需
输入标签字符串或标签对象。如果传递了 Label 对象,该对象将按原样返回。

repository_name

string repository_name()

从中调用规则或 build 扩展的代码库的名称。例如,在由 WORKSPACE 节 local_repository(name='local', path=...) 调用存在的软件包中,它将被设置为 @local。在主代码库的软件包中,此属性将设置为 @。此函数相当于已废弃的变量 REPOSITORY_NAME

select

unknown select(x, no_match_error='')

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

参数

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

子软件包

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

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

参数

参数 说明
include string序列;必需
要包含在子软件包扫描中的 glob 模式列表。
exclude string序列;默认值为 []
要从子软件包扫描中排除的 glob 模式列表。
allow_empty 默认值为 False
确定在调用返回空列表时是否失败。默认情况下,空列表表示 BUILD 文件中可能存在错误,其中对 subpackages() 的调用是多余的。如果设置为 true,则此函数可在这种情况下成功运行。