アクション

問題を報告 ソースを表示 ナイトリー · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

アクションを作成するための関数を提供するモジュール。このモジュールにアクセスするには、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」がない場合指定された新しいファイルのパス（現在のパッケージに対する相対パス）。それ以外の場合は、ファイルのベース名を指定します（兄弟要素でディレクトリが決まります）。
sibling File:または None デフォルトは None
です 新しく作成されたファイルと同じディレクトリに存在するファイル。ファイルは現在のパッケージ内に存在する必要があります。 

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

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

パラメータ

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

do_nothing

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

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

パラメータ

パラメータ 説明
mnemonic 必須
アクションの 1 単語の説明（CppCompile や GoLink など）。
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。 デフォルトは [] です
アクションの入力ファイルのリストまたは依存関係。
unused_inputs_list File:または None デフォルトは None
です アクションで使用しない入力のリストを含むファイル。

このファイルの内容（通常はアクションの出力の一つ）は、アクションの実行中に使用されなかった入力ファイルのリストに対応しています。これらのファイルを変更しても、アクションの出力にはどのような影響も及びません。

executable File:または stringまたは FilesToRunProvider。 必須
アクションによって呼び出される実行可能ファイル。
tools sequence;または depset デフォルトは unbound
アクションに必要なツールを列挙またはデプロイします。ツールは、アクションで自動的に使用可能になる追加のランファイルを含む入力です。リストを指定する場合、Files の異種コレクション、FilesToRunProvider インスタンス、または Files の Depset になります。リスト内に直接あり、{6}cache.executable からのファイルには、runfile が自動的に追加されます。依存関係を指定する場合は、Files のみを含める必要があります。いずれの場合も、depset 内のファイルは、runfile で HDFS.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_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 string;または None デフォルトは None
です 指定された実行グループの実行プラットフォームでアクションを実行します。指定しない場合、ターゲットのデフォルトの実行プラットフォームが使用されます。
shadowed_action 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 ラベル:または stringまたは 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 ファイルのシーケンス 必須
アクションの出力ファイルのリスト。
inputs ファイルのシーケンスまたは depset。 デフォルトは [] です
アクションの入力ファイルのリストまたは依存関係。
tools ファイルのシーケンスまたは depset。 デフォルトは unbound です
アクションに必要なツールを列挙またはデプロイします。ツールは、アクションで自動的に使用可能になる追加のランファイルを含む入力です。このリストには、Files インスタンスまたは FilesToRunProvider インスタンスを含めることができます。
arguments sequence; デフォルトは []
です アクションのコマンドライン引数。文字列または actions.args() オブジェクトのリストにする必要があります。

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

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

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

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;または 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 string;または None デフォルトは None
です 指定された実行グループの実行プラットフォームでアクションを実行します。指定しない場合、ターゲットのデフォルトの実行プラットフォームが使用されます。
shadowed_action Action: デフォルトは None
です アクションの入力リストに追加された、指定されたシャドウ アクションで検出された入力を使用してアクションを実行します。指定しない場合、アクションの入力のみを使用します。
resource_set callableまたは None デフォルトは None
ローカルで実行する場合のリソース使用量を見積もるためのコールバック関数。ctx.actions.run() を参照してください。
toolchain ラベル:または stringまたは 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 を使用する場合は、output を declare_file() または declare_directory() で宣言し、target_file の型と一致させます。これにより、シンボリック リンクが target_file を指すようになります。Bazel は、シンボリック リンクのターゲットまたはその内容が変更されるたびに、このアクションの出力を無効にします。

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

パラメータ

パラメータ 説明
output 必須
このアクションの出力。
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 オブジェクトを返します。

write

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

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

パラメータ

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