Args

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

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

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

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*() メソッドにはそれぞれ、追加の位置パラメータを受け取る代替形式があります。これは、残りの引数の前に挿入する「arg name」文字列です。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

# 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_all
• add_joined
• set_param_file_format
• use_param_file

追加

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

パラメータ

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 が指定されている場合は、それぞれ最初と最後の引数として挿入されます。

パラメータ

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(...) のように単一の引数に結合され、指定された format_joined 文字列テンプレートを使用してフォーマットされます。add_all() とは異なり、アイテムが 1 つの引数に結合される場合は通常有用ではないため、before_each パラメータや terminate_with パラメータはありません。

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

パラメータ

set_param_file_format

Args Args.set_param_file_format(format)

パラメータ

use_param_file

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

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

パラメータ