永続ワーカーを使用すると、ビルドを高速化できます。起動コストが高いアクションや、クロスアクション キャッシュ化のメリットがあるアクションがビルド内で繰り返される場合は、独自の永続ワーカーを実装してこれらのアクションを実行することを検討してください。
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 のみ、または request_id
がゼロより大きいリクエストのみを受信することを保証します。シングルプレックス リクエストはシリアルで送信されます。たとえば、サーバーがレスポンスを受信するまで別のリクエストを送信しない場合などです(キャンセル リクエストを除く、下記を参照)。
注
- 各プロトコル バッファの前に、その長さが
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"
も有効な実行要件ですが、プロトワーカーはデフォルトであるため、プロトワーカーには必要ありません。実行要件で
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 には他にも多くの例があります。