アクション

問題を報告 ソースを表示 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

メンバー

args

Args actions.args()

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

declare_directory

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

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

パラメータ

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

declare_file

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

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

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

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

パラメータ

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

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

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

パラメータ

パラメータ 説明
filename string; required
「sibling」が指定されていない場合、現在のパッケージに対する新しいシンボリック リンクのパス。それ以外の場合は、ファイルのベース名(「sibling」はディレクトリを定義します)。
sibling ファイル。または 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 File; 必須
出力ファイル。UTF-8 でエンコードされたテキスト ファイルです。
substitutions dict; デフォルトは {}
テンプレートを展開するときに行う置換。
is_executable bool; デフォルトは 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 Filesequence。必須
アクションの出力ファイルのリスト。
inputs Filesequence、または depset。デフォルトは []
です。 アクションの入力ファイルのリストまたは depset。
unused_inputs_list ファイル。または None。デフォルトは None
です。 アクションで使用されていない入力のリストを含むファイル。

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

executable Filestring、または FilesToRunProvider。必須
アクションによって呼び出される実行可能ファイル。
tools sequence または depset。デフォルトは unbound
です。 アクションに必要なツールのリストまたは depset。ツールは、アクションで自動的に利用可能になる追加のランファイルを含む入力です。リストが指定されている場合、Files、FilesToRunProvider インスタンス、または Files の depsets の異種コレクションにすることができます。リストに直接含まれていて、ctx.executable から取得されたファイルには、ランファイルが自動的に追加されます。depsset が指定されている場合、Files のみを含める必要があります。どちらの場合も、depsets 内のファイルは runfiles の ctx.executable と相互参照されません。
arguments sequence; デフォルトは []
アクションのコマンドライン引数。文字列または actions.args() オブジェクトのリストにする必要があります。
mnemonic 文字列、または None。デフォルトは None
です。 アクションの 1 語の説明(CppCompile や GoLink など)。
progress_message 文字列、または None。デフォルトは None
です。 ビルド中にユーザーに表示する進行状況メッセージ(例: 「foo.cc をコンパイルして foo.o を作成しています」)。メッセージには %{label}%{input}%{output} のパターンを含めることができます。これらのパターンは、それぞれラベル文字列、最初の入力、出力のパスに置き換えられます。静的文字列よりもパターンを使用することをおすすめします。パターンの方が効率的です。
use_default_shell_env bool。デフォルトは 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
です。 以前の引数。無視されます。
exec_group 文字列、または None。デフォルトは None
です。 指定された実行グループの実行プラットフォームでアクションを実行します。指定しない場合は、ターゲットのデフォルトの実行プラットフォームを使用します。
shadowed_action アクション。デフォルトは None
です。指定されたシャドー アクションの入力と環境を使用してアクションを実行します。この入力と環境は、アクションの入力リストと環境に追加されます。アクション環境は、シャドーイングされたアクションの環境変数を上書きできます。ない場合は、アクションの入力と指定された環境のみを使用します。
resource_set 呼び出し可能、または None。デフォルトは None
です。 このアクションがローカルで実行される場合に、実行時のリソース使用量を推定するために使用される、リソースセット ディクショナリを返すコールバック関数。

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

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

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

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

toolchain ラベル文字列None。デフォルトは unbound
です。

このアクションで使用される実行可能ファイルまたはツールのツールチェーン タイプ。

実行可能ファイルとツールがツールチェーンから取得されていない場合は、このパラメータを `None` に設定します。

実行可能ファイルとツールがツールチェーンから提供される場合、アクションが正しい実行プラットフォームで実行されるように、ツールチェーン タイプを設定する必要があります。

このアクションを作成するルールでは、その 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 Filesequence。必須
アクションの出力ファイルのリスト。
inputs Filesequence、または depset。デフォルトは []
です。 アクションの入力ファイルのリストまたは depset。
tools Filesequence、または 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)などとしてコマンドで使用できます。argumentsactions.args() オブジェクトが含まれている場合、その内容はコマンドラインに 1 つずつ追加されるため、$i は Args オブジェクト内の個々の文字列を参照できます。サイズの不明な Args オブジェクトが arguments の一部として渡されると、文字列は不明なインデックスに配置されます。この場合、$@ シェル置換(すべての引数を取得)が役立ちます。

(非推奨) command が文字列のシーケンスの場合、最初の項目は実行する実行可能ファイルで、残りの項目はその引数です。この形式を使用する場合、arguments パラメータを指定することはできません。なお、このフォームはサポート終了により間もなくご利用いただけなくなります。`--incompatible_run_shell_command_string` で無効になっています。このフラグを使用して、コードの互換性を確認してください。

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

progress_message 文字列、または None。デフォルトは None
です。 ビルド中にユーザーに表示する進行状況メッセージ(例: 「foo.cc をコンパイルして foo.o を作成しています」)。メッセージには %{label}%{input}%{output} のパターンを含めることができます。これらのパターンは、それぞれラベル文字列、最初の入力、出力のパスに置き換えられます。静的文字列よりもパターンを使用することをおすすめします。パターンの方が効率的です。
use_default_shell_env bool。デフォルトは 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
です。 以前の引数。無視されます。
exec_group 文字列、または None。デフォルトは None
です。 指定された実行グループの実行プラットフォームでアクションを実行します。指定しない場合は、ターゲットのデフォルトの実行プラットフォームを使用します。
shadowed_action Action: デフォルトは None
指定されたシャドー アクションの検出された入力がアクションの入力リストに追加された状態で、アクションを実行します。指定しない場合は、アクションの入力のみを使用します。
resource_set 呼び出し可能。または None。デフォルトは None
です。ローカルで実行する場合のリソース使用量を推定するためのコールバック関数。ctx.actions.run() をご覧ください。
toolchain ラベル文字列None。デフォルトは unbound
です。

このアクションで使用される実行可能ファイルまたはツールのツールチェーン タイプ。

実行可能ファイルとツールがツールチェーンから取得されていない場合は、このパラメータを `None` に設定します。

実行可能ファイルとツールがツールチェーンから提供される場合、アクションが正しい実行プラットフォームで実行されるように、ツールチェーン タイプを設定する必要があります。

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

`toolchain` パラメータと `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 ファイル; 必須
このアクションの出力。
target_file ファイル。または None。デフォルトは None
です。 出力シンボリック リンクが指すファイル。
target_path 文字列、または None。デフォルトは None
です。 出力シンボリック リンクが指す正確なパス。正規化などの処理は適用されません。
is_executable bool; デフォルトは False
target_file でのみ使用できます。target_path では使用できません。true の場合、アクションの実行時に target_file のパスがチェックされ、実行可能であることが確認されます。実行可能でない場合はエラーが報告されます。is_executable を False に設定しても、ターゲットが実行不可能になるわけではありません。検証が行われないだけです。

target_path では、ビルド時にぶら下がりシンボリック リンクが存在しない可能性があるため、この機能は意味がありません。

progress_message 文字列、または None。デフォルトは None
です。 ビルド中にユーザーに表示する進行状況メッセージ。

template_dict

TemplateDict actions.template_dict()

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

write

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

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

パラメータ

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