永続ワーカーの作成

問題を報告 ソースを表示 Nightly · 7.4 . 7.3 7.2 7.1 7.0 6.5

永続ワーカーを使用すると、ビルドを高速化できます。起動コストが高いアクションや、クロスアクション キャッシュ化のメリットがあるアクションがビルド内で繰り返される場合は、独自の永続ワーカーを実装してこれらのアクションを実行することを検討してください。

Bazel サーバーは stdin/stdout を使用してワーカーと通信します。プロトコル バッファまたは JSON 文字列の使用をサポートしています。

ワーカーの実装は 2 つの部分で構成されています。

ワーカーを作成する

永続ワーカーには、次の要件があります。

  • 読みます。 WorkRequests stdin から。
  • 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 に書き込まれます。ワーカーは外部 IP アドレスから 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 は 0 よりも大きくなります。シングルプレックス リクエストはシリアルで送信されます。たとえば、サーバーがレスポンスを受信するまで別のリクエストを送信しない場合などです（キャンセル リクエストを除く、下記を参照）。

注

  • 各プロトコル バッファの先頭には、varint 形式の長さが付加されています（ MessageLite.writeDelimitedTo()。
  • JSON リクエストとレスポンスの前にサイズの指標はありません。
  • JSON リクエストは protobuf と同じ構造を保持しますが、標準の すべてのフィールド名でキャメルケースを使用します。
  • 下位互換性と上位互換性を維持するために、 JSON ワーカーはこれらのメッセージ内の不明なフィールドを許容する必要がある 欠損値には protobuf のデフォルトを使用します。
  • Bazel はリクエストを protobuf として保存し、 protobuf の JSON 形式

キャンセル

必要に応じて、作業リクエストが完了する前にキャンセルされるように設定できます。これは、ローカル環境で実行を行う場合に特に便利です。 より高速なリモート実行によって定期的に実行を中断できます。キャンセルを許可するには、execution-requirements フィールドに supports-worker-cancellation: 1 を追加し（下記を参照）、--experimental_worker_cancellation フラグを設定します。

キャンセル リクエストは、cancel フィールドが設定された WorkRequest です（ 同様に、キャンセル レスポンスは was_cancelled を含む WorkResponse です。 設定されます。キャンセル リクエストまたはキャンセル レスポンスに含める必要がある他のフィールドは、キャンセルするリクエストを示す request_id のみです。request_id フィールドは、シングルプレックス ワーカーの場合 0、または以前のワーカーの 0 以外の request_id になります。 Multiplex ワーカーに WorkRequest を送信しました。サーバーがキャンセル リクエストを送信する可能性がある ワーカーがすでに応答しているリクエストの場合、 キャンセルは 無視する必要があります。

キャンセル以外の 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" は、ワーカーが 実行プラットフォーム（つまり、Worker を使用して 使用しないでください）。

作業アクションの要件

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

  • 「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 コードベースでは、 Java コンパイラ ワーカー さらに、 サンプル JSON ワーカー 統合テストで使われる

こちらの スキャフォールディング 適切なコールバックを渡すことで、Java ベースのツールをワーカーにすることができます。

ワーカーを使用するルールの例については、Bazel のワーカー統合テストをご覧ください。

外部の貢献者は、さまざまな言語でワーカーを導入しています。CANNOT TRANSLATE 見て Bazel 永続ワーカーの多言語実装。 Google Chat では GitHub で他にも多くのサンプルがあります。