アクション

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

メンバー

args

Args actions.args()

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

declare_directory

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

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

パラメータ

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

declare_file

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

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

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

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

パラメータ

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

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

試験運用中:このパラメータは試験運用中であり、いつでも変更される可能性があります。頼りにしないでください。--experimental_allow_unresolved_symlinks を設定することで、試験運用版で有効にできます。

ルールまたはアスペクトが、現在のパッケージ内に指定された名前のシンボリック リンクを作成することを宣言します。このシンボリック リンクを生成するアクションを作成する必要があります。Bazel では、このシンボリック リンクの逆参照は行わず、そのままサンドボックスまたはリモート エグゼキュータに転送します。

パラメータ

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

do_nothing

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

空のアクションを作成します。このアクションはコマンドを実行せず、出力も生成しませんが、「追加のアクション」を挿入する際に役立ちます。

パラメータ

パラメータ 説明
mnemonic 必須
アクションを 1 単語で説明します（例: CppCompile、GoLink）。
inputs sequence of Files; or depset; default = []
アクションの入力ファイルのリスト。

expand_template

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

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

パラメータ

パラメータ 説明
template 必須
テンプレート ファイル（UTF-8 でエンコードされたテキスト ファイル）。
output 必須
出力ファイル（UTF-8 でエンコードされたテキスト ファイル）。
substitutions default = {}
テンプレートを開くときに使用する置換。
is_executable default = False
出力ファイルを実行可能かどうか。
computed_substitutions TemplateDict; default = unbound
試験運用版。このパラメータは試験運用中であり、いつでも変更される可能性があります。頼りにしないでください。--+experimental_lazy_template_expansion
試験運用版: テンプレートを展開するときに実行する置換。これを設定することで、試験運用版で有効にすることができます。

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=None)

実行可能ファイルを実行するアクションを作成します。使用例を見る。

パラメータ

パラメータ 説明
outputs sequence of Files; 必須
アクションの出力ファイルのリスト。
inputs sequence of Files; or depset; default = []
アクションの入力ファイルのリストまたは依存関係セット。
unused_inputs_list File; or None; default = なし
アクションによって使用されない入力のリストを含むファイル。

このファイルの内容（通常はアクションの出力の 1 つ）は、アクション全体で使用されなかった入力ファイルのリストに対応しています。これらのファイルを変更しても、アクションの出力に影響が及ぶことはありません。
executable File; or string; or FilesToRunProvider; 必須
アクションによって呼び出される実行可能ファイル。
tools sequence; or depset; default = unbound
アクションに必要なツールのリストまたは依存関係。ツールとは、アクションで自動的に利用可能になる追加のランファイルを含む入力です。リストを指定する場合は、Files、FilesToRunProvider インスタンスの異種コレクション、または Files の依存関係の異なるコレクションを指定できます。直接リストにあるファイルのうち、hangouts.executable で作成されたファイルについては、ランファイルが自動的に追加されます。依存関係を指定する場合は、Files のみを含める必要があります。どちらの場合も、depset 内のファイルは runfile の setIamPolicy.executable と相互参照されません。
arguments sequence; default = []
アクションのコマンドライン引数。文字列または actions.args() オブジェクトのリストでなければなりません。
mnemonic string; or None; default = None
CppCompile、GoLink など、アクションの 1 単語の説明。
progress_message string; or None; default = None
ビルド中にユーザーに表示される進行状況メッセージ。例: 「Compiling foo.cc to create foo.o」メッセージには %{label}、%{input}、%{output} のパターンを含めることができます。これらのパターンはそれぞれ、ラベル文字列、最初の入力、出力のパスに置き換えられます。静的文字列ではなくパターンを使用することをおすすめします。静的文字列のほうが効率的です。
use_default_shell_env default = False
アクションが組み込みのシェル環境を使用するかどうか。
env dict; or None; default = None
環境変数の辞書を設定します。
execution_requirements dict; or None; default = なし
アクションのスケジュール設定に関する情報。便利なキーについては、タグをご覧ください。
input_manifests sequence; or None; default = None
（試験運用版）入力 runfiles メタデータを設定します。通常、resolve_command によって生成されます。
exec_group string; or None; default = None
指定されたエグゼクティブ グループの実行プラットフォームでアクションを実行します。指定しなかった場合は、ターゲットのデフォルトの実行プラットフォームが使用されます。
shadowed_action Action; default = None
指定されたシャドウ アクションの入力と、アクションの入力リストと環境に追加された環境を使用して、アクションを実行します。アクション環境では、シャドウアクションの環境変数のいずれかを上書きできます。存在しない場合は、アクションの入力と指定された環境のみを使用します。
resource_set callable; or None; default = None
リソースセット辞書を返すコールバック関数。このアクションがローカルで実行されている場合に、実行時のリソース使用量を見積もるために使用されます。

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

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

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

コールバックはトップレベルでなければなりません（ラムダ関数とネストされた関数は使用できません）。
toolchain Label; or string; or None; デフォルト = なし

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

現時点では何もできませんが、今後の Bazel リリースで必須となるため、ツールチェーンの使用時に設定することをおすすめします。

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

「ツールチェーン」と「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=None)

シェルコマンドを実行するアクションを作成します。使用例を見る。

パラメータ

パラメータ 説明
outputs sequence of Files; 必須
アクションの出力ファイルのリスト。
inputs sequence of Files; or depset; default = []
アクションの入力ファイルのリストまたは依存関係セット。
tools sequence of Files; or depset; default = unbound
アクションに必要なツールのリストまたは依存関係。ツールとは、アクションで自動的に利用可能になる追加のランファイルを含む入力です。リストには、Files または FilesToRunProvider インスタンスを含めることができます。
arguments sequence; default = []
アクションのコマンドライン引数。文字列または actions.args() オブジェクトのリストでなければなりません。

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

command が文字列のリストの場合、このパラメータは使用できません。
mnemonic string; or None; default = None
CppCompile、GoLink など、アクションの 1 単語の説明。
command string; or sequence of strings; 必須
実行するシェルコマンド。文字列（推奨）または文字列のシーケンス（非推奨）のいずれかを指定できます。

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

（非推奨）command が文字列のシーケンスである場合、最初のアイテムが実行可能になり、残りのアイテムがその引数になります。この形式を使用する場合、arguments パラメータを指定することはできません。このフォームはサポートが終了し、まもなく削除されます。これは「--compatible_run_shell_command_string」を使用すると無効になります。このフラグを使用して、コードの互換性を確認できます。

Bazel は、genrules の場合と同じシェルを使用してコマンドを実行します。
progress_message string; or None; default = None
ビルド中にユーザーに表示される進行状況メッセージ。例: 「Compiling foo.cc to create foo.o」メッセージには %{label}、%{input}、%{output} のパターンを含めることができます。これらのパターンはそれぞれ、ラベル文字列、最初の入力、出力のパスに置き換えられます。静的文字列ではなくパターンを使用することをおすすめします。静的文字列のほうが効率的です。
use_default_shell_env default = False
アクションが組み込みのシェル環境を使用するかどうか。
env dict; or None; default = None
環境変数の辞書を設定します。
execution_requirements dict; or None; default = なし
アクションのスケジュール設定に関する情報。便利なキーについては、タグをご覧ください。
input_manifests sequence; or None; default = None
（試験運用版）入力 runfiles メタデータを設定します。通常、resolve_command によって生成されます。
exec_group string; or None; default = None
指定されたエグゼクティブ グループの実行プラットフォームでアクションを実行します。指定しなかった場合は、ターゲットのデフォルトの実行プラットフォームが使用されます。
shadowed_action Action; default = None
アクションの入力リストに追加された、指定されたシャドウ アクションの検出入力を使用して、アクションを実行します。いずれも指定しない場合は、アクションの入力のみを使用します。
resource_set callable; or None; default = None
ローカルで実行されている場合のリソース使用量を見積もるためのコールバック関数。ctx.actions.run() をご覧ください。
toolchain Label; or string; or None; デフォルト = なし

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

現時点では何もできませんが、今後の Bazel リリースで必須となるため、ツールチェーンの使用時に設定することをおすすめします。

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

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

 

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

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

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

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

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

パラメータ

パラメータ 説明
output required
このアクションの出力。
target_file File; or None; default = None
出力シンボリック リンクが指すファイル。
target_path string; or None; default = None
（試験運用版）出力シンボリック リンクが指す正確なパス。正規化やその他の処理は適用されません。この機能を使用するには、--experimental_allow_unresolved_symlinks を設定する必要があります。
is_executable default = False
target_file でのみ使用でき、target_path では使用できません。true の場合、アクションの実行時に target_file のパスがチェックされ、実行可能であることが確認され、そうでない場合はエラーが報告されます。is_executable を False に設定しても、ターゲットが実行不可ということではなく、検証が行われないということです。

ビルド時にダングリング シンボリック リンクが存在しない可能性があるため、この機能は target_path では意味をなしません。
progress_message string; or None; default = なし
ビルド中にユーザーに表示される進行状況メッセージ。

template_dict

TemplateDict actions.template_dict()

試験運用中:この API は試験運用版であり、いつでも変更される可能性があります。頼りにしないでください。--+experimental_lazy_template_expansion
試験運用版: メモリ効率の高いテンプレート展開が可能な TemplateDict オブジェクトを返します。

write

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

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

パラメータ

パラメータ 説明
output 必須
出力ファイル。
content string; or Args。必須。
ファイルの内容。文字列または actions.args() オブジェクトのいずれかです。
is_executable default = False
出力ファイルを実行可能かどうか。