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")

如需执行模块解析，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 支持以下非注册表替换项：

代码库名称和严格依赖项

为模块提供支持的代码库的规范名称为 module_name~version（例如 bazel_skylib~1.0.3）。对于具有非注册表替换项的模块，请将 version 部分替换为字符串 override。请注意，规范名称格式不是您应依赖的 API，并且可能会随时发生变化。

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

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