此页面由 Cloud Translation API 翻译。

使用 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：显示 info 命令使用的键列表。

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 会执行构建的编译器和其他工具。

在构建的执行阶段，Bazel 会输出进度消息。进度消息包含开始的当前构建步骤（例如编译器或链接器）以及已完成的构建操作总数和已完成的步骤数量。随着构建开始，随着 Bazel 发现整个操作图，操作总数通常会增加，但该操作的数量会在几秒钟内稳定下来。

在构建结束时，Bazel 会输出请求的目标、是否已成功构建这些目标；如果构建成功，则会显示输出文件的位置。运行构建的脚本可以可靠地解析此输出；如需了解详情，请参阅 --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/... 是 packages 中的通配符，表示以递归方式在目录 foo（针对软件包路径的所有根目录）下的所有软件包。:all 是目标的通配符，与软件包中的所有规则匹配。这两个通配符可以组合使用，如 foo/...:all 中所示，当同时使用两个通配符时，可以将其缩写为 foo/...。

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

这意味着 :* 表示 :all 的超集；虽然可能会令人困惑，但此语法允许将熟悉的 :all 通配符用于典型 build，其中不需要构建 _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:all-apis 依赖于 //foo/bar:api，那么后者将作为构建前者的一部分进行构建。

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

提取外部依赖项

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

如果您在构建期间禁止提取，但 Bazel 找到了新的外部依赖项，您的构建将会失败。

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

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

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

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

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

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

bazel fetch //...

使用 Bazel 7.1 或更高版本，如果您启用了 Bzlmod，还可以通过运行以下命令来提取所有外部依赖项

bazel fetch

如果您在工作区根目录下拥有要使用的所有工具（从库 jar 文件到 JDK 本身），则根本不需要运行 bazel fetch 服务。不过，如果您使用的是工作区目录以外的任何项目，则 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 项目时才不会捆绑和提取。

但是，即使您已提供所有工作区依赖项，在经过隔离的环境中运行 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 位机器。显然，构建需要使用能够创建 64 位可执行文件的工具链构建 //foo:bin，但构建系统还必须构建在构建过程中使用的各种工具（例如在源代码构建后随后用于 genrule 等的工具），并且这些工具必须构建为能够在工作站上运行。因此，我们可以确定两种配置：一种是“exec”配置，用于构建在构建期间运行的工具；另一种是“目标配置”（或“请求配置”，但我们经常说“目标配置”，尽管这个词已经有多种含义），用于构建您最终请求的二进制文件。

通常情况下，许多库是请求的构建目标 (//foo:bin) 以及一个或多个执行工具的前提条件，例如某些基础库。此类库必须构建两次，一次针对 exec 配置，一次针对目标配置。Bazel 会确保构建这两个变体，并将派生文件单独放置以避免干扰；通常可以同时构建此类目标，因为它们是彼此独立的。如果您看到进度消息，指示给定目标正在构建两次，这很可能是说明原因。

exec 配置派生自目标配置，如下所示：

除非指定了 --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++ 代码使用优化 build (-c opt)。
不生成调试信息 (--copt=-g0)。
从可执行文件和共享库 (--strip=always) 中删除调试信息。
将所有派生文件放在特殊位置，与任何可能的请求配置使用的位置不同。
禁止标记包含 build 数据的二进制文件（请参阅 --embed_* 选项）。
所有其他值将保持默认值。

从请求配置中选择不同的执行配置的原因可能有很多种。最重要的一点是：

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

其次，通过分离所有 build 中的 exec 和请求配置，您可以避免因对请求配置进行小幅更改（例如更改链接器选项）而导致费用非常高昂的重新构建，如前所述。

纠正增量重新构建

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

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

更笼统地说，虽然 Make 可以检测文件更改，但不会检测命令更改。如果您更改在指定构建步骤中传递给编译器的选项，Make 不会重新运行编译器，并且需要使用 make clean 手动舍弃上一个构建的无效输出。

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

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

使用正确的增量 build 对用户的好处是：减少了因混淆而浪费的时间。（此外，无论是必要还是抢占的，因使用 make clean 而导致的重建等待时间缩短了。）

构建一致性和增量构建

正式地，当所有预期输出文件存在且文件内容正确（如创建文件所需的步骤或规则所述）时，我们将构建状态定义为一致。当您修改源文件时，构建状态会被视为“不一致”，并将保持不一致状态，直到您下次运行构建工具成功完成为止。我们将这种情况称为“不稳定的不一致性”，因为它只是暂时的，运行构建工具可以恢复一致性。

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

从概念上讲，实现一致 build 的最简单方法是舍弃之前的所有构建输出并重新开始构建：使每个 build 都是干净的 build。这种方法显然太耗时，不切实际（发布工程师除外）。因此，构建工具必须在不影响一致性的情况下执行增量构建，这样才能派上用场。

执行正确的增量依赖项分析很困难，如上所述，许多其他构建工具在避免增量构建期间出现稳定状态不一致方面做得非常糟糕。相比之下，Bazel 提供以下保证：在成功调用构建工具且您未进行任何修改的情况下，构建将处于一致的状态。（如果您在构建期间修改源文件，Bazel 无法保证当前构建的结果的一致性。但这确实可以保证下一次构建的结果将恢复一致性。）

与所有保证一样，有一些细节要求：使用 Bazel 时，有一些已知的方法可以使 Bazel 进入稳定的不一致状态。我们无法保证调查因故意在增量依赖项分析中查找 bug 而导致的此类问题，但我们会开展调查，并尽最大努力解决因正常或“合理”使用构建工具而导致的所有稳定状态不一致的问题。

如果您在使用 Bazel 时检测到稳定的状态不一致，请报告 bug。

沙盒化执行

Bazel 使用沙盒来保证操作能够封闭且正确运行。Bazel 会在沙盒中运行 spawns（简单来说是操作），这些沙盒仅包含工具完成其工作所需的最小文件集。目前，沙盒功能适用于启用了 CONFIG_USER_NS 选项的 Linux 3.12 或更高版本，以及 macOS 10.11 或更高版本。

如果您的系统不支持沙盒，Bazel 会输出一条警告，提醒您构建不一定是封闭的，并且可能会以未知方式影响主机系统。如需停用此警告，您可以将 --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 的其他规则停用沙盒。此外，请在我们的问题跟踪器中报告 bug，并说明您使用的是哪个 Linux 发行版，以便我们进行调查，并在后续版本中提供解决方案。

构建的各个阶段

在 Bazel 中，构建分三个不同的阶段进行；作为用户，了解这些阶段之间的差异有助于深入了解控制构建的选项（见下文）。

加载阶段

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

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

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

分析阶段

第二个阶段是分析，这涉及到每条构建规则的语义分析和验证、构建依赖关系图，以及确切确定要在构建的每个步骤中完成的工作。

与加载一样，整体计算时，分析也需要几秒钟的时间。不过，Bazel 会将依赖项图缓存到下一次构建，并且仅会重新分析其所包含的内容，这样一来，如果软件包自上次构建以来没有任何更改，增量构建能够以极快的速度进行。

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

加载和分析阶段的速度很快，因为 Bazel 可以在此阶段避免了不必要的文件 I/O，只需读取 build 文件即可确定要完成的工作。这是设计使然，并使得 Bazel 成为了分析工具（例如，在加载阶段之上实现的 Bazel 的 query 命令）的良好基础。

执行阶段

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