简介
初次使用 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 输出。它还包含以下重要文件:
,用于将目录及其内容标识为 Bazel 工作区,位于项目目录结构的根目录中。WORKSPACE
file- 一个或多个
,用于告知 Bazel 如何构建项目的不同部分。工作区内包含BUILD
filesBUILD
文件的目录是一个软件包。(本教程稍后会详细介绍软件包。)
在未来的项目中,如需将某个目录指定为 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 的其他规则,请参阅此参考指南。
祝您构建顺利!