本页面假定您熟悉 Bazel,并提供了有关如何构建项目以充分利用 Bazel 功能的准则和建议。
总体目标如下:
- 使用精细依赖项允许并行性和增量。
- 确保依赖项保持良好封装。
- 确保代码结构良好且可测试。
- 创建易于理解和维护的 build 配置。
这些准则并非强制性要求:只有少数项目能够遵守所有准则。正如 lint 的手册页面所说:“将对第一个人显示一项特别奖励,让其生成通过严格检查不会产生任何错误的真实程序。”不过,纳入尽可能多的这些原则应该使项目更易读、不易出错且构建速度更快。
本页面使用了此 RFC 中所述的要求级别。
运行构建和测试
项目应始终能够在其稳定分支上成功运行 bazel build //...
和 bazel test //...
。必要但不在特定条件下(例如,需要特定 build 标志、无需在特定平台上构建、需要许可协议)构建的目标应尽可能有针对性地进行标记(例如“requires-osx
”)。与使用“人工”标记相比,这种标记可让目标进行更精细的过滤,并且可让他人通过检查 BUILD
文件来了解目标的局限性。
第三方依赖项
您可以声明第三方依赖项:
- 请在
WORKSPACE
文件中将其声明为远程代码库。 - 或者,将它们放在工作区目录下名为
third_party/
的目录中。
具体取决于二进制文件
应尽可能从源代码构建所有内容。这通常意味着,您应该创建一个 BUILD
文件并根据其源代码构建 some-library.so
,然后依赖于该目标,而不是依赖于某个库 some-library.so
。
始终从源代码构建可确保 build 使用的库不是使用不兼容的标志或其他架构构建的。此外,还有其他一些功能,例如覆盖率、静态分析或动态分析,这些功能仅适用于来源。
版本控制
最好尽可能从头构建代码。如果必须使用版本,请避免在目标名称中包含版本(例如,//guava
,而不是 //guava-20.0
)。这种命名方式使库更易于更新(只需更新一个目标)。这种方式也更能有效应对依赖项问题:如果一个库依赖于 guava-19.0
,而另一个库依赖于 guava-20.0
,那么您最终得到的库可能会尝试依赖于两个不同的版本。如果您创建了误导性别名,将两个目标都指向一个 guava
库,则 BUILD
文件会造成误导。
使用 .bazelrc
文件
如需了解项目特定选项,请使用配置文件 workspace/.bazelrc
(请参阅 bazelrc 格式)。
如果您希望为项目支持按用户控制的方案,但不想签入源代码控制系统,请添加以下行:
try-import %workspace%/user.bazelrc
(或其他任何文件名)添加到 workspace/.bazelrc
,并将 user.bazelrc
添加到 .gitignore
。
软件包
每个包含可构建文件的目录都应该是一个软件包。如果 BUILD
文件引用了子目录中的文件(例如 srcs = ["a/b/C.java"]
),则表示应将 BUILD
文件添加到该子目录中。此结构存在的时间越长,无意中创建的循环依赖项就越多,目标范围也会逐渐扩大,并且必须更新越来越多的反向依赖项。