アクション

問題を報告 ソースを表示

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

メンバー

args

Args actions.args()

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

宣言ディレクトリ

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

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

パラメータ

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

宣言ファイル

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

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

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

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

パラメータ

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

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

このパラメータは試験運用版であり、いつでも変更される可能性があります。--noexperimental_allow_unresolved_symlinks を設定すると無効になる場合があります

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

パラメータ

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

禁止事項

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

コマンドを実行せず、出力もしない空のアクションを作成しますが、「追加のアクション」を挿入すると便利です。

パラメータ

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

拡張テンプレート

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

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

パラメータ

パラメータ 説明
outputs sequence of Files 必須
アクションの出力ファイルのリスト。
inputs sequence of Files; or depset; default = []
アクションの入力ファイルの一覧表示またはデプト。
unused_inputs_list File; or None; default = None
アクションで使用されていない入力のリストを含むファイル。

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

executable File; or string; or FilesToRunProvider(必須)
アクションによって呼び出される実行可能ファイル。
tools sequence; or depset; default = unbound
アクションに必要なツールのリストまたはデプト。ツールは、自動的に追加された実行ファイルを含む入力です。リストが提供されると、リストには Files、FilesToRunProvider インスタンス、ファイルのセットが含まれます。リストに直接含まれ、ctx.executable に由来するファイルには、ランファイルが自動的に追加されます。DEPSET を指定する場合は、Files のみを含める必要があります。どちらの場合も、デセット内のファイルは、runfile の ctx.executable と相互参照されません。
arguments sequence; default = []
アクションのコマンドライン引数。文字列または actions.args() オブジェクトのリストである必要があります。
mnemonic string; or None; default = None
アクションの 1 語の説明(例: CppCompile、GoLink)。
progress_message string; or None; default = None
ビルド中にユーザーに表示される進行状況メッセージ(例: 「foo.cc を作成して foo.o を作成する」など)。メッセージには %{label}%{input}、または %{output} のパターンを含めることができ、それぞれラベル文字列、最初の入力、出力のパスに置き換えられます。前者の方が効率的であるため、静的な文字列ではなくパターンを使用することをおすすめします。
use_default_shell_env default = False
アクションが組み込みのシェル環境を使用するかどうか。
env dict; or None; default = None
環境変数のディクショナリを設定します。
execution_requirements dict; or None; デフォルト = なし
アクションのスケジュール設定に関する情報。有用なキーについては、タグをご覧ください。
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 つの位置引数を受け入れます。OS 名(「osx」など)を表す文字列と、アクションへの入力数を表す整数です。返される辞書には、次のエントリを含めることができます。各エントリは浮動小数点数または整数です。

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

このパラメータを None に設定するか、--experimental_action_resource_set を false に設定すると、デフォルト値が使用されます。

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

toolchain Label; or string; or None(デフォルト = 制限なし)

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

現時点では noop ではありませんが、今後の 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 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
アクションの 1 語の説明(例: CppCompile、GoLink)。
command string; or sequence of strings (必須)
実行するシェルコマンド。これは文字列(推奨)か、一連の文字列(非推奨)のいずれかになります。

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; or None; default = None
ビルド中にユーザーに表示される進行状況メッセージ(例: 「foo.cc を作成して foo.o を作成する」など)。メッセージには %{label}%{input}、または %{output} のパターンを含めることができ、それぞれラベル文字列、最初の入力、出力のパスに置き換えられます。前者の方が効率的であるため、静的な文字列ではなくパターンを使用することをおすすめします。
use_default_shell_env default = False
アクションが組み込みのシェル環境を使用するかどうか。
env dict; or None; default = None
環境変数のディクショナリを設定します。
execution_requirements dict; or None; デフォルト = なし
アクションのスケジュール設定に関する情報。有用なキーについては、タグをご覧ください。
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(デフォルト = 制限なし)

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

現時点では noop ではありませんが、今後の 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 必須
このアクションの出力。
target_file File; or None; default = None
出力シンボリック リンクが指すファイル。
target_path string; or None; default = None
出力シンボリック リンクが指す正確なパス。正規化などの処理は適用されません。
is_executable default = False
target_file でのみ使用できます。target_path では使用できません。true の場合、アクションの実行時に target_file のパスが実行可能であることを確認し、実行されていない場合はエラーが報告されます。is_executable を False に設定しても、ターゲットが実行可能でないということではなく、検証が行われていないだけです。

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

progress_message string; or None; default = None
ビルド中にユーザーに表示する進行状況メッセージ。

template_dict

TemplateDict actions.template_dict()

試験運用版。この API は試験運用版であり、随時変更される可能性があります。依存しないでください。試験運用版では、--+experimental_lazy_template_expansion
を設定することで有効になります。試験運用版: メモリ効率の良いテンプレートの拡張のために TemplateDict オブジェクトを返します。

書き込み

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

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

パラメータ

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