标签

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

标签是目标的标识符。一个典型的标签(采用完整的规范形式)如下所示:

@@myrepo//my/app/main:app_binary

标签的第一部分是代码库名称 @@myrepo。双 @ 语法表示这是一个规范代码库名称,在工作区中是唯一的。带有规范代码库名称的标签可明确标识目标,无论它们出现在哪个上下文中。

规范代码库名称通常是类似于 @@rules_java++toolchains+local_jdk 的神秘字符串。更常见的是带有明显代码库名称的标签,如下所示:

@myrepo//my/app/main:app_binary

唯一的区别是,代码库名称的前缀是一个 @,而不是两个。这指的是名称为 myrepo 的代码库,该名称可能会因相应标签所在的上下文而异。

在标签引用与使用标签的代码位于同一代码库的典型情况下,可以省略代码库名称部分。因此,在 @@myrepo 中,第一个标签通常写为

//my/app/main:app_binary

标签的第二部分是不含限定符的软件包名称 my/app/main,即相对于代码库根目录的软件包路径。代码库名称和非限定的软件包名称共同构成完全限定的软件包名称 @@myrepo//my/app/main。如果标签是指其所用到的同一软件包,则可以省略软件包名称(以及可选的英文冒号)。因此,在 @@myrepo//my/app/main 内,此标签可以采用以下任一方式编写:

app_binary
:app_binary

按照惯例,文件会省略冒号,但规则会保留冒号,除此之外,冒号并无其他重要意义。

英文冒号后面的标签部分(即 app_binary)是不合格的目标名称。如果与软件包路径的最后一个组成部分匹配,则可以省略它和冒号。因此,这两个标签是等效的:

//my/app/lib
//my/app/lib:lib

软件包子目录中文件目标的名称是相对于软件包根目录(包含 BUILD 文件的目录)的文件路径。因此,此文件位于代码库的 my/app/main/testdata 子目录中:

//my/app/main:testdata/input.txt

//my/app@@some_repo//my/app 等字符串具有两种含义,具体取决于它们的使用环境:当 Bazel 需要标签时,它们分别表示 //my/app:app@@some_repo//my/app:app。但是,当 Bazel 需要软件包时(例如在 package_group 规范中),它们会引用包含相应标签的软件包。

BUILD 文件中一个常见的错误是使用 //my/app 来引用软件包或软件包中的所有目标,但实际上并非如此。请注意,它等同于 //my/app:app,因此它命名了当前代码库的 my/app 软件包中的 app 目标。

不过,在 package_group 的规范或 .bzl 文件中,建议使用 //my/app 来引用软件包,因为这样可以清楚地表明软件包名称是绝对的,并且位于工作区的顶级目录中。

相对标签不能用于引用其他软件包中的目标;在这种情况下,必须始终指定代码库标识符和软件包名称。例如,如果源树同时包含软件包 my/app 和软件包 my/app/testdata(这两个目录各自都有自己的 BUILD 文件),则后一个软件包包含一个名为 testdepot.zip 的文件。以下是在 //my/app:BUILD 中引用此文件的两种方式(一种错误,一种正确):

错误 - testdata 是不同的软件包,因此您无法使用相对路径

testdata/testdepot.zip

正确 - 引用 testdata 时使用完整路径

//my/app/testdata:testdepot.zip

@@// 开头的标签是对主代码库的引用,即使从外部代码库中引用,这些标签仍可正常使用。因此,从外部代码库引用时,@@//a/b/c//a/b/c 不同。前者会返回到主代码库,而后者会在外部代码库本身中查找 //a/b/c。当您在主代码库中编写引用主代码库中的目标,并将在外部代码库中使用的规则时,这一点尤其重要。

如需了解引用目标的不同方式,请参阅目标模式

标签的词汇规范

标签语法不鼓励使用对 shell 具有特殊含义的元字符。这有助于避免意外的引用问题,并更轻松地构建用于操纵标签的工具和脚本,例如 Bazel 查询语言

允许的目标名称的详细信息如下。

目标名称 - package-name:target-name

target-name 是软件包中目标的名称。规则的名称是 BUILD 文件中规则声明的 name 属性的值;文件的名称是其相对于包含 BUILD 文件的目录的路径名。

目标名称必须完全由以下字符组成:a-zA-Z0-9 以及标点符号 !%-@^_"#$&'()*-+,;<=>?[]{|}~/.

文件名必须是采用标准形式的相对路径名,这意味着它们既不能以斜杠开头也不能以斜杠结尾(例如,禁止使用 /foofoo/),也不能包含多个连续的斜杠作为路径分隔符(例如,禁止使用 foo//bar)。同样,禁止使用上级引用 (..) 和当前目录引用 (./)。

错误 - 请勿使用 .. 来引用其他软件包中的文件

正确 - 使用 //package-name:filename

虽然在文件目标的名称中使用 / 很常见,但应避免在规则的名称中使用 /。尤其是当使用标签的简写形式时,可能会让读者感到困惑。标签 //foo/bar/wiz 始终是 //foo/bar/wiz:wiz 的简写形式,即使没有此类软件包 foo/bar/wiz 也是如此;它绝不会引用 //foo:bar/wiz,即使该目标存在也是如此。

不过,在某些情况下,使用斜杠会很方便,有时甚至很有必要。例如,某些规则的名称必须与其主要源文件(可能位于软件包的子目录中)相符。

软件包名称 - //package-name:target-name

软件包的名称是包含其 BUILD 文件的目录的名称,相对于包含该软件包的代码库的顶级目录而言。例如:my/app

从技术层面来说,Bazel 会强制执行以下操作:

  • 软件包名称中允许使用的字符包括小写字母 az、大写字母 AZ、数字 09、字符 ! \"#$%&'()*+,-.;<=>?@[]^_`{|}(没错,这里有一个空格字符),当然还有正斜杠 /(因为它是目录分隔符)。
  • 软件包名称不得以正斜杠字符 / 开头或结尾。
  • 软件包名称不得包含子字符串 //。这毫无意义,因为相应的目录路径是什么?
  • 软件包名称不得包含子字符串 /.//..//.../ 等。之所以强制执行此规定,是为了避免在逻辑软件包名称和物理目录名称之间进行转换时出现混淆,因为点字符在路径字符串中具有语义含义。

从实际层面来说:

  • 对于目录结构对其模块系统具有重要意义的语言(例如 Java),选择在该语言中有效的标识符作为目录名称非常重要。例如,不要以数字开头,并避免使用特殊字符,尤其是下划线和连字符。
  • 虽然 Bazel 支持工作区根软件包中的目标(例如 //:foo),但最好将该软件包留空,以便所有有意义的软件包都具有描述性名称。

规则

规则用于指定输入与输出之间的关系,以及构建输出的步骤。规则可以有多种不同的类型(有时称为“规则类”),这些规则可以生成编译后的可执行文件和库、测试可执行文件以及其他受支持的输出,如构建百科全书中所述。

BUILD 文件通过调用规则来声明目标

在下面的示例中,我们看到使用 cc_binary 规则声明目标 my_app

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

每个规则调用都有一个 name 属性(必须是有效的目标名称),用于声明 BUILD 文件所在软件包中的目标。

每条规则都有一组属性;给定规则的适用属性以及每个属性的重要性和语义是规则类型的函数;如需查看规则及其相应属性的列表,请参阅build 百科全书。每个属性都有一个名称和一个类型。属性可具有的一些常见类型包括整数、标签、标签列表、字符串、字符串列表、输出标签、输出标签列表。并非所有属性都需要在每条规则中指定。因此,属性会形成一个从键(名称)到可选类型化值的字典。

许多规则中存在的 srcs 属性的类型为“标签列表”;如果存在,其值是一个标签列表,每个标签都是相应规则的输入目标名称。

在某些情况下,规则种类的名称有些随意,更有趣的是由规则生成的文件名,genrule 就是如此。如需了解详情,请参阅常规规则:genrule

在其他情况下,名称非常重要:例如,对于 *_binary*_test 规则,规则名称决定了 build 生成的可执行文件的名称。

这种以目标为节点的有向非循环图称为目标图构建依赖关系图,是 Bazel Query 工具运行的网域。

目标 BUILD 文件