コマンドラインの一部の構築または全体の構築に必要なデータを、メモリ効率の高い方法でカプセル化するオブジェクト。
多くの場合、アクションには、伝播依存関係から蓄積された値を含む大きなコマンドラインが必要になります。たとえば、リンカー コマンドラインには、リンクされるすべてのライブラリに必要なすべてのオブジェクト ファイルが一覧表示されます。このような伝播データを depset
に保存して、複数のターゲットで共有することをおすすめします。ただし、ルール作成者がアクション コマンドラインを作成する際にこれらの 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
値に変換されます。- 他のすべての型は、未指定の方法で文字列に変換されます。そのため、文字列型または
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)
処理のほとんどは、次の手順に沿って、追加される引数のリストに対して行われます。
- 各ディレクトリ
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
|
シーケンスまたはdepset(デフォルトは unbound )。アイテムを追加するリスト、タプル、または depset。 |
map_each
|
呼び出し可能関数、または None 。デフォルトは None 。各アイテムを 0 個以上の文字列に変換する関数。追加前にさらに処理できます。このパラメータを指定しない場合は、標準変換が使用されます。 この関数には、変換するアイテムと、オプションの 戻り値の型は、アイテムに生成される引数の数によって異なります。
None を返すと、それぞれ長さ 1 または長さ 0 のリストが返されるのと同じ効果があります。ただし、リストが不要な場合は作成しないようにすると、効率的で読みやすくなります。通常、ディレクトリであるアイテムは、 分析フェーズで生成された大規模なデータ構造が実行フェーズに意図せず保持されないようにするには、 警告: |
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
|
文字列、または 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()
とは異なり、アイテムが 1 つの引数に結合される場合は通常有用ではないため、before_each
パラメータや terminate_with
パラメータはありません。
フィルタ後に引数に結合する文字列が存在せず、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
|
呼び出し可能。または 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
|
必須 次のいずれかである必要があります。
呼び出されなかった場合、形式はデフォルトで「shell」になります。 |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)
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 はシステムと引数の長さに基づいて、引数をスピンアウトする必要があるかどうかを判断します。 |