外部依赖项概览

报告问题 查看源代码

Bazel 支持外部依赖项，即构建中使用的并非来自工作区的源文件（文本和二进制文件）。例如，这些目录可能是托管在 GitHub 代码库中的规则集、Maven 工件或本地机器上当前工作区之外的目录。

从 Bazel 6.0 开始，您可以通过以下两种方式使用 Bazel 管理外部依赖项：以存储库为中心的传统 WORKSPACE 系统和以模块的较新 MODULE.bazel 系统（代号为 Bzlmod，使用 --enable_bzlmod 标志启用）。这两个系统可以一起使用，但 Bzlmod 将在未来的 Bazel 中取代 WORKSPACE 系统迁移到 Bazel。

本文档将介绍 Bazel 中外部依赖项管理的概念，然后再按顺序详细了解这两个系统。

概念

仓库

包含 WORKSPACE 或 WORKSPACE.bazel 文件的目录，其中包含要在 Bazel 构建中使用的源文件。通常简称为“repo”。

主代码库

运行当前 Bazel 命令的代码库。

Workspace

所有 Bazel 命令共享的环境都在同一主代码库中运行。

请注意，“仓库”和“工作区”的概念历来混淆；术语“工作区”通常用来指代主仓库，有时甚至用作“仓库”的同义词。

规范代码库名称

代码库可寻址的规范名称。在工作区环境中，每个代码库都有一个规范名称。代码库中的规范名称为 canonical_name 的目标可通过标签 @@canonical_name//pac/kage:target（请注意双 @）进行寻址。

主代码库始终将空字符串作为规范名称。

明显的代码库名称

代码库在某个其他代码库的上下文中可寻址的名称。这可视为代码库的“昵称”：采用规范名称 michael 的代码库在代码库 alice 的上下文中可能具有表观名称 mike，但在代码库 bob 的上下文中可能具有外表名称 mickey。在这种情况下，michael 中的目标可以通过标签 @mike//pac/kage:target 在 alice 的上下文中进行处理（请注意单个 @）。

反之，您可以将其理解为代码库映射：每个代码库都维护着从“表观的代码库名称”到“规范代码库名称”的映射。

代码库规则

用于告知 Bazel 如何具体化代码库的代码库定义的架构。例如，它可以是“从特定网址下载 zip 归档文件并解压缩”，“提取特定 Maven 工件并使其作为 java_import 目标可用”，也可以是“对本地目录进行符号链接”。每个代码库都是通过调用具有适当数量的参数的代码库规则进行定义的。

如需详细了解如何编写自己的代码库规则，请参阅代码库规则。

到目前为止，最常用的代码库规则是 http_archive，用于从网址下载归档文件并将其解压缩；以及 local_repository，通过符号链接表示一个已经是 Bazel 代码库的本地目录。

提取代码库

通过运行关联的代码库规则在本地磁盘上提供代码库的操作。在提取之前，工作区中定义的代码库在本地磁盘上不可用。

通常，Bazel 仅在需要从代码库中获取某些内容，且尚未提取代码库时才会提取代码库。如果代码库之前已被提取过，则 Bazel 只会在其定义发生变化时重新提取它。

目录布局

提取后，您可以在输出基准中的子目录 external 的规范名称下找到代码库。

您可以运行以下命令，查看规范名称为 canonical_name 的代码库的内容：

ls $(bazel info output_base)/external/ canonical_name

使用 Bzlmod 管理外部依赖项

Bzlmod（新的外部依赖项子系统）不直接使用 Repo 定义。而是从“模块”构建依赖关系图，在该图之上运行扩展程序，并相应地定义代码库。

Bazel 模块模块是可以有多个版本的 Bazel 项目，每个版本发布其所依赖的其他模块的元数据。模块的代码库根目录中必须在 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")

模块只能列出其直接依赖项，Bzlmod 会在 Bazel 注册表（默认为 Bazel 中央注册表）中查找这些依赖项。注册表提供了依赖项的 MODULE.bazel 文件，以便 Bazel 在执行版本解析之前发现整个传递依赖项图。

在版本解析（为每个模块选择一个版本）后，Bazel 会再次查询注册表，了解如何为每个模块定义代码库（大多数情况下，使用 http_archive）。

模块还可以指定名为“标记”的自定义数据段，在模块解析后，模块扩展会使用这些数据，以定义额外的代码库。这些扩展程序具有与代码库规则类似的功能，能够执行文件 I/O 和发送网络请求等操作。此外，它们允许 Bazel 与其他软件包管理系统交互，同时遵循基于 Bazel 模块构建的依赖关系图。

使用 WORKSPACE 定义代码库

过去，您可以通过在 WORKSPACE（或 WORKSPACE.bazel）文件中定义代码库来管理外部依赖项。此文件的语法与 BUILD 文件类似，采用 Repo 规则而不是构建规则。

以下代码段展示了如何在 WORKSPACE 文件中使用 http_archive 代码库规则：

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "foo",
    urls = ["https://example.com/foo.zip"],
    sha256 = "c9526390a7cd420fdcec2988b4f3626fe9c5b51e2959f685e8f4d170d1a9bd96",
)

该代码段定义了一个规范名称为 foo 的代码库。在 WORKSPACE 系统中，默认情况下，代码库的规范名称也是它对所有其他代码库的明显名称。

请参阅 WORKSPACE 文件中提供的函数的完整列表。

WORKSPACE 系统的缺点

自从 WORKSPACE 系统推出以来的几年里，用户曾报告过许多痛点，包括：

  • Bazel 不会评估任何依赖项的 WORKSPACE 文件，因此除了直接依赖项之外，所有传递依赖项都必须在主代码库的 WORKSPACE 文件中定义。
  • 为了解决此问题，项目采用了“deps.bzl”模式，在该模式下，项目会定义一个宏，而该宏又会定义多个代码库，并要求用户在其 WORKSPACE 文件中调用此宏。
    • 这也存在一些问题：宏无法 load 其他 .bzl 文件，因此这些项目必须在此“deps”宏中定义其传递依赖项，或者让用户调用多个分层“deps”宏来解决此问题。
    • Bazel 会依序评估 WORKSPACE 文件。此外，依赖项是使用含网址的 http_archive 指定的，不包含任何版本信息。这意味着，存在菱形依赖项时，没有可靠的方法可以执行版本解析（A 依赖于 B 和 C；B 和 C 都依赖于不同版本的 D）。

由于 WORKSPACE 的缺点，Bzlmod 将在未来的 Bazel 版本中取代旧版 WORKSPACE 系统。如需了解如何迁移到 Bzlmod，请参阅 Bzlmod 迁移指南。