构建事件协议

<ph type="x-smartling-placeholder"></ph> 报告问题 查看来源 敬上 每晚 · 7.3。 · 7.2 条 · 7.1。 · 7.0。 · 6.5

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

协议是一组协议 缓冲区中, 以其为基础定义的语义。其中包含有关构建和测试的信息 结果、构建进度、构建配置等信息。BEP 是 以编程方式使用,且解析 Bazel 的 命令行输出的旧内容。

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

  • 构建事件标识符:可能是 不透明 字符串结构化 信息 显示更多关于构建事件的信息构建事件标识符在 构建。

  • 子级:构建事件可能会通过以下方式公布其他构建事件: 子项的 子项中的 build 事件标识符 字段。 例如,PatternExpanded 构建事件会公布它扩展的目标 儿童。该协议可保证除第一个事件 事件都会通过上一个事件播报。

  • 载荷:载荷包含有关构建事件的结构化信息, 被编码为特定于该事件的协议缓冲区消息。请注意, 载荷可能不是预期的类型,但可能是 Aborted 消息 则会发生此错误

构建事件图

所有构建事件均通过其父级和子级形成有向无环图 关系。除初始构建事件外,每个构建事件都有一个或 更多父事件。请注意,并非子活动的所有父活动都必须 必须在此之前发布构建完成(成功或失败) 所有公布的活动都会发布。如果 Bazel 崩溃或失败 某些已公布的构建事件可能永远无法发布。

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

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

使用 Build Event Protocol

以二进制格式使用

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

  1. 让 Bazel 将协议缓冲区消息序列化为一个文件,方法是指定 选项 --build_event_binary_file=/path/to/file。该文件将包含 序列化协议缓冲区消息,每条消息用长度分隔。 每条消息都以其长度为前缀,编码为可变长度的整数。 可以使用协议缓冲区库的 parseDelimitedFrom(InputStream) 方法。

  2. 然后,编写一个程序,用于从 序列化协议缓冲区消息。

以文本或 JSON 格式使用

以下 Bazel 命令行标志将以 人类可读的格式,例如文本和 JSON:

--build_event_text_file
--build_event_json_file

构建事件服务

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

构建事件服务标志

Bazel 有多个与构建事件服务协议相关的标志,包括:

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

有关上述每个标志的说明,请参阅 命令行参考

身份验证和安全性

Bazel 的“Build Event Service”实现还支持身份验证和 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