此页面由 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`	只有 1 个目标 `//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:wiz`（如果 `foo/bar/wiz` 是一个软件包） `//foo/bar:wiz`（如果 `foo/bar` 是一个软件包）否则返回 `//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 通配符用于不需要构建类似 _deploy.jar 的目标的典型 build。

此外，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 标志。请注意，此标志仅适用于不指向本地文件系统中目录的代码库规则。例如，对 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 二进制文件版本执行此操作，因为每个版本的隐式依赖项可能各不相同。

如需在 Airgapped 环境之外构建这些依赖项，请先检出正确版本的 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 压缩文件导出到可以复制到 Airgapped 环境中的目录。请注意 --strip-components 标志，因为 --distdir 在目录嵌套级别时可能非常讲究：

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

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

build --distdir=path/to/directory

build 配置和交叉编译

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

在任何给定的 build 中，都可能有多个配置。考虑进行交叉编译，其中为 64 位架构构建 //foo:bin 可执行文件，但您的工作站是 32 位机器。显然，构建将需要使用能够创建 64 位可执行文件的工具链构建 //foo:bin，但构建系统还必须构建构建本身使用的各种工具（例如，从源代码构建然后随后在 Genrule 中使用的工具），并且这些工具必须构建为在您的工作站上运行。因此，我们可以确定两种配置：一种是主机配置，用于构建在构建期间运行的工具；目标配置（或“请求配置”，虽然“目标配置”这个词的意思也更常用，我们称之为“目标配置”），它用于构建您最终请求的二进制文件。

通常情况下，有许多库既是所请求的构建目标 (//foo:bin) 的先决条件，又是一个或多个宿主工具的先决条件，例如某些基础库。此类库必须构建两次，一次用于主机配置，另一次用于目标配置。Bazel 负责确保两个变体均已构建，并且派生的文件会分开保存以避免干扰；此类目标通常可以同时构建，因为它们相互独立。如果您看到进度消息，表明给定目标构建了两次，这很可能就是原因。

Bazel 根据 --distinct_host_configuration 选项，使用两种方法之一来选择主机配置。此布尔选项有点微妙，此设置可能会提高（或变差）构建速度。

`--distinct_host_configuration=false`

当此选项为 false 时，主机和请求配置完全相同：构建期间所需的所有工具的构建方式与目标程序完全相同。此设置意味着在单次构建期间无需构建两次库。

但是，这确实意味着对请求配置所做的任何更改也会影响您的主机配置，导致所有工具以及依赖于工具输出的所有内容都需要重新构建。因此，例如，简单地在 build 之间更改链接器选项就可能导致重新链接所有工具，重新执行使用这些工具的所有操作，以此类推，导致重建工作量非常大。

`--distinct_host_configuration=true` （默认）

如果此选项为 true，则系统不会对主机和请求使用相同的配置，而是使用完全不同的主机配置。主机配置派生自目标配置，如下所示：

除非指定了 --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_* 选项）。
所有其他值均保留默认值。

最好从请求配置中选择不同的主机配置，这样做的原因有很多。其中有些机制过于深奥，在这里我们就不一一提及了，不过其中有两个方面值得一提。

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

其次，通过分离所有 build 中的主机和请求配置，您可以避免因对请求配置进行细微更改（例如，更改链接器选项）而导致的成本很高的重新构建，如前文所述。

不过，对于某些 build，此选项可能会造成阻碍。特别是，不经常更改配置的 build（尤其是某些 Java build），以及必须在主机配置和目标配置中构建大量代码的 build，这些构建可能不会受益。

正确执行增量重新编译

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

首先，文件的时间戳单调递增。虽然这属于典型情况，但很容易与这种假设相抵触；同步到文件的早期修订版本会导致文件的修改时间缩短；基于 Make 的系统不会重新构建。

更笼统地说，虽然 Make 可以检测对文件所做的更改，但它不会检测对命令的更改。如果您在给定构建步骤中更改传递给编译器的选项，Make 将不会重新运行编译器，您必须使用 make clean 手动舍弃之前构建的无效输出。

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

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

使用正确的增量 build 对用户的好处是：因混淆而浪费的时间更少。（此外，无论是必要还是预先执行，因使用 make clean 而导致的等待重新构建所需的时间更短。）

构建一致性和增量构建

正式地说，当所有预期输出文件都存在，并且其内容正确无误时（根据创建这些文件所需的步骤或规则指定），我们将构建状态定义为“一致”。当您修改源文件时，build 的状态会被视为“不一致”，并且在您下次运行构建工具成功完成之前会保持不一致状态。我们将这种情况描述为“不稳定的不一致性”，因为它只是暂时的，可通过运行构建工具来恢复一致性。

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

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

纠正增量依赖项分析并非易事，如上所述，许多其他构建工具在避免增量构建期间的稳定不一致状态方面表现非常糟糕。相比之下，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 发行版，以便我们调查问题并在后续版本中提供修复。

build 的阶段

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

加载阶段

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

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

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

分析阶段

第二阶段“分析”包括对每条 build 规则的语义分析和验证、构建 build 依赖关系图，以及确定在 build 的每个步骤中要完成的具体工作。

与加载一样，完整计算时，分析也需要几秒钟。但是，Bazel 会缓存从一个 build 到下一个 build 的依赖关系图，并且仅重新分析必需的内容，如果软件包自上次构建以来没有更改，则 Bazel 可以非常快速地进行增量构建。

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

加载和分析阶段很快，因为 Bazel 可避免在此阶段进行不必要的文件 I/O，只读取 BUILD 文件以便确定要完成的工作。这是设计使 Bazel 奠定了良好基础，可作为分析工具（例如在加载阶段顶部实现的 Bazel 的 query 命令）的基础。

执行阶段

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