本页将介绍如何使用 Bazel 构建程序、构建命令语法 目标模式语法。
快速入门
如需运行 Bazel，请前往您的基本工作区目录或其任何子目录，然后输入 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 |
相当于：
<ph type="x-smartling-placeholder">
|
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/... 是软件包的通配符，表示目录 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:all-apis 依赖于 //foo/bar:api，那么在构建前者时，系统会一并构建后者。
具有 tags = ["manual"] 的目标不包含在通配符目标模式中
（例如，...、:*、:all 等），在如下命令中指定
bazel build 和 bazel test；则应指定
如果您需要 Bazel，可以在命令行中使用明确的目标模式测试目标
来构建/测试它们相比之下，bazel query 则不执行任何
此类过滤（否则会违反
bazel query）。
提取外部依赖项
默认情况下，Bazel 将下载外部依赖项并对外部依赖项进行符号链接，
build。不过，您可能并不希望这么做，因为您可能想了解
或者因为您想要
“预提取”依赖项（比如在广告投放前，您将处于离线状态）。如果您
想要防止在构建期间添加新的依赖项，
可以指定 --fetch=false 标志。请注意
适用于未指向本地
文件系统例如，更改为 local_repository
new_local_repository 以及 Android SDK 和 NDK 代码库规则
无论值 --fetch 为何，该值始终有效。
如果您在构建期间禁止提取，并且 Bazel 找到了新的外部 依赖项，您的构建将失败。
您可以通过运行 bazel fetch 手动提取依赖项。如果
禁止在 build 提取期间执行某些操作，则需要运行 bazel fetch：
- 在首次构建之前。
- 添加新的外部依赖项后。
运行脚本之后，在进入工作区之前， 文件更改。
fetch 会获取一系列目标的依赖项，以便获取其依赖项。例如，这会提取构建 //foo:bar 和 //bar:baz 所需的依赖项：
bazel fetch //foo:bar //bar:baz
如需提取工作区的所有外部依赖项，请运行以下命令：
bazel fetch //...
如果您使用的所有工具（从库 jar 到 JDK 本身）都在工作区根目录下，则无需运行 bazel fetch。但是，如果你使用的是工作区目录之外的任何内容，则使用 Bazel
将在运行前bazel fetch自动运行
bazel build。
代码库缓存
Bazel 会尽量避免多次提取同一个文件，即使提取同一个文件
文件，或者如果外部
代码库已更改，但仍需下载同一文件。为此，
bazel 将下载的所有文件缓存在代码库缓存中，默认情况下，
位于 ~/.cache/bazel/_bazel_$USER/cache/repos/v1/。通过
可通过 --repository_cache 选项更改位置。该缓存在所有工作区和安装的 bazel 版本之间共享。如果 Bazel 确信自己拥有正确文件的副本（即下载请求包含指定文件的 SHA256 校验和，并且缓存中存在具有该哈希值的文件），则会从缓存中提取条目。为每个外部文件指定一个哈希
不仅从安全角度看是个好主意；还有助于避免
不必要的下载
每次命中缓存时，缓存中文件的修改时间都会更新。这样，便可轻松确定缓存目录中文件的上次使用时间，例如手动清理缓存。缓存绝不会自动清理，因为其中可能包含上游不再提供的文件的副本。
分发文件目录
分发目录是另一种用于避免不必要下载的 Bazel 机制。Bazel 会在代码库缓存之前搜索分发目录。 主要区别在于，分发目录需要手动准备。
使用 --distdir=/path/to-directory 选项，您可以指定其他只读目录来查找文件，而不是提取文件。如果某个文件的名称为
等于该网址的基础名称，此外，该文件的哈希值为
与下载请求中指定的那个 ID 相同。只有在 WORKSPACE 声明中指定了文件哈希时，此操作才有效。
虽然文件名中的条件对于确保正确性并非必要条件， 将候选文件数量减少到每个指定目录一个。这样，即使此类目录中的文件数量很大，指定分发文件目录仍然高效。
在空气隔离环境中运行 Bazel
为了保持 Bazel 的二进制文件大小较小，系统会在 Bazel 首次运行时通过网络提取 Bazel 的隐式依赖项。这些隐式依赖项 包含可能并非所有人都需要的工具链和规则。例如，只有在构建 Android 项目时，才会解封装和提取 Android 工具。
不过，这些隐式依赖项可能会导致 即使你已经为所有应用场景 WORKSPACE 依赖项。为解决此问题，您可以在具有网络访问权限的机器上准备包含这些依赖项的分发目录，然后使用离线方法将其传输到空气隔离环境。
如需准备分发目录，请使用 --distdir 标志。您需要为每个新的 Bazel 二进制版本执行此操作一次，因为每个版本的隐式依赖项可能不同。
如需在 Airgapp 环境之外构建这些依赖项，请先 查看正确版本的 Bazel 源代码树：
git clone https://github.com/bazelbuild/bazel "$BAZEL_DIR"cd "$BAZEL_DIR"git checkout "$BAZEL_VERSION"
然后，构建包含其隐式运行时依赖项的 tar 压缩文件 特定 Bazel 版本：
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 中，都可能有多个配置。考虑采用一种
交叉编译，即为 64 位架构的 //foo:bin 可执行文件
但您的工作站是 32 位机器。显然，构建过程需要使用能够创建 64 位可执行文件的工具链构建 //foo:bin，但构建系统还必须构建构建过程中使用的各种工具（例如从源代码构建的工具，然后在 genrule 等中使用），并且这些工具必须构建为在工作站上运行。因此
我们可以确定两种配置：exec 配置，这用于
（用于构建在构建期间运行的工具），以及目标配置
（或请求配置，但我们更常用的是“目标配置”
（尽管这个词已有许多含义），
您最终请求的二进制文件。
通常，许多库都是所请求的 build 目标 (//foo:bin) 和一个或多个工具（例如某些基础库）的前提条件。必须针对 exec 和 target 配置多次构建此类库。Bazel 会负责确保构建所有变体
应将派生文件分开保存以免造成干扰；通常如此
目标可以同时构建，因为它们彼此独立。如果您看到进度消息，其中指明系统正在多次构建给定目标，那么这很可能是原因所在。
exec 配置派生自目标配置，如下所示：
- 请求目标的执行平台将成为 exec 配置的目标平台。
- 使用与请求配置中指定的版本相同的 Crosstool (
--crosstool_top)，除非指定了--host_crosstool_top。 - 将
--host_cpu的值用作--cpu（默认值：k8）。 - 使用与请求配置中指定的选项相同的值：
--compiler、--use_ijars，如果使用--host_crosstool_top，则--host_cpu的值用于在交叉工具中查找主机配置的default_toolchain（忽略--compiler）。 - 为
--javabase使用--host_javabase的值 - 为
--java_toolchain使用--host_java_toolchain的值 - 使用针对 C++ 代码的优化 build (
-c opt)。 - 不生成调试信息 (
--copt=-g0)。 - 从可执行文件和共享库中剥离调试信息 (
--strip=always)。 - 将所有派生文件放在一个特殊位置，不同于 任何可能的请求配置。
- 禁止使用 build 数据标记二进制文件（请参阅
--embed_*选项）。 - 所有其他值均保留默认值。
正确执行增量重新编译
Bazel 项目的主要目标之一是确保正确的增量 重建。以前的构建工具（尤其是基于 Make 的工具）在实现增量 build 时会做出一些不合理的假设。
首先，文件的时间戳单调递增。虽然这是典型情况，但很容易违背此假设；同步到文件的较早修订会导致该文件的修改时间缩短；基于 make 的系统不会重新构建。
更笼统地说，虽然 Make 可以检测文件更改，但不会检测更改
命令。如果您更改了在给定 build 中传递给编译器的选项
Make 不会重新运行编译器，您必须手动舍弃
使用 make clean 检查上一次构建的无效输出。
此外，即使某个操作系统的某一个实例未成功终止，Make 也并不可靠。 之后，该子进程开始写入其输出文件。虽然当前的 Make 执行将失败，但 Make 的后续调用将盲目地假定截断的输出文件有效（因为它比其输入更新），并且不会重新构建。同样，如果 Make 进程被终止，也可能会出现类似的情况。
Bazel 避免了这些假设以及其他假设。Bazel 会维护一个包含之前完成的所有工作的数据库，并且只有在发现该构建步骤的输入文件集（及其时间戳）和该构建步骤的编译命令与数据库中的某个构建步骤完全匹配，并且数据库条目的输出文件集（及其时间戳）与磁盘上文件的时间戳完全匹配时，才会忽略该构建步骤。对输入文件、输出文件或命令本身进行任何更改都会导致重新执行构建步骤。
正确的增量 build 对用户的好处在于：减少因混淆而浪费的时间。（此外，由于使用 make
clean（无论是必要的还是预防性的），等待重新构建的时间也会缩短。）
构建一致性和增量构建
正式地说，当所有预期结果都符合时，我们将构建状态定义为“一致” 输出文件存在，并且文件内容正确无误， 创建它们所需的规则修改源文件后，构建状态会被视为不一致，并且在下次成功运行构建工具之前保持不一致状态。我们将这种情况称为不稳定的无效性，因为它只是暂时的，运行构建工具即可恢复一致性。
还有一种比较恶劣的不一致性：stable
不一致性。如果 build 达到稳定的不一致状态，然后重复
成功调用构建工具不会恢复一致性：构建
卡住了，输出依然不正确。稳定的不一致状态
是 Make（和其他构建工具）的用户类型为 make clean 的主要原因。
发现构建工具会以这种方式失败（然后恢复
可能非常耗时且令人沮丧。
从概念上讲，实现一致构建的最简单方法是舍弃 所有先前的构建输出，然后重新开始：使每个构建都成为干净的构建。 显然，这种方法非常耗时，不切实际（除了 发布工程师），因此为了有用，构建工具必须能够 可以在不影响一致性的情况下执行增量构建。
正确的增量依赖项分析很难，如上文所述， 其他构建工具在避免稳定不一致状态方面表现不佳， 增量构建。相比之下，Bazel 提供了以下保证： 成功调用了构建工具，但在此期间未进行任何修改， build 将处于一致的状态（如果您在构建期间修改源文件，Bazel 无法保证当前构建结果的一致性。但它可以保证下一个 build 的结果会恢复一致性。）
与所有保证一样，这也有一些细则：有一些已知的方法会导致 Bazel 进入稳定的不一致状态。我们不保证 调查因故意试图在 Google Play 中 增量依赖项分析，但我们会进行调查并尽最大努力修复 所有由正常或“合理”引起的稳定的不一致状态使用 构建工具。
如果您发现 Bazel 存在稳定的不一致状态，请报告 bug。
沙盒化执行
Bazel 使用沙盒来保证操作封闭运行
正确。Bazel 会在沙盒中运行生成的子进程（粗略地说：操作），沙盒中仅包含该工具执行其任务所需的一组最少文件。目前，沙盒功能适用于启用了 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 的消息。在这种情况下，请尝试使用以下代码为 Genrule 停用沙盒
--strategy=Genrule=standalone，以及使用
--spawn_strategy=standalone。此外，请在我们的
问题跟踪工具，并说明您使用的 Linux 发行版，以便我们
并在后续版本中提供修复。
build 的阶段
在 Bazel 中，构建过程分为三个不同的阶段；作为用户，了解它们之间的区别有助于深入了解用于控制构建过程的选项（见下文）。
加载阶段
第一种是加载，在此过程中，系统会加载、解析、评估和缓存初始目标的所有必要 BUILD 文件及其依赖项的传递闭包。
对于启动 Bazel 服务器后的首次构建，加载阶段通常需要几秒钟，因为系统需要从文件系统加载许多 BUILD 文件。在后续 build 中（尤其是在没有任何 BUILD 文件发生更改的情况下），加载速度非常快。
在此阶段报告的错误包括：找不到软件包、找不到目标、 BUILD 文件中的词汇和语法错误，以及评估错误。
分析阶段
第二个阶段是分析，包括语义分析和验证 每个构建规则、构建依赖关系图的构建，以及 确定在构建过程中每一步具体要完成的工作。
与加载一样，完整计算时，分析也需要几秒钟。 但是，Bazel 会将依赖关系图从一个构建缓存到下一个构建， 它会重新分析其内容，这样可以使增量构建以 软件包自上次构建以来未发生更改的情况。
此阶段报告的错误包括：不适当的依赖项、规则的无效输入，以及所有特定于规则的错误消息。
加载和分析阶段速度很快，因为 Bazel 会在此阶段避免不必要的文件 I/O，只读取 BUILD 文件以确定要执行的工作。这是设计使 Bazel 奠定了良好基础的分析工具， 例如 Bazel 的 query 命令，该命令是在加载作业之上实现的 阶段。
执行阶段
构建的第三个阶段也是最后一个阶段：执行。此阶段可确保 build 中每个步骤的输出与其输入一致，并根据需要重新运行编译/链接等工具。在这一步中 而对于大型电视而言， build。在此阶段报告的错误包括：缺少源文件、某个 build 操作执行的工具中存在错误，或工具未能生成预期的一组输出。