创建永久性工作器

持久性工作器可让您的构建速度更快。如果您在构建中有重复的操作,这些操作具有较高的启动成本或受益于交叉操作缓存,则可能需要实现自己的持久性 worker 来执行这些操作。

Bazel 服务器使用 stdin/stdout 与 worker 进行通信。它支持使用协议缓冲区或 JSON 字符串。

worker 实现包含两个部分:

创建 Worker

永久性磁盘需要满足几项要求:

  • 它会从其 stdin 中读取 WorkRequests
  • 它会将 WorkResponses(且仅 WorkResponse)写入其 stdout
  • 它接受 --persistent_worker 标志。封装容器必须识别 --persistent_worker 命令行标记,并且仅在传递该标记时永久保留该标记,否则必须执行一次性编译并退出。

如果您的程序满足这些要求,就可以将其用作持久性 worker!

工作请求

WorkRequest 包含 worker 的参数列表、表示 worker 可以访问的输入的路径-摘要对列表(这未强制执行,但您可以使用此信息进行缓存)和一个请求 ID(对于单工工作器,此 ID 为 0)。

注意:虽然协议缓冲区规范使用“蛇形命名法”(request_id),但 JSON 协议使用“驼峰式大小写”(requestId)。本文档在 JSON 示例中使用的是驼峰式大小写,但在谈论字段时,无论采用何种协议,都采用了蛇形命名法。

{
  "arguments" : ["--some_argument"],
  "inputs" : [
    { "path": "/path/to/my/file/1", "digest": "fdk3e2ml23d"},
    { "path": "/path/to/my/file/2", "digest": "1fwqd4qdd" }
 ],
  "requestId" : 12
}

可选的 verbosity 字段可用于从工作器请求额外的调试输出。输出内容是什么以及如何输出完全由 worker 决定。值越高,表示输出越详细。将 --worker_verbose 标志传递给 Bazel 会将 verbosity 字段设置为 10,但您可以手动为不同的输出量使用更小或更大的值。

可选的 sandbox_dir 字段仅由支持多路复用沙盒的工作器使用。

工作回复

WorkResponse 包含一个请求 ID、一个零或非零退出代码,以及一个输出字符串(用于描述处理或执行请求过程中遇到的任何错误)。output 字段包含简短说明;完整日志可能会写入工作器的 stderr。由于工作器只能将 WorkResponses 写入 stdout,因此工作器通常会将其使用的任何工具的 stdout 重定向到 stderr

{
  "exitCode" : 1,
  "output" : "Action failed with the following message:\nCould not find input
    file \"/path/to/my/file/1\"",
  "requestId" : 12
}

根据 protobuf 的规范,所有字段都是可选的。不过,Bazel 要求 WorkRequest 和对应的 WorkResponse 具有相同的请求 ID,因此,如果请求 ID 为非零,则必须指定请求 ID。这是有效的 WorkResponse

{
  "requestId" : 12,
}

request_id 为 0 表示“单工”请求,当此请求无法与其他请求并行处理时使用。服务器可保证给定工作器接收仅 request_id 为 0 或仅 request_id 大于零的请求。单工请求以串行方式发送,例如,如果服务器在收到响应之前不发送其他请求(取消请求除外,请参阅下文)。

备注

  • 每个协议缓冲区的前面都是其长度,采用 varint 格式(请参阅 MessageLite.writeDelimitedTo())。
  • JSON 请求和响应前面没有大小指示器。
  • JSON 请求保持与 protobuf 相同的结构,但使用标准 JSON,所有字段名称使用驼峰式大小写。
  • 为了保持与 protobuf 相同的后向和向前兼容性属性,JSON 工作器必须容忍这些消息中的未知字段,并对缺失值使用 protobuf 默认值。
  • Bazel 将请求存储为 protobuf,并使用 protobuf 的 JSON 格式将请求转换为 JSON

取消

工作器可以选择允许在工作请求完成之前取消这些请求。这在与动态执行有关时特别有用,动态执行中本地执行可能会被更快的远程执行定期中断。如需允许取消,请将 supports-worker-cancellation: 1 添加到 execution-requirements 字段(见下文),并设置 --experimental_worker_cancellation 标志。

取消请求是设置了 cancel 字段的 WorkRequest(类似地,取消响应是设置了 was_cancelled 字段的 WorkResponse)。取消请求或取消响应中必须包含的唯一另一个字段是 request_id,用于表示要取消哪个请求。对于单工工作器,request_id 字段为 0;对于多路工作器,该字段为先前发送的 WorkRequest 的非 0 request_id。服务器可能会针对工作器已响应的请求发送取消请求,在这种情况下,必须忽略取消请求。

每条非取消 WorkRequest 消息都必须只回复一次,无论是否已取消。服务器发送取消请求后,工作器可能会以 WorkResponse 作为响应,并将 request_id 设置为 true,并将 was_cancelled 字段设置为 true。也可以发送常规 WorkResponse,但 outputexit_code 字段将被忽略。

在针对 WorkRequest 发送响应后,工作器便不得处理其工作目录中的文件。服务器可以自由清理这些文件,包括临时文件。

创建使用 worker 的规则

您还需要创建一条规则,用于生成要由 worker 执行的操作。创建使用工作器的 Starlark 规则就像创建任何其他规则一样。

此外,规则需要包含对 worker 本身的引用,并且对它生成的操作有一些要求。

引用 worker

使用 worker 的规则需要包含一个引用 worker 的字段,因此您需要创建 \*\_binary 规则的实例来定义 worker。如果您的工作器名为 MyWorker.Java,这可能是关联的规则:

java_binary(
    name = "worker",
    srcs = ["MyWorker.Java"],
)

这会创建“工作器”标签,用于指代工作器二进制文件。然后定义一条使用 worker 的规则。此规则应定义一个引用工作器二进制文件的特性。

如果您构建的工作器二进制文件位于 build 顶层的名为“work”的软件包中,则属性定义可能如下所示:

"worker": attr.label(
    default = Label("//work:worker"),
    executable = True,
    cfg = "exec",
)

cfg = "exec" 表示应将工作器构建为在您的执行平台上运行,而不是在目标平台上运行(即,工作器在构建期间用作工具)。

工作操作要求

使用 worker 的规则会创建供 worker 执行的操作。这些操作有几项要求。

  • "arguments"字段。这需要一个字符串列表,除最后一个字符串外,其余所有字符串都是启动时传递给 worker 的参数。“参数”列表中的最后一个元素是 flag-file(@ 前面)参数。工作器会根据每个 WorkRequest 从指定的 flagfile 中读取参数。您的规则可以将工作器的非启动参数写入此标志文件。

  • "execution-requirements" 字段,该字段接受包含 "supports-workers" : "1" 和/或 "supports-multiplex-workers" : "1" 的字典。

    对于发送到工作器的所有操作,“参数”和“执行要求”字段均为必填字段。此外,应由 JSON 工作器执行的操作需要在执行要求字段中包含 "requires-worker-protocol" : "json""requires-worker-protocol" : "proto" 也是一项有效的执行要求,但对于 proto 工作器而言并不是必需的,因为它们是默认值。

    您还可以在执行要求中设置 worker-key-mnemonic。如果您要将可执行文件重复用于多种操作类型,并且希望区分此 worker 的操作,这样做可能很有用。

  • 在操作过程中生成的临时文件应保存到工作器的目录中。这样即可启用沙盒。

假设规则定义具有上述“worker”属性,但除了表示输入的“srcs”属性、表示输出的“output”属性以及表示工作器启动参数的“args”属性之外,对 ctx.actions.run 的调用可能如下所示:

ctx.actions.run(
  inputs=ctx.files.srcs,
  outputs=[ctx.outputs.output],
  executable=ctx.executable.worker,
  mnemonic="someMnemonic",
  execution_requirements={
    "supports-workers" : "1",
    "requires-worker-protocol" : "json"},
  arguments=ctx.attr.args + ["@flagfile"]
 )

如需查看其他示例,请参阅实现持久性工作器

示例

除了在我们的集成测试中使用的示例 JSON 工作器之外,Bazel 代码库会使用 Java 编译器工作器

通过传入正确的回调,您可以使用其基架将任何基于 Java 的工具转换为 worker。

如需查看使用工作器的规则的示例,请参阅 Bazel 的工作器集成测试

外部贡献者已用多种语言实现了 worker;请参阅 Bazel 永久性磁盘的 Polyglot 实现。您可以在 GitHub 上找到更多示例