Args

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

アクションを実行するときに、推移的な依存関係から蓄積された値を含む大規模なコマンドラインが必要になることがよくあります。たとえば、リンカー コマンドラインで、リンクされているすべてのライブラリに必要なすべてのオブジェクト ファイルが一覧表示されます。このような推移的なデータを 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
• add_all
• add_joined
• set_param_file_format
• use_param_file

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)

このコマンドラインに複数の引数を追加します。アイテムは実行フェーズで遅延的に処理されます。

処理のほとんどは、次のように、追加する引数のリストで行われます。

1. ディレクトリの各 File アイテムが、そのディレクトリ内に再帰的に含まれているすべての File に置き換えられます。
2. map_each を指定すると、その値が各項目に適用され、文字列のリストが連結されて初期引数リストが作成されます。それ以外の場合、最初の引数リストは、各アイテムに標準変換を適用した結果になります。
3. リスト内の各引数の形式は format_each です（存在する場合）。
4. uniquify が true の場合、重複する引数が削除されます。最初の回が残ります。
5. before_each 文字列が指定されている場合は、リスト内の既存の引数の前に新しい引数として挿入されます。これにより、この時点で追加する引数の数が実質的に 2 倍になります。
6. リストが空で、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 つの位置引数が渡されます。つまり、変換対象のアイテムと、その後にオプションの DirectoryExpander が渡されます。2 番目の引数は、指定された関数がユーザー定義（組み込みではなく）であり、複数のパラメータを宣言している場合にのみ渡されます。 戻り値の型は、そのアイテムに対して生成される引数の数によって異なります。 通常、各アイテムが 1 つの文字列に変換されると、関数はその文字列を返します。 アイテムを完全に除外する場合、この関数は None を返します。 アイテムが複数の文字列になる場合、関数はそれらの文字列のリストを返します。 単一の文字列または None を返すと、それぞれ長さ 1 または長さ 0 のリストを返すのと同じ効果があります。ただし、不要な場合はリストの作成を回避できる方が効率的で読みやすくなります。 通常、ディレクトリであるアイテムは、expand_directories=True が設定されている場合、その内容に自動的に展開されます。ただし、アイテムがフィールドとしてディレクトリを持つ構造体である場合などは、他の値内に含まれるディレクトリは展開されません。この場合、DirectoryExpander 引数を適用すると、指定したディレクトリのファイルを手動で取得できます。 分析フェーズの大規模なデータ構造を実行フェーズに意図せず保持することを回避するには、最上位の def ステートメントで map_each 関数を宣言する必要があります。デフォルトでは、ネストされた関数の終了ではない場合があります。 警告: map_each の呼び出し中に実行される print() ステートメントでは、目に見える出力は生成されません。
format_each	string; or None; default = None map_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	required 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 = False add_all と同じです。
expand_directories	default = True add_all と同じです。
allow_closure	default = False add_all と同じです。

set_param_file_format

Args Args.set_param_file_format(format)

パラメータ ファイルが使用されている場合は、その形式を設定します。

パラメータ

パラメータ	説明
format	必須 次のいずれかにする必要があります。 "multiline": 各項目（引数名または値）をそのままパラメータ ファイルに記述し、その後に改行文字を付けます。 "shell": "multiline" と同じですが、項目はシェルで囲まれます "flag_per_line": "multiline" と同じですが、(1) パラメータ ファイルにはフラグ（「--」で始まる）のみが書き込まれ、フラグの値があれば、それと同じ行に「=」区切り文字で書き込まれます。これは、Abseil フラグ ライブラリで想定されている形式です。 呼び出されない場合、形式はデフォルトの「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 は、引数をスピルする必要があるかどうかをシステムと引数の長さに基づいて決定します。