アクション

Action の作成関数を提供するモジュール。このモジュールには ctx.actions を使用してアクセスします。

メンバー

args

Args actions.args()

メモリ効率の高いコマンドラインを作成するのに使用できる Args オブジェクトを返します。

declare_directory

File actions.declare_directory(filename, *, sibling=None)

ルールまたはアスペクトが、現在のパッケージ内に指定の名前のディレクトリを作成することを宣言します。ディレクトリを生成するアクションを作成する必要があります。ディレクトリの内容には Starlark から直接アクセスできませんが、Args.add_all() を使用してアクション コマンドで展開できます。predicted_directory の展開済みコンテンツに含めることができるのは、通常のファイルとディレクトリのみです。

パラメータ

パラメータ 説明
filename required
sibling が指定されていない場合、新しいディレクトリのパス（現在のパッケージを基準とする相対パス）。それ以外の場合は、ファイルのベース名（「兄弟」はディレクトリを定義します）。
sibling ファイル、または None。デフォルトは None。
新しく宣言されたディレクトリと同じディレクトリにあるファイル。ファイルは現在のパッケージ内に存在する必要があります。

declare_file

File actions.declare_file(filename, *, sibling=None)

ルールまたはアスペクトが指定されたファイル名のファイルを作成することを宣言します。sibling が指定されていない場合、ファイル名はパッケージ ディレクトリを基準とします。指定されている場合は、ファイルは sibling と同じディレクトリにあります。現在のパッケージの外部でファイルを作成することはできません。

ファイルを宣言するだけでなく、ファイルを出力するアクションを別途作成する必要があります。このアクションを作成するには、返された File オブジェクトをアクションの作成関数に渡す必要があります。

事前宣言された出力ファイルは、この関数を使用して宣言する必要はありません（宣言できません）。代わりに、ctx.outputs から File オブジェクトを取得できます。使用例をご覧ください。

パラメータ

パラメータ 説明
filename 必須
「兄弟」が指定されていない場合、現在のパッケージを基準とする新しいファイルのパス。それ以外の場合は、ファイルのベース名（兄弟要素でディレクトリが決まります）。
sibling ファイル、または None。デフォルトは None。
新しく作成されたファイルと同じディレクトリにあるファイル。ファイルは現在のパッケージ内に存在する必要があります。		 

File actions.declare_symlink(filename, *, sibling=None)

ルールまたはアスペクトが、現在のパッケージに指定された名前のシンボリック リンクを作成することを宣言します。このシンボリック リンクを生成するアクションを作成する必要があります。Bazel は、このシンボリック リンクを参照解除することはなく、そのままサンドボックスまたはリモート エグゼキュータに転送します。ツリー アーティファクト内のシンボリック リンクは現在サポートされていません。

パラメータ

パラメータ 説明
filename 必須
「兄弟」が指定されていない場合、現在のパッケージに対する新しいシンボリック リンクのパス。それ以外の場合は、ファイルのベース名（「兄弟」はディレクトリを定義します）。
sibling ファイル、または None。デフォルトは None。
新しく宣言されたシンボリック リンクと同じディレクトリにあるファイル。

do_nothing

None actions.do_nothing(mnemonic, inputs=[])

コマンドを実行も出力も生成しない空のアクションを作成しますが、これは「追加のアクション」を挿入する場合に便利です。

パラメータ

パラメータ 説明
mnemonic required
CppCompile や GoLink など、アクションの 1 単語の説明。
inputs ファイルのシーケンスまたはdepset。デフォルトは []
。アクションの入力ファイルのリスト。

expand_template

None actions.expand_template(template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)

テンプレートの展開アクションを作成します。アクションを実行すると、テンプレートに基づいてファイルが生成されます。テンプレートの一部は、置換が指定された順序で substitutions ディクショナリを使用して置き換えられます。テンプレート（または以前の置換の結果）に辞書のキーが出現するたびに、関連する値に置き換えられます。キーに特別な構文はありません。たとえば、競合を避けるために中かっこを使用できます（例: {KEY}）。使用例を見る

パラメータ

パラメータ 説明
template 必須
UTF-8 でエンコードされたテキスト ファイルであるテンプレート ファイル。
output 必須
UTF-8 でエンコードされたテキスト ファイルである出力ファイル。
substitutions デフォルトは {} です。
テンプレートの拡張時に行う置換。
is_executable デフォルトは False
です。出力ファイルを実行可能にするかどうか。
computed_substitutions TemplateDict: デフォルトは unbound
。テンプレートを拡張するときに行う置換です。

run

None actions.run(outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)

実行可能ファイルを実行するアクションを作成します。使用例をご覧ください。

パラメータ

パラメータ 説明
outputs ファイルのシーケンス。必須
アクションの出力ファイルのリスト。
inputs ファイルのシーケンスまたはdepset。デフォルトは []
。アクションの入力ファイルのリストまたは depset。
unused_inputs_list ファイル、または None。デフォルトは None。
アクションで使用されない入力のリストを含むファイル。

このファイルの内容（通常はアクションの出力の 1 つ）は、アクションの実行全体で使用されなかった入力ファイルのリストに対応しています。これらのファイルの変更が、アクションの出力に影響を与えないようにする必要があります。

executable ファイル、文字列、FilesToRunProvider。必須
アクションによって呼び出される実行可能ファイル。
tools sequence または depset。デフォルトは unbound です。
アクションに必要なツールのリストまたは depset。ツールは、アクションで自動的に使用できる追加のランファイルを備えた入力です。リストが指定されている場合は、Files、FilesToRunProvider インスタンス、または Files の depset の異種コレクションにすることができます。リスト内に直接あり、{6}cache.executable からのファイルには、runfile が自動的に追加されます。depset を指定する場合は、Files のみを含める必要があります。どちらの場合も、depset 内のファイルは、runfile の ctx.executable と相互参照されません。
arguments 順序: デフォルトは [] です
アクションのコマンドライン引数。文字列または actions.args() オブジェクトのリストにする必要があります。
mnemonic string; または None: デフォルトは None
アクションの 1 単語の説明（例: CppCompile、GoLink）。
progress_message 文字列、または None。デフォルトは None。
ビルド中にユーザーに表示する進行状況メッセージ（「foo.cc をコンパイルして foo.o を作成」など）。メッセージには %{label}、%{input}、%{output} のいずれかのパターンが含まれ、それぞれラベル文字列、最初の入力、出力のパスに置き換えられます。静的文字列ではなくパターンを使用する方が効率的であるため、パターンを使用します。
use_default_shell_env デフォルトは False
アクションでデフォルトのシェル環境を使用するかどうか。デフォルトのシェル環境は、OS に依存するいくつかの変数と --action_env で設定された変数で構成されます。

use_default_shell_env と env の両方が True に設定されている場合、--incompatible_merge_fixed_and_default_shell_env が有効になっている（デフォルト）と、env に設定された値がデフォルトのシェル環境を上書きします。フラグが有効になっていない場合、env は無視されます。
env dict、または None。デフォルトは None です。
環境変数の辞書を設定します。

use_default_shell_env と env の両方が True に設定されている場合、--incompatible_merge_fixed_and_default_shell_env が有効になっている（デフォルト）と、env に設定された値がデフォルトのシェル環境を上書きします。フラグが有効になっていない場合、env は無視されます。
execution_requirements dict、または None（デフォルトは None）
アクションのスケジュール設定に関する情報。役立つキーについては、タグをご覧ください。
input_manifests sequence、または None。デフォルトは None。
（試験運用版）は、入力ランファイルのメタデータを設定します。通常は resolve_command によって生成されます。
exec_group 文字列、または None。デフォルトは None。
指定された実行グループの実行プラットフォームでアクションを実行します。指定しない場合、ターゲットのデフォルトの実行プラットフォームが使用されます。
shadowed_action アクション。デフォルトは None
。指定されたシャドウされたアクションの入力と、アクションの入力リストと環境に追加された環境を使用してアクションを実行します。アクション環境は、シャドウされたアクションの環境変数をオーバーライドできます。指定しない場合、アクションの入力と指定された環境のみを使用します。
resource_set コールバック関数、または None。デフォルトは None。
リソースセット ディクショナリを返すコールバック関数。このアクションがローカルで実行される場合、実行時のリソース使用量の推定に使用されます。

この関数は、OS 名を表す文字列（osx など）と、アクションへの入力の数を表す整数という 2 つの位置引数を受け取ります。返される辞書には、次のエントリが含まれます。各エントリは浮動小数点数または整数です。

  • "cpu": CPU の数。デフォルトは 1
  • "memory": MB 単位。デフォルトは 250
  • "local_test": ローカルテストの数（デフォルト: 1）

このパラメータが None に設定されている場合、または --experimental_action_resource_set が false の場合、デフォルト値が使用されます。

コールバックはトップレベルである必要があります（ラムダ関数とネストされた関数は使用できません）。
toolchain ラベル、文字列、または None。デフォルトは unbound
です。

このアクションで使用される実行可能ファイルまたはツールのツールチェーン タイプ。アクションが正しい実行プラットフォームで実行されるように、パラメータを設定する必要があります。

現在は no-op ですが、今後の Bazel リリースで必須となるため、ツールチェーンを使用する場合は設定することをおすすめします。

このアクションを作成するルールでは、「rule()」関数内でこのツールチェーンを定義する必要があります。

「toolchain」パラメータと「exec_group」パラメータの両方が設定されている場合、「exec_group」が使用されます。「exec_group」が同じ値を指定していない場合、エラーが発生します。

run_shell

None actions.run_shell(outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)

シェルコマンドを実行するアクションを作成します。使用例をご覧ください。

パラメータ

パラメータ 説明
outputs ファイルのシーケンス。必須
アクションの出力ファイルのリスト。
inputs ファイルのシーケンスまたはdepset。デフォルトは []
。アクションの入力ファイルのリストまたは depset。
tools ファイルのシーケンスまたはdepset。デフォルトは unbound
。アクションに必要なツールのリストまたは depset。ツールは、アクションで自動的に使用できる追加のランファイルを備えた入力です。このリストには、Files または FilesToRunProvider のインスタンスを含めることができます。
arguments sequence: デフォルトは []
です。アクションのコマンドライン引数。文字列または actions.args() オブジェクトのリストにする必要があります。

Bazel は、この属性の要素をコマンドに引数として渡します。コマンドは、$1、$2 などのシェル変数置換を使用してこれらの引数にアクセスできます。Args オブジェクトはインデックス化の前にフラット化されるため、サイズが不明な Args オブジェクトがある場合、その後のすべての文字列は予測できないインデックスになります。サイズが不明な Args オブジェクトと組み合わせて $@（すべての引数を取得）を使用すると便利です。

command が文字列のリストである場合、このパラメータは使用できません。

mnemonic 文字列、または None。デフォルトは None。
アクションの 1 語の説明（CppCompile や GoLink など）。
command 文字列、または文字列のシーケンス。必須
実行するシェルコマンド。文字列（推奨）か、文字列のシーケンス（非推奨）になります。

command が文字列の場合、sh -c <command> "" <arguments> によって実行されるように実行されます。つまり、arguments 内の要素は、$1、$2（Windows バッチを使用している場合は %1、%2）としてコマンドで使用できるようになります。arguments に actions.args() オブジェクトが含まれている場合、その内容はコマンドラインに一行ずつ追加されるため、$i は Args オブジェクト内の個々の文字列を参照できます。サイズが不明な Args オブジェクトが arguments の一部として渡された場合、文字列は不明なインデックスになります。この場合は、$@ シェル置換（すべての引数を取得）が役に立ちます。

（非推奨）command が文字列のシーケンスの場合、最初の項目は実行する実行可能ファイルで、残りの項目はその引数です。この形式を使用する場合、arguments パラメータを指定しないでください。なお、このフォームは非推奨となり、まもなく削除される予定です。これは `--incompatible_run_shell_command_string` で無効になります。このフラグを使用して、コードが互換性があることを確認してください。

Bazel では、genrules と同じシェルを使用してコマンドを実行します。

progress_message string; または None: デフォルトは None
ビルド中にユーザーに表示される進行状況メッセージ（例: 「Compiling foo.cc to create foo.o」）。メッセージには %{label}、%{input}、%{output} のいずれかのパターンが含まれ、それぞれラベル文字列、最初の入力、出力のパスに置き換えられます。静的文字列ではなくパターンを使用することをおすすめします。パターンの方が効率的です。
use_default_shell_env デフォルトは False
アクションでデフォルトのシェル環境を使用するかどうか。デフォルトのシェル環境は、OS に依存するいくつかの変数と --action_env で設定された変数で構成されます。

use_default_shell_env と env の両方が True に設定されている場合、--incompatible_merge_fixed_and_default_shell_env が有効になっている（デフォルト）と、env に設定された値がデフォルトのシェル環境を上書きします。このフラグが有効になっていない場合、env は無視されます。

env dict、または None。デフォルトは None です。
環境変数の辞書を設定します。

use_default_shell_env と env の両方が True に設定されている場合、--incompatible_merge_fixed_and_default_shell_env が有効になっている（デフォルト）と、env に設定された値がデフォルトのシェル環境を上書きします。このフラグが有効になっていない場合、env は無視されます。

execution_requirements dict、または None（デフォルトは None）
アクションのスケジュール設定に関する情報。役立つキーについては、タグをご覧ください。
input_manifests sequence、または None。デフォルトは None。
（試験運用版）は、入力ランファイルのメタデータを設定します。通常は resolve_command によって生成されます。
exec_group 文字列、または None。デフォルトは None。
指定された実行グループの実行プラットフォームでアクションを実行します。指定しない場合、ターゲットのデフォルトの実行プラットフォームが使用されます。
shadowed_action Action: デフォルトは None です。
指定されたシャドウ アクションで検出された入力がアクションの入力リストに追加され、その入力を使用してアクションを実行します。指定しない場合、アクションの入力のみが使用されます。
resource_set 呼び出し可能関数、または None。デフォルトは None。
ローカルで実行する場合のリソース使用量を推定するコールバック関数。ctx.actions.run() をご覧ください。
toolchain ラベル、文字列、または None。デフォルトは unbound
です。

このアクションで使用される実行可能ファイルまたはツールのツールチェーン タイプ。アクションが正しい実行プラットフォームで実行されるように、パラメータを設定する必要があります。

現在は no-op ですが、今後の Bazel リリースで必須となるため、ツールチェーンを使用する場合は設定することをおすすめします。

このアクションを作成するルールでは、「rule()」関数内でこのツールチェーンを定義する必要があります。

「ツールチェーン」と「exec_group」の両方のパラメータが設定されている場合、`exec_group` が使用されます。「exec_group」で同じ toolchain が指定されていない場合、エラーが発生します。

 

None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)

ファイル システムにシンボリック リンクを書き込成するアクションを作成します。

この関数は、target_file または target_path のいずれか 1 つのみを指定して呼び出す必要があります。

target_file を使用する場合は、declare_file() または declare_directory() で output を宣言し、target_file の型と一致させます。これにより、シンボリック リンクが target_file を指すようになります。Bazel は、シンボリック リンクのターゲットまたはその内容が変更されるたびに、このアクションの出力を無効にします。

それ以外の場合は、target_path を使用する場合は declare_symlink() で output を宣言します。この場合、シンボリック リンクは target_path を参照します。Bazel はシンボリック リンクを解決しません。このアクションの出力が無効になるのは、シンボリック リンクのテキスト コンテンツ（readlink() の値）が変更された場合のみです。特に、ダングリング シンボリック リンクの作成に使用できます。

パラメータ

パラメータ 説明
output 必須
このアクションの出力。
target_file ファイル、または None（デフォルトは None）
出力シンボリック リンクが参照するファイル。
target_path 文字列または None。 デフォルトは None です。
出力シンボリック リンクが指す正確なパス。正規化などの処理は適用されません。
is_executable デフォルトは False
target_path ではなく target_file でのみ使用できます。true の場合、アクションの実行時に target_file のパスを確認して実行可能かどうかを判断し、実行可能でない場合エラーを報告します。is_executable を False に設定しても、ターゲットが実行不可であるわけではなく、単に検証が行われないだけです。

ビルド時にダングル シンボリック リンクが存在しない可能性があるため、この機能は target_path には適していません。
progress_message string: None: デフォルトは None です
ビルド中にユーザーに表示される進行状況メッセージ。

template_dict

TemplateDict actions.template_dict()

メモリ効率の高いテンプレート展開用の TemplateDict オブジェクトを返します。

write

None actions.write(output, content, is_executable=False)

ファイル書き込みアクションを作成します。アクションの実行時に、指定されたコンテンツがファイルに書き込まれます。これは、分析フェーズで利用可能な情報を使用してファイルを生成するために使用されます。ファイルが大きく、静的コンテンツが多い場合は、expand_template の使用を検討してください。

パラメータ

パラメータ 説明
output 必須
出力ファイル。
content 文字列、または 引数。
ファイルの内容。文字列または actions.args() オブジェクトのいずれかになります。
is_executable デフォルトは False
です。出力ファイルを実行可能にするかどうか。