构建事件协议的完整规范可在其协议缓冲区定义中找到。不过,在查看规范之前建立一些直觉可能会有所帮助。
假设有一个简单的 Bazel 工作区,它由两个空的 Shell 脚本 foo.sh
和 foo_test.sh
以及以下 BUILD
文件组成:
sh_library(
name = "foo_lib",
srcs = ["foo.sh"],
)
sh_test(
name = "foo_test",
srcs = ["foo_test.sh"],
deps = [":foo_lib"],
)
对此项目运行 bazel test ...
时,生成的构建事件的构建图类似于下图。箭头表示上述父级和子级关系。请注意,为简洁起见,省略了某些构建事件和大多数字段。
图 1. BEP 图表。
最初,系统会发布 BuildStarted
事件。该事件会通知我们通过 bazel test
命令调用了构建,并公布子事件:
OptionsParsed
WorkspaceStatus
CommandLine
UnstructuredCommandLine
BuildMetadata
BuildFinished
PatternExpanded
Progress
前三个事件提供了 Bazel 调用方式的信息。
PatternExpanded
构建事件可让您深入了解 ...
模式扩展到了哪些特定目标://foo:foo_lib
和 //foo:foo_test
。为此,它会将两个 TargetConfigured
事件声明为子级。请注意,TargetConfigured
事件将 Configuration
事件声明为子事件,即使在 TargetConfigured
事件之前发布了 Configuration
。
除了父子关系与子关系外,事件还可使用其 build 事件标识符相互引用。例如,在上图中,TargetComplete
事件在其 fileSets
字段中引用了 NamedSetOfFiles
事件。
引用文件的构建事件通常不会在事件中嵌入文件名和路径。而是包含 NamedSetOfFiles
事件的 build 事件标识符,此标识符随后会包含实际的文件名和路径。NamedSetOfFiles
事件允许一组文件被报告一次并被多个目标引用。此结构很有必要,因为否则在某些情况下,构建事件协议的输出大小会随着文件数量成倍增加。此外,NamedSetOfFiles
事件也可能不嵌入其所有文件,而是通过其构建事件标识符引用其他 NamedSetOfFiles
事件。
以下是上图中 //foo:foo_lib
目标的 TargetComplete
事件实例,以协议缓冲区的 JSON 表示法输出。build 事件标识符以不透明字符串的形式包含目标,并使用其 build 事件标识符来引用 Configuration
事件。该事件不会公布任何子事件。载荷包含有关目标是否成功构建、输出文件集以及目标类型的信息。
{
"id": {
"targetCompleted": {
"label": "//foo:foo_lib",
"configuration": {
"id": "544e39a7f0abdb3efdd29d675a48bc6a"
}
}
},
"completed": {
"success": true,
"outputGroup": [{
"name": "default",
"fileSets": [{
"id": "0"
}]
}],
"targetKind": "sh_library rule"
}
}
BEP 中的方面结果
普通 build 会评估与 (target, configuration)
对关联的操作。在启用方面的情况下进行构建时,Bazel 还会针对受已启用的方面影响的每个目标,进一步评估与 (target, configuration,
aspect)
三元组关联的目标。
尽管没有特定于方面的事件类型,但 BEP 中提供了切面的评估结果。对于具有适用切面的每个 (target, configuration)
对,Bazel 会额外发布一个 TargetConfigured
和 TargetComplete
事件,其中包含将切面应用于目标时的结果。例如,如果使用 --aspects=aspects/myaspect.bzl%custom_aspect
构建 //:foo_lib
,此事件也会显示在 BEP 中:
{
"id": {
"targetCompleted": {
"label": "//foo:foo_lib",
"configuration": {
"id": "544e39a7f0abdb3efdd29d675a48bc6a"
},
"aspect": "aspects/myaspect.bzl%custom_aspect"
}
},
"completed": {
"success": true,
"outputGroup": [{
"name": "default",
"fileSets": [{
"id": "1"
}]
}]
}
}
消耗量:NamedSetOfFiles
确定给定目标(或切面)生成的工件是一个常见的 BEP 用例,只需进行一些准备即可高效地完成。本部分介绍了 NamedSetOfFiles
事件提供的递归共享结构,该结构与 Starlark Depset 的结构匹配。
在处理 NamedSetOfFiles
事件时,使用者必须注意避免使用二次算法,因为大型 build 可能包含数万个此类事件,在二次复杂性遍历中需要执行数亿次操作。
图 2. NamedSetOfFiles
BEP 图表。
NamedSetOfFiles
事件始终显示在 BEP 流中引用它的 TargetComplete
或 NamedSetOfFiles
事件之前。这与“父级-子级”事件关系相反,即除第一个事件外,所有其他事件都出现在至少一个播报该事件的事件之后。NamedSetOfFiles
事件由没有语义的 Progress
事件公布。
鉴于这些排序和共享约束,典型使用方必须缓冲所有 NamedSetOfFiles
事件,直到 BEP 流用尽。以下 JSON 事件流和 Python 代码演示了如何填充从目标/维度到“默认”输出组中已构建工件的映射,以及如何处理一部分已构建目标/维度的输出:
named_sets = {} # type: dict[str, NamedSetOfFiles]
outputs = {} # type: dict[str, dict[str, set[str]]]
for event in stream:
kind = event.id.WhichOneof("id")
if kind == "named_set":
named_sets[event.id.named_set.id] = event.named_set_of_files
elif kind == "target_completed":
tc = event.id.target_completed
target_id = (tc.label, tc.configuration.id, tc.aspect)
outputs[target_id] = {}
for group in event.completed.output_group:
outputs[target_id][group.name] = {fs.id for fs in group.file_sets}
for result_id in relevant_subset(outputs.keys()):
visit = outputs[result_id].get("default", [])
seen_sets = set(visit)
while visit:
set_name = visit.pop()
s = named_sets[set_name]
for f in s.files:
process_file(result_id, f)
for fs in s.file_sets:
if fs.id not in seen_sets:
visit.add(fs.id)
seen_sets.add(fs.id)