构建事件协议

报告问题 查看源代码 每夜 build · 7.4 .

通过构建事件协议 (BEP),第三方程序可以深入了解 Bazel 调用。例如,您可以使用 BEP 为 IDE 插件或显示构建结果的信息中心收集信息。

协议是一组基于其定义的语义的协议缓冲区消息。其中包含有关 build 和测试结果、build 进度、build 配置等方面的信息。BEP 旨在以编程方式使用,让解析 Bazel 的命令行输出成为过去式。

Build Event Protocol(构建事件协议)将有关构建的信息表示为事件。构建事件是协议缓冲区消息,由构建事件标识符、一组子事件标识符和载荷组成。

  • 构建事件标识符:它可能是不透明字符串,也可能是透露有关 build 事件的更多信息的结构化信息,具体取决于构建事件的类型。build 事件标识符在 build 内是唯一的。

  • 子项:构建事件可以通过在其子字段中添加其构建事件标识符来公布其他构建事件。例如,PatternExpanded build 事件会将其展开到的目标作为子目标进行通告。该协议可保证除第一个事件之外的所有事件都由上一个事件进行公布。

  • 载荷:载荷包含有关构建事件的结构化信息,以特定于该事件的协议缓冲区消息的形式编码。请注意,如果 build 过早终止,载荷可能不是预期类型,而是 Aborted 消息。

构建事件图

所有构建事件都通过其父级和子级关系形成一个有向无环图。除初始构建事件外,每个构建事件都有一个或多个父事件。请注意,子事件的所有父事件不一定都必须在子事件之前发布。构建完成(成功或失败)后,系统会发布所有已宣布的事件。如果发生 Bazel 崩溃或网络传输失败,某些已公布的构建事件可能永远无法发布。

事件图的结构反映了命令的生命周期。每个 BEP 图都具有以下特征形状:

  1. 根事件始终是 BuildStarted 事件。所有其他事件都是其后代。
  2. BuildStarted 事件的直接子项包含有关命令的元数据。
  3. 包含此命令生成的数据(如构建的文件和测试结果的文件)的事件会显示在 BuildFinished 事件之前。
  4. BuildFinished 事件之后可以跟着包含 build 摘要信息(例如指标或分析数据)的事件。

使用 Build Event Protocol

以二进制格式使用

如需以二进制格式使用 BEP,请执行以下操作:

  1. 通过指定 --build_event_binary_file=/path/to/file 选项,让 Bazel 将协议缓冲区消息序列化到某个文件。该文件将包含序列化协议缓冲区消息,其中每条消息用长度分隔。每条消息的前面都附加一个长度,该长度编码为可变长度整数。您可以使用 Protocol Buffer 库的 parseDelimitedFrom(InputStream) 方法读取此格式。

  2. 然后,编写一个程序,从序列化协议缓冲区消息中提取相关信息。

以文本或 JSON 格式使用

以下 Bazel 命令行标志将以文本和 JSON 等人类可读格式输出 BEP:

--build_event_text_file
--build_event_json_file

构建事件服务

Build Event Service 协议是一种用于发布 build 事件的通用 gRPC 服务。构建事件服务协议独立于 BEP,并将 BEP 事件视为不透明字节。Bazel 附带了构建事件服务协议的 gRPC 客户端实现,该协议用于发布构建事件协议事件。您可以使用 --bes_backend=HOST:PORT 标志指定要将事件发送到的端点。如果您的后端使用 gRPC,您必须在地址前面添加适当的架构:grpc:// 表示明文 gRPC,grpcs:// 表示启用了 TLS 的 gRPC。

构建事件服务标志

Bazel 有几个与 Build Event Service 协议相关的标志,包括:

  • --bes_backend
  • --[no]bes_best_effort
  • --[no]bes_lifecycle_events
  • --bes_results_url
  • --bes_timeout
  • --project_id

如需了解其中每个标志,请参阅命令行参考

身份验证和安全性

Bazel 的构建事件服务实现还支持身份验证和 TLS。 您可以使用以下标记控制这些设置。请注意,这些标志也用于 Bazel 的 Remote Execution。这意味着构建事件服务和 Remote Execution 端点需要共享相同的身份验证和 TLS 基础架构。

  • --[no]google_default_credentials
  • --google_credentials
  • --google_auth_scopes
  • --tls_certificate
  • --[no]tls_enabled

如需了解其中每个标志,请参阅命令行参考

构建事件服务和远程缓存

BEP 通常包含对日志文件(test.log、test.xml 等)的多个引用,这些文件存储在运行 Bazel 的机器上。远程 BES 服务器通常无法访问这些文件,因为它们位于不同的机器上。解决此问题的一种方法是将 Bazel 与远程缓存结合使用。Bazel 会将所有输出文件上传到远程缓存(包括 BEP 中引用的文件),然后 BES 服务器可以从缓存中提取引用的文件。

如需了解详情,请参阅 GitHub 问题 3689