本国的/原生的/土著

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

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

existing_rule

unknown native.existing_rule(name)

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

在这里,不可变的字典型对象是指支持字典型迭代的深层不可变对象 xlen(x)name in xx[name]x.get(name)x.items()x.keys()x.values()

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

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

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

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

参数

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

existing_rules

unknown native.existing_rules()

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

在这里,不可变的字典型对象是指支持字典型迭代的深层不可变对象 xlen(x)name in xx[name]x.get(name)x.items()x.keys()x.values()

注意:请尽可能避免使用此函数。这会导致 BUILD 文件变得脆弱且依赖于顺序。

exports_files

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

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

参数

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

glob

sequence native.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
是否允许全局通配模式匹配任何内容。如果 `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 string; 必需
此规则的唯一名称。
packages 字符串序列; 默认为 []
此组中软件包的完整枚举。
includes 字符串序列; 默认为 []
此软件包组包含的其他软件包组。

package_name

string native.package_name()

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

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

参数

参数 说明
input 字符串;或标签; 必需
输入标签字符串或 Label 对象。如果传递 Label 对象,系统会原封不动地将其返回。

repo_name

string native.repo_name()

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

repository_name

string native.repository_name()

实验性。此 API 目前处于实验阶段,随时可能会发生变化。请勿依赖此功能。您可以通过设置 --+incompatible_enable_deprecated_label_apis
以实验性方式启用此功能已废弃。建议改用 repo_name,它不包含多余的前置 @ 符号,但在其他方面行为完全相同。

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

子软件包

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

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

参数

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