ルールは、Bazel が入力に対して実行する一連のアクションを定義し、一連の出力を生成します。これらのアクションは、ルールの実装関数によって返されるプロバイダで参照されます。たとえば、C++ バイナリルールは次のようになります。
.cpp
ソースファイル(入力)のセットを取得します。- ソースファイルに対して
g++
を実行します(アクション)。 - 実行可能出力と実行時に利用できるようにするその他のファイルとともに
DefaultInfo
プロバイダを返します。 - ターゲットとその依存関係から収集された C++ 固有の情報を使用して、
CcInfo
プロバイダを返します。
Bazel の観点からは、g++
と標準の C++ ライブラリもこのルールの入力になります。ルールの作成者は、ユーザーがルールに指定した入力だけでなく、アクションの実行に必要なすべてのツールとライブラリも考慮する必要があります。
ルールを作成または変更する前に、Bazel のビルドフェーズを十分に理解してください。ビルドの 3 つのフェーズ(読み込み、分析、実行)を理解することが重要です。また、マクロについて学ぶと、ルールとマクロの違いを理解するのに役立ちます。使用を開始するには、まずルールのチュートリアルをご覧ください。このページを参照用として使用します。
Bazel 自体には、いくつかのルールが組み込まれています。これらのネイティブ ルール(genrule
や filegroup
など)は、コアサポートを提供します。独自のルールを定義することで、Bazel がネイティブにサポートしていない言語とツールのサポートを追加できます。
Bazel には、Starlark 言語を使用してルールを作成するための拡張モデルが用意されています。これらのルールは、BUILD
ファイルから直接読み込める .bzl
ファイルに記述します。
独自のルールを定義する際は、ルールがサポートする属性と、その出力の生成方法を決定できます。
ルールの implementation
関数は、分析フェーズでの正確な動作を定義します。この関数は外部コマンドを実行しません。代わりに、実行フェーズで必要に応じてルールの出力を作成するために使用するアクションを登録します。
ルールの作成
.bzl
ファイルで、rule 関数を使用して新しいルールを定義し、結果をグローバル変数に格納します。rule
の呼び出しでは、属性と実装関数を指定します。
example_library = rule(
implementation = _example_library_impl,
attrs = {
"deps": attr.label_list(),
...
},
)
これにより、example_library
という名前のルールの種類が定義されます。
また、rule
の呼び出しでは、ルールが実行ファイル(executable = True
を使用)またはテスト実行可能ファイル(test = True
を使用)を作成するかどうかも指定する必要があります。後者の場合、ルールはテストルールであり、ルールの名前の末尾は _test
にする必要があります。
ターゲットのインスタンス化
ルールは、BUILD
ファイルで読み込んで呼び出すことができます。
load('//some/pkg:rules.bzl', 'example_library')
example_library(
name = "example_target",
deps = [":another_target"],
...
)
ビルドルールの各呼び出しは値を返しませんが、ターゲットを定義するという副作用があります。これをルールのインスタンス化と呼びます。これにより、新しいターゲットの名前と、ターゲットの属性の値を指定します。
ルールは、Starlark 関数から呼び出し、.bzl
ファイルに読み込むこともできます。ルールを呼び出す Starlark 関数は、Starlark マクロと呼ばれます。Starlark マクロは最終的に BUILD
ファイルから呼び出す必要があり、ターゲットをインスタンス化するために BUILD
ファイルが評価される読み込みフェーズでのみ呼び出すことができます。
属性
属性はルールの引数です。属性は、ターゲットの実装に特定の値を提供したり、他のターゲットを参照したりして、依存関係のグラフを作成できます。
ルール固有の属性(srcs
や deps
など)は、属性名のスキーマ(attr
モジュールを使用して作成)へのマップを rule
の attrs
パラメータに渡すことで定義されます。name
や visibility
などの共通の属性は、すべてのルールに暗黙的に追加されます。実行可能ルールとテストルールには、追加属性が暗黙的に追加されます。ルールに暗黙的に追加される属性は、attrs
に渡される辞書に含めることはできません。
依存関係属性
通常、ソースコードを処理するルールでは、各種の依存関係を処理するために次の属性を定義します。
srcs
には、ターゲットのアクションで処理されるソースファイルを指定します。多くの場合、属性スキーマは、ルールで処理するソースファイルの種類に必要なファイル拡張子を指定します。ヘッダー ファイルを使用する言語のルールでは、通常、ターゲットとそのコンシューマによって処理されるヘッダーに個別のhdrs
属性を指定します。deps
は、ターゲットのコード依存関係を指定します。属性スキーマでは、それらの依存関係が提供する必要があるプロバイダを指定する必要があります。(たとえば、cc_library
はCcInfo
を提供します)。data
は、ターゲットに依存する実行可能ファイルに対して実行時に使用可能にするファイルを指定します。これにより、任意のファイルを指定できます。
example_library = rule(
implementation = _example_library_impl,
attrs = {
"srcs": attr.label_list(allow_files = [".example"]),
"hdrs": attr.label_list(allow_files = [".header"]),
"deps": attr.label_list(providers = [ExampleInfo]),
"data": attr.label_list(allow_files = True),
...
},
)
これらは依存関係属性の例です。入力ラベル(attr.label_list
、attr.label
、または attr.label_keyed_string_dict
で定義される属性)を指定する属性では、ターゲットと、ターゲットが定義されているときに、そのラベル(または対応する Label
オブジェクト)がリストされるターゲットとの間の特定の型の依存関係を指定します。これらのラベルのリポジトリ(場合によってはパス)は、定義されたターゲットを基準として解決されます。
example_library(
name = "my_target",
deps = [":other_target"],
)
example_library(
name = "other_target",
...
)
この例では、other_target
が my_target
の依存関係であるため、other_target
が最初に分析されます。ターゲットの依存関係グラフにサイクルがある場合はエラーになります。
非公開属性と暗黙的な依存関係
依存関係属性にデフォルト値を設定すると、暗黙的な依存関係が作成されます。これはターゲット グラフの一部であり、ユーザーが BUILD
ファイルで指定しないため、暗黙的に指定されます。暗黙的な依存関係は、ルールとツール(コンパイラなどのビルド時の依存関係)の関係をハードコードする場合に役立ちます。ほとんどの場合、ユーザーはルールでどのツールを使用するかの指定に興味がないためです。ルールの実装関数内では、これは他の依存関係と同様に扱われます。
ユーザーにその値をオーバーライドすることを許可しないで暗黙的な依存関係を提供する場合は、アンダースコア(_
)で始まる名前を指定して属性を非公開にできます。非公開属性にはデフォルト値が必要です。通常は、暗黙的な依存関係にプライベート属性を使用するのが適切です。
example_library = rule(
implementation = _example_library_impl,
attrs = {
...
"_compiler": attr.label(
default = Label("//tools:example_compiler"),
allow_single_file = True,
executable = True,
cfg = "exec",
),
},
)
この例では、example_library
型のすべてのターゲットがコンパイラ //tools:example_compiler
に暗黙的に依存しています。これにより、ユーザーがラベルを入力として渡さなかった場合でも、example_library
の実装関数でコンパイラを呼び出すアクションを生成できます。_compiler
は非公開属性であるため、このルールタイプのすべてのターゲットで、ctx.attr._compiler
は常に //tools:example_compiler
を指します。または、属性にアンダースコアを付けずに compiler
という名前を付け、デフォルト値をそのまま使用することもできます。これにより、ユーザーは必要に応じて別のコンパイラに置き換えることができますが、コンパイラのラベルを認識する必要はありません。
暗黙的な依存関係は通常、ルールの実装と同じリポジトリにあるツールに使用されます。ツールが実行プラットフォームまたは別のリポジトリから提供されている場合、ルールはツールチェーンからそのツールを取得する必要があります。
出力属性
出力属性(attr.output
や attr.output_list
など)は、ターゲットが生成する出力ファイルを宣言します。これらは、次の 2 つの点で依存関係属性と異なります。
- 他の場所で定義されているターゲットを参照する代わりに、出力ファイル ターゲットを定義します。
- 出力ファイル ターゲットは、インスタンス化されたルール ターゲットに依存します。
通常、出力属性は、ルールでターゲット名に基づくことはできないユーザー定義の名前で出力を作成する必要がある場合にのみ使用されます。ルールに 1 つの出力属性がある場合、通常は out
または outs
という名前が付けられます。
出力属性は、事前に宣言された出力を作成するためのおすすめの方法です。出力属性は、明示的に依存するか、コマンドラインでリクエストできます。
実装関数
すべてのルールに implementation
関数が必要です。これらの関数は分析フェーズで厳密に実行され、読み込みフェーズで生成されたターゲットのグラフを、実行フェーズで実行されるアクションのグラフに変換します。そのため、実装関数で実際にファイルを読み書きすることはできません。
ルールの実装関数は通常、非公開です(名前の先頭にアンダースコアを付けます)。通常は、ルールと同じ名前が付けられますが、末尾に _impl
が付きます。
実装関数は 1 つのパラメータを受け取ります。ルール コンテキスト(通常は ctx
という名前)です。このメソッドはプロバイダのリストを返します。
ターゲット
依存関係は、分析時に Target
オブジェクトとして表されます。これらのオブジェクトには、ターゲットの実装関数が実行されたときに生成されたプロバイダが含まれます。
ctx.attr
には、各依存関係属性の名前に対応するフィールドがあり、その属性を使用してそれぞれの直接的な依存関係を表す Target
オブジェクトが含まれています。label_list
属性の場合、これは Targets
のリストです。label
属性の場合、これは単一の Target
または None
です。
プロバイダ オブジェクトのリストは、ターゲットの実装関数によって返されます。
return [ExampleInfo(headers = depset(...))]
これらには、プロバイダの型をキーとして、インデックス表記([]
)を使用してアクセスできます。これには、Starlark で定義されたカスタム プロバイダ、または Starlark グローバル変数として利用可能なネイティブ ルール用のプロバイダを使用できます。
たとえば、ルールで hdrs
属性を使用してヘッダー ファイルを取得し、ターゲットとそのコンシューマのコンパイル アクションに提供する場合、次のように収集できます。
def _example_library_impl(ctx):
...
transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs]
従来の構造体スタイルがありますが、そのようなスタイルは使用しないことを強くおすすめします。このルールを移行してください。
ファイル
ファイルは File
オブジェクトで表されます。Bazel は分析フェーズでファイル I/O を実行しないため、これらのオブジェクトを使用してファイル コンテンツを直接読み書きすることはできません。代わりに、アクションを出力する関数(ctx.actions
を参照)に渡され、アクション グラフを構成します。
File
は、ソースファイルまたは生成されたファイルのいずれかです。生成される各ファイルは、1 つのアクションの出力である必要があります。ソースファイルをアクションの出力にすることはできません。
依存関係属性ごとに、ctx.files
の対応するフィールドには、その属性を使用するすべての依存関係のデフォルト出力のリストが含まれます。
def _example_library_impl(ctx):
...
headers = depset(ctx.files.hdrs, transitive = transitive_headers)
srcs = ctx.files.srcs
...
ctx.file
には、仕様が allow_single_file = True
に設定された依存関係属性の File
または None
が 1 つ含まれます。ctx.executable
は ctx.file
と同じように動作しますが、仕様で executable = True
が設定されている依存関係属性のフィールドのみを含みます。
出力の宣言
分析フェーズでは、ルールの実装関数で出力を作成できます。読み込みフェーズですべてのラベルを認識する必要があるため、これらの追加の出力にはラベルがありません。出力用の File
オブジェクトは、ctx.actions.declare_file
と ctx.actions.declare_directory
を使用して作成できます。多くの場合、出力の名前はターゲットの名前 ctx.label.name
に基づいています。
def _example_library_impl(ctx):
...
output_file = ctx.actions.declare_file(ctx.label.name + ".output")
...
出力属性用に作成された出力など、事前に宣言された出力の場合、代わりに File
オブジェクトは対応する ctx.outputs
のフィールドから取得できます。
アクション
アクションは、入力のセットから一連の出力を生成する方法を記述します(例: 「hello.c で gcc を実行し、hello.o を取得」)。アクションを作成しても、Bazel はすぐにコマンドを実行しません。あるアクションは別のアクションの出力に依存する可能性があるため、依存関係のグラフに登録します。たとえば C では、コンパイラの後にリンカーを呼び出す必要があります。
アクションを作成する汎用関数は、ctx.actions
で定義されています。
ctx.actions.run
: 実行可能ファイルを実行します。ctx.actions.run_shell
: シェルコマンドを実行します。ctx.actions.write
: 文字列をファイルに書き込みます。ctx.actions.expand_template
: テンプレートからファイルを生成します。
ctx.actions.args
を使用すると、アクションの引数を効率的に蓄積できます。実行時まで depset のフラット化を回避します。
def _example_library_impl(ctx):
...
transitive_headers = [dep[ExampleInfo].headers for dep in ctx.attr.deps]
headers = depset(ctx.files.hdrs, transitive = transitive_headers)
srcs = ctx.files.srcs
inputs = depset(srcs, transitive = [headers])
output_file = ctx.actions.declare_file(ctx.label.name + ".output")
args = ctx.actions.args()
args.add_joined("-h", headers, join_with = ",")
args.add_joined("-s", srcs, join_with = ",")
args.add("-o", output_file)
ctx.actions.run(
mnemonic = "ExampleCompile",
executable = ctx.executable._compiler,
arguments = [args],
inputs = inputs,
outputs = [output_file],
)
...
アクションは入力ファイルのリストまたは依存関係を受け取り、出力ファイルの(空でない)リストを生成します。入力ファイルと出力ファイルのセットは、分析フェーズで把握している必要があります。依存関係のプロバイダなど、属性の値に依存する場合もありますが、実行の結果には依存しません。たとえば、アクションで unzip コマンドを実行する場合は、インフレートするファイルを(unzip を実行する前に)指定する必要があります。内部で作成するファイルの数を変えるアクションでは、それらのファイルを 1 つのファイル(zip、tar、その他のアーカイブ形式など)にラップできます。
アクションはすべての入力を列挙する必要があります。使用されていない入力を一覧表示することは許可されていますが、効率的ではありません。
アクションは、すべての出力を作成する必要があります。他のファイルを書き込むことはできますが、出力にないファイルはコンシューマが使用できません。宣言された出力はすべて、なんらかのアクションによって書き込まれる必要があります。
アクションは純粋な関数と同等です。つまり、指定された入力にのみ依存し、コンピュータ情報、ユーザー名、クロック、ネットワーク、I/O デバイスへのアクセスを避けてください(入力の読み取りと出力の書き込みを除く)。出力がキャッシュに保存され、再利用されるため、これは重要です。
依存関係は、実行するアクションを決定する Bazel によって解決されます。依存関係グラフにサイクルがある場合はエラーになります。アクションを作成しても、そのアクションが必ず実行されるとは限りません。これは、そのアクションの出力がビルドに必要かどうかによって異なります。
プロバイダ
プロバイダは、あるルールがそのルールに依存する他のルールに公開する情報です。このデータには、出力ファイル、ライブラリ、ツールのコマンドラインに渡すパラメータなど、ターゲットのコンシューマが認識すべきあらゆるデータを含めることができます。
ルールの実装関数は、インスタンス化されたターゲットの直接的な依存関係からのみプロバイダを読み取ることができるため、ターゲットのコンシューマが認識する必要があるターゲットの依存関係の情報をルールに転送する必要があります。そのためには、通常は情報を depset
に蓄積します。
ターゲットのプロバイダは、実装関数によって返されるプロバイダ オブジェクトのリストで指定します。
古い実装関数は、プロバイダ オブジェクトのリストではなく struct
を返す以前のスタイルで記述することもできます。このスタイルは使用しないことを強くおすすめします。ルールは移行しないようにしてください。
デフォルトの出力
ターゲットのデフォルトの出力は、コマンドラインでビルドに対してターゲットがリクエストされたときに、デフォルトでリクエストされる出力です。たとえば、java_library
ターゲット //pkg:foo
にはデフォルトの出力として foo.jar
があるため、コマンド bazel build //pkg:foo
でビルドされます。
デフォルトの出力は、DefaultInfo
の files
パラメータで指定されます。
def _example_library_impl(ctx):
...
return [
DefaultInfo(files = depset([output_file]), ...),
...
]
ルールの実装で DefaultInfo
が返されない場合、または files
パラメータが指定されていない場合、DefaultInfo.files
はデフォルトで事前に宣言されたすべての出力(通常は出力属性によって作成された出力)になります。
アクションを実行するルールでは、出力が直接使用されることが想定されていなくても、デフォルトの出力を提供する必要があります。リクエストされた出力のグラフにないアクションはプルーニングされます。出力がターゲットのコンシューマによってのみ使用される場合、ターゲットが単独で構築されている場合、これらのアクションは実行されません。この場合、失敗したターゲットのみを再構築すると障害が再現されないため、デバッグが難しくなります。
実行ファイル
実行ファイルは、(ビルド時ではなく)実行時にターゲットが使用するファイルのセットです。実行フェーズで、Bazel は runfile を指すシンボリック リンクを含むディレクトリ ツリーを作成します。これにより、バイナリの環境がステージングされ、実行時に実行ファイルにアクセスできるようになります。
Runfile は、ルールの作成時に手動で追加できます。runfiles
オブジェクトは、ルール コンテキスト ctx.runfiles
の runfiles
メソッドで作成し、DefaultInfo
の runfiles
パラメータに渡すことができます。実行可能ルールの実行可能出力は、暗黙的に実行ファイルに追加されます。
一部のルールでは属性(通常は data
という名前)が指定され、その出力はターゲットの runfile に追加されます。Runfile も data
からマージする必要があります。また、最終的に実行するためのコードを提供する可能性のある属性からもマージする必要があります。一般的には、srcs
(data
が関連付けられた filegroup
ターゲットを含む場合があります)、deps
などです。
def _example_library_impl(ctx):
...
runfiles = ctx.runfiles(files = ctx.files.data)
transitive_runfiles = []
for runfiles_attr in (
ctx.attr.srcs,
ctx.attr.hdrs,
ctx.attr.deps,
ctx.attr.data,
):
for target in runfiles_attr:
transitive_runfiles.append(target[DefaultInfo].default_runfiles)
runfiles = runfiles.merge_all(transitive_runfiles)
return [
DefaultInfo(..., runfiles = runfiles),
...
]
カスタム プロバイダ
プロバイダを定義するには、provider
関数を使用してルール固有の情報を伝達します。
ExampleInfo = provider(
"Info needed to compile/link Example code.",
fields = {
"headers": "depset of header Files from transitive dependencies.",
"files_to_link": "depset of Files from compilation.",
},
)
その後、ルール実装関数でプロバイダ インスタンスを作成して返すことができます。
def _example_library_impl(ctx):
...
return [
...
ExampleInfo(
headers = headers,
files_to_link = depset(
[output_file],
transitive = [
dep[ExampleInfo].files_to_link for dep in ctx.attr.deps
],
),
)
]
プロバイダのカスタム初期化
カスタムの前処理と検証ロジックを使用して、プロバイダのインスタンス化を保護できます。これにより、すべてのプロバイダ インスタンスが特定の不変条件を満たすようにしたり、インスタンスを取得するためのすっきりした API をユーザーに提供したりできます。
これを行うには、init
コールバックを provider
関数に渡します。このコールバックを指定すると、provider()
の戻り値の型は 2 つの値のタプルになります。1 つはプロバイダ シンボル(init
を使用しない場合の通常の戻り値)で、もう 1 つは「未加工のコンストラクタ」です。
この場合、プロバイダ シンボルが呼び出されると、新しいインスタンスを直接返すのではなく、init
コールバックに引数が転送されます。コールバックの戻り値は、フィールド名(文字列)を値にマッピングする辞書である必要があります。これは、新しいインスタンスのフィールドを初期化するのに使用されます。コールバックには任意のシグネチャが存在する可能性があり、引数がシグネチャと一致しない場合、コールバックが直接呼び出された場合と同様にエラーが報告されます。
一方、未加工のコンストラクタは init
コールバックをバイパスします。
次の例では、init
を使用して引数の前処理と検証を行います。
# //pkg:exampleinfo.bzl
_core_headers = [...] # private constant representing standard library files
# Keyword-only arguments are preferred.
def _exampleinfo_init(*, files_to_link, headers = None, allow_empty_files_to_link = False):
if not files_to_link and not allow_empty_files_to_link:
fail("files_to_link may not be empty")
all_headers = depset(_core_headers, transitive = headers)
return {"files_to_link": files_to_link, "headers": all_headers}
ExampleInfo, _new_exampleinfo = provider(
fields = ["files_to_link", "headers"],
init = _exampleinfo_init,
)
ルールの実装では、次のようにプロバイダをインスタンス化できます。
ExampleInfo(
files_to_link = my_files_to_link, # may not be empty
headers = my_headers, # will automatically include the core headers
)
未加工のコンストラクタを使用すると、init
ロジックを経由しない別のパブリック ファクトリ関数を定義できます。たとえば、exampleinfo.bzl は以下を定義できます。
def make_barebones_exampleinfo(headers):
"""Returns an ExampleInfo with no files_to_link and only the specified headers."""
return _new_exampleinfo(files_to_link = depset(), headers = all_headers)
通常、未加工のコンストラクタは名前がアンダースコアで始まる変数(上記の _new_exampleinfo
)にバインドされるため、ユーザーコードでこのコンストラクタを読み込んで任意のプロバイダ インスタンスを生成することはできません。
init
のもう 1 つの使用方法は、ユーザーがプロバイダ シンボルをまったく呼び出さないようにして、代わりにファクトリ関数を使用するように強制することです。
def _exampleinfo_init_banned(*args, **kwargs):
fail("Do not call ExampleInfo(). Use make_exampleinfo() instead.")
ExampleInfo, _new_exampleinfo = provider(
...
init = _exampleinfo_init_banned)
def make_exampleinfo(...):
...
return _new_exampleinfo(...)
実行可能なルールとテストルール
実行可能なルールは、bazel run
コマンドで呼び出すことができるターゲットを定義します。テストルールは特別な種類の実行可能ルールであり、そのターゲットは bazel test
コマンドでも呼び出すことができます。実行可能なルールとテストルールは、rule
の呼び出しでそれぞれの executable
引数または test
引数を True
に設定することで作成されます。
example_binary = rule(
implementation = _example_binary_impl,
executable = True,
...
)
example_test = rule(
implementation = _example_binary_impl,
test = True,
...
)
テストルールの名前は、_test
で終わる必要があります。(テスト ターゲット名も慣例により _test
で終わることがよくありますが、これは必須ではありません)。テスト以外のルールでは、この接尾辞を付けないでください。
どちらの種類のルールも、run
コマンドまたは test
コマンドで呼び出される実行可能な出力ファイル(事前に宣言されていてもしなくてもよい)を生成する必要があります。この実行可能ファイルとして使用するルールの出力を Bazel に伝えるには、返された DefaultInfo
プロバイダの executable
引数として渡します。この executable
は、ルールのデフォルトの出力に追加されます(そのため、executable
と files
の両方に渡す必要はありません)。また、暗黙的に runfiles にも追加されます。
def _example_binary_impl(ctx):
executable = ctx.actions.declare_file(ctx.label.name)
...
return [
DefaultInfo(executable = executable, ...),
...
]
このファイルを生成するアクションでは、ファイルで実行可能ビットを設定する必要があります。ctx.actions.run
アクションまたは ctx.actions.run_shell
アクションの場合、アクションによって呼び出される基になるツールによって行う必要があります。ctx.actions.write
アクションの場合は is_executable = True
を渡します。
従来の動作として、実行可能なルールには特別な ctx.outputs.executable
出力が事前に宣言されています。このファイルは、DefaultInfo
で指定しない場合、デフォルトの実行可能ファイルとして機能します。それ以外の場合は使用しないでください。この出力メカニズムは、分析時の実行可能ファイル名のカスタマイズをサポートしていないため、非推奨となっています。
実行可能なルールとテストルールには、すべてのルールに追加される属性に加えて、追加の属性が暗黙的に定義されます。暗黙的に追加される属性のデフォルトは変更できませんが、デフォルトを変更する Starlark マクロでプライベート ルールをラップすることで回避できます。
def example_test(size = "small", **kwargs):
_example_test(size = size, **kwargs)
_example_test = rule(
...
)
実行ファイルの場所
bazel run
(または test
)で実行可能なターゲットを実行すると、runfiles ディレクトリのルートは実行可能ファイルに隣接します。パスは次のように関係します。
# Given launcher_path and runfile_file:
runfiles_root = launcher_path.path + ".runfiles"
workspace_name = ctx.workspace_name
runfile_path = runfile_file.short_path
execution_root_relative_path = "%s/%s/%s" % (
runfiles_root, workspace_name, runfile_path)
runfiles ディレクトリの下にある File
へのパスは、File.short_path
に対応します。
bazel
によって直接実行されるバイナリは、runfiles
ディレクトリのルートに隣接しています。ただし、実行ファイルから呼び出されるバイナリでは、同じ仮定はできません。これを軽減するために、各バイナリは、環境またはコマンドライン引数またはフラグを使用して、ランファイルのルートをパラメータとして受け取る方法を提供する必要があります。これにより、バイナリは、呼び出すバイナリに正規の正規ランファイル ルートを渡すことができます。この属性が設定されていない場合、バイナリは、それが最初に呼び出されたバイナリであると判断し、隣接する runfiles ディレクトリを探します。
高度なトピック
出力ファイルのリクエスト
1 つのターゲットに複数の出力ファイルを含めることができます。bazel build
コマンドを実行すると、コマンドに指定されたターゲットの出力の一部はリクエスト済みとみなされます。Bazel は、リクエストされたファイルと、それらが直接的または間接的に依存するファイルのみをビルドします。(アクション グラフでは、Bazel はリクエストされたファイルの推移的依存関係として到達可能なアクションのみを実行します)。
デフォルトの出力に加えて、事前に宣言された出力は、コマンドラインで明示的にリクエストできます。ルールでは、出力属性を使用して、事前に宣言された出力を指定できます。その場合、ユーザーはルールをインスタンス化するときに、出力のラベルを明示的に選択します。出力属性の File
オブジェクトを取得するには、対応する ctx.outputs
の属性を使用します。ルールでは、ターゲット名に基づいて事前に宣言された出力を暗黙的に定義することもできますが、この機能は非推奨です。
デフォルトの出力に加えて、出力グループがあります。これは、まとめてリクエストできる出力ファイルのコレクションです。これらは --output_groups
を使用してリクエストできます。たとえば、ターゲット //pkg:mytarget
が debug_files
出力グループを持つルールタイプの場合、bazel build //pkg:mytarget
--output_groups=debug_files
を実行してこれらのファイルを作成できます。事前に宣言されていない出力にはラベルがないため、リクエストするには、デフォルトの出力または出力グループに表示される必要があります。
出力グループは、OutputGroupInfo
プロバイダで指定できます。多くの組み込みプロバイダとは異なり、OutputGroupInfo
は任意の名前のパラメータを受け取り、その名前で出力グループを定義できます。
def _example_library_impl(ctx):
...
debug_file = ctx.actions.declare_file(name + ".pdb")
...
return [
DefaultInfo(files = depset([output_file]), ...),
OutputGroupInfo(
debug_files = depset([debug_file]),
all_files = depset([output_file, debug_file]),
),
...
]
また、ほとんどのプロバイダとは異なり、OutputGroupInfo
は、同じ出力グループを定義しない限り、アスペクトとそのアスペクトが適用されるルール ターゲットの両方で返すことができます。この場合、結果として得られるプロバイダはマージされます。
通常、OutputGroupInfo
は、特定の種類のファイルをターゲットからコンシューマのアクションに伝えるためには使用しないでください。代わりに、ルール固有のプロバイダを定義します。
構成
別のアーキテクチャ用の C++ バイナリをビルドするとします。ビルドは複雑で、複数のステップを含む場合があります。コンパイラやコード生成ツールなどの一部の中間バイナリは、実行プラットフォーム(ホストまたはリモート エグゼキュータ)で実行する必要があります。最終出力などの一部のバイナリは、ターゲット アーキテクチャ用にビルドする必要があります。
そのため、Bazel には「構成」と遷移の概念があります。最上位のターゲット(コマンドラインでリクエストされるターゲット)は「ターゲット」構成に組み込まれ、実行プラットフォームで実行されるツールには「exec」構成が組み込まれています。ルールでは、コンパイラに渡される CPU アーキテクチャを変更するなど、構成に基づいてさまざまなアクションを生成できます。場合によっては、異なる構成で同じライブラリが必要になる場合があります。その場合は分析が行われ、複数回ビルドされる可能性があります。
デフォルトでは、Bazel はターゲット自体と同じ構成、つまり移行なしでターゲットの依存関係をビルドします。依存関係がターゲットのビルドに必要なツールである場合は、対応する属性で exec 構成への移行を指定する必要があります。これにより、実行プラットフォーム用にツールとそのすべての依存関係がビルドされます。
依存関係属性ごとに、cfg
を使用して、依存関係を同じ構成でビルドするか、exec 構成に移行するかを決定できます。依存関係属性に executable = True
フラグがある場合は、cfg
を明示的に設定する必要があります。これは、誤った構成でツールを誤って構築することを防ぐためです。例を見る
一般に、実行時に必要となるソース、依存ライブラリ、実行可能ファイルは同じ構成を使用できます。
ビルドの一環として実行されるツール(コンパイラやコード生成ツールなど)は、exec 構成用にビルドする必要があります。この場合は、属性に cfg = "exec"
を指定します。
それ以外の場合は、(テストなどで)実行時に使用される実行可能ファイルをターゲット構成用にビルドする必要があります。この場合は、属性に cfg = "target"
を指定します。
cfg = "target"
は実際には何も行いません。ルール設計者が意図を明確に指定できるようにすることを目的に、単純に便宜的な値です。executable = False
(cfg
が省略可能)の場合は、読みやすくする場合にのみ設定してください。
また、cfg = my_transition
を使用してユーザー定義の遷移を使用することもできます。これにより、ルール作成者は構成を変更する際の柔軟性が大幅に向上しますが、ビルドグラフが大きくなり、わかりにくくなるという欠点があります。
注: 従来、Bazel には実行プラットフォームのコンセプトがなく、代わりにすべてのビルド アクションがホストマシンで実行されると見なされていました。6.0 より前のバージョンの Bazel では、これを表す個別の「ホスト」構成を作成しました。コードや古いドキュメントで「host」という言及がある場合は、それがそれを指します。この追加の概念的なオーバーヘッドを回避するために、Bazel 6.0 以降を使用することをおすすめします。
構成フラグメント
ルールでは、cpp
や java
などの構成フラグメントにアクセスできます。ただし、アクセスエラーを回避するために、必要なすべてのフラグメントを宣言する必要があります。
def _impl(ctx):
# Using ctx.fragments.cpp leads to an error since it was not declared.
x = ctx.fragments.java
...
my_rule = rule(
implementation = _impl,
fragments = ["java"], # Required fragments of the target configuration
...
)
Runfiles のシンボリック リンク
通常、runfiles ツリー内のファイルの相対パスは、ソースツリーまたは生成された出力ツリー内のそのファイルの相対パスと同じです。なんらかの理由で異なる必要がある場合は、root_symlinks
引数または symlinks
引数を指定できます。root_symlinks
は、ファイルへのパスをマッピングする辞書です。パスは runfiles ディレクトリのルートからの相対パスです。symlinks
辞書は同じですが、パスの先頭には暗黙的にメイン ワークスペースの名前が付加されます(現在のターゲットを含むリポジトリの名前ではありません)。
...
runfiles = ctx.runfiles(
root_symlinks = {"some/path/here.foo": ctx.file.some_data_file2}
symlinks = {"some/path/here.bar": ctx.file.some_data_file3}
)
# Creates something like:
# sometarget.runfiles/
# some/
# path/
# here.foo -> some_data_file2
# <workspace_name>/
# some/
# path/
# here.bar -> some_data_file3
symlinks
または root_symlinks
を使用する場合は、2 つの異なるファイルを runfiles ツリーの同じパスにマッピングしないように注意してください。これにより、ビルドが失敗し、競合を説明するエラーが返されます。この問題を解決するには、ctx.runfiles
引数を変更して競合を解消する必要があります。このチェックは、ルールを使用するすべてのターゲットと、それらのターゲットに依存するすべてのターゲットに対して行われます。ツールが別のツールによって推移的に使用される可能性がある場合、これは特に危険です。シンボリック リンク名は、ツールのランファイルとそのすべての依存関係全体で一意である必要があります。
コード カバレッジ
coverage
コマンドの実行時に、ビルドで特定のターゲットに対するカバレッジ インストルメンテーションの追加が必要になる場合があります。また、インストゥルメント化されたソースファイルのリストも収集します。考慮されるターゲットのサブセットは、フラグ --instrumentation_filter
で制御されます。--instrument_test_targets
が指定されていない限り、テスト ターゲットは除外されます。
ルールの実装でビルド時にカバレッジ インストルメンテーションを追加する場合、その実装関数でそれを考慮する必要があります。ターゲットのソースをインストルメント化する必要がある場合、ctx.coverage_instrumented はカバレッジ モードで True
を返します。
# Are this rule's sources instrumented?
if ctx.coverage_instrumented():
# Do something to turn on coverage for this compile action
ターゲットのソースがインストゥルメント化されているかどうかにかかわらず、常にカバレッジ モードでオンにする必要があるロジックは、ctx.configuration.coverage_enabled で条件にできます。
コンパイル前に依存関係のソース(ヘッダー ファイルなど)がルールに直接含まれている場合、依存関係のソースをインストルメント化する必要がある場合は、コンパイル時のインストルメンテーションも有効にする必要があります。
# Are this rule's sources or any of the sources for its direct dependencies
# in deps instrumented?
if (ctx.configuration.coverage_enabled and
(ctx.coverage_instrumented() or
any([ctx.coverage_instrumented(dep) for dep in ctx.attr.deps]))):
# Do something to turn on coverage for this compile action
また、coverage_common.instrumented_files_info
を使用して作成された InstrumentedFilesInfo
プロバイダのカバレッジに関連する属性に関する情報も提供する必要があります。instrumented_files_info
の dependency_attributes
パラメータで、deps
などのコード依存関係や data
などのデータ依存関係を含む、すべてのランタイム依存関係属性をリストする必要があります。カバレッジ インストルメンテーションを追加できる場合は、source_attributes
パラメータでルールのソースファイルの属性をリストする必要があります。
def _example_library_impl(ctx):
...
return [
...
coverage_common.instrumented_files_info(
ctx,
dependency_attributes = ["deps", "data"],
# Omitted if coverage is not supported for this rule:
source_attributes = ["srcs", "hdrs"],
)
...
]
InstrumentedFilesInfo
が返されない場合、dependency_attributes
の属性スキーマで cfg
が "exec"
に設定されていないツール以外の依存関係属性ごとに、デフォルトの依存関係が作成されます。(srcs
などの属性が source_attributes
ではなく dependency_attributes
に配置されるため、これは理想的な動作ではありませんが、依存関係チェーン内のすべてのルールに対して明示的なカバレッジ構成が不要になります)。
検証アクション
場合によっては、ビルドについて検証する必要があり、その検証に必要な情報はアーティファクト(ソースファイルまたは生成されたファイル)でのみ使用できます。この情報はアーティファクトに含まれているため、ルールではファイルを読み取ることができないため、分析時にルールでこの検証を行うことはできません。代わりに、アクションは実行時にこの検証を行う必要があります。検証が失敗するとアクションも失敗し、ビルドも失敗します。
実行される検証の例としては、静的分析、lint チェック、依存関係と整合性のチェック、スタイル チェックがあります。
検証アクションは、アーティファクトのビルドに不要なアクションの一部を別のアクションに移動することで、ビルドのパフォーマンスを向上させることもできます。たとえば、コンパイルと lint チェックを実行する単一のアクションをコンパイル アクションと lint チェック アクションに分離できる場合、lint チェック アクションを検証アクションとして実行し、他のアクションと並行して実行できます。
これらの「検証アクション」では、入力に関するアサーションのみが必要なため、多くの場合、ビルド内の他の場所で使用されるものは生成されません。ただし、この場合、ビルド内の他の場所で使用されるものが検証アクションによって生成されない場合、ルールによってアクションをどのように実行させるのでしょうか。これまでは、検証アクションで空のファイルを出力し、その出力をビルド内の他の重要なアクションの入力に人為的に追加していました。
コンパイル アクションの実行時に Bazel が常に検証アクションを実行するため、これは機能しますが、次のような大きなデメリットがあります。
検証アクションがビルドのクリティカル パスにある。Bazel は、コンパイル アクションを実行するには空の出力が必要であると判断しているため、コンパイル アクションが入力を無視しても、最初に検証アクションを実行します。 これにより、並列処理が減り、ビルドが遅くなります。
コンパイル アクションの代わりにビルド内の他のアクションが実行される可能性がある場合は、検証アクションの空の出力もこれらのアクションに追加する必要があります(
java_library
のソース jar 出力など)。これは、コンパイル アクションの代わりに実行される可能性のある新しいアクションが後で追加され、空の検証出力が誤って中断される場合にも問題となります。
この問題を解決するには、Validations 出力グループを使用します。
検証出力グループ
Validations Output Group は、本来は使用されていない検証アクションの出力を保持するように設計された出力グループです。これにより、他のアクションの入力に人為的に追加する必要がなくなります。
このグループは、--output_groups
フラグの値に関係なく、またターゲットがどのように依存するか(コマンドライン、依存関係として、ターゲットの暗黙的な出力など)に関係なく、出力が常にリクエストされる点が特殊です。通常のキャッシュとインクリメンタリティが適用されることに注意してください。検証アクションへの入力が変更されておらず、以前に検証アクションが成功している場合、検証アクションは実行されません。
この出力グループを使用する場合、検証アクションでなんらかのファイル(空のファイルも含む)を出力する必要があります。この場合、通常は出力を作成しない一部のツールをラップして、ファイルを作成することが必要になる場合があります。
次の 3 つのケースでは、ターゲットの検証アクションは実行されません。
- ターゲットがツールとして依存している場合
- ターゲットが暗黙的な依存関係として依存している場合(「_」で始まる属性など)
- ターゲットが exec 構成に組み込まれているとき。
これらのターゲットには、検証の失敗を発見する独自のビルドとテストがあることが前提です。
Validations 出力グループの使用
検証出力グループには _validation
という名前が付けられ、他の出力グループと同様に使用されます。
def _rule_with_validation_impl(ctx):
ctx.actions.write(ctx.outputs.main, "main output\n")
ctx.actions.write(ctx.outputs.implicit, "implicit output\n")
validation_output = ctx.actions.declare_file(ctx.attr.name + ".validation")
ctx.actions.run(
outputs = [validation_output],
executable = ctx.executable._validation_tool,
arguments = [validation_output.path],
)
return [
DefaultInfo(files = depset([ctx.outputs.main])),
OutputGroupInfo(_validation = depset([validation_output])),
]
rule_with_validation = rule(
implementation = _rule_with_validation_impl,
outputs = {
"main": "%{name}.main",
"implicit": "%{name}.implicit",
},
attrs = {
"_validation_tool": attr.label(
default = Label("//validation_actions:validation_tool"),
executable = True,
cfg = "exec"
),
}
)
検証出力ファイルは、DefaultInfo
や他のアクションへの入力には追加されません。このルール種類のターゲットに対する検証アクションは、ターゲットがラベルに依存している場合、またはターゲットの暗黙的な出力が直接的または間接的に依存している場合、引き続き実行されます。
通常、検証アクションの出力は検証出力グループにのみ送信し、他のアクションの入力には追加しないことが重要です。これにより、並列処理のメリットが低下する可能性があります。ただし、Bazel には、これを適用するための特別なチェックはありません。したがって、Starlark ルールのテストでは、検証アクションの出力がアクションの入力に追加されないことをテストする必要があります。次に例を示します。
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
def _validation_outputs_test_impl(ctx):
env = analysistest.begin(ctx)
actions = analysistest.target_actions(env)
target = analysistest.target_under_test(env)
validation_outputs = target.output_groups._validation.to_list()
for action in actions:
for validation_output in validation_outputs:
if validation_output in action.inputs.to_list():
analysistest.fail(env,
"%s is a validation action output, but is an input to action %s" % (
validation_output, action))
return analysistest.end(env)
validation_outputs_test = analysistest.make(_validation_outputs_test_impl)
検証アクション フラグ
検証アクションの実行は、--run_validations
コマンドライン フラグで制御されます。このフラグはデフォルトで true に設定されます。
サポートが終了した機能
非推奨の事前宣言済み出力
事前に宣言された出力を使用する際は、次の 2 つの方法があります(非推奨)。
rule
のoutputs
パラメータは、事前に宣言された出力ラベルを生成するための、出力属性名と文字列テンプレート間のマッピングを指定します。事前に宣言されていない出力を使用し、出力をDefaultInfo.files
に明示的に追加することをおすすめします。事前に宣言された出力のラベルの代わりに、出力を使用するルールの入力として、ルール ターゲットのラベルを使用します。実行可能ルールの場合、
ctx.outputs.executable
はルール ターゲットと同じ名前の、事前に宣言された実行可能な出力を指します。ctx.actions.declare_file(ctx.label.name)
などを使用して出力を明示的に宣言し、実行可能ファイルを生成するコマンドで、実行を許可するように権限を設定してください。実行可能な出力をDefaultInfo
のexecutable
パラメータに明示的に渡します。
避けるべき実行ファイルの機能
ctx.runfiles
タイプと runfiles
タイプには複雑な機能セットがあり、その多くは以前の理由で保持されています。次の推奨事項は複雑さの軽減に役立ちます。
ctx.runfiles
のcollect_data
モードとcollect_default
モードは使用しないでください。これらのモードでは、ハードコードされた特定の依存関係エッジにわたって、紛らわしい方法でランファイルが暗黙的に収集されます。代わりに、ctx.runfiles
のfiles
パラメータまたはtransitive_files
パラメータを使用するか、runfiles = runfiles.merge(dep[DefaultInfo].default_runfiles)
で依存関係からランファイルにマージして、ファイルを追加します。DefaultInfo
コンストラクタのdata_runfiles
とdefault_runfiles
は使用しないでください。代わりにDefaultInfo(runfiles = ...)
を指定してください。従来の理由から、runfile の「default」と「data」の区別は維持されます。たとえば、一部のルールではデフォルトの出力がdata_runfiles
に配置され、default_runfiles
に配置されません。ルールでは、data_runfiles
を使用する代わりに、デフォルトの出力を含める両方と、実行ファイルを提供する属性(多くの場合data
)からdefault_runfiles
にマージする必要があります。DefaultInfo
からrunfiles
を取得する場合(通常は、現在のルールとその依存関係の間で runfile をマージする場合のみ)、DefaultInfo.data_runfiles
ではなくDefaultInfo.default_runfiles
を使用します。
以前のプロバイダからの移行
従来、Bazel プロバイダは Target
オブジェクト上の単純なフィールドでした。これらはドット演算子を使用してアクセスされ、プロバイダ オブジェクトのリストではなく、ルールの実装関数によって返される struct
にフィールドを配置して作成されました。
return struct(example_info = struct(headers = depset(...)))
このようなプロバイダは、Target
オブジェクトの対応するフィールドから取得できます。
transitive_headers = [hdr.example_info.headers for hdr in ctx.attr.hdrs]
このスタイルはサポートが終了しているため、新しいコードでは使用できません。移行に役立つ情報については、以下をご覧ください。新しいプロバイダ メカニズムにより、名前の競合が回避されます。また、プロバイダのインスタンスにアクセスするコードでプロバイダ シンボルを使用してインスタンスを取得することで、データの非表示もサポートします。
現時点では、従来のプロバイダは引き続きサポートされます。次のように、ルールでレガシープロバイダと最新のプロバイダの両方を返すことができます。
def _old_rule_impl(ctx):
...
legacy_data = struct(x = "foo", ...)
modern_data = MyInfo(y = "bar", ...)
# When any legacy providers are returned, the top-level returned value is a
# struct.
return struct(
# One key = value entry for each legacy provider.
legacy_info = legacy_data,
...
# Additional modern providers:
providers = [modern_data, ...])
dep
がこのルールのインスタンスの結果の Target
オブジェクトである場合、プロバイダとその内容は dep.legacy_info.x
と dep[MyInfo].y
として取得できます。
返される構造体には、providers
以外にも、特別な意味を持つ(したがって対応するレガシー プロバイダが作成されない)複数のフィールドを指定できます。
フィールド
files
、runfiles
、data_runfiles
、default_runfiles
、executable
は、DefaultInfo
の同じ名前のフィールドに対応しています。DefaultInfo
プロバイダを返しながら、これらのフィールドを指定することはできません。フィールド
output_groups
は構造体値を取り、OutputGroupInfo
に対応します。
ルールの provides
宣言と、依存関係属性の providers
宣言で、以前のプロバイダは文字列として渡され、最新のプロバイダは Info
記号で渡されます。移行する際は、必ず文字列から記号に変更してください。すべてのルールをアトミックに更新することが難しい複雑なルールセットや大規模なルールセットの場合は、次の一連の手順に従うと簡単なことがあります。
上記の構文を使用して、レガシー プロバイダを生成するルールを変更し、レガシー プロバイダと最新プロバイダの両方を生成します。以前のプロバイダを返すことを宣言するルールについては、その宣言を更新して、レガシー プロバイダと最新のプロバイダの両方を含めます。
以前のプロバイダを使用するルールを変更して、代わりに最新のプロバイダを使用する。以前のプロバイダを必要とする属性宣言がある場合は、代わりに最新のプロバイダを要求するように更新してください。必要に応じて、コンシューマーがプロバイダを承認または要求するようにして、この作業をステップ 1 でインターリーブできます。
hasattr(target, 'foo')
を使用してレガシー プロバイダのプレゼンスをテストするか、FooInfo in target
を使用して新しいプロバイダの存在をテストします。以前のプロバイダをすべてのルールから完全に削除します。