Bazel 模块

报告问题 查看源代码 每夜 build · 7.4 .

Bazel 模块是一种可以有多个版本的 Bazel 项目，每个版本都会发布与其依赖的其他模块相关的元数据。这类似于其他依赖项管理系统中常见的概念，例如 Maven 工件、npm 软件包、Go 模块或 Cargo crate。

模块必须在其代码库根目录（WORKSPACE 文件旁边）有一个 MODULE.bazel 文件。此文件是模块的清单，用于声明其名称、版本、直接依赖项列表和其他信息。下面是一个基本示例：

module(name = "my-module", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

请参阅 MODULE.bazel 文件中可用的指令的完整列表。

如需执行模块解析，Bazel 首先会读取根模块的 MODULE.bazel 文件，然后重复从 Bazel 注册库请求任何依赖项的 MODULE.bazel 文件，直到发现整个依赖关系图。

默认情况下，Bazel 会选择每个模块的一个版本来使用。Bazel 表示具有代码库的每个模块，并再次查询注册表以了解如何定义每个代码库。

版本格式

Bazel 拥有多元化的生态系统，项目使用各种版本控制方案。到目前为止，最受欢迎的是 SemVer，但也有一些知名项目使用不同的方案，例如 Abseil，其版本基于日期（例如 20210324.2）。

因此，Bzlmod 采用了更宽松的 SemVer 规范版本。差异包括：

  • SemVer 规定，版本的“release”部分必须由 3 个部分组成：MAJOR.MINOR.PATCH。在 Bazel 中，此要求已放宽，允许使用任意数量的段。
  • 在 SemVer 中，“release”部分中的每个部分都必须是纯数字。在 Bazel 中，这已放宽，也允许使用字母，并且比较语义与“预发布”部分中的“标识符”相匹配。
  • 此外，系统不会强制执行主要版本号、次要版本号和补丁版本号递增的语义。不过，如需详细了解我们如何表示向后兼容性，请参阅兼容性级别。

任何有效的 SemVer 版本都是有效的 Bazel 模块版本。此外，如果将两个 SemVer 版本 a 和 b 作为 Bazel 模块版本进行比较，只有当它们的比较结果为 a < b 时，才会将这两个版本的比较结果也视为 a < b。

版本选择

考虑菱形依赖项问题，这是版本化依赖项管理空间中的一个重要问题。假设您有以下依赖关系图：

       A 1.0
      /     \
   B 1.0    C 1.1
     |        |
   D 1.0    D 1.1

应使用哪个版本的 D？为了解决此问题，Bzlmod 使用 Go 模块系统中引入的最小版本选择 (MVS) 算法。MVS 假定模块的所有新版本都向后兼容，因此会选择任何依赖项（在我们的示例中为 D 1.1）指定的最高版本。之所以称之为“最小”，是因为 D 1.1 是能够满足我们要求的最低版本 - 即使存在 D 1.2 或更高版本，我们也不会选择它们。使用 MVS 可以创建一个高保真且可重现的版本选择过程。

被取消的版本

如果某些版本应被避免（例如存在安全漏洞），注册表可以将其声明为已移除。在选择被提取的模块版本时，Bazel 会抛出错误。如需修复此错误，请升级到未拉取的较新版本，或使用 --allow_yanked_versions 标志明确允许被拉取的版本。

兼容性级别

在 Go 中，MVS 关于向后兼容性的假设是可行的，因为它将向后不兼容的模块版本视为单独的模块。从 SemVer 的角度来看，这意味着 A 1.x 和 A 2.x 被视为不同的模块，可以在解析后的依赖项图中共存。反过来，这得益于在 Go 的软件包路径中对主要版本进行编码，因此不会出现任何编译时或链接时冲突。

不过，Bazel 无法提供此类保证，因此需要“主要版本”号才能检测向后不兼容的版本。此编号称为兼容性级别，由每个模块版本在其 module() 指令中指定。有了这些信息，当 Bazel 检测到已解析的依赖项图中存在具有不同兼容性级别的同一模块的版本时，便可以抛出错误。

覆盖对象

在 MODULE.bazel 文件中指定替换项，以更改 Bazel 模块解析的行为。只有根模块的替换项会生效 - 如果某个模块用作依赖项，系统会忽略其替换项。

每个替换项都是为特定模块名称指定的，这会影响依赖项图中的所有版本。虽然只有根模块的替换项才会生效，但它们适用于根模块不直接依赖的传递依赖项。

单版本替换

single_version_override 有多种用途：

  • 借助 version 属性，您可以将依赖项固定到特定版本，无论依赖项图中请求的是哪个版本的依赖项。
  • 借助 registry 属性，您可以强制此依赖项来自特定注册库，而不是遵循常规的注册库选择流程。
  • 借助 patch* 属性，您可以指定要应用于下载的模块的一组补丁。

这些属性均为可选属性，可以相互混合和匹配。

多版本替换

可以指定 multiple_version_override，以允许同一模块的多个版本在已解析的依赖关系图中共存。

您可以为模块指定允许的版本的明确列表，这些版本必须在解析之前都存在于依赖项图中，并且必须存在某些传递依赖项，具体取决于每个允许的版本。解析后，系统只会保留允许的模块版本，而 Bazel 会将模块的其他版本升级到同一兼容性级别中允许的最近较高版本。如果不存在同一兼容性级别的更高允许版本，Bazel 会抛出错误。

例如，如果在解析之前依赖项图中存在版本 1.1、1.3、1.5、1.7 和 2.0，并且主要版本是兼容性级别：

  • 允许使用 1.3、1.7 和 2.0 的多版本替换项会导致 1.1 升级到 1.3、1.5 升级到 1.7，而其他版本保持不变。
  • 允许 1.5 和 2.0 的多版本替换会导致错误，因为 1.7 没有相同兼容性级别的更高版本可供升级。
  • 允许 1.9 和 2.0 的多版本替换会导致错误，因为在解析之前，依赖关系图中不存在 1.9。

此外，用户还可以使用 registry 属性替换注册表，与单版本替换类似。

非注册表替换项

非注册表替换项会将模块从版本解析中完全移除。Bazel 不会从注册表请求这些 MODULE.bazel 文件，而是从代码库本身请求这些文件。

Bazel 支持以下非注册表替换项：

定义不代表 Bazel 模块的代码库

借助 bazel_dep，您可以定义代表其他 Bazel 模块的代码库。有时，您需要定义一个不代表 Bazel 模块的代码库；例如，包含要作为数据读取的纯 JSON 文件的代码库。

在这种情况下，您可以使用 use_repo_rule 指令通过调用代码库规则直接定义代码库。此代码库仅对定义它的模块可见。

在后台，此功能是使用与模块扩展相同的机制实现的，这样您就可以更灵活地定义代码库。

代码库名称和严格依赖项

为模块提供直接依赖项的代码库的显式名称默认为其模块名称，除非 bazel_dep 指令的 repo_name 属性另有说明。请注意，这意味着模块只能找到其直接依赖项。这有助于防止因传递依赖项发生变化而意外中断。

支持某个模块的代码库的规范名称为 module_name~version（例如 bazel_skylib~1.0.3）或 module_name~（例如 bazel_features~），具体取决于整个依赖关系图中是否存在该模块的多个版本（请参阅 multiple_version_override）。请注意，规范名称格式不是您应该依赖的 API，并且可能会随时更改。您无需对规范名称进行硬编码，而是使用受支持的方式直接从 Bazel 获取规范名称： * 在 BUILD 和 .bzl 文件中，对通过代码库名称提供的标签字符串构造的 Label 实例使用 Label.repo_name，例如Label("@bazel_skylib").repo_name。 * 在查找 runfile 时，请使用 $(rlocationpath ...) 或 @bazel_tools//tools/{bash,cpp,java}/runfiles 中的某个 runfile 库，对于规则集 rules_foo，请使用 @rules_foo//foo/runfiles 中的 runfile 库。* 通过外部工具（例如 IDE 或语言服务器）与 Bazel 交互时，请使用 bazel mod dump_repo_mapping 命令获取给定一组代码库的显式名称与规范名称之间的映射。

模块扩展还可以将其他代码库引入到模块的可见范围内。