永続ワーカーを使用すると、ビルドを高速化できます。ビルドで繰り返しのアクションで起動コストが高い場合や、クロス アクション キャッシュが有効な場合は、これらのアクションを実行する独自の永続ワーカーを実装することをおすすめします。
Bazel サーバーは、stdin
/stdout
を使用してワーカーと通信します。プロトコル バッファまたは JSON 文字列の使用をサポートしています。
ワーカーの実装は 2 つの部分に分かれています。
ワーカーの作成
永続ワーカーはいくつかの要件を満たします。
stdin
から WorkRequests を読み取ります。- WorkResponses(
WorkResponse
のみ)をstdout
に書き込みます。 --persistent_worker
フラグを受け入れます。ラッパーは、--persistent_worker
コマンドライン フラグを認識し、フラグが渡された場合にのみ自身を永続化する必要があります。それ以外の場合は、ワンショット コンパイルを実行して終了する必要があります。
プログラムがこれらの要件を満たしていれば、永続ワーカーとして使用できます。
処理リクエスト
WorkRequest
には、ワーカーへの引数のリスト、ワーカーがアクセスできる入力を表すパス / ダイジェスト ペアのリスト(強制適用されませんが、この情報をキャッシュに使用できます)、リクエスト 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,
}
request_id
が 0 の場合、このリクエストを他のリクエストと並行して処理できない場合に使用されます。サーバーは、特定のワーカーが request_id
0 のみ、または 0 より大きい request_id
のみを含むリクエストを受信することを保証します。Singleplex リクエストは順次送信されます。たとえば、サーバーがレスポンスを受信するまで別のリクエストを送信しない場合です(キャンセル リクエストを除き、以下を参照)。
メモ
- 各プロトコル バッファの先頭には、
varint
形式の長さが続きます(MessageLite.writeDelimitedTo()
を参照)。 - JSON のリクエストとレスポンスの前にサイズインジケーターはありません。
- JSON リクエストは protobuf と同じ構造を保持しますが、標準 JSON を使用し、すべてのフィールド名にキャメルケースを使用します。
- protobuf と同じ下位互換性と上位互換性のプロパティを維持するため、JSON ワーカーはこれらのメッセージ内の不明なフィールドを許容し、欠損値に protobuf のデフォルトを使用する必要があります。
- Bazel はリクエストを protobuf として保存し、protobuf の JSON 形式を使用して JSON に変換します。
キャンセル
ワーカーは、処理リクエストが完了前にキャンセルできるようにすることもできます。これは、高速なリモート実行によってローカル実行を定期的に中断できる動的実行で特に有用です。キャンセルを許可するには、execution-requirements
フィールドに supports-worker-cancellation: 1
を追加し(下記参照)、--experimental_worker_cancellation
フラグを設定します。
キャンセル リクエストは、cancel
フィールドが設定された WorkRequest
です(同様に、キャンセル レスポンスは was_cancelled
フィールドが設定された WorkResponse
です)。キャンセル リクエストまたはキャンセル レスポンスに含められる必要があるその他のフィールドは、キャンセルするリクエストを示す request_id
のみです。request_id
フィールドは、シングルプレックス ワーカーの場合は 0、マルチプレックス ワーカーの場合は以前に送信された WorkRequest
の 0 以外の request_id
になります。サーバーは、ワーカーがすでに応答したリクエストに対してキャンセル リクエストを送信することがあります。この場合、キャンセル リクエストを無視する必要があります。
キャンセル以外の各 WorkRequest
メッセージは、キャンセルされたかどうかにかかわらず、1 回だけ応答する必要があります。サーバーがキャンセル リクエストを送信すると、ワーカーは request_id
を設定し、was_cancelled
フィールドを true に設定した WorkResponse
で応答できます。通常の WorkResponse
を送信することもできますが、output
フィールドと exit_code
フィールドは無視されます。
WorkRequest
に対するレスポンスの送信後、ワーカーはその作業ディレクトリ内のファイルに触れません。サーバーは一時ファイルを含むファイルを自由にクリーンアップできます。
ワーカーを使用するルールを作成する
また、ワーカーが実行するアクションを生成するルールも作成する必要があります。ワーカーを使用する Starlark ルールの作成は、他のルールの作成と同じです。
また、ルールにはワーカー自体への参照を含める必要があり、ワーカーが生成するアクションにはいくつかの要件があります。
ワーカーの参照
ワーカーを使用するルールには、ワーカー自体を参照するフィールドを含める必要があるため、\*\_binary
ルールのインスタンスを作成してワーカーを定義する必要があります。ワーカーの名前が MyWorker.Java
の場合は、次のルールが関連付けられている可能性があります。
java_binary(
name = "worker",
srcs = ["MyWorker.Java"],
)
これにより、ワーカー バイナリを参照する「worker」ラベルが作成されます。次に、ワーカーを使用するルールを定義します。このルールでは、ワーカー バイナリを参照する属性を定義します。
ビルドしたワーカー バイナリが、ビルドの最上位にある「work」という名前のパッケージにある場合、属性定義は次のようになります。
"worker": attr.label(
default = Label("//work:worker"),
executable = True,
cfg = "exec",
)
cfg = "exec"
は、ワーカーをターゲット プラットフォームではなく実行プラットフォームで実行するようにビルドする必要があることを示します(つまり、ワーカーはビルド中にツールとして使用されます)。
作業アクションの要件
ワーカーを使用するルールによって、ワーカーが実行するアクションが作成されます。これらのアクションには 2 つの要件があります。
"arguments" フィールドこれは文字列のリストを受け取ります。最後の引数を除くすべての文字列が、起動時にワーカーに渡されます。「arguments」リストの最後の要素は
flag-file
(@ で始まる)引数です。ワーカーは、WorkRequest ごとに指定されたフラグファイルから引数を読み取ります。ルールでは、ワーカーの起動以外の引数をこのフラグファイルに書き込むことができます。"execution-requirements" フィールド。
"supports-workers" : "1"
、"supports-multiplex-workers" : "1"
、またはその両方を含む辞書を取得します。「arguments」フィールドと「execution-requirements」フィールドは、ワーカーに送信されるすべてのアクションに必要です。また、JSON ワーカーで実行する必要があるアクションでは、実行要件フィールドに
"requires-worker-protocol" : "json"
を含める必要があります。"requires-worker-protocol" : "proto"
も有効な実行要件ですが、proto ワーカーの場合、デフォルトであるため必須ではありません。また、実行要件で
worker-key-mnemonic
を設定することもできます。これは、複数のアクション タイプで実行可能ファイルを再利用し、このワーカーでアクションを区別する場合に役立ちます。アクションの過程で生成される一時ファイルは、ワーカーのディレクトリに保存する必要があります。これにより、サンドボックス化が有効になります。
上記の「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"]
)
別の例については、永続ワーカーの実装をご覧ください。
例
Bazel コードベースは、統合テストで使用される サンプルの JSON ワーカーに加えて、Java コンパイラ ワーカーを使用します。
そのスキャフォールディングを使用して、正しいコールバックを渡すことで、Java ベースのツールをワーカーにすることができます。
ワーカーを使用するルールの例については、Bazel のワーカー統合テストをご覧ください。
外部の貢献者がさまざまな言語でワーカーを実装しています。Bazel 永続ワーカーの多言語実装をご覧ください。GitHub には他にも多くの例があります。