アクションを実行するときに、推移的な依存関係から蓄積された値を含む大規模なコマンドラインが必要になることがよくあります。たとえば、リンカー コマンドラインで、リンクされているすべてのライブラリに必要なすべてのオブジェクト ファイルが一覧表示されます。このような推移的なデータを 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
|
required 2 つの位置パラメータが渡された場合、引数名として解釈されます。引数名は値の前に追加され、何も処理されません。位置パラメータが 1 つだけ渡された場合は、 value と解釈されます(下記参照)。 |
value
|
default = unbound 追加するオブジェクト。上記の標準の変換により、文字列に変換されます。この関数には map_each パラメータがないため、value は文字列または File にする必要があります。リスト、タプル、依存関係、ディレクトリ File は、このメソッドの代わりに add_all() または add_joined() に渡す必要があります。
|
format
|
string; or None ;
default = なし書式設定文字列パターン。 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)このコマンドラインに複数の引数を追加します。アイテムは実行フェーズで遅延的に処理されます。
処理のほとんどは、次のように、追加する引数のリストで行われます。
- ディレクトリの各
File
アイテムが、そのディレクトリ内に再帰的に含まれているすべてのFile
に置き換えられます。 map_each
を指定すると、その値が各項目に適用され、文字列のリストが連結されて初期引数リストが作成されます。それ以外の場合、最初の引数リストは、各アイテムに標準変換を適用した結果になります。- リスト内の各引数の形式は
format_each
です(存在する場合)。 uniquify
が true の場合、重複する引数が削除されます。最初の回が残ります。before_each
文字列が指定されている場合は、リスト内の既存の引数の前に新しい引数として挿入されます。これにより、この時点で追加する引数の数が実質的に 2 倍になります。- リストが空で、
omit_if_empty
が true(デフォルト)である場合を除き、引数名とterminate_with
は、指定された最初の引数として挿入され、最後の引数として挿入されます。
パラメータ
パラメータ | 説明 |
---|---|
arg_name_or_values
|
required 2 つの位置パラメータが渡された場合、引数名として解釈されます。引数名は、処理なしで values の前に追加されます。omit_if_empty が true(デフォルト)で、他のアイテムが追加されない場合(values が空の場合、またはそのアイテムがすべてフィルタされている場合など)、この引数名は追加されません。位置パラメータが 1 つだけ渡された場合は、values と解釈されます(下記参照)。 |
values
|
sequence; or depset ;
default = unboundアイテムを追加するリスト、タプル、または depset。 |
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 = なしvalues から派生した各引数が追加される前に追加するオプションの文字列。
|
omit_if_empty
|
default = True true の場合、追加する values から派生した引数がない場合、それ以降の処理はすべて行われず、コマンドラインは変更されません。false の場合、他の引数があるかどうかに関係なく、引数名と terminate_with (指定されている場合)が付加されます。
|
uniquify
|
default = False true の場合、 values から派生した重複する引数は省略されます。各引数の最初の出現のみが残ります。すでに依存関係は省略されているため、通常はこの機能は必要ありませんが、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
|
required 2 つの位置パラメータが渡された場合、引数名として解釈されます。引数名は、処理されずに values の前に追加されます。omit_if_empty が true(デフォルト)で、結合するための values から派生した文字列が存在しない場合(values が空か、そのアイテムがすべてフィルタされた場合に発生することがあります)場合、この引数は追加されません。位置パラメータが 1 つだけ渡された場合は、values と解釈されます(下記参照)。 |
values
|
sequence; or depset ;
default = unboundアイテムを結合するリスト、タプル、または depset。 |
join_with
|
requiredstring.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
|
default = Trueadd_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 では、効率を高めるために、実行時に出力ツリーへのパラメータ ファイルの書き込みを省略できます。アクションをデバッグする際に param ファイルを検査する場合は、ビルドに --materialize_param_files
を渡します。
パラメータ
パラメータ | 説明 |
---|---|
param_file_arg
|
必須 単一の「%s」を含む形式文字列。引数が params ファイルにオーバーフローした場合は、params ファイルのパスでフォーマットされたこの文字列で構成される引数に置き換えられます。 たとえば、引数がパラメータ ファイル「params.txt」にオーバーフローする場合、「--file=%s」を指定すると、アクション コマンドラインに「--file=params.txt」が含まれます。 |
use_always
|
default = False 引数を常にパラメータ ファイルにスピルするかどうか。false の場合、bazel は、引数をスピルする必要があるかどうかをシステムと引数の長さに基づいて決定します。 |