引数

問題を報告する ソースを表示 ナイトリー · 7.4 . 7.3 7.2 7.1 7.0 6.5

コマンドラインの一部または全体を構築するために必要なデータをメモリ効率の高い方法でカプセル化するオブジェクト。

多くの場合、アクションには、伝播依存関係から蓄積された値を含む大きなコマンドラインが必要になります。たとえば、リンカー コマンドラインには、リンクされるすべてのライブラリに必要なすべてのオブジェクト ファイルが一覧表示されます。このような伝播データを depset に保存して、複数のターゲットで共有することをおすすめします。しかし、ルールの作成者がアクションのコマンドラインを作成するためにこれらのデプセットを文字列のリストに変換する必要がある場合、このメモリ共有の最適化は無効になります。

このため、アクション構築関数は文字列に加えて Args オブジェクトを受け入れます。各 Args オブジェクトは、文字列と depset の連結を表します。データ操作の変換は省略可能です。Args オブジェクトは、実行フェーズでコマンドラインを計算するまで、カプセル化された depset を処理しません。これにより、費用のかかるコピーを分析フェーズが完了するまで遅らせることができます。詳細については、パフォーマンスの最適化のページをご覧ください。

Args は ctx.actions.args() を呼び出して作成されます。これらは、ctx.actions.run() または ctx.actions.run_shell() の arguments パラメータとして渡すことができます。Args オブジェクトの各ミューテーションは、最終的なコマンドラインに値を追加します。

map_each 機能を使用すると、アイテムを文字列に変換する方法をカスタマイズできます。map_each 関数を指定しない場合、標準の変換は次のようになります。

  • すでに文字列になっている値は、そのままになります。
  • File オブジェクトは File.path 値に変換されます。
  • Label オブジェクトは文字列表現に変換され、メイン リポジトリのコンテキストで解決されると同じオブジェクトに解決されます。可能であれば、文字列表現ではリポジトリの正規名を優先してリポジトリの名前を使用します。そのため、この表現は BUILD ファイルでの使用に適しています。表現の正確な形式は保証されませんが、//foo:bar、@repo//foo:bar、@@canonical_name~//foo:bar.bzl がその典型的な例です。
  • 他のすべての型は、未指定の方法で文字列に変換されます。そのため、文字列型または File 型以外の値を add() に渡さないようにしてください。add_all() または add_joined() に渡す場合は、map_each 関数を指定する必要があります。

文字列書式設定（add*() メソッドの format、format_each、format_joined パラメータ）を使用する場合、書式設定テンプレートは文字列の % 置換と同じように解釈されます。ただし、テンプレートには置換プレースホルダが 1 つだけで、%s である必要があります。リテラルの割合は、%% としてエスケープできます。上記のように値が文字列に変換された後、書式設定が適用されます。

各 add*() メソッドには、追加の位置パラメータ（残りの引数の前に挿入する「引数名」文字列）を受け入れる代替形式があります。add_all と add_joined の場合、シーケンスが空の場合、余分な文字列は追加されません。たとえば、同じ使用方法で、指定されたシーケンスに val1..val3 が含まれているか空かに応じて、--foo val1 val2 val3 --bar または --bar のみをコマンドラインに追加できます。

コマンドラインの大きさがシステムで許容される最大サイズを超える可能性がある場合は、引数をパラメータ ファイルにスプールできます。use_param_file() と set_param_file_format() をご覧ください。

例: コマンドライン 

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
を生成するとします。次の Args オブジェクトを使用できます。 
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)

メンバー

追加

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

このコマンドラインにアラゲメントを追加します。

パラメータ

パラメータ 説明
arg_name_or_value 必須
位置パラメータが 2 つ渡された場合、引数名として解釈されます。引数名は、何も処理せずに値の前に追加されます。位置パラメータが 1 つだけ渡された場合は、value として解釈されます（以下を参照）。
value デフォルトは unbound
追加するオブジェクト。上記の標準変換を使用して文字列に変換されます。この関数には map_each パラメータがないため、value は文字列または File にする必要があります。このメソッドの代わりに、リスト、タプル、depset、ディレクトリの File を add_all() または add_joined() に渡す必要があります。
format 文字列、または None（デフォルトは None）

value の文字列バージョンに適用される書式文字列パターン。

add_all

Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)

このコマンドラインに複数の引数を追加します。アイテムは実行フェーズで遅延処理されます。

処理の大部分は、次の手順に沿って追加される引数のリストに対して行われます。

  1. 各ディレクトリ File 項目は、そのディレクトリに再帰的に含まれるすべての File に置き換えられます。
  2. map_each が指定されている場合、それは各アイテムに適用され、結果の文字列リストが連結されて最初の引数リストが形成されます。それ以外の場合、最初の引数リストは、各項目に標準変換を適用した結果です。
  3. リスト内の各引数は、存在する場合は format_each でフォーマットされます。
  4. uniquify が true の場合、重複する引数が削除されます。最初の発生が残ります。
  5. before_each 文字列が指定されている場合、リスト内の既存の引数の前に新しい引数として挿入されます。これにより、この時点で追加される引数の数は実質的に 2 倍になります。
  6. リストが空で、omit_if_empty が true（デフォルト）である場合を除き、引数名と terminate_with が指定されている場合は、それぞれ最初と最後の引数として挿入されます。
空の文字列は有効な引数であり、これらの処理ステップのすべてが適用されます。

パラメータ

パラメータ 説明
arg_name_or_values 必須
位置パラメータが 2 つ渡された場合、引数名として解釈されます。引数名は、処理なしで values の前に別の引数として追加されます。omit_if_empty が true（デフォルト）で、他のアイテムが追加されていない場合（values が空の場合や、そのアイテムがすべてフィルタされている場合など）、この引数名は追加されません。渡される位置パラメータが 1 つだけの場合は、values と解釈されます（以下を参照）。
values シーケンスまたはdepset（デフォルトは unbound
）。アイテムが追加されるリスト、タプル、depset。
map_each 呼び出し可能関数、または None。デフォルトは None。
各アイテムを 0 個以上の文字列に変換する関数。追加前にさらに処理できます。このパラメータが指定されていない場合、標準の変換が使用されます。

この関数には、1 つまたは 2 つの位置引数が渡されます。変換対象アイテムの後に、省略可能な DirectoryExpander が続きます。2 番目の引数は、指定された関数がユーザー定義（組み込みではない）で、複数のパラメータを宣言している場合にのみ渡されます。

戻り値の型は、アイテムに生成される引数の数によって異なります。

  • 各アイテムが 1 つの文字列に変換される一般的なケースでは、関数はその文字列を返す必要があります。
  • アイテム全体を除外する場合は、None を返します。
  • アイテムが複数の文字列に変換された場合、関数はこれらの文字列のリストを返します。
単一の文字列または None を返すと、それぞれ長さ 1 または長さ 0 のリストが返されるのと同じ効果があります。ただし、不要なリストを作成しないようにするほうが、効率的で読みやすいものになります。

通常、ディレクトリであるアイテムは、expand_directories=True が設定されると、その内容に自動的に展開されます。ただし、他の値に含まれるディレクトリは展開されません。たとえば、アイテムがディレクトリをフィールドとして持つ構造体の場合です。この場合、DirectoryExpander 引数を適用して、特定のディレクトリのファイルを手動で取得できます。

分析フェーズの大規模なデータ構造が実行フェーズに意図せず保持されないように、トップレベルの def ステートメントで map_each 関数を宣言する必要があります。デフォルトではネストされた関数のクロージャにすることはできません。

警告: map_each の呼び出し中に実行される print() ステートメントは、目に見える出力を生成しません。

format_each 文字列、または None。デフォルトは None。
オプションの書式文字列パターン。map_each 関数によって返される各文字列に適用されます。形式文字列には「%s」プレースホルダを 1 つだけ含める必要があります。
before_each 文字列、または None。デフォルトは None。
values から派生した各引数の前に追加するオプションの引数。
omit_if_empty デフォルトは True
true の場合、追加する values から派生した引数がない場合、それ以降の処理はすべて抑制され、コマンドラインは変更されません。false の場合、引数名と terminate_with（指定されている場合）は、他の引数があるかどうかにかかわらず、引き続き追加されます。
uniquify デフォルトは False
true に設定すると、values から派生した重複する引数は省略されます。各引数が最初に一致したもののみが残ります。通常、depset では重複がすでに除外されているため、この機能は必要ありませんが、map_each が複数のアイテムに対して同じ文字列を出力する場合は便利です。
expand_directories デフォルトは True
true の場合、values 内のディレクトリはファイルのフラットリストに展開されます。これは、map_each が適用される前に行われます。
terminate_with string;または None デフォルトは None
です 他のすべての引数の後に追加するオプションの引数。omit_if_empty が true（デフォルト）で、他のアイテムが追加されていない場合（values が空の場合や、そのアイテムがすべてフィルタされている場合など）、この引数は追加されません。
allow_closure デフォルトは False
true の場合、map_each などの関数パラメータでクロージャを使用できます。通常これは必要なく、分析フェーズで大規模なデータ構造を実行フェーズに保持してしまうリスクがあります。

add_joined

Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)

区切り記号で複数の値を連結して、このコマンドラインに引数を追加します。アイテムは実行フェーズで遅延して処理されます。

処理は add_all() と似ていますが、values から派生した引数のリストは、join_with.join(...) のように 1 つの引数に結合され、指定された format_joined 文字列テンプレートを使用してフォーマットされます。add_all() とは異なり、before_each または terminate_with パラメータは一般に、アイテムを 1 つの引数に結合する場合には有用ではないため、存在しません。

フィルタリング後に引数に結合する文字列がなく、omit_if_empty が true（デフォルト）の場合、処理は行われません。それ以外の場合、結合する文字列がないのに omit_if_empty が false の場合、結合される文字列は空の文字列になります。

パラメータ

パラメータ 説明
arg_name_or_values 必須
位置パラメータが 2 つ渡された場合、引数名として解釈されます。引数名は、処理なしで values の前に追加されます。omit_if_empty が true（デフォルト）で、values から派生した文字列が結合されない場合は、この引数は追加されません（values が空であるか、そのアイテムがすべてフィルタされている場合に発生する可能性があります）。位置パラメータが 1 つだけ渡された場合は、values として解釈されます（以下を参照）。
values シーケンスまたは depset（デフォルトは unbound）
項目が結合されるリスト、タプル、または depset。
join_with 必須
string.join() と同じ方法で map_each と format_each を適用して取得した文字列を結合するために使用される区切り文字。
map_each callable;または None デフォルトは None
add_all と同じです。
format_each 文字列、または None。デフォルトは None。
add_all と同じです。
format_joined 文字列、または None。デフォルトは None。
結合された文字列に適用される書式文字列パターン（省略可）。形式文字列には「%s」プレースホルダを 1 つだけ含める必要があります。
omit_if_empty デフォルトは True
です。true の場合、結合する文字列がない場合（values が空であるか、すべての項目がフィルタされている場合）、それ以降の処理はすべて抑制され、コマンドラインは変更されません。false の場合、結合する文字列がない場合でも、2 つの引数（引数名と空の文字列）が追加されます（これはゼロ文字列の論理結合です）。
uniquify デフォルトは False
。add_all と同じです。
expand_directories デフォルトは True
。add_all と同じです。
allow_closure デフォルトは False
add_all と同じです。

set_param_file_format

Args Args.set_param_file_format(format)

パラメータ ファイルの形式を設定します（使用する場合）

パラメータ

パラメータ 説明
format 必須
次のいずれかである必要があります。
  • 「multiline」：各項目（引数名または値）は、改行文字でパラメータファイルにそのまま書き込まれます。
  • 「shell」: 「multiline」と同じですが、アイテムはシェル引用符で囲まれます
  • 「flag_per_line」: 「multiline」と同じですが、（1）パラメータ ファイルにはフラグ（「--」で始まる）のみが書き込まれ、（2）フラグの値（存在する場合）は同じ行に「=」区切りで書き込まれます。これは、Abseil フラグ ライブラリで想定される形式です。

デフォルトの形式は「shell」です。渡されます。

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

引数を params ファイルにスピンアウトし、パラメータ ファイルへのポインタに置き換えます。システムのコマンドの長さの上限を超える可能性がある引数を使用する場合に使用します。

Bazel では、効率を高めるために、実行中に params ファイルの出力ツリーへの書き込みを省略する場合があります。アクションをデバッグしていて、パラメータ ファイルを検査する場合は、--materialize_param_files をビルドに渡します。

パラメータ

パラメータ 説明
param_file_arg 必須
「%s」が 1 つ含まれる形式文字列。引数が params ファイルにあふれた場合、params ファイルのパスでフォーマットされたこの文字列で構成される引数に置き換えられます。

たとえば、引数がパラメータ ファイル「params.txt」にあふれている場合は、「--file=%s」を指定します。アクションのコマンドラインに「--file=params.txt」が含まれるようになります。

use_always デフォルトは False
引数を常に params ファイルにオーバーフローするかどうか。false の場合、bazel はシステムと引数の長さに基づいて、引数をあふれさせる必要があるかどうかを判断します。