多くの場合、アクションには、推移的な依存関係から蓄積された値を含む大きなコマンドラインが必要です。たとえば、リンカーのコマンドラインでは、リンクされるすべてのライブラリで必要なすべてのオブジェクト ファイルを一覧表示できます。このような推移的データは、複数のターゲットで共有できるように depset に保存することをおすすめします。ただし、ルールの作成者がアクション コマンドラインを作成するために、これらのデセットを文字列のリストに変換しなければ、このメモリ共有の最適化は機能しません。
このため、アクション作成関数は、文字列に加えて Args オブジェクトを受け入れます。各 Args オブジェクトは、文字列とデセットの連結を表し、オプションでデータを操作するための変換が可能です。Args オブジェクトは、実行フェーズ（コマンドラインの計算時）まで、カプセル化されたデプセットを処理しません。これにより、分析フェーズが完了するまで高価なコピーを延期できます。詳しくは、パフォーマンスの最適化のページをご覧ください。
Args は、ctx.actions.args() を呼び出して作成されます。これらは、ctx.actions.run() または ctx.actions.run_shell() の arguments パラメータとして渡すことができます。Args オブジェクトの各ミューテーションにより、最終的なコマンドラインに値が追加されます。
map_each 機能を使用すると、アイテムを文字列に変換する方法をカスタマイズできます。map_each 関数を指定しない場合、標準の変換は次のとおりです。
- すでに文字列である値はそのまま残ります。
FileオブジェクトはFile.path値に変換されます。- その他の型はすべて、不特定の方法で文字列に変換されます。このため、文字列型または
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],
...
)
メンバー
add
Args Args.add(arg_name_or_value, value=unbound, *, format=None)このコマンドラインに引数を追加します。
パラメータ
| パラメータ | 説明 |
|---|---|
arg_name_or_value
|
必須 2 つの位置パラメータを渡すと、引数名として解釈されます。引数名は値の前に追加され、処理されません。1 つの位置パラメータのみを渡すと、 value として解釈されます（以下を参照）。
|
value
|
default = unbound 追加するオブジェクト。これは上記の標準変換を使用して文字列に変換されます。この関数には map_each パラメータがないため、value は文字列または File にする必要があります。リスト、タプル、デセット、またはディレクトリは、このメソッドではなく add_all() または add_joined() に渡す必要があります。 |
format
|
string; or None;
default = None文字列文字列の value に適用する書式文字列パターン。 |
すべて追加
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)このコマンドラインに複数の引数を追加します。アイテムは、実行フェーズ内で遅延処理されます。
ほとんどの処理は、次の手順で追加される引数のリストで実行されます。
- 各ディレクトリの
Fileアイテムは、そのディレクトリ内のすべての再帰的なFileに置き換えられます。 map_eachを指定すると各アイテムに適用され、結果の文字列リストが連結されて最初の引数のリストが形成されます。それ以外の場合は、標準変換を各アイテムに適用した結果が初期引数リストとなります。- リスト内の各引数の形式は、
format_each（存在する場合）です。 uniquifyが true の場合、重複する引数は削除されます。最初に出現するのは、残るものです。- 指定した
before_each文字列は、リスト内の既存の各引数の前に新しい引数として挿入されます。これにより、この時点で加算する引数の数が倍になります。 - リストが空で、
omit_if_emptyが true（デフォルト）の場合を除いて、引数名とterminate_withはそれぞれ最初の引数と最後の引数として挿入されます。
パラメータ
| パラメータ | 説明 |
|---|---|
arg_name_or_values
|
必須 2 つの位置パラメータを渡すと、引数名として解釈されます。引数名は、処理を行わずに別の引数として values の前に追加されます。omit_if_empty が true（デフォルト）で、他のアイテムが追加されていない場合は、この引数名は追加されません（values が空の場合、またはすべてのアイテムがフィルタされている場合と同様）。1 つの位置パラメータのみを渡すと、values として解釈されます（以下を参照）。
|
values
|
sequence; or depset;
default = unboundアイテムを追加するリスト、タプル、またはデセット。 |
map_each
|
callable; or None; default = None各項目を 0 個以上の文字列に変換する関数で、追加前に追加で処理される場合があります。このパラメータを指定しない場合は、標準のコンバージョンが使用されます。 関数には 1 つまたは 2 つの位置引数が渡されます。この引数には、変換対象のアイテムとその後にオプションの 戻り値の型は、そのアイテムに対して生成される引数の数によって決まります。
None でそれぞれ長さ 1 または長さ 0 のリストを返す場合と同じ結果が得られます。必要以上にリストを作成するのではなく、より効率的で読みやすいものにします。通常、ディレクトリに設定されているアイテムは、 大規模な分析フェーズのデータ構造を実行フェーズで意図せず保持しないようにするには、最上位の 警告: |
format_each
|
string; or None; default = Nonemap_each 関数で返される各文字列に適用される、省略可能な形式設定文字列パターン。形式設定文字列には「%s」プレースホルダを 1 つだけ含める必要があります。
|
before_each
|
string; or None; default = Nonevalues から導出された各引数が付加されるオプションの引数。 |
omit_if_empty
|
default = True true の場合、 values から派生する引数が追加されない場合、それ以降の処理はすべて抑制され、コマンドラインは変更されません。false の場合、他の引数があるかどうかにかかわらず、引数名と terminate_with（存在する場合）が付加されます。
|
uniquify
|
default = False true の場合、 values から派生した重複する引数は省略されます。最初に出現した引数のみが残ります。Depset では重複がすでに省略されているため、通常はこの機能は不要ですが、map_each が複数のアイテムで同じ文字列を出力する場合に役立ちます。
|
expand_directories
|
default = True true の場合、 values 内のディレクトリはフラットなファイルに展開されます。これは map_each の適用前に行われます。 |
terminate_with
|
string; or None;
default = None他のすべての引数の後に追加するオプションの引数。 omit_if_empty が true（デフォルト）で、他のアイテムが追加されていない場合は、この引数は追加されません（values が空である場合、またはすべてのアイテムがフィルタされている場合と同様）。
|
allow_closure
|
default = 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
|
sequence; or depset; default = unboundアイテムが結合されるリスト、タプル、またはデセット。 |
join_with
|
必須string.join() と同様に、map_each と format_each の適用から取得した文字列を結合する区切り文字です。 |
map_each
|
callable; or None（デフォルト = なし）add_all と同じです。 |
format_each
|
string; or None（デフォルト = なし）add_all と同じです。 |
format_joined
|
string; or None;
default = None結合された文字列に適用される、オプションの書式設定文字列パターン。形式設定文字列には「%s」プレースホルダを 1 つだけ含める必要があります。 |
omit_if_empty
|
default = True true の場合、 values が空であるか、すべてのアイテムがフィルタされているために結合する文字列がない場合、それ以降の処理はすべて抑制され、コマンドラインは変更されません。false の場合、結合する文字列がない場合でも、2 つの引数が追加されます。つまり、引数名の後に空の文字列（ゼロ文字列を論理的に結合したもの）が追加されます。
|
uniquify
|
default = Falseadd_all と同じです。 |
expand_directories
|
デフォルトは true です。add_all と同じです。 |
allow_closure
|
default = Falseadd_all と同じです。 |
set_param_file_format
Args Args.set_param_file_format(format)パラメータ ファイルの形式を設定します（使用されている場合）。
パラメータ
| パラメータ | 説明 |
|---|---|
format
|
必須 次のいずれかにする必要があります。
呼び出されない形式はデフォルトの「shell」になります。 |
#use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)引数をパラメータ ファイルにスピルし、パラメータ ファイルへのポインタに置き換えます。引数がシステムのコマンド長の制限に対して大きすぎる場合に使用します。
Bazel は、効率化を図るために、パラメータ ファイルを出力ツリーに書き込まないようにすることもできます。アクションをデバッグする際にパラメータ ファイルを検査する場合は、ビルドに --materialize_param_files を渡します。
パラメータ
| パラメータ | 説明 |
|---|---|
param_file_arg
|
必須 単一の「%s」を含むフォーマット文字列。引数がパラメータ ファイルにスピルされた場合、それらはパラメータ ファイルのパスが書式設定されたこの文字列で構成される引数に置き換えられます。 たとえば、引数がパラメータ ファイル「params.txt」にオーバーフローした場合、「--file=%s」と指定すると、アクション コマンドラインに「--file=params.txt」が含まれるようになります。 |
use_always
|
default = False 常にパラメータ ファイルに引数をスピルするかどうかを指定します。false の場合、システムと引数の長さに基づいて、引数をオーバーフローする必要があるかどうかを判断します。 |