Bazel 教程：构建 C++ 项目

报告问题 查看来源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

简介

初次使用 Bazel？您来对地方了。请按照“首次构建”教程操作，以简要了解如何使用 Bazel。本教程定义了 Bazel 上下文中使用的关键术语，并介绍了 Bazel 工作流程的基础知识。从所需工具开始，您将构建并运行三个复杂度不断增加的项目，并了解这些项目为何以及如何变得更加复杂。

虽然 Bazel 是一个支持多语言构建的构建系统，但本教程以 C++ 项目为例，并提供适用于大多数语言的常规指南和流程。

预计完成时间：30 分钟。

前提条件

首先安装 Bazel（如果您尚未安装）。本教程使用 Git 进行源代码控制，因此为获得最佳效果，请同时安装 Git。

接下来，在您选择的命令行工具中运行以下命令，从 Bazel 的 GitHub 代码库中检索示例项目：

git clone https://github.com/bazelbuild/examples

本教程的示例项目位于 examples/cpp-tutorial 目录中。

请参阅下文，了解其结构：

examples
└── cpp-tutorial
    ├──stage1
    │  ├── main
    │  │   ├── BUILD
    │  │   └── hello-world.cc
    │  └── WORKSPACE
    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── WORKSPACE
    └──stage3
       ├── main
       │   ├── BUILD
       │   ├── hello-world.cc
       │   ├── hello-greet.cc
       │   └── hello-greet.h
       ├── lib
       │   ├── BUILD
       │   ├── hello-time.cc
       │   └── hello-time.h
       └── WORKSPACE

有三组文件，每组文件代表本教程中的一个阶段。在第一阶段，您将构建一个位于单个软件包中的单个目标。在第二阶段，您将从单个软件包构建二进制文件和库。在第三个也是最后一个阶段，您将构建一个包含多个软件包的项目，并使用多个目标进行构建。

总结：简介

通过安装 Bazel（和 Git）并克隆本教程的代码库，您已为使用 Bazel 进行首次构建奠定了基础。请继续阅读下一部分，了解一些术语并设置您的工作区。

使用入门

设置工作区

在构建项目之前，您需要设置其工作区。工作区是一个目录，其中包含项目的源文件和 Bazel 的 build 输出。它还包含以下重要文件：

• WORKSPACE file ，用于将目录及其内容标识为 Bazel 工作区，位于项目目录结构的根目录中。
• 一个或多个 BUILD files ，用于告知 Bazel 如何构建项目的不同部分。工作区内包含 BUILD 文件的目录是一个软件包。（本教程稍后会详细介绍软件包。）

在未来的项目中，如需将某个目录指定为 Bazel 工作区，请在该目录中创建一个名为 WORKSPACE 的空文件。在本教程中，每个阶段都已存在一个 WORKSPACE 文件。

注意：当 Bazel 构建项目时，所有输入都必须位于同一工作区中。除非链接在一起，否则位于不同工作区中的文件彼此独立。如需详细了解工作区规则，请参阅本指南。

了解 BUILD 文件

BUILD 文件包含针对 Bazel 的多种不同类型的指令。每个 BUILD 文件都需要至少一条 规则作为一组指令，用于告知 Bazel 如何构建所需的输出，例如可执行二进制文件或库。BUILD 文件中 build 规则的每个实例都称为目标，并指向一组特定的源文件和依赖项。一个目标也可以指向其他目标。

查看 cpp-tutorial/stage1/main 目录中的 BUILD 文件：

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)

在我们的示例中，hello-world 目标会实例化 Bazel 的内置 cc_binary rule。 该规则指示 Bazel 从不含任何依赖项的 hello-world.cc 源文件构建一个独立的执行二进制文件。

总结：入门

现在，您已经熟悉了一些关键术语，以及它们在此项目和 Bazel 中的一般含义。在下一部分中，您将构建并测试项目的第 1 阶段。

阶段 1：单个目标，单个软件包

现在，我们来构建项目的第一部分。为了便于直观参考，项目第 1 阶段部分的结构如下：

examples
└── cpp-tutorial
    └──stage1
       ├── main
       │   ├── BUILD
       │   └── hello-world.cc
       └── WORKSPACE

运行以下命令以移至 cpp-tutorial/stage1 目录：

cd cpp-tutorial/stage1

然后运行：

bazel build //main:hello-world

在目标标签中，//main: 部分是 BUILD 文件相对于工作区根目录的位置，而 hello-world 是 BUILD 文件中的目标名称。

Bazel 会生成如下所示的内容：

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.267s, Critical Path: 0.25s

您刚刚构建了第一个 Bazel 目标。Bazel 会将 build 输出放置在工作区根目录的 bazel-bin 目录中。

现在，测试您刚刚构建的二进制文件，即：

bazel-bin/main/hello-world

这会输出“Hello world”消息。

以下是阶段 1 的依赖关系图：

总结：第 1 阶段

现在，您已完成第一个 build，对 build 的结构有了基本的了解。在下一阶段，您将添加另一个目标，从而增加复杂性。

第 2 阶段：多个 build 目标

虽然单个目标足以满足小型项目的需求，但您可能需要将大型项目拆分为多个目标和软件包。这样一来，Bazel 就可以快速进行增量构建（即仅重新构建已更改的内容），并通过同时构建项目的多个部分来加快构建速度。本教程的这一阶段会添加一个目标，下一阶段会添加一个软件包。

这是您在第 2 阶段中使用的目录：

    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── WORKSPACE

请查看以下 cpp-tutorial/stage2/main 目录中的 BUILD 文件：

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
    ],
)

借助此 BUILD 文件，Bazel 首先构建 hello-greet 库（使用 Bazel 的内置 cc_library rule），然后构建 hello-world 二进制文件。hello-world 目标中的 deps 属性会告知 Bazel，构建 hello-world 二进制文件需要 hello-greet 库。

在构建此项目的新版本之前，您需要通过运行以下命令来更改目录，切换到 cpp-tutorial/stage2 目录：

cd ../stage2

现在，您可以使用以下熟悉的命令构建新的二进制文件：

bazel build //main:hello-world

Bazel 再次生成了如下所示的内容：

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.399s, Critical Path: 0.30s

现在，您可以测试刚刚构建的二进制文件，该文件会返回另一个“Hello world”：

bazel-bin/main/hello-world

如果您现在修改 hello-greet.cc 并重新构建项目，Bazel 只会重新编译该文件。

查看依赖关系图，您可以看到 hello-world 依赖于名为 hello-greet 的额外输入：

总结：第 2 阶段

您现在已构建包含两个目标的项目。hello-world 目标会构建一个源文件，并依赖于另一个目标 (//main:hello-greet)，后者会构建另外两个源文件。在下一部分中，我们将更进一步，添加另一个软件包。

第 3 阶段：多个软件包

下一个阶段会增加复杂性，并构建一个包含多个软件包的项目。请查看下方的 cpp-tutorial/stage3 目录的结构和内容：

└──stage3
   ├── main
   │   ├── BUILD
   │   ├── hello-world.cc
   │   ├── hello-greet.cc
   │   └── hello-greet.h
   ├── lib
   │   ├── BUILD
   │   ├── hello-time.cc
   │   └── hello-time.h
   └── WORKSPACE

您可以看到，现在有两个子目录，每个子目录都包含一个 BUILD 文件。因此，对于 Bazel 而言，工作区现在包含两个软件包：lib 和 main。

查看 lib/BUILD 文件：

cc_library(
    name = "hello-time",
    srcs = ["hello-time.cc"],
    hdrs = ["hello-time.h"],
    visibility = ["//main:__pkg__"],
)

在 main/BUILD 文件中：

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
        "//lib:hello-time",
    ],
)

主软件包中的 hello-world 目标依赖于 lib 软件包中的 hello-time 目标（因此目标标签为 //lib:hello-time）- Bazel 通过 deps 属性了解这一点。这体现在依赖关系图中：

为了使 build 成功，您可以使用 visibility 属性使 lib/BUILD 中的 //lib:hello-time 目标明确显示在 main/BUILD 的目标中。这是因为默认情况下，目标仅对同一 BUILD 文件中的其他目标可见。Bazel 使用目标可见性来防止出现以下问题：包含实现细节的库泄露到公共 API 中。

现在构建此项目的最终版本。运行以下命令，切换到 cpp-tutorial/stage3 目录：

cd  ../stage3

再次运行以下命令：

bazel build //main:hello-world

Bazel 会生成如下所示的内容：

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 0.167s, Critical Path: 0.00s

现在，测试本教程的最后一个二进制文件，以查看最终的 Hello world 消息：

bazel-bin/main/hello-world

总结：第 3 阶段

您现在已将项目构建为包含三个目标的两个软件包，并且了解了它们之间的依赖关系，这让您能够继续使用 Bazel 构建未来的项目。在下一部分中，了解如何继续您的 Bazel 之旅。

后续步骤

您现在已使用 Bazel 完成了第一个基本 build，但这只是一个开始。以下是一些其他资源，可帮助您继续学习 Bazel：

• 如需继续专注于 C++，请了解常见的 C++ build 使用场景。
• 如需开始使用 Bazel 构建其他应用，请参阅 Java、Android 应用或 iOS 应用的相关教程。
• 如需详细了解如何使用本地和远程代码库，请参阅外部依赖项。
• 如需详细了解 Bazel 的其他规则，请参阅此参考指南。

祝您构建顺利！