从脚本调用 Bazel

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

您可以从脚本调用 Bazel,以执行构建、运行测试或查询依赖关系图。Bazel 旨在实现有效的脚本编写,但本部分列出了一些需要注意的细节,以便使脚本更加稳健。

选择输出基准

--output_base 选项用于控制 Bazel 进程应将 build 的输出写入到何处,以及 Bazel 在内部使用的各种工作文件,其中一个工作文件是一个锁,用于防止多个 Bazel 进程对输出基准进行并发变异。

为脚本选择正确的输出基目录取决于多个因素。如果您需要将 build 输出放置在特定位置,则需要使用相应的输出基准。如果您对 Bazel 进行“只读”调用(例如 bazel query),锁定因素将更为重要。特别是,如果您需要并发运行脚本的多个实例,请注意,每个 Blaze 服务器进程一次只能处理一个调用。根据您的具体情况,脚本的每个实例等待轮流是有意义的做法,也可以使用 --output_base 运行多个 Blaze 服务器并使用这些服务器。

如果您使用默认的输出基准值,则将与用户的 Interactive Bazel 命令争用同一锁。如果用户发出长时间运行的命令(如构建),您的脚本必须等待这些命令完成后才能继续操作。

关于服务器模式的注意事项

默认情况下,Bazel 使用长时间运行的服务器进程作为优化。在脚本中运行 Bazel 时,请务必在使用完服务器后调用 shutdown,或者指定 --max_idle_secs=5,以便闲置服务器立即关闭。

我将获得什么退出代码?

Bazel 会尝试区分因所考虑的源代码而导致的失败与导致 Bazel 无法正常执行的外部错误。Bazel 执行可能会导致以下退出代码:

所有命令通用的退出代码:

  • 0 - 成功
  • 2 - 命令行问题、标志或命令组合无效或不正确,或环境变量不正确。您必须修改命令行。
  • 8 - 构建中断,但我们已通过有序关闭方式终止。
  • 9 - 已持有服务器锁定,并且传递了 --noblock_for_lock
  • 32 - 此机器上不存在外部环境故障。

  • 33 - Bazel 内存不足并崩溃。您需要修改命令行。

  • 34 - 留给 Google 内部使用。

  • 35 - 留给 Google 内部使用。

  • 36 - 本地环境问题,疑似永久性问题。

  • 37 - 未处理的异常/内部 Bazel 错误。

  • 38 - 将结果发布到构建事件服务时出现暂时性错误。

  • 39 - 从远程缓存中逐出 Bazel 所需的 Blob。

  • 41-44 - 预留供 Google 内部使用。

  • 45 - 向 Build Event Service 发布结果时出现持续性错误。

  • 47 - 预留供 Google 内部使用。

  • 49 - 留给 Google 内部使用。

命令 bazel buildbazel test 的返回代码

  • 1 - 构建失败。
  • 3 - 构建成功,但部分测试失败或超时。
  • 4 - 构建成功,但即使请求了测试,也未找到任何测试。

对于 bazel run

  • 1 - 构建失败。
  • 如果构建成功,但已执行的子进程返回非零退出代码,则它也将是命令的退出代码。

对于 bazel query

  • 3 - 部分成功,但查询在输入 BUILD 文件集中遇到 1 个或多个错误,因此操作结果不是 100% 可靠。这可能是由于命令行中的 --keep_going 选项造成的。
  • 7 - 命令失败。

未来的 Bazel 版本可能会添加其他退出代码,将通用失败退出代码 1 替换为具有特定含义的其他非零值。不过,所有非零退出值始终会构成错误。

读取 .bazelrc 文件

默认情况下,Bazel 会从基本工作区目录或用户的主目录读取 .bazelrc 文件。是否需要这样做取决于您的脚本;如果您的脚本需要完全密封(例如在进行发布 build 时),您应使用 --bazelrc=/dev/null 选项停用对 .bazelrc 文件的读取。如果您想使用用户的首选设置进行构建,则默认行为更适合。

命令日志

命令日志文件中也提供了 Bazel 输出,您可以使用以下命令找到该文件:

bazel info command_log

命令日志文件包含最新 Bazel 命令的交错标准输出和标准错误流。请注意,运行 bazel info 会覆盖此文件的内容,因为它会成为最新的 Bazel 命令。不过,除非您更改 --output_base--output_user_root 选项的设置,否则命令日志文件的位置不会发生变化。

解析输出

Bazel 输出易于解析,可用于多种用途。以下两个选项可能对您的脚本很有帮助:用于抑制进度消息的 --noshow_progress,以及用于控制是否输出“build up-to-date”消息的 --show_result n;这些消息可以被解析,以便了解哪些目标成功构建,以及它们创建的输出文件的位置。如果您依赖这些消息,请务必指定一个非常大的 n 值。

通过性能分析排查性能问题

请参阅性能分析部分。