Bazel Labels 全面解析：从规范形式到词法校验的权威指南

Bazel Labels 全面解析：从规范形式到词法校验的权威指南

【免费下载链接】bazela fast, scalable, multi-language and extensible build system项目地址: https://gitcode.com/GitHub_Trending/ba/bazel

导读

Label（标签）是 Bazel 中标识构建目标（target）的核心概念，无论是声明deps依赖、执行bazel build，还是编写BUILD文件，都离不开它。本文以 Bazel 官方文档《Labels》为骨架，结合本仓库（bazel 构建系统源码）中的标签解析与校验实现（src/main/java/com/google/devtools/build/lib/cmdline/LabelParser.java、LabelValidator.java），完整讲解 Label 的规范形式、缩写规则、词法限制、包名与目标名的边界，以及它在BUILD文件、查询语言和命令行中的实际用法。读完本文，你将能准确写出无歧义的 Label、避开跨包引用的常见陷阱，并理解 Bazel 为何要对 Label 字符集做如此严格的约束。

一、Label 是什么：目标的全局标识符

Label是 Bazel 中一个 target（构建目标）的标识符。一个典型的完整规范形式（full canonical form）的 Label 长这样：

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

它由三部分组成：

1.1 规范仓库名（Canonical Repo Name）与双@语法

Label 的第一部分是仓库名。双@语法（@@）表示这是一个canonical（规范）仓库名，在整个 workspace 内全局唯一。带有规范仓库名的 Label 无论出现在什么上下文中，都能无歧义地标识同一个目标，相关概念见 外部依赖总览。

不过，规范的仓库名往往是一串晦涩的字符串，例如：

@@rules_java++toolchains+local_jdk

这种名称由 Bzlmod 的模块解析机制生成，可读性差。因此实际代码中更常见的是带apparent（表面）仓库名的 Label，其唯一区别是仓库名前缀只有一个@：

@myrepo//my/app/main:app_binary

@myrepo是 apparent 名称，它可能因 Label 出现的上下文不同而指向不同的仓库。从源码结构看，Bazel 在解析阶段会同时区分这两类语法：LabelParser.java 中通过rawLabel.startsWith("@@")判断repoIsCanonical，从而决定后续按哪种语义解析仓库部分。

1.2 仓库名可以省略的情形

在典型场景下，Label 引用的就是它所在的同一个仓库，此时仓库名部分可以省略。例如在@@myrepo内部，第一个 Label 通常写作：

//my/app/main:app_binary

1.3 包名的两层含义：未限定包名与全限定包名

Label 的第二部分是未限定包名（un-qualified package name）my/app/main，即包相对于仓库根目录的路径。仓库名与未限定包名合在一起构成全限定包名（fully-qualified package name）：

@@myrepo//my/app/main

1.4 包名与冒号可以省略的情形

当 Label 引用的是它所在包内的目标时，包名（以及可选的冒号）都可以省略。因此在@@myrepo//my/app/main包内，下面两种写法等价：

app_binary :app_binary

按惯例，文件目标省略冒号、规则目标保留冒号，但这并非强制，冒号本身在语法上没有其他含义。

1.5 目标名与包路径末段重合时可以省略

冒号后面的app_binary是未限定目标名。当它恰好与包路径的最后一个组成部分同名时，目标名和冒号都可以省略。因此下面两个 Label 完全等价：

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

1.6 包内子目录中的文件目标

位于包内子目录中的文件目标，其名称是文件相对于包根目录（即包含BUILD文件的目录）的路径。例如下面的文件位于仓库的my/app/main/testdata子目录中（前提是my/app/main是一个包）：

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

二、//my/app的双重含义：包还是目标？

像//my/app和@@some_repo//my/app这样的字符串，在不同上下文中有两种含义：

• 当 Bazel期望一个 Label时，它们分别等价于//my/app:app和@@some_repo//my/app:app；
• 当 Bazel期望一个包名（例如在package_group规范中）时，它们引用的是包含该 Label 的那个包。

2.1 最常见的错误：用//my/app引用整个包

在BUILD文件中一个常见错误是：用//my/app来指代一个包，或者指代包内所有目标——它并不会这么做。请记住，//my/app等价于//my/app:app，它命名的是当前仓库my/app包中的app目标。

不过，在package_group的规范中，或在.bzl文件中，用//my/app指代包是被鼓励的写法，因为它能清楚地表达：包名是绝对的、以 workspace 顶层目录为根。

2.2 跨包引用必须使用完整路径

相对 Label 不能用于引用其他包中的目标；这种情况下必须始终给出仓库标识符和包名。

例如，假设源码树中同时存在包my/app和包my/app/testdata（这两个目录各有自己的BUILD文件），后者包含一个名为testdepot.zip的文件。下面是//my/app:BUILD中引用该文件的两种方式（一错一对）：

错误——testdata是另一个包，不能使用相对路径：

testdata/testdepot.zip

正确—— 使用完整路径引用testdata：

//my/app/testdata:testdepot.zip

2.3@@//引用主仓库：外部仓库也能用

以@@//开头的 Label 是对**主仓库（main repository）**的引用，即使从外部仓库中使用也依然有效。因此，从外部仓库引用时，@@//a/b/c与//a/b/c是不同的：

• @@//a/b/c指回主仓库；
• //a/b/c会在外部仓库自身内部查找//a/b/c。

这一点在编写「主仓库中的规则、但会被外部仓库使用」的场景下尤为重要——如果规则内引用主仓库目标时写成//a/b/c，一旦该规则被外部仓库引用，就会解析失败。

关于在命令行中指定构建目标的更多方式（目标模式 target patterns），见 build 命令的目标模式章节。

三、Label 的词法规范（Lexical Specification）

Label 语法刻意避免使用对 shell 有特殊含义的元字符。这有助于避免意外的引号问题，也让构造、操作 Label 的工具和脚本（例如 Bazel Query 语言）更加容易。

3.1 目标名规则 —package-name:target-name

target-name是目标在包内的名称：

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

目标名允许的字符集：a–z、A–Z、0–9，以及标点符号!%-@^_"#$&'()*+,;<=>?[]{|}~/.。

文件名的额外约束：文件名必须是正规形式的相对路径名，即：

• 不能以斜杠开头或结尾（例如/foo和foo/都是禁止的）；
• 不能包含连续多个斜杠作为路径分隔符（例如foo//bar被禁止）；
• 不能包含上级引用..或当前目录引用./。

错误—— 不要用..引用其他包中的文件：

../other_pkg/foo.cc

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

//other_pkg:foo.cc

斜杠的使用建议：文件目标名中经常使用/，但应尽量避免在规则名中使用/，尤其在用 Label 的缩写形式时容易让读者混淆。Label//foo/bar/wiz永远是//foo/bar/wiz:wiz的缩写，即使不存在foo/bar/wiz这个包也是如此；它永远不会指//foo:bar/wiz，即使该目标确实存在。

当然也存在必须用斜杠的场景：某些规则的名称必须与其主源文件同名，而该源文件可能位于包的子目录中（例如cc_library与同名头文件子目录的组合）。

源码级验证：目标名校验实现

从源码结构看，Bazel 在 LabelValidator.java 的validateTargetName中逐字符执行这些约束：

• 以/开头或结尾均报错；
• 以..、../、./开头的路径段分别被标记为 "up-level references" 或 "'.' as a path segment"；
• 循环中遇到/../、/./、//会立即返回对应错误；
• 控制字符（\u001f及以下）和\u007f（DEL）被明确拒绝，并给出\xXX十六进制提示；
• 未在允许集合内的字符统一报错target names may not contain '<c>'。

值得注意的是，ALWAYS_ALLOWED_TARGET_CHARACTERS还通过CharMatcher.inRange(128, 65535)放行了全部非 ASCII 字符（源码注释说明这与 Bazel 内部字符串与 Unicode 字符串的双编码兼容有关），因此非 ASCII 文件名在目标名中是允许的。

3.2 包名规则 —//package-name:target-name

包名是包含其BUILD文件的目录名，相对于所在仓库的顶层目录。例如：my/app。

技术层面的强制约束

Bazel 对包名施加以下硬性规则：

• 允许的字符：小写字母a–z、大写字母A–Z、数字0–9，以及字符! " # $ % & ' ( ) * + , - . ; < = > ? @ [ ] ^ _ ` { | }（注意其中包含一个空格字符！），当然还有正斜杠/（作为目录分隔符）。
• 不能以/开头或结尾。
• 不能包含子串//——否则对应的目录路径无法定义。
• 不能包含/./、/../、/.../等子串——这是为了避免在逻辑包名与物理目录名之间转换时，路径字符串中.的语义造成混淆。

源码 LabelValidator.java 的validatePackageName完整实现了上述规则：先用ALLOWED_CHARACTERS_IN_PACKAGE_NAME字符矩阵做整体校验，再从字符串尾部反向扫描，检测//连续分隔符与纯.路径段（PACKAGE_NAME_DOT_ERROR：package name component contains only '.' characters）。

实践层面的建议

• 对于目录结构对模块系统有意义的语言（例如 Java），务必选择在语言中合法的标识符作为目录名。例如：不要以数字开头，避免特殊字符，尤其是下划线和连字符（_、-），因为它们在 Java 包名中会有问题。
• 虽然 Bazel 支持 workspace 根包中的目标（例如//:foo），但最好让根包保持为空，这样所有有意义的包都有描述性的名称。

四、Rules（规则）与 Label 的关系

规则（rule）描述的是输入与输出之间的关系，以及构建输出的步骤。规则有很多种类（有时称为rule class），它们可以产出可执行文件与库、测试可执行文件等受支持的输出，详见本仓库的 构建百科全书式参考 所关联的规则体系。

BUILD文件通过调用规则（rules）来声明目标（targets）。

下面这个例子用cc_binary规则声明了目标my_app：

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

4.1name属性与属性类型

每次规则调用都必须有一个name属性（必须是合法的 目标名），它在BUILD文件所在的包内声明一个目标。

每条规则都有一组属性（attributes）。某条规则适用的属性，以及每个属性的意义和语义，取决于规则的种类（rule kind）。每个属性都有名称和类型，常见类型包括：

并非所有属性都需要在每条规则中指定。属性由此构成一个从键（名称）到可选、类型化值的字典。

许多规则都有的srcs属性类型是 "list of labels"；若给出，其值是一个 Label 列表，每个 Label 都是该规则输入目标的名称。

4.2 规则名何时重要

有些情况下规则种类（rule kind）的名称有些随意，更值得关注的是规则生成文件的名称——这正是 genrule 的情况（见 General Rules: genrule 相关说明）。而在另一些情况下名称至关重要：例如对*_binary和*_test规则，规则名直接决定了构建产出的可执行文件名。

4.3 目标图与查询工具

目标之间构成的这个有向无环图被称为目标图（target graph）或构建依赖图（build dependency graph），它是 Bazel Query 工具 作用的领域。理解 Label 的解析规则，是正确使用bazel query、bazel cquery与bazel build目标模式的前提。

五、延伸：Label 解析与命令行目标模式

5.1 解析器眼中的 Label 形态

从源码结构看，Bazel 的 LabelParser.java 将原始 Label 字符串拆解为repo（仓库名）、repoIsCanonical（是否双@）、pkgIsAbsolute（包部分是否以//开头）、pkg（包部分）、pkgEndsWithTripleDots（是否以...结尾）、target（目标部分）等字段。其内置的解析表覆盖了全部常见形态：

其中@foo被特殊处理为@foo//:foo的同义形式。这张表直观地印证了前文所述的省略规则：无仓库名、无//前缀、无冒号时，目标名就是整个字符串本身；只有//前缀时目标名默认取包路径的最后一段。

5.2 从 Label 到目标模式（Target Patterns）

Label 用于标识单个目标（例如在BUILD文件的依赖声明中），而 bazel build 等命令 接受的目标模式（target patterns）是 Label 语法的集合泛化，支持通配符。最简单的情形下，任何合法 Label 本身就是一个目标模式，它标识恰好一个目标的集合。常用模式包括：

不带//开头的目标模式相对于当前工作目录解析；:all是目标级通配符（匹配包内所有规则），...是包级通配符（递归匹配目录下所有包），二者可组合为foo/...:all并缩写为foo/...。另外:*（或:all-targets）匹配的是所有目标，包括不被任何规则正常构建的文件（如java_binary的_deploy.jar），因此:*是:all的超集。

六、常见误区速查

结语

Label 是 Bazel 世界的地基。理解其「仓库名 + 包名 + 目标名」的三段式结构、双@规范仓库名与单@表面仓库名的区别、各组成部分的省略时机，以及目标名与包名各自的字符集约束，能让你在编写BUILD文件、调试依赖解析、使用bazel query时少走大量弯路。本仓库中的 LabelValidator.java 与 LabelParser.java 是这些规则的权威实现，遇到模糊的边界情况时，直接查阅源码即是最可靠的答案。

【免费下载链接】bazela fast, scalable, multi-language and extensible build system项目地址: https://gitcode.com/GitHub_Trending/ba/bazel