前面部分简要地介绍了软件包、目标和标签以及 build 依赖关系图。本部分介绍了用于定义软件包的具体语法。
根据定义,每个软件包都包含一个 BUILD
文件,这是一个简短的程序。使用命令式语言 Starlark 评估 BUILD
文件。
它们被解释为语句的顺序列表。
一般来说,顺序很重要:例如,必须先定义变量,然后才能使用变量。不过,大多数 BUILD
文件仅包含构建规则的声明,这些语句的相对顺序无关紧要;重要的是在软件包评估完成之前声明了哪些规则以及声明了哪些值。
在执行构建规则函数(例如 cc_library
)时,它会在图中创建一个新目标。稍后可以使用标签来引用此目标。
在简单的 BUILD
文件中,规则声明可以随意重新排序,而无需更改行为。
为了促进代码和数据之间的完全分离,BUILD
文件不能包含函数定义、for
语句或 if
语句(但允许使用列表推导和 if
表达式)。可以改为在 .bzl
文件中声明函数。此外,BUILD
文件中不允许使用 *args
和 **kwargs
参数;而应明确列出所有参数。
至关重要的是,Starlark 中的程序无法执行任意 I/O。这种不变性使得 BUILD
文件的解释封闭,仅依赖于一组已知的输入,这对于确保 build 的可重现性至关重要。如需了解详情,请参阅密集性。
BUILD
文件应仅使用 ASCII 字符编写,尽管从技术层面来讲,它们使用 Latin-1 字符集解释。
由于每当底层代码的依赖项发生变化时,BUILD
文件都需要更新,因此它们通常由团队中的多人维护。BUILD
文件的作者应明确说明每个 build 目标的作用(无论其是否供公众使用),并记录软件包本身的角色。
加载扩展程序
Bazel 扩展程序是以 .bzl
结尾的文件。使用 load
语句从扩展程序导入符号。
load("//foo/bar:file.bzl", "some_library")
这段代码会加载 foo/bar/file.bzl
文件,并将 some_library
符号添加到环境中。此方法可用于加载新规则、函数或常量(例如字符串或列表)。您可以通过在调用 load
时使用额外参数导入多个符号。参数必须是字符串字面量(无变量),并且 load
语句必须出现在顶层 - 它们不能位于函数正文中。
load
的第一个参数是标识 .bzl
文件的标签。如果是相对标签,则会根据包含当前 bzl
文件的软件包(而非目录)解析该标签。load
语句中的相对标签应使用前导 :
。
load
还支持别名,因此您可以为导入的符号指定不同的名称。
load("//foo/bar:file.bzl", library_alias = "some_library")
您可以在一个 load
语句中定义多个别名。此外,参数列表可以同时包含别名和常规符号名称。以下示例完全合法(请注意何时使用引号)。
load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
在 .bzl
文件中,以 _
开头的符号不会被导出,无法从其他文件加载。
您可以使用加载可见性来限制谁可以加载 .bzl
文件。
构建规则的类型
大多数构建规则都有所属系列,并按语言分组。例如,cc_binary
、cc_library
和 cc_test
分别是 C++ 二进制文件、库和测试的构建规则。其他语言使用相同的命名方案,但前缀不同,例如 Java 的 java_*
就是如此。构建百科全书中记录了其中一些函数,但任何人都可以创建新规则。
*_binary
规则使用给定语言构建可执行程序。构建完成后,可执行文件会位于构建工具的二进制输出树中与规则标签对应的名称处,因此//my:program
会显示在(例如)$(BINDIR)/my/program
处。在某些语言中,此类规则还会创建一个 runfiles 目录,其中包含属于该规则的
data
属性中提及的所有文件,或其依赖项传递闭包中的任何规则;这组文件会集中在一起,以便于部署到生产环境。*_test
规则是*_binary
规则的特质,用于自动化测试。测试只是在成功时返回零的程序。与二进制文件一样,测试也有 runfiles 树,其下方的文件是测试在运行时可以合法打开的唯一文件。例如,程序
cc_test(name='x', data=['//foo:bar'])
可能会在执行期间打开并读取$TEST_SRCDIR/workspace/foo/bar
。(每种编程语言都有自己的实用函数来访问$TEST_SRCDIR
的值,但它们都等同于直接使用环境变量。)未能遵守规则将导致在远程测试主机上执行测试时失败。*_library
规则使用给定编程语言指定单独编译的模块。库可以依赖于其他库,而二进制文件和测试可以依赖于库,并且具有预期的单独编译行为。
标签 | 依赖项 |