安定版リリースのドキュメントについては、[バージョニングされたドキュメント] プルダウンを使用してください。デフォルトのビューには HEAD の最新バージョンが表示されます。

このページは Cloud Translation API によって翻訳されました。

永続ワーカーの作成

永続ワーカーを使用すると、ビルドを高速化できます。起動コストが高い、またはクロスアクションキャッシュが役立つと思われるアクションがビルド内で繰り返されている場合は、そのようなアクションを実行する独自の永続ワーカーを実装することをおすすめします。

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、ゼロまたはゼロ以外の終了コード、リクエストの処理または実行中に発生したエラーを説明する出力文字列が含まれます。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 である必要があるため、0 以外の場合はリクエスト ID を指定する必要があります。これは有効な WorkResponse です。

{
  "requestId" : 12,
}

request_id が 0 の場合は「シングルプレックス」リクエストであり、このリクエストが他のリクエストと並行して処理できない場合に使用されます。サーバーは、指定されたワーカーが request_id 0 のみ、または 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 になります。Multiplex ワーカーの場合は、以前に送信された 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" は、ターゲットプラットフォームではなく実行プラットフォームで実行するようにワーカーをビルドすることを示します（つまり、ワーカーはビルド中にツールとして使用されます）。

作業要件

ワーカーを使用するルールは、ワーカーが実行するアクションを作成します。これらのアクションには、いくつかの要件があります。

"arguments" フィールドこれは、文字列のリストを受け取ります。文字列のリストのうち、最後のもの以外はすべて起動時にワーカーに渡されます。"arguments" リストの最後の要素は flag-file（@-preceded）引数です。ワーカーは、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 には他にも多くの例があります。