借助构建事件协议 (BEP),第三方程序可以深入了解 Bazel 调用。例如,您可以使用 BEP 收集 IDE 插件或显示构建结果的信息中心的信息。
协议是一组协议缓冲区消息,在其之上定义了一些语义。其中包含有关构建和测试结果、构建进度、构建配置等信息。BEP 旨在以编程方式使用,使解析 Bazel 的命令行输出成为过去式。
构建事件协议将有关构建的信息表示为事件。构建事件是一种协议缓冲区消息,由构建事件标识符、一组子事件标识符和载荷组成。
build 事件标识符:根据 build 事件的种类,它可能是不透明的字符串或能够显示相应 build 事件的更多详情的结构化信息。build 事件标识符在 build 中是唯一的。
子项:构建事件可以通过在其子字段中添加其他构建事件标识符来通告其他构建事件。例如,
PatternExpanded
构建事件会通告它作为子项展开的目标。协议可保证除第一个事件之外的所有事件均由先前事件公布。载荷:载荷包含有关构建事件的结构化信息,编码为特定于该事件的协议缓冲区消息。请注意,载荷可能不是预期类型,但如果构建提前中止,则可能是
Aborted
消息。
构建事件图表
所有构建事件都通过其父级和子级关系形成有向无环图。除初始构建事件外,每个构建事件都有一个或多个父事件。请注意,并非子事件的所有父事件都必须在子事件之前发布。当构建完成(成功或失败)时,系统会发布所有已公布的事件。如果 Bazel 崩溃或网络传输失败,一些已公布的构建事件可能永远无法发布。
事件图的结构反映了命令的生命周期。每个 BEP 图都具有以下特征形状:
- 根事件始终是
BuildStarted
事件。所有其他事件均为其后代事件。 - BuildStarted 事件的直接子项包含有关命令的元数据。
- 包含该命令生成的数据(例如构建的文件和测试结果)的事件显示在
BuildFinished
事件之前。 BuildFinished
事件可以后跟包含 build 摘要信息(例如指标或分析数据)的事件。
使用构建事件协议
以二进制格式使用
如需以二进制格式使用 BEP,请执行以下操作:
指定
--build_event_binary_file=/path/to/file
选项,让 Bazel 将协议缓冲区消息序列化为文件。该文件将包含序列化协议缓冲区消息,其中每条消息都以长度分隔。每条消息都以其长度为前缀,编码为可变长度整数。可以使用协议缓冲区库的parseDelimitedFrom(InputStream)
方法读取此格式。然后,编写一个程序,用于从序列化协议缓冲区消息中提取相关信息。
使用文本或 JSON 格式
以下 Bazel 命令行标志将以简单易懂的格式(例如文本和 JSON)输出 BEP:
--build_event_text_file
--build_event_json_file
构建事件服务
构建事件服务协议是一种用于发布构建事件的通用 gRPC 服务。构建事件服务协议独立于 BEP,并将 BEP 事件视为不透明字节。Bazel 附带有构建事件服务协议的 gRPC 客户端实现,以用于发布构建事件协议事件。用户可以使用 --bes_backend=HOST:PORT
标志指定要将事件发送到的端点。如果您的后端使用 gRPC,那么您必须为地址添加适当的前缀:grpc://
(对于明文 gRPC)和 grpcs://
(对于启用了 TLS 的 gRPC)。
构建事件服务标志
Bazel 有多个与构建事件服务协议相关的标志,包括:
--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 通常包含对运行 Bazel 的机器上存储的日志文件(test.log、test.xml 等)的许多引用。远程 BES 服务器通常无法访问这些文件,因为它们位于不同的机器上。如需解决此问题,可以将 Bazel 与远程缓存搭配使用。Bazel 会将所有输出文件上传到远程缓存(包括 BEP 中引用的文件),然后 BES 服务器可以从缓存中提取引用的文件。
如需了解详情,请参阅 GitHub 问题 3689。