相约 2023 年 BazelCon 将于 10 月 24 日至 25 日在 Google 慕尼黑举办！报名现已开放！ 了解详情

使用 Bazel 构建程序

报告问题 查看源代码

本页面介绍了如何使用 Bazel 和构建命令语法构建程序。

快速入门

如需运行 Bazel，请转到基本 workspace 目录或其任何子目录，然后输入 bazel。如果您需要创建新的工作区，请参阅构建。

bazel help
                             [Bazel release bazel version]
Usage: bazel command options ...

可用命令

  • analyze-profile：分析 build 配置文件数据。
  • aquery：对分析后的操作图执行查询。
  • build：构建指定的目标。
  • canonicalize-flags：可以标准化 Bazel 标志。
  • clean：移除输出文件，并视情况停止服务器。
  • cquery：执行分析后图查询。
  • dump：转储 Bazel 服务器进程的内部状态。
  • help：输出命令或索引帮助。
  • info：显示有关 bazel 服务器的运行时信息。
  • fetch：提取目标的所有外部依赖项。
  • mobile-install：在移动设备上安装应用。
  • query：执行依赖项图表查询。
  • run：运行指定的目标。
  • shutdown：停止 Bazel 服务器。
  • test：构建并运行指定的测试目标。
  • version：输出 Bazel 的版本信息。

获取帮助

  • bazel help command：输出 command 的帮助和选项。
  • bazel helpstartup_options：适用于托管 Bazel 的 JVM 的选项。
  • bazel helptarget-syntax：说明指定目标的语法。
  • bazel help info-keys：显示信息命令使用的键的列表。

bazel 工具执行很多函数，称为命令。最常用的属性包括 bazel build 和 bazel test。您可以使用 bazel help 浏览在线帮助消息。

构建一个目标

您需要先有一个工作区，然后才能开始构建。工作区是一种目录树，其中包含构建应用所需的所有源文件。Bazel 允许您从完全只读的卷执行构建。

如需使用 Bazel 构建程序，请输入 bazel build，后跟要构建的目标。

bazel build //foo

发出构建 //foo 的命令后，您会看到类似于以下内容的输出：

INFO: Analyzed target //foo:foo (14 packages loaded, 48 targets configured).
INFO: Found 1 target...
Target //foo:foo up-to-date:
  bazel-bin/foo/foo
INFO: Elapsed time: 9.905s, Critical Path: 3.25s
INFO: Build completed successfully, 6 total actions

首先，Bazel 会加载目标依赖项图中的所有软件包。其中包括声明的依赖项、直接列在目标的 BUILD 文件中的文件，以及传递依赖项、目标依赖项的 BUILD 文件中列出的文件。确定所有依赖项后，Bazel 会分析它们的正确性并创建构建操作。最后，Bazel 会执行相应 build 的编译器和其他工具。

在构建执行阶段，Bazel 会输出进度消息。进度消息包括当前构建步骤（如编译器或链接器）启动时的状态，以及已完成的构建次数除以构建操作总数。随着构建开始，总操作次数通常会随着 Bazel 发现整个操作图而增加，但这一数字会在几秒内稳定下来。

在构建结束时，Bazel 会输出请求的目标，无论这些目标是否构建成功；如果构建成功，在哪里可以找到输出文件。运行 build 的脚本可以可靠地解析此输出；如需了解详情，请参阅 --show_result。

如果您再次输入相同的命令，构建就会完成得更快。

bazel build //foo
INFO: Analyzed target //foo:foo (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
Target //foo:foo up-to-date:
  bazel-bin/foo/foo
INFO: Elapsed time: 0.144s, Critical Path: 0.00s
INFO: Build completed successfully, 1 total action

这是一个 null build。由于没有任何变化，因此无需重新加载任何软件包，也无需执行任何构建步骤。如果“foo”或其依赖项发生变化，Bazel 将重新执行一些构建操作，或完成增量构建。

构建多个目标

Bazel 允许您通过多种方式指定要构建的目标。这些统称为“目标模式”。此语法用于 build、test 或 query 等命令。

标签用于指定单个目标，例如在 BUILD 文件中声明依赖项，而 Bazel 的目标模式指定多个目标。目标模式是使用通配符对目标集的标签语法进行归纳。在最简单的情况下，任何有效的标签也是一个有效的目标模式，用于标识正好包含一个目标的一组集。

以 // 开头的所有目标模式都将相对于当前工作区进行解析。

//foo/bar:wiz 只有一个目标 //foo/bar:wiz。
//foo/bar 等同于 //foo/bar:bar。
//foo/bar:all 软件包 foo/bar 中的所有规则目标。
//foo/... foo 目录下所有软件包中的所有规则目标。
//foo/...:all foo 目录下所有软件包中的所有规则目标。
//foo/...:* foo 目录下所有软件包中的所有目标（规则和文件）。
//foo/...:all-targets foo 目录下所有软件包中的所有目标（规则和文件）。
//... 工作区中所有软件包的目标。这不包括外部代码库中的目标。
//:all 顶级软件包中的所有目标（如果工作区的根目录存在“BUILD”文件）。

不以 // 开头的目标模式相对于当前工作目录进行解析。以下示例假定有一个工作目录 foo：

:foo 等同于 //foo:foo。
bar:wiz 等同于 //foo/bar:wiz。
bar/wiz 等同于：
  • 如果 foo/bar/wiz 是软件包，则为 //foo/bar/wiz:wiz
  • 如果 foo/bar 是软件包，则为 //foo/bar:wiz
  • 否则为 //foo:bar/wiz
bar:all 等同于 //foo/bar:all。
:all 等同于 //foo:all。
...:all 等同于 //foo/...:all。
... 等同于 //foo/...:all。
bar/...:all 等同于 //foo/bar/...:all。

默认情况下，递归目标模式遵循目录符号链接，但指向输出基础下的模式（例如在工作区的根目录中创建的便捷符号链接）除外。

此外，在包含目录名称如下的任何目录中评估递归目标模式时，Bazel 不会遵循符号链接：DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN

foo/... 是 package 上方的通配符，表示以递归方式在 foo 目录下（针对软件包路径的所有根目录）的所有软件包。:all 是目标上方的通配符，用于匹配软件包中的所有规则。这两种字符可以组合使用，如在 foo/...:all 中一样。当同时使用这两个通配符时，这可以简化为 foo/...。

此外，:*（或 :all-targets）是与匹配的软件包中的每个目标（包括通常不由任何规则构建的文件，例如与 java_binary 规则关联的 _deploy.jar 文件）匹配的通配符。

这意味着 :* 表示 :all 的超集；虽然可能会混淆，但该语法确实允许将熟悉的 :all 通配符用于典型构建（其中不需要构建目标，如 _deploy.jar）。

此外，Bazel 支持使用斜杠代替标签语法所需的冒号；在使用 Bash 文件名扩展时，这通常很方便。例如，foo/bar/wiz 等同于 //foo/bar:wiz（如果有软件包 foo/bar）或 //foo:bar/wiz（如果存在软件包 foo）。

许多 Bazel 命令都接受目标模式列表作为参数，并且它们都遵循前缀否定运算符 -。这可用于从上述参数指定的集合中减去一组目标。请注意，这意味着顺序很重要。例如，

bazel build foo/... bar/...

指“在 foo 下构建所有目标，在 bar 下构建所有目标”，而

bazel build -- foo/... -foo/bar/...

指“构建 foo 下的所有目标，但不在 foo/bar 下”。（-- 参数是必需的，可以防止以 - 开头的后续参数被解释为其他选项。）

但需要注意的是，以这种方式减去目标时，并不能保证它们不会被构建，因为它们可能是未减去的目标的依赖项。例如，如果存在一个依赖于 //foo/bar:api 等的目标 //foo:all-apis，那么后者将作为构建前者的一部分进行构建。

在 bazel build 和 bazel test 等命令中指定具有 tags = ["manual"] 的目标时，它们未包含在通配符目标模式中（...、:*、:all 等），但它们包含在负通配符目标模式中，也就是说，它们会被减去。如果您希望 Bazel 构建/测试这些目标，则应在命令行中使用明确的目标模式指定此类测试目标。相比之下，bazel query 不会自动执行任何此类过滤（这有违 bazel query 的用途）。

提取外部依赖项

默认情况下，Bazel 会在构建期间下载外部依赖项并为其建立符号链接。但是，您可能希望知道何时添加新的外部依赖项，或者是否想要“预提取”依赖项（例如，在将离线的广告投放之前）。如果您想阻止在构建期间添加新的依赖项，可以指定 --fetch=false 标志。请注意，此标志仅适用于未指向本地文件系统中的目录的代码库规则。例如，对 local_repository、new_local_repository 以及 Android SDK 和 NDK 代码库规则所做的更改将始终生效，无论值 --fetch 如何。

如果您在构建期间禁止提取，并且 Bazel 发现新的外部依赖项，则构建将失败。

您可以通过运行 bazel fetch 手动提取依赖项。如果您在构建期间禁止提取，则需要运行 bazel fetch：

  • 首次构建之前。
  • 添加新的外部依赖项后。

运行后，您无需在 WORKSPACE 文件更改之前再次运行。

fetch 获取提取其依赖项的目标列表。例如，这将提取构建 //foo:bar 和 //bar:baz 所需的依赖项：

bazel fetch //foo:bar //bar:baz

如需提取某个工作区的所有外部依赖项，请运行以下命令：

bazel fetch //...

如果您在工作区根目录下拥有自己使用的所有工具（从库 JAR 到 JDK 本身），则根本不需要运行 bazel 提取。但是，如果您使用工作区目录之外的任何内容，则 Bazel 会在运行 bazel build 之前自动运行 bazel fetch。

代码库缓存

Bazel 会尽量避免多次提取同一文件，即使不同工作区需要同一个文件，或者如果外部代码库的定义发生更改，但仍需要下载同一个文件。为此，bazel 会缓存在代码库缓存中下载的所有文件，这些文件默认位于 ~/.cache/bazel/_bazel_$USER/cache/repos/v1/。位置可通过 --repository_cache 选项更改。缓存会在所有工作区和安装的 bazel 版本之间共享。如果 Bazel 确定某个条目包含正确文件的副本，也就是说，如果下载请求已指定文件的 SHA256 总和，且位于该缓存中的文件位于缓存中，则会从缓存中提取条目。因此，从安全角度来看，为每个外部文件指定哈希不仅是一个好主意，还有助于避免不必要的下载。

每次缓存命中时，系统都会更新缓存中文件的修改时间。这样一来，便可以轻松确定上次在缓存目录中使用文件的情况，例如，手动清理缓存。缓存永远不会自动进行清理，因为它可能包含不再向上游提供的文件的副本。

分发文件目录

分发目录是另一种 Bazel 机制，可避免不必要的下载。Bazel 会在存储库缓存之前搜索分发目录。主要区别在于分发目录需要手动准备。

使用 --distdir=/path/to-directory 选项，您可以指定其他只读目录来查找（而非提取）文件。如果文件名等于网址的基本名称，且文件的哈希值等于下载请求中指定的哈希值，即会从此类目录中获取文件。只有在 WORKSPACE 声明中指定了文件哈希时，这种方法才有效。

虽然文件名上的条件对于正确性而言不是必要的，但它可以将候选文件的数量减少到每个指定的目录中。通过这种方式，指定分发文件目录将保持高效，即使此类目录中的文件数量庞大也是如此。

在密封的环境中运行 Bazel

为了确保 Bazel 的二进制文件大小较小，在首次运行时 Bazel 会通过网络提取隐式依赖项。这些隐式依赖项包含可能并非每个人都需要的工具链和规则。例如，Android 工具仅在构建 Android 项目时未捆绑并提取。

但是，即使您已为所有 WORKSPACE 依赖项提供供应商代码，在隐式隔离的环境中运行 Bazel 时，这些隐式依赖项也可能会导致问题。如需解决此问题，您可以在具有网络访问权限的机器上准备包含这些依赖项的分发目录，然后使用离线方法将其传输到密封的环境。

如需准备分发目录，请使用 --distdir 标志。您需要为每个新的 Bazel 二进制版本执行此操作一次，因为隐式依赖项可能因每个版本而异。

如需在 气封隔离的环境之外构建这些依赖项，请先查看正确版本的 Bazel 源代码树：

git clone https://github.com/bazelbuild/bazel "$BAZEL_DIR"
cd "$BAZEL_DIR"
git checkout "$BAZEL_VERSION"

然后，构建包含该特定 Bazel 版本的隐式运行时依赖项的 tar 压缩文件：

bazel build @additional_distfiles//:archives.tar

将此 tar 压缩文件导出到一个气压式目录中，请注意 --strip-components 标志，因为 --distdir 可能非常复杂，具体位于目录嵌套级别：

tar xvf bazel-bin/external/additional_distfiles/archives.tar \
  -C "$NEW_DIRECTORY" --strip-components=3

最后，在隔离掉的环境中使用 Bazel 时，请传递指向该目录的 --distdir 标志。为方便起见，您可以将其添加为 .bazelrc 条目：

build --distdir=path/to/directory

build 配置和交叉编译

指定给定构建的行为和结果的所有输入可划分为两个不同的类别。第一种是项目的 BUILD 文件中存储的固有信息：build 规则、其属性的值，以及其完整的传递依赖项集。第二种类型是用户或构建工具提供的外部或环境数据：目标架构的选择、编译和链接选项以及其他工具链配置选项。我们将一组完整的环境数据称为“配置”。

在任何给定 build 中，可能有多个配置。假设有一个交叉编译，其中您为 64 位架构构建 //foo:bin 可执行文件，但您的工作站是 32 位机器。显然，build 将需要使用能够创建 64 位可执行文件的工具链来构建 //foo:bin，但构建系统还必须构建在 build 本身期间使用的各种工具，例如从源代码构建然后随后在 genrule 中使用等的工具，并且必须在您的工作站上运行。因此，我们可以识别两种配置：构建配置（用于构建在构建期间运行的工具）和目标配置（或请求配置，但即使目标已经具有多种含义，我们也会更频繁地将其称为“目标配置”），此配置用于构建您最终请求的二进制文件。

通常，有许多库是所请求的构建目标 (//foo:bin) 和一个或多个执行工具（例如某些基本库）的先决条件。此类库必须构建两次，一次用于执行配置，另一次用于目标配置。Bazel 会负责确保构建两个变体，并且派生的文件保持独立，以免受到干扰；通常，您可以同时构建此类目标，因为它们是相互独立的。如果您看到指示已构建指定目标两次的进度消息，则很可能是原因所在。

执行配置衍生自目标配置，如下所示：

  • 除非指定了 --host_crosstool_top，否则请使用与请求配置中指定的相同版本的 Crosstool (--crosstool_top)。
  • 对 --cpu 使用 --host_cpu 的值（默认为 k8）。
  • 使用与请求配置中指定的那些选项相同的值：--compiler、--use_ijars。如果使用 --host_crosstool_top，则系统将使用 --host_cpu 的值在 Crosstool 中针对执行配置查找 default_toolchain（忽略 --compiler）。
  • 对 --javabase 使用 --host_javabase 的值
  • 对 --java_toolchain 使用 --host_java_toolchain 的值
  • 使用针对 C++ 代码 (-c opt) 的优化 build。
  • 不生成任何调试信息 (--copt=-g0)。
  • 从可执行文件和共享库 (--strip=always) 中移除调试信息。
  • 将所有派生文件放在与任何可能的请求配置不同的位置。
  • 抑制带有 build 数据的二进制文件签名（请参阅 --embed_* 选项）。
  • 其他所有值都保留默认值。

与请求配置相比，选择不同的执行配置可能更合适，原因有很多。最重要的是：

首先，通过使用剥离和优化的二进制文件，您可以减少链接和执行工具所花费的时间、这些工具占用的磁盘空间以及分布式构建中的网络 I/O 时间。

其次，通过分离所有 build 中的 exec 和请求配置，您可以避免因请求配置发生细微更改（例如更改链接器选项）而产生的开销非常高的重新构建，如前所述。

更正增量重新构建

Bazel 项目的主要目标之一是确保正确的增量重建。以前的构建工具（尤其是基于 Make 的构建工具）在实现增量构建时做了一些不合理的假设。

首先，文件的时间戳是单调的。虽然这是典型情况，但很容易忽视此假设；同步到文件的更早修订版本会导致该文件的修改时间缩短；基于 Make 的系统不会重新构建。

从更广义的角度来说，虽然 Make 能够检测文件更改，但它并不会检测命令更改。如果您在指定构建步骤中更改传递给编译器的选项，Make 将不会重新运行编译器，有必要使用 make clean 手动舍弃上一个 build 的无效输出。

此外，在其中一个子进程开始向其输出文件写入数据后，Make 并非稳健地终止该子进程的某个子进程。虽然当前执行 Make 会失败，但后续对 Make 的调用会盲目地认为被截断的输出文件是有效的（因为它比其输入更新），并且不会重新构建。同样，如果 Make 进程终止，也会发生类似的情况。

Bazel 避免了这些假设以及其他假设。Bazel 会维护一个数据库，该数据库包含先前完成的所有工作，并且仅在发现该构建步骤的输入文件集（及其时间戳）以及该构建步骤的编译命令与数据库中的某个文件完全一致，并且该数据库条目的输出文件集（及其时间戳）与磁盘上文件的时间戳完全匹配时，才会省略构建步骤。对输入文件或输出文件中的任何更改，或者对命令本身所做的任何更改，都会导致重新执行构建步骤。

使用正确的增量 build 给用户的好处是：由于混淆而浪费了时间。（此外，等待使用 make clean 导致的重新构建所需的时间减少，必要或优先）。

构建一致性和增量构建

正式情况下，如果所有预期的输出文件都存在，并且其内容正确无误（如创建这些文件所需的步骤或规则所指定），我们会将 build 的状态定义为一致。当您修改源文件时，系统会认为构建状态不一致，并使其保持不一致，直到您下次运行构建工具以成功完成迁移为止。我们将这种情况描述为“不稳定不一致”，因为它只是临时性的，而且您可以通过运行构建工具来恢复一致性。

还有一种类型的不一致是有害的，即稳定不一致。如果 build 达到稳定的不一致状态，那么反复成功调用构建工具不会恢复一致性：build 被“卡住”，输出仍不正确。稳定不一致的状态是 Make（和其他构建工具）用户输入 make clean 的主要原因。发现构建工具以这种方式失败（然后从其恢复）可能会非常耗时，而且令人沮丧。

从概念上讲，实现一致 build 的最简单方法是舍弃先前的所有 build 输出并重新开始：让每个 build 都干净 build。显然，这种方法非常耗时（除非是发布工程师），因此为了能够发挥作用，构建工具必须能够在不牺牲一致性的情况下执行增量构建。

正确的增量依赖关系分析很难，如上所述，许多其他构建工具在避免在增量构建期间避免稳定的不一致状态方面表现不佳。相比之下，Bazel 提供以下保证：在您成功调用构建工具后，如果您未进行修改，build 将处于一致状态。（如果您在构建期间修改源文件，Bazel 无法保证当前构建的结果的一致性。但这可以保证下一次构建的结果将恢复一致性。

与所有保证一样，也有一些细则：使用 Bazel 可通过一些已知的方式来保持稳定的不一致状态。我们不能保证调查在增量依赖项分析中故意尝试查找 bug 而导致的此类问题，但我们将调查并尽最大努力来修复由于构建工具使用不当或“合理”使用而导致的所有稳定版不一致状态。

如果您曾使用 Bazel 检测到稳定的状态，请报告 bug。

沙盒化执行

Bazel 使用沙盒来确保操作正常、正确运行。Bazel 在沙盒中运行生成（松散地说过：操作），其中仅包含该工具执行其工作所需的最小文件集。目前，沙盒适用于启用了 CONFIG_USER_NS 选项的 Linux 3.12 或更高版本，以及 macOS 10.11 或更高版本。

如果您的系统不支持沙盒化功能，Bazel 将输出警告，让您知道 build 不一定是封闭的，并且可能会对未知系统造成影响。如需停用此警告，您可以将 --ignore_unsupported_sandboxing 标志传递给 Bazel。

在某些平台（例如 Google Kubernetes Engine 集群节点或 Debian）上，出于安全考虑，用户命名空间默认处于停用状态。可以通过查看文件 /proc/sys/kernel/unprivileged_userns_clone 进行检查：如果存在文件且该文件包含 0，则可通过 sudo sysctl kernel.unprivileged_userns_clone=1 激活用户命名空间。

在某些情况下，由于系统设置，Bazel 沙盒无法执行规则。问题通常表现为输出类似于 namespace-sandbox.c:633: execvp(argv[0], argv): No such file or directory 的消息。 在这种情况下，请尝试通过 --strategy=Genrule=standalone 为 genrule 停用沙盒，而对 --spawn_strategy=standalone 对其他规则停用沙盒。此外，请在我们的问题跟踪器上报告错误，并说明您使用的是哪个 Linux 发行版，以便我们调查并后续版本中修正问题。

构建的各个阶段

在 Bazel 中，构建分为三个不同的阶段；作为用户，了解它们之间的差异可以深入了解控制构建的选项（请参阅下文）。

加载阶段

第一种方式是“加载”，在此期间，系统将加载、解析、评估和缓存初始目标的所有必要 BUILD 文件，及其传递依赖项的闭包。

对于 Bazel 服务器启动后的第一个构建，加载阶段通常需要几秒钟的时间，因为许多 BUILD 文件都是从文件系统中加载的。在后续构建中，尤其是在没有 build 文件更改的情况下，加载速度会非常快。

在此阶段报告的错误包括：未找到软件包、未找到目标、build 文件中的词法和语法错误以及评估错误。

分析阶段

第二阶段“分析”涉及每个构建规则的语义分析和验证、构建依赖项图的构建，以及确定构建过程中每个步骤的确切工作。

与加载一样，如果完整计算，分析过程也需要几秒钟的时间。不过，Bazel 会将依赖项图从一个 build 缓存到下一个 build 并仅重新分析它包含的内容，这样一来，在自上一个 build 以来软件包未发生更改的情况下，这可以使增量 build 变得极快。

此阶段报告的错误包括：不当依赖项、规则输入无效，以及所有特定于规则的错误消息。

加载和分析阶段速度较快，因为 Bazel 避免了在此阶段不必要的文件 I/O，仅读取 BUILD 文件以确定要完成的工作。这是特意设计的，这使得 Bazel 成为了各种分析工具（例如 Bazel 的 query 命令，可在加载阶段上方实现）的良好基础。

执行阶段

构建的第三阶段（也是最后一个阶段）是执行。此阶段可确保 build 中每个步骤的输出与其输入一致，并根据需要重新运行编译/链接/工具。此步骤是构建所花费时间大部分的时间，范围从几秒到一个小时以上（对于大型构建）。在此阶段报告的错误包括：缺少源文件、某个构建操作在工具中执行的错误，或某个工具无法生成预期的一组输出。