原文:Writing Bazel rules: library rule, depsets, providers
作者:Jay Conrod,曾在 Google 的 Go 团队工作,现就职于 EngFlow。
原文发表于 2018-08-15,更新于 2025-09-08。
译注:文中的“我”指原作者。版本号和工具行为保留原文发表或更新时的语境,示例代码与技术术语保留原样。
Writing Bazel rules 系列:
- 编写 Bazel rules(一):simple binary rule
- 编写 Bazel rules(二):library rule、depset 和 provider
- 编写 Bazel rules(三):data 和 runfiles
- 编写 Bazel rules(四):将逻辑移到 execution phase
- 编写 Bazel rules(五):repository rules
- 编写 Bazel rules(六):platform 和 toolchain
- 编写 Bazel rules(七):module extensions
上一篇文章编写了一个 go_binary rule,用一组源文件编译并链接出 Go executable。这次我们来定义 go_library rule,用它编译一个可供其他 library 和 binary 依赖的 Go package。
本文关注 rule 之间如何传递信息,建立可供 linker 或类似 linking action 使用的 dependency graph。全部代码都来自 rules_go_simple 的 v2 branch。
和上次一样,不懂 Go 也不影响理解。我只是比较喜欢用 Go,所以拿它举例。
背景知识
看代码之前,先介绍三个重要概念:struct、provider 和 depset。它们是 rule 之间传递信息所用的数据结构,收集依赖信息时会用到。
Struct
Struct 值是一个由 key-value pair 组成的 dictionary,有点像 Python 或 JavaScript 中的 object。虽然 struct 是一种基本数据结构,但它由 Bazel 提供,严格来说并不属于 Starlark 语言本身。调用 struct 函数可以创建一个 struct 值:
my_value = struct(
foo = 12,
bar = 34,
)
访问 struct 的 field,与访问 Python object 的 field 写法相同。
print(my_value.foo + my_value.bar)
dir 函数可以列出 struct 的 field name。getattr 和 hasattr 的行为也和预期一样,不过,attribute 设置后就不能修改或删除,因为 struct 值是 immutable 的。可以用 json.encode 和 json.decode 在 struct 或其他值与 JSON 之间转换。
Provider
provider 是一种有名称的 struct type,用来传递 rule 的信息。Rule 的 implementation function 求值后会返回 provider struct。依赖这个 rule 的其他 rule 可以读取它返回的 provider。上一篇中,go_binary 返回了 DefaultInfo,它是 built-in providers 之一。本文会定义 GoLibraryInfo provider,用来携带 library 的 metadata。
调用 provider 函数可以定义新的 provider。
MyProvider = provider(
doc = "My custom provider",
fields = {
"foo": "A foo value",
"bar": "A bar value",
},
)
创建 provider 值的方式与创建 struct 值相同:
my_provider = MyProvider(foo = 12, bar = 34)
Depset
Bazel 提供了一种专门的数据结构,叫作 depset。和其他 set 一样,depset 中的值都是唯一的。它的特别之处在于合并速度快,而且 iteration order 有明确的定义。
Depset 通常用于在大型 dependency graph 中汇总源文件、header file 等信息。Dependency graph 可能包含数十万个节点,因此所有 depset 操作的时间和空间开销都保持在线性范围内很重要。本文会用 depset 汇总 Go 依赖的信息,包括 import path 和编译后的文件名。Linker 可以直接使用这些信息,不需要让 go_binary 显式列出所有 transitive dependencies。
一个 depset 由 direct element 列表、transitive depset child 列表,以及 iteration order 组成。

构造 depset 很快,因为只需要创建一个持有 direct list 和 transitive list 的对象。时间复杂度为 O(D+T),其中 D 是 direct list 中的元素数量,T 是 transitive child 的数量。Bazel 构造 set 时会对两个列表中的元素去重。遍历 depset 或将它转换为 list 的时间复杂度是 O(n),其中 n 是这个 set 及其所有 child 中的元素总数,包含重复项。
定义 go_library
GoLibraryInfo provider
原理讲完了,接下来看代码。
首先定义一个新的 provider。GoLibraryInfo 携带每个 library 及其依赖的信息,定义在新文件 providers.bzl 中。
GoLibraryInfo = provider(
doc = "Contains information about a Go library",
fields = {
"info": """A struct containing information about this library.
Has the following fields:
importpath: Name by which the library may be imported.
archive: The .a file compiled from the library's sources.
""",
"deps": "A depset of info structs for this library's dependencies",
},
)
doc 为 Stardoc 设置 documentation string。fields 列出 provider 允许使用的 field 及其 documentation string。还可以给 init 传入自定义 constructor function;需要更复杂的 validation 或 initialization 时,这可能很有用。详情见 provider。
go_library rule
现在可以定义 go_library rule 了。下面是 rules.bzl 中新增的 rule 声明。
go_library = rule(
implementation = _go_library_impl,
attrs = {
"srcs": attr.label_list(
allow_files = [".go"],
doc = "Source files to compile",
),
"deps": attr.label_list(
providers = [GoLibraryInfo],
doc = "Direct dependencies of the library",
),
"importpath": attr.string(
mandatory = True,
doc = "Name by which the library may be imported",
),
"_stdlib": attr.label(
allow_single_file = True,
default = "//internal:stdlib",
doc = "Hidden dependency on the Go standard library",
),
},
doc = "Compiles a Go archive from Go sources and dependencies",
)
这里有四个 attribute。srcs 是一组 label,指向 .go 源文件或生成 .go 文件的 rule。deps 也是一组 label,指向其他 Go library rule。它们不一定非得是 go_library,但必须返回 GoLibraryInfo provider 才能兼容。importpath 是一个 string,用来生成 compiler 和 linker 使用的 importcfg 文件,将 import string 映射到编译后的 .a 文件。最后,_stdlib 和 go_binary 中的一样,是对编译后 standard library 的 hidden dependency,名称以 _ 开头。
下面是这个 rule 的 implementation。
def _go_library_impl(ctx):
# Declare an output file for the library package and compile it from srcs.
archive = ctx.actions.declare_file("{name}.a".format(name = ctx.label.name))
go_compile(
ctx,
srcs = ctx.files.srcs,
importpath = ctx.attr.importpath,
stdlib = ctx.file._stdlib,
deps = [dep[GoLibraryInfo] for dep in ctx.attr.deps],
out = archive,
)
# Return the output file and metadata about the library.
return [
DefaultInfo(files = depset([archive])),
GoLibraryInfo(
info = struct(
importpath = ctx.attr.importpath,
archive = archive,
),
deps = depset(
direct = [dep[GoLibraryInfo].info for dep in ctx.attr.deps],
transitive = [dep[GoLibraryInfo].deps for dep in ctx.attr.deps],
),
),
]
首先调用 ctx.actions.declare_file 声明编译输出文件,再用 go_compile 声明 compile command。这和 go_binary 中的做法相同。
留意这里访问 attribute 的几种不同方式。
ctx.files.srcs 返回 srcs attribute 对应的所有文件。这个列表的长度不一定等于传给 srcs 的 label 数量;例如,其中某个 label 可能指向一个 filegroup,里面可以包含任意数量的文件。
ctx.attr.importpath 返回一个 string 值,因为 importpath 是 string attribute。
ctx.file._stdlib 返回 _stdlib 对应的单个 File,实际上是一个目录。之所以可以这样访问,是因为声明时设置了 allow_single_file = True。
ctx.attr.deps 返回一组 Target。下标表达式 dep[GoLibraryInfo] 取得这个 target 返回的 GoLibraryInfo provider。
最后,返回一个包含两个 provider 的列表,分别是 DefaultInfo 和 GoLibraryInfo。GoLibraryInfo.info field 是一个 struct,包含正在编译的 library 的信息。这个 struct 必须是 immutable 的,而且要相对小一些,因为它会被加入其他 library 的 GoLibraryInfo.deps depset,并参与 hashing。
go_compile 和 go_link
go_compile 和 go_link 有一个重要变化,你注意到了吗?它们现在都接收 deps 参数,内容是 direct dependency 的 GoLibraryInfo provider 列表。两者都用这个列表生成 importcfg 文件。Go compiler 和 linker 通过 importcfg 文件,将 import string 映射到编译后的 .a 文件。
对于 go_compile,importcfg 文件只需要列出 direct dependencies,所以内容可以这样生成:
dep_importcfg_text = "\n".join([
"packagefile {importpath}={filepath}".format(
importpath = dep.info.importpath,
filepath = dep.info.archive.path,
)
for dep in deps
])
对于 go_link,importcfg 文件需要包含所有 transitive dependencies,因此要先构造一个 depset,再遍历它。这就是我们需要 GoLibraryInfo.deps 的原因。
deps_set = depset(
direct = [d.info for d in deps],
transitive = [d.deps for d in deps],
)
dep_importcfg_text = "\n".join([
"packagefile {importpath}={filepath}".format(
importpath = dep.importpath,
filepath = dep.archive.path,
)
for dep in deps_set.to_list()
])
这些内容最终会被插入一段 Bash script。那段脚本既不好看,也与编写其他语言的 rule 无关,这里就不展开了。后面的文章会把它整理干净。
go_binary 还有一处变化:现在有了 deps attribute,并在调用 go_link 时传入这些 target 返回的 GoLibraryInfo provider。与上一版相比,改动很小,所以这里不再贴完整源码。
暴露 public interface
所有定义都在 internal 目录中,需要让其他人能够使用。因此,我们在只包含 public definition 的 def.bzl 中加载它们,同时暴露 go_library 和 GoLibraryInfo。想实现兼容 rule 的人也会用到后者。
load(
"//internal:rules.bzl",
_go_binary = "go_binary",
_go_library = "go_library",
)
load(
"//internal:providers.bzl",
_GoLibraryInfo = "GoLibraryInfo",
)
go_binary = _go_binary
go_library = _go_library
GoLibraryInfo = _GoLibraryInfo
测试 go_library rule
新功能仍然沿用上次的测试方法:用 sh_test 运行一个使用新功能构建出来的 go_binary。
sh_test(
name = "bin_with_libs_test",
srcs = ["bin_with_libs_test.sh"],
args = ["$(rootpath :bin_with_libs)"],
data = [":bin_with_libs"],
)
go_binary(
name = "bin_with_libs",
srcs = ["bin_with_libs.go"],
deps = [":foo"],
)
go_library(
name = "foo",
srcs = ["foo.go"],
importpath = "rules_go_simple/tests/foo",
deps = [
":bar",
":baz",
],
)
go_library(
name = "bar",
srcs = ["bar.go"],
importpath = "rules_go_simple/tests/bar",
deps = [":baz"],
)
go_library(
name = "baz",
srcs = ["baz.go"],
importpath = "rules_go_simple/tests/baz",
)
运行 bazel test //tests/... 就能试一试。