コマンドラインの一部または全体を構築するために必要なデータをメモリ効率の高い方法でカプセル化するオブジェクト。
アクションが推移的依存関係から蓄積された値を含む大きなコマンドラインを必要とすることがよくあります。たとえば、リンカー コマンドラインでは、リンクされるすべてのライブラリが必要とするすべてのオブジェクト ファイルをリストできます。このような推移的データは、複数のターゲットで共有できるように 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 にする必要があります。list、タプル、depset、またはディレクトリ File は、このメソッドの代わりに add_all() または add_joined() に渡す必要があります。
|
format
|
string;または 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)このコマンドラインに複数の引数を追加します。アイテムは実行フェーズで遅延して処理されます。
ほとんどの処理は、次の手順に従って、追加する引数のリストに対して行われます。
- ディレクトリの各
File
項目は、そのディレクトリに再帰的に含まれているすべてのFile
に置き換えられます。 map_each
を指定すると、各アイテムに適用され、文字列の結果リストが連結されて最初の引数リストが生成されます。それ以外の場合、最初の引数リストは、各項目に標準変換を適用した結果です。- リスト内の各引数は、
format_each
の形式になります(存在する場合)。 uniquify
が true の場合、重複する引数が削除されます。最初に一致したものが残ります。before_each
文字列を指定すると、新しい引数としてリスト内の既存の各引数の前に挿入されます。これにより、この時点までに追加される引数の数が実質的に 2 倍になります。- リストが空で、
omit_if_empty
が true(デフォルト)である場合を除き、引数名とterminate_with
が指定されている場合は、それぞれ最初と最後の引数として挿入されます。
パラメータ
パラメータ | 説明 |
---|---|
arg_name_or_values
|
必須 2 つの位置パラメータが渡された場合、引数名として解釈されます。引数名は、 values の前に、処理を行わずに別の引数として追加されます。omit_if_empty が true(デフォルト)で、他のアイテムが追加されていない場合(values が空であるか、そのアイテムがすべてフィルタされている場合)、この引数名は追加されません。渡される位置パラメータが 1 つだけの場合は、values と解釈されます(以下を参照)。
|
values
|
sequence;または depset
デフォルトは unbound 項目が追加されるリスト、タプル、または depset。 |
map_each
|
callableまたは None
デフォルトは None 各項目を 0 個以上の文字列に変換する関数。文字列は付加前にさらに処理できます。このパラメータが指定されていない場合、標準の変換が使用されます。 この関数には、1 つまたは 2 つの位置引数が渡されます。変換対象アイテムの後に、省略可能な 戻り値の型は、そのアイテムに対して生成される引数の数によって異なります。
None を返すことは、それぞれ長さ 1 または長さ 0 のリストを返すのと同じ効果があります。ただし、不要なリストを作成しないようにするほうが、効率的で読みやすいものになります。通常、ディレクトリのアイテムは、 分析フェーズの大規模なデータ構造が実行フェーズに意図せず保持されないように、トップレベルの 警告: |
format_each
|
string;または None
デフォルトは None です map_each 関数によって返される各文字列に適用される、オプションの形式設定文字列パターン。形式文字列には「%s」を 1 つだけ含める必要があります使用します。
|
before_each
|
string;または None
デフォルトは None です values から派生した各引数の前に付加するオプションの引数が追加されます。
|
omit_if_empty
|
bool;
デフォルトは True です true の場合、追加する values から派生した引数がない場合、それ以降の処理はすべて抑制され、コマンドラインは変更されません。false の場合、引数名と terminate_with (指定されている場合)は、他の引数があるかどうかにかかわらず、引き続き追加されます。
|
uniquify
|
bool;
デフォルトは False です true の場合、 values から派生した重複する引数は省略されます。各引数が最初に一致したもののみが残ります。依存関係はすでに重複が省略されているため、通常この機能は必要ありませんが、map_each が複数の項目に対して同じ文字列を出力する場合は便利です。
|
expand_directories
|
bool;
デフォルトは True です true の場合、 values 内のディレクトリはファイルのフラットリストに展開されます。これは、map_each が適用される前に行われます。
|
terminate_with
|
string;または None
デフォルトは None です 他のすべての引数の後に追加するオプションの引数。 omit_if_empty が true(デフォルト)の場合、この引数は追加されず、他のアイテムは追加されません(values が空であるか、そのアイテムがすべてフィルタされた場合に発生する)。
|
allow_closure
|
bool;
デフォルトは 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;または depset
デフォルトは unbound 項目を結合するリスト、タプル、または depset。 |
join_with
|
string;
必須string.join() と同じ方法で map_each と format_each を適用して取得した文字列を結合するために使用される区切り文字。
|
map_each
|
callableまたは None
デフォルトは None add_all と同じです。
|
format_each
|
string;または None
デフォルトは None です add_all と同じです。
|
format_joined
|
string;または None
デフォルトは None です 結合された文字列に適用されるオプションの形式文字列パターン。形式文字列には「%s」を 1 つだけ含める必要があります使用します。 |
omit_if_empty
|
bool;
デフォルトは True です true の場合、結合する文字列がない場合( values が空であるか、そのアイテムがすべてフィルタされているため)、それ以降の処理はすべて抑制され、コマンドラインは変更されません。false の場合、結合する文字列がない場合でも、2 つの引数が追加されます。引数名の後に空の文字列(ゼロの文字列を論理的に結合したもの)が続きます。
|
uniquify
|
bool;
デフォルトは False です add_all と同じです。
|
expand_directories
|
bool;
デフォルトは True です add_all と同じです。
|
allow_closure
|
bool;
デフォルトは False です add_all と同じです。
|
set_param_file_format
Args Args.set_param_file_format(format)パラメータ ファイルの形式を設定します(使用している場合)。
パラメータ
パラメータ | 説明 |
---|---|
format
|
string;
必須 次のいずれかにする必要があります。
デフォルトの形式は「shell」です。渡されます。 |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)引数を params ファイルにスピルし、param ファイルへのポインタに置き換えます。システムのコマンド長の上限に対して引数が大きすぎる可能性がある場合に使用します。
Bazel では、効率を高めるために、実行中に params ファイルの出力ツリーへの書き込みを省略する場合があります。アクションをデバッグしていて param ファイルを調べる場合は、ビルドに --materialize_param_files
を渡します。
パラメータ
パラメータ | 説明 |
---|---|
param_file_arg
|
string;
必須 「%s」を 1 つ含むフォーマット文字列。引数が params ファイルにあふれた場合、params ファイルのパスでフォーマットされたこの文字列で構成される引数に置き換えられます。 たとえば、引数がパラメータ ファイル「params.txt」にあふれている場合は、「--file=%s」を指定します。アクションのコマンドラインに「--file=params.txt」が含まれるようになります。 |
use_always
|
bool;
デフォルトは False です 引数を常に params ファイルにオーバーフローするかどうか。false の場合、bazel はシステムと引数の長さに基づいて、引数をあふれさせる必要があるかどうかを判断します。 |