アクション

問題を報告する ソースを表示

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

メンバー

args

Args actions.args()

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

declare_directory

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

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

パラメータ

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

do_nothing

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

コマンドの実行も出力も生成しない空のアクションを作成しますが、「追加のアクション」を挿入するために役立ちます。

パラメータ

パラメータ 説明
mnemonic 必須
アクションの 1 単語の説明(例: CppCompile、GoLink)。
inputs Fileシーケンス、または 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 Fileシーケンス。必須
アクションの出力ファイルのリスト。
inputs Fileシーケンス、または depset。デフォルトは []
アクションの入力ファイルのリストまたは依存関係。
unused_inputs_list File、または None(デフォルトは None
アクションで使用されていない入力のリストを含むファイル。

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

executable File文字列、または FilesToRunProvider。必須
アクションによって呼び出される実行可能ファイル。
tools sequence、または depset、デフォルトは unbound
アクションに必要なツールのリストまたはデプセット。ツールとは、追加の実行ファイルを含む入力であり、アクションで自動的に利用可能になります。リストが提供される場合は、Files、FilesToRunProvider インスタンス、または Files のデセットの異種コレクションを指定できます。リストに直接含まれているファイルのうち、 datastore.executable から来るファイルには、実行ファイルが自動的に追加されます。依存関係を指定するときは、ファイルのみを含める必要があります。どちらの場合も、depset 内のファイルは runfile の hangouts.executable と相互参照されません。
arguments sequence。デフォルトは []
アクションのコマンドライン引数。文字列または actions.args() オブジェクトのリストにする必要があります。
mnemonic string、または None。デフォルトは None
アクションの 1 単語の説明(例: CppCompile、GoLink)。
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_envenv の両方が True に設定されている場合、--incompatible_merge_fixed_and_default_shell_env が有効な場合(デフォルト)に、env に設定された値によってデフォルトのシェル環境が上書きされます。このフラグが有効になっていない場合、env は無視されます。

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

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

execution_requirements dict または None(デフォルトは None
アクションをスケジュール設定するための情報。有用なキーについては、タグをご覧ください。
input_manifests sequence、または None(デフォルトは None
(試験運用版)入力の runfiles メタデータを設定します。通常は resolve_command によって生成されます。
exec_group string; または None(デフォルトは None
指定された実行グループの実行プラットフォームでアクションを実行します。何も指定しなかった場合は、ターゲットのデフォルトの実行プラットフォームが使用されます。
shadowed_action アクション(デフォルトは None
指定されたシャドウ アクションの入力と、アクションの入力リストと環境に追加された環境を使用して、アクションを実行します。アクション環境は、シャドウ アクションの環境変数を上書きできます。指定しない場合、アクションの入力と指定された環境のみを使用します。
resource_set callable、または None(デフォルトは None
リソースセット辞書を返すコールバック関数。このアクションがローカルで実行されている場合に、実行時のリソース使用量を見積もるために使用されます。

この関数は 2 つの位置引数を受け入れます。OS 名を表す文字列(「osx」など)と、アクションへの入力の数を表す整数です。返される辞書には、次のエントリが含まれることがあります。各エントリは float または int です。

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

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

コールバックはトップレベルである必要があります(ラムダ関数とネストされた関数は使用できません)。

toolchain ラベル文字列、または None(デフォルトは unbound

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

現時点では何もする必要はありませんが、今後の 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=unbound)

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

パラメータ

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

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

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

mnemonic string、または None。デフォルトは None
アクションの 1 単語の説明(例: CppCompile、GoLink)。
command 文字列、または文字列シーケンス(必須)
実行するシェルコマンド。これは、文字列(推奨)または一連の文字列(非推奨)のいずれかです。

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

(非推奨)command が文字列のシーケンスである場合、最初のアイテムは実行する実行可能ファイル、残りのアイテムはその引数です。この形式を使用する場合は、arguments パラメータを指定しないでください。このフォームはサポートが終了したため、まもなく削除されます。「--compatible_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_envenv の両方が True に設定されている場合、--incompatible_merge_fixed_and_default_shell_env が有効な場合(デフォルト)に、env に設定された値によってデフォルトのシェル環境が上書きされます。このフラグが有効になっていない場合、env は無視されます。

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

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

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

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

現時点では何もする必要はありませんが、今後の 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 を使用する場合は、declare_file() または declare_directory()output を宣言し、target_file の型と一致させます。これにより、シンボリック リンクが target_file を指すようになります。Bazel は、シンボリック リンクのターゲットまたはその内容が変更されるたびに、このアクションの出力を無効にします。

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

パラメータ

パラメータ 説明
output required
このアクションの出力。
target_file File、または None(デフォルトは None)。
出力シンボリック リンクが指すファイル。
target_path string; または None(デフォルトは None
出力シンボリック リンクがポイントする正確なパス。正規化やその他の処理は適用されません。
is_executable デフォルトは False です。
target_file でのみ使用できます。target_path では使用できません。true の場合、アクションの実行時に target_file のパスがチェックされ、実行可能であることが確認され、実行可能でない場合はエラーが報告されます。is_executable を False に設定しても、ターゲットが実行可能ではないということではなく、検証が行われないというだけです。

ビルド時にダングリング シンボリック リンクが存在しない可能性があるため、この機能は target_path には適していません。

progress_message string; または None(デフォルトは None
ビルド中にユーザーに表示される進行状況メッセージ。

template_dict

TemplateDict actions.template_dict()

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

書き込み

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

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

パラメータ

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