持久型工作器可加快构建速度。如果您的 build 中有启动成本高或可受益于跨操作缓存的重复操作,您可能需要实现自己的持久工作器来执行这些操作。
Bazel 服务器使用 stdin
/stdout
与工作器通信。它支持使用协议缓冲区或 JSON 字符串。
工作器实现包含两个部分:
创建工作器
持久性工作器需要满足以下几项要求:
- 它会从其
stdin
中读取 WorkRequests。 - 它会将 WorkResponses(以及仅限
WorkResponse
)写入其stdout
。 - 它接受
--persistent_worker
标志。封装容器必须识别--persistent_worker
命令行标志,并且仅在传递该标志时才使自身保持持久状态,否则必须进行一次性编译并退出。
如果您的程序符合这些要求,就可以用作持久性工作器!
工作请求
WorkRequest
包含工作器的实参列表、表示工作器可访问的输入的路径-摘要对列表(此项不是强制性的,但您可以将此信息用于缓存),以及请求 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_verbose
标志传递给 Bazel 会将 verbosity
字段设置为 10,但您可以手动使用较小或较大的值来控制输出量。
可选的 sandbox_dir
字段仅供支持多路复用沙盒的工作人员使用。
工作回答
WorkResponse
包含请求 ID、零或非零退出代码,以及描述在处理或执行请求时遇到的任何错误的输出消息。工作线程应捕获其调用的任何工具的 stdout
和 stderr
,并通过 WorkResponse
报告它们。将其写入工作器进程的 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 不为零,则必须指定。这是一个有效的 WorkResponse
。
{
"requestId" : 12,
}
值为 0 的 request_id
表示“单路复用”请求,当此请求无法与其他请求并行处理时使用。服务器保证给定的工作器收到的请求要么只有 request_id
0,要么只有大于零的 request_id
。单路复用请求是按顺序发送的,例如,服务器在收到响应之前不会发送其他请求(取消请求除外,请参阅下文)。
备注
- 每个协议缓冲区都以
varint
格式的长度为前缀(请参阅MessageLite.writeDelimitedTo()
)。 - JSON 请求和响应前面没有大小指示符。
- JSON 请求与 protobuf 保持相同的结构,但使用标准 JSON,并对所有字段名称使用驼峰式命名法。
- 为了保持与 protobuf 相同的向后和向前兼容性,JSON worker 必须容忍这些消息中的未知字段,并使用 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;对于多路工作器,request_id
字段将为之前发送的 WorkRequest
的非零值。服务器可能会针对工作线程已响应的请求发送取消请求,在这种情况下,必须忽略取消请求。
每个非取消 WorkRequest
消息都必须得到一次响应,无论是否已取消。服务器发送取消请求后,工作器可能会返回 WorkResponse
,其中 request_id
已设置,且 was_cancelled
字段设置为 true。系统也接受发送常规 WorkResponse
,但会忽略 output
和 exit_code
字段。
一旦针对 WorkRequest
发送了响应,工作器就不得再触及其工作目录中的文件。服务器可以随意清理文件,包括临时文件。
创建使用工作器的规则
您还需要创建一条规则,用于生成要由工作器执行的操作。创建使用工作器的 Starlark 规则与创建任何其他规则一样。
此外,该规则还需要包含对工作器本身的引用,并且对其生成的操作有一些要求。
引用工作器
使用工作器的规则需要包含一个引用工作器本身的字段,因此您需要创建 \*\_binary
规则的实例来定义工作器。如果您的工作器名为 MyWorker.Java
,则相关规则可能如下所示:
java_binary(
name = "worker",
srcs = ["MyWorker.Java"],
)
这会创建“worker”标签,用于指代工作器二进制文件。然后,您将定义一个使用该工作器的规则。此规则应定义一个引用工作器二进制文件的属性。
如果您构建的工作器二进制文件位于名为“work”的软件包中(该软件包位于 build 的顶层),则属性定义可能如下所示:
"worker": attr.label(
default = Label("//work:worker"),
executable = True,
cfg = "exec",
)
cfg = "exec"
表示应构建工作器以在执行平台(而非目标平台)上运行(即,在构建期间将工作器用作工具)。
工作操作要求
使用工作器的规则会创建供工作器执行的操作。这些操作有几项要求。
“实参”字段。此参数接受一个字符串列表,其中除最后一个字符串之外的所有字符串都是在启动时传递给工作器的实参。“arguments”列表中的最后一个元素是
flag-file
(以 @ 开头)实参。工作器会根据每个 WorkRequest 从指定的标志文件中读取实参。您的规则可以将工作器的非启动实参写入此标志文件。“execution-requirements”字段,该字段接受包含
"supports-workers" : "1"
、"supports-multiplex-workers" : "1"
或两者的字典。对于发送给工作器的所有操作,“arguments”和“execution-requirements”字段都是必需的。此外,应由 JSON worker 执行的操作需要在执行要求字段中包含
"requires-worker-protocol" : "json"
。"requires-worker-protocol" : "proto"
也是有效的执行要求,但对于 proto worker 来说,这不是必需的,因为它们是默认的。您还可以在执行要求中设置
worker-key-mnemonic
。如果您要将可执行文件重复用于多种操作类型,并希望通过此工作器区分操作,那么此功能可能很有用。在操作过程中生成的临时文件应保存到工作器的目录中。这样可启用沙盒。
假设规则定义具有上述“worker”属性,以及表示输入的“srcs”属性、表示输出的“output”属性和表示 worker 启动实参的“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"]
)
如需查看其他示例,请参阅实现持久性 worker。
示例
除了集成测试中使用的示例 JSON 工作器之外,Bazel 代码库还使用 Java 编译器工作器。
您可以使用其脚手架,通过传入正确的回调,将任何基于 Java 的工具转换为工作器。
如需查看使用工作器的规则示例,请参阅 Bazel 的工作器集成测试。
外部贡献者已使用多种语言实现了工作器;请参阅 Bazel 永久性工作器的多语言实现。 您可以在 GitHub 上找到更多示例!