Bazel 构建事件协议(BEP)实战指南:事件图解析、NamedSetOfFiles 共享结构与消费端实现

原创2026-09-12 11:39:142,268 阅读
文章标签:构建工具开发工具

Bazel 构建事件协议(BEP)实战指南:事件图解析、NamedSetOfFiles 共享结构与消费端实现

导读:构建事件协议(Build Event Protocol,BEP)是 Bazel 面向第三方程序开放的一次构建调用的结构化"数字孪生",涵盖了构建与测试结果、进度、配置等信息。本文以 Bazel 官方 BEP 示例文档为主体,通过一个最小 sh_library/sh_test 工作区逐步剖析完整 BEP 事件图,深入讲解 NamedSetOfFiles 共享文件集合的设计动机与排序约束、Aspect 结果在 BEP 中的表达方式,并给出可直接落地的 Python 消费代码,帮助你理解 BEP 的底层原理并写出高效、无二次复杂度陷阱的 BEP 消费者。

从一个最小工作区理解 BEP 事件图

BEP 的完整规范定义在协议缓冲区(Protocol Buffer)定义文件中(见 build_event_stream.proto)。在查阅规范之前,先通过一个具体例子建立直觉。

考虑一个仅包含两个空 shell 脚本 foo.sh、foo_test.sh 以及如下 BUILD 文件的简单 Bazel 工作区:

sh_library(
    name = "foo_lib",
    srcs = ["foo.sh"],
)

sh_test(
    name = "foo_test",
    srcs = ["foo_test.sh"],
    deps = [":foo_lib"],
)

对该项目运行 bazel test ... 时,生成的事件流构成下图所示的构建事件图。图中箭头表示前文提到的父事件与子事件关系;为简洁起见,部分事件及大多数字段被省略。

BEP 事件图:以 BuildStarted 为根、覆盖 PatternExpanded、TargetConfigured、TargetComplete 等事件的完整事件层级

图 1. bazel test ... 的 BEP 事件图。

BuildStarted:一切事件的根

构建开始时,Bazel 首先发布一个 BuildStarted 事件。该事件告诉我们构建是通过 bazel test 命令发起的,并宣布了以下子事件:

  • OptionsParsed
  • WorkspaceStatus
  • CommandLine
  • UnstructuredCommandLine
  • BuildMetadata
  • BuildFinished
  • PatternExpanded
  • Progress

前三个事件(OptionsParsed、WorkspaceStatus、CommandLine)提供关于 Bazel 是如何被调用的信息。从 build_event_stream.proto 中可以看到,BuildStarted 的 payload 携带了命令名(command)、工作目录、工作区目录、服务器 PID、主机名与用户名等元数据;而 CommandLine 事件则进一步包含 "original"(Bazel 客户端收到的原始命令行)、"canonical"(展开 .rc 文件并应用调用策略后的有效命令行)与 "tool"(通过 --experimental_tool_command_line 注入的包装工具命令行)三种表示,详见 BEP 术语表。

PatternExpanded:模式展开的结果

PatternExpanded 事件揭示了 ... 模式具体展开到了哪些目标://foo:foo_lib 和 //foo:foo_test。它通过把两个 TargetConfigured 事件声明为自己的子事件来实现这一点。

值得注意的是,TargetConfigured 事件将 Configuration 事件声明为子事件,即使 Configuration 在 TargetConfigured 之前就已经发布。这印证了 BEP 的核心语义之一:父事件不必先于子事件发布。在 BEP 主文档 bep.mdx 中对此有明确说明:所有构建事件通过父子关系构成一张有向无环图(DAG),除首个事件外,每个事件都有至少一个父事件;而"所有事件必须由之前的某个事件宣布"是协议的基本保证。也就是说,事件在流中的物理发布顺序与其在图中的逻辑层级关系是解耦的。

事件间的第二种关联方式:按 ID 相互引用

除了父子关系,事件还可以通过构建事件标识符(build event identifier)互相引用。例如在图 1 中,TargetComplete 事件通过其 fileSets 字段引用 NamedSetOfFiles 事件。

这种引用机制建立在事件 ID 的唯一性之上:根据 build_event_stream.proto 中的注释,每个事件拥有一个 ID 与一组子事件 ID,除初始事件外,每个事件的 ID 都曾被某个更早的事件作为子 ID 提及;一次构建调用"完成"当且仅当初始事件的所有直接与间接子事件都已被发布。

NamedSetOfFiles:防止 BEP 输出体积二次膨胀的共享文件集合

引用文件的构建事件通常不会把文件名和路径直接内嵌在事件中。相反,它们携带一个 NamedSetOfFiles 事件的构建事件标识符,由后者承载真实的文件名与路径。

NamedSetOfFiles 事件允许一组文件只被报告一次、被多个目标反复引用。这种结构是必要的——否则在某些情况下,BEP 的输出体积会随文件数量二次方增长。设想一个大型构建:大量目标共享同一组头文件或资源文件,若每个目标都把完整文件列表内嵌在自己的事件里,事件流的总大小将迅速失控。

更进一步,一个 NamedSetOfFiles 事件甚至可以不完全内嵌所有文件,而是通过事件 ID 引用其他 NamedSetOfFiles 事件。这与 Starlark 中 Depset 的结构完全对应——NamedSetOfFiles 正是 depset 在 BEP 事件流中的投影,允许集合共享与嵌套组合。相关的底层定义见 build_event_stream.proto。

剖析一个真实的 TargetComplete 事件

下面是对上图 //foo:foo_lib 目标的 TargetComplete 事件实例,以 Protocol Buffer 的 JSON 表示打印。事件 ID 将目标作为不透明字符串包含在内,并通过其构建事件 ID 引用 Configuration 事件;该事件没有宣布任何子事件;payload 则包含目标是否成功构建、输出文件集合以及目标种类等信息。

{
  "id": {
    "targetCompleted": {
      "label": "//foo:foo_lib",
      "configuration": {
        "id": "544e39a7f0abdb3efdd29d675a48bc6a"
      }
    }
  },
  "completed": {
    "success": true,
    "outputGroup": [{
      "name": "default",
      "fileSets": [{
        "id": "0"
      }]
    }],
    "targetKind": "sh_library rule"
  }
}

逐字段解读:

  • id.targetCompleted.label:目标标签,作为不透明字符串使用;
  • id.targetCompleted.configuration.id:配置 ID。根据 proto 注释(build_event_stream.proto),消费者不应假设该 ID 有任何内部结构,也不应假设它跨事件流保持一致;特殊值 "none" 表示空配置(null configuration),用于不可配置的目标(如源文件);
  • completed.success:目标构建是否成功;
  • completed.outputGroup:目标请求的输出组列表,每个输出组(如 "default")通过 fileSets[].id 引用 NamedSetOfFiles 事件;
  • completed.targetKind:目标种类,例如 "sh_library rule"。

注意这里 fileSets<a href="https://link.gitcode.com/i/4f295bb0bc7072c6685e931e8920030b" target="_blank">].id 为 "0" —— 一个不透明字符串,仅在当前事件流实例内有效(见 [NamedSetOfFilesId 定义),跨构建没有任何可复用的含义。

Aspect 结果在 BEP 中的表达

普通构建只评估与 (target, configuration) 二元组关联的 action。当启用 aspects 构建时,Bazel 会额外评估与 (target, configuration, aspect) 三元组关联的目标——对每个受已启用 aspect 影响的目标都会如此。

尽管 BEP 没有专门的 aspect 专用事件类型,Aspect 的评估结果仍然完整可用:对于每个存在适用 aspect 的 (target, configuration) 二元组,Bazel 会额外发布一个承载"将该 aspect 应用到该目标"结果的 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"
      }]
    }]
  }
}

注意:普通事件与 aspect 事件 ID 之间的唯一区别是 aspect 字段的有无(TargetConfiguredId 与 TargetCompletedId 中均为可选字段,见 build_event_stream.proto 与 TargetCompletedId 定义)。因此,一个不检查 aspect ID 字段、仅按目标累计输出文件的工具,可能会把目标输出与 aspect 输出混为一谈。编写消费者时务必把 (target, configuration, aspect) 三元组作为一个整体键来处理。

高效消费 NamedSetOfFiles:避免二次复杂度算法

确定某个目标(或 aspect)产生的制品,是 BEP 最常见的用例之一,且通过少量准备工作即可高效完成。本节讨论 NamedSetOfFiles 事件提供的递归、共享结构——它与 Starlark Depset 的结构一致。

为什么必须警惕二次复杂度

消费者在遍历 NamedSetOfFiles 事件时必须小心避免二次复杂度的算法:大型构建可能包含数万个这样的事件,一个二次复杂度的遍历意味着数亿次操作。这正是 NamedSetOfFiles 引入共享机制的根本原因——复用集合引用而非复制文件列表,让消费端能够以近似线性的代价完成遍历。

NamedSetOfFiles 事件图:展示 named_set 事件被多个 target_completed 事件共享引用的结构

图 2. NamedSetOfFiles BEP 事件图。

排序约束:先于引用者出现

NamedSetOfFiles 事件在 BEP 流中的出现位置有一条重要规则:

一个 NamedSetOfFiles 事件总是出现在引用它的 TargetComplete 或 NamedSetOfFiles 事件之前。

这与"父子"事件关系正好相反——父子关系中,除首个事件外,所有事件都出现在至少一个宣布它的事件之后。而 NamedSetOfFiles 事件由一条无语义的 Progress 事件宣布。Progress 事件在 build_event_stream.proto 中的定义是"汇总构建到目前为止进度的事件的 payload",同时承担着"在逻辑父事件因信息尚不完整而无法发布时充当父事件"的职责——NamedSetOfFiles 正是这一职责的典型受益者。

结合排序与共享约束的典型消费模式

鉴于上述排序与共享约束,一个典型的消费者必须缓冲所有 NamedSetOfFiles 事件,直到 BEP 流耗尽,才能安全地解析引用。下面的 JSON 事件流示例与 Python 代码演示了如何构建从"目标/aspect"到"default 输出组内制品"的映射,以及如何处理已构建目标/aspect 子集的输出。

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)

该代码的关键设计点:

  1. 第一遍:建索引。named_sets 字典以集合 ID 为键缓冲所有 NamedSetOfFiles 事件;outputs 字典以 (label, configuration.id, aspect) 三元组为键,记录每个目标/aspect 的各输出组引用的文件集合 ID 列表。把 aspect 纳入键正是为了避免上一节提到的"目标输出与 aspect 输出混为一谈"的陷阱。
  2. 第二遍:惰性展开。仅对感兴趣的目标子集(relevant_subset 的结果)做展开;seen_sets 集合保证每个 NamedSetOfFiles 集合最多被访问一次——这是把共享结构从"二次复杂度"拉回"线性复杂度"的核心:即使多个目标引用同一个集合,该集合也只被展开一次,输出文件只会被 process_file 处理一次。

延伸阅读与工程落地

理解示例后,你可以进一步在工程中落地:

  • 如何消费 BEP 流:Bazel 支持 --build_event_binary_file(长度前缀分隔的二进制 protobuf,可用 parseDelimitedFrom(InputStream) 读取)、--build_event_text_file 与 --build_event_json_file 三种输出格式;也可以使用 --bes_backend=HOST:PORT 将事件推送到 gRPC 的 Build Event Service 端点(纯文本 gRPC 用 grpc:// 前缀,启用 TLS 用 grpcs://),详见 BEP 主文档。
  • 事件类型速查:BuildStarted、PatternExpanded、TargetConfigured、TargetComplete、TestResult、TestSummary、BuildFinished、BuildMetrics、Aborted 等每个事件类型的语义与 JSON 示例,见 BEP 术语表。
  • 协议底层定义:所有事件 ID 的 oneof 结构、payload 消息与字段注释,均可在 build_event_stream.proto 中查阅——它同时是本文所有 JSON 示例字段命名的权威出处。

把握住三条主线——父子关系与 ID 引用的双通道关联、NamedSetOfFiles 的共享与先行排序约束、以及以 (target, configuration, aspect) 为完整键的消费模型——你就能写出既正确又高效(近线性复杂度)的 BEP 消费者,为 IDE 插件、构建结果看板或 CI 集成提供可靠的构建洞察。

登录后查看全文
bazel