相约 2023 年 BazelCon 将于 10 月 24 日至 25 日在 Google 慕尼黑举办!了解详情

原生

报告问题 查看源代码

一个内置模块,用于支持原生规则和其他软件包辅助函数。所有原生规则都在此模块中显示为函数,例如 native.cc_library。请注意,原生模块仅在加载阶段(即宏,不适用于规则实现)可用。属性会忽略 None 值,并将其视为未设置属性。
您也可以使用以下函数:

会员

现有规则

unknown native.existing_rule(name)

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

此处,类似于字典的不可变对象表示支持字典的迭代、len(x)name in xx[name]x.get(name)x.items()x.keys()x.values() 的深度不可变对象 x

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

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

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

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

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

参数

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

现有的规则

unknown native.existing_rules()

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

此处,类似于字典的不可变对象表示支持字典的迭代、len(x)name in xx[name]x.get(name)x.items()x.keys()x.values() 的深度不可变对象 x

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

注意:请尽可能避免使用此函数。这会让 BUILD 文件变得脆弱且依赖于顺序。此外,如果设置了 --noincompatible_existing_rules_immutable_view 标志,该函数的开销可能会很大,特别是在循环内调用时。

导出文件

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

指定属于此软件包的文件列表,这些文件会导出到其他软件包。

参数

参数 说明
srcs sequence of strings;必需
要导出的文件列表。
visibility sequence; or None; default = None
可以指定可见性声明。目标文件将对指定目标可见。如果未指定可见性,文件将对所有软件包可见。
licenses sequence of strings; or None; default = None
要指定的许可。

glob

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

Glob 会返回当前软件包中每个文件的新且可变的排序列表,该文件:
  • 至少匹配一个 include 格式。
  • exclude(默认为 [])中的任何格式均不匹配。
如果启用了 exclude_directories 参数(设置为 1),结果中会忽略类型目录文件(默认为 1)。

参数

参数 说明
include sequence of strings; default = []
要包含的 glob 模式列表。
exclude sequence of strings; default = []
要排除的 glob 模式列表。
exclude_directories default = 1
用于排除目录的标志。
allow_empty default = unbound
是否允许 glob 模式不匹配任何内容。如果“allow_empty”为 False,那么每个个人的包含模式都必须匹配某种内容,最终结果不得为空(在排除“exclude”模式的匹配之后)。

module_name

string native.module_name()

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

module_version

string native.module_version()

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

package_group

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

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

参数

参数 说明
name 必需
此规则的唯一名称。
packages sequence of strings; default = []
此组中软件包的完整枚举。
includes sequence of strings; default = []
此软件包中包含的其他软件包组。

软件包名称

string native.package_name()

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

package_Relative_label

Label native.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; or Label;必需
输入标签字符串或标签对象。如果传递了 Label 对象,它将按原样返回。

代码库名称

string native.repository_name()

从中调用规则或构建扩展程序的代码库的名称。例如,在 WORKSPACE 节 local_repository(name='local', path=...) 调用存在的软件包中,它会设置为 @local。在主代码库中的软件包中,它会设置为 @。此函数等效于已弃用的变量 REPOSITORY_NAME

子软件包

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

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

参数

参数 说明
include sequence of strings;必需
要包含在子软件包扫描中的 glob 模式列表。
exclude sequence of strings; default = []
要从子软件包扫描中排除的 glob 模式列表。
allow_empty default = False
调用是否返回空列表时是否失败。默认情况下,如果对 subpackages() 的调用非常多,系统会在 BUILD 文件中显示空错误。在这种情况下,设置为 true 可让此函数成功。