ルールは、Bazel が入力に対して実行して一連の出力を生成する一連のアクションを定義します。これらの出力は、ルールの実装関数から返されるプロバイダで参照されます。たとえば、C++ バイナリルールは次のようになります。
.cpp
ソースファイル(入力)のセットを取得します。- ソースファイルに対して
g++
を実行します(アクション)。 - 実行可能な出力とその他のファイルで
DefaultInfo
プロバイダを返す 実行時に利用できるようにします - ターゲットとその依存関係から収集された C++ 固有の情報を含む
CcInfo
プロバイダを返します。
Bazel の観点からは、g++
と標準の C++ ライブラリも入力です
追加します。ルール作成者は、ルールへのユーザー提供入力だけでなく、アクションの実行に必要なすべてのツールとライブラリも考慮する必要があります。
ルールを作成または変更する前に、Bazel のビルドフェーズをよく理解してください。データ アナリストは、 (読み込み、分析、実行)。また、kubectl の マクロについて学び、ルールとルールの違いを理解する マクロ。始める前に、ルール チュートリアルをご覧ください。このページを参照用として使用します。
Bazel 自体には、いくつかのルールが組み込まれています。cc_library
や java_binary
などのネイティブ ルールは、特定の言語のコア サポートを提供します。独自のルールを定義することで、Bazel がネイティブでサポートしていない言語とツールに対して同様のサポートを追加できます。
Bazel は、Terraform を使用してルールを作成するための拡張モデルを提供します。
Starlark 言語。これらのルールは、.bzl
ファイルに記述され、
BUILD
ファイルから直接読み込むことができます。
独自のルールを定義するときは、ルールでサポートする属性と、ルールで実行できる属性と 出力の生成方法を確認できます。
ルールの 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
ファイルで指定しないターゲット グラフの一部であるため、暗黙的です。暗黙的な依存関係は、Terraform をハードコードする
ルールとツールの関係(例:
コンパイラ)を指定できます。ほとんどの場合、ユーザーは
使用されます。ルールの実装関数内では、これは他の依存関係と同じように扱われます。
ユーザーがその値をオーバーライドできないように暗黙的な依存関係を指定するには、属性にアンダースコア(_
)で始まる名前を付けて、属性を非公開にします。非公開属性にはデフォルト値が必要です。通常、プライベート属性は暗黙的な依存関係にのみ使用します。
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 つのパラメータを取ります。
rule context(通常は 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]
プロバイダ オブジェクトのリストではなく、ターゲットの実装関数から struct
が返される従来スタイルの場合:
return struct(example_info = struct(headers = depset(...)))
プロバイダは、Target
オブジェクトの対応するフィールドから取得できます。
transitive_headers = [hdr.example_info.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
には、次の要素に対する単一の File
または None
が含まれています。
仕様で allow_single_file=True
が設定されている依存関係属性。
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")
...
事前に宣言された出力(Google 広告用に作成された出力など)
出力属性がありますが、代わりに 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
を使用すると、アクションの引数を効率的に蓄積できます。次の時点までデプセットのフラット化を回避
実行時間:
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],
)
...
アクションは、入力ファイルのリストまたは depset を受け取り、出力ファイルの(空ではない)リストを生成します。入力ファイルと出力ファイルのセットは、 分析フェーズに進みましょう。モデルのパフォーマンスに 属性も指定できますが、依存関係のプロバイダに依存することはできません。 示されます。たとえば、アクションで unzip コマンドを実行する場合は、展開するファイルを指定する必要があります(unzip の実行前に)。内部で可変数のファイルを内部に作成するアクションでは、それらを (zip、tar、その他のアーカイブ形式など)に圧縮できます。
アクションはすべての入力を列挙する必要があります。使用されていない入力の一覧表示 可能ですが、効率的ではありません。
アクションはすべての出力を作成する必要があります。他のファイルを書き込むこともありますが、 出力に含まれないものは コンシューマは利用できなくなります宣言されたすべての出力 なんらかのアクションで書き込む必要があります。
アクションは純粋関数に似ています。提供された入力にのみ依存し、コンピュータ情報、ユーザー名、時計、ネットワーク、I/O デバイスにアクセスしないでください(入力の読み取りと出力の書き込みを除く)。これは、出力がキャッシュに保存されて再利用されるため重要です。
依存関係は Bazel によって解決され、Bazel が実行するアクションを決定します。依存関係グラフにサイクルがある場合はエラーになります。作成中 アクションの実行が保証されるわけではなく、アクションは その出力がビルドに必要です。
プロバイダ
プロバイダは、ルールが依存する他のルールに公開する情報の一部です。このデータには、出力ファイル、ライブラリ、ツールのコマンドライン経由で渡すパラメータ、ターゲットのコンシューマが知っておくべきその他のデータが含まれます。
ルールの実装関数は、インスタンス化されたターゲットの直接依存関係からプロバイダのみを読み取ることができるため、ルールは、ターゲットのコンシューマが認識する必要があるターゲットの依存関係から情報を転送する必要があります。通常は、その情報を depset
に蓄積します。
ターゲットのプロバイダは、実装関数によって返される Provider
オブジェクトのリストで指定します。
古い実装関数は、実装関数がプロバイダ オブジェクトのリストではなく struct
を返すレガシー スタイルで記述することもできます。このスタイルは強く推奨されず、ルールはこのスタイルから移行する必要があります。
デフォルトの出力
ターゲットのデフォルト出力は、コマンドラインでターゲットのビルドがリクエストされたときにデフォルトでリクエストされる出力です。たとえば、java_library
ターゲット //pkg:foo
のデフォルト出力は foo.jar
であるため、コマンド bazel build //pkg:foo
によってビルドされます。
デフォルトの出力は、DefaultInfo
の files
パラメータで指定します。
def _example_library_impl(ctx):
...
return [
DefaultInfo(files = depset([output_file]), ...),
...
]
ルール実装または files
によって DefaultInfo
が返されない場合
パラメータが指定されていない場合、DefaultInfo.files
はデフォルトですべてに設定されます。
事前に宣言された出力(通常は outputs によって作成される出力)
属性)。
アクションを実行するルールでは、出力が直接使用されないことが想定されていても、デフォルトの出力を指定する必要があります。グラフにないアクションは 出力がプルーニングされます。出力がターゲットのコンシューマによってのみ使用される場合、ターゲットが個別にビルドされている場合、これらのアクションは実行されません。この 失敗したターゲットのみを再構築することはできないため、デバッグが困難になります。 失敗を再現します
Runfiles
Runfile は、(ビルド時ではなく)実行時にターゲットによって使用される一連のファイルです。実行フェーズで、Bazel は runfile を指すシンボリック リンクを含むディレクトリ ツリー。これにより、バイナリの環境がステージングされ、実行時にランファイルにアクセスできるようになります。
ランファイルは、ルールの作成時に手動で追加できます。runfiles
オブジェクトは runfiles
メソッドで作成できます。
ルールのコンテキスト(ctx.runfiles
)で指定され、
DefaultInfo
の runfiles
パラメータ。実行可能な出力は、
実行可能ルールは暗黙的に runfile に追加されます。
一部のルールでは、属性を指定する属性で、通常は
data
: この出力は
ターゲットrunfiles.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 つの値のタプル(init
が使用されていない場合の通常の戻り値であるプロバイダ シンボルと「未加工のコンストラクタ」)に変更されます。
この場合、プロバイダ シンボルが呼び出されたときに、元のアイテムが
引数が init
コールバックに転送されます。コールバックの戻り値は、フィールド名(文字列)を値にマッピングする辞書である必要があります。これは、新しいインスタンスのフィールドを初期化するために使用されます。コールバックには任意のシグネチャを指定できます。引数がシグネチャと一致しない場合、コールバックが直接呼び出されたようにエラーが報告されます。
一方、未加工のコンストラクタは init
コールバックをバイパスします。
次の例では、init
を使用して引数を前処理して検証します。
# //pkg:exampleinfo.bzl
_core_headers = [...] # private constant representing standard library files
# It's possible to define an init accepting positional arguments, but
# 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(
...
init = _exampleinfo_init)
export ExampleInfo
ルールの実装では、次のようにプロバイダをインスタンス化できます。
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
コマンドで呼び出されます。実行可能なルールとテストのルールは、
それぞれの executable
または
rule
の呼び出しの True
に test
引数を追加します。
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
件
(アクションによって呼び出される)基盤のツールによってのみ取得されます。1 つの
ctx.actions.write
アクションの場合は、is_executable=True
を渡します。
従来の動作として、実行可能ルールには特別な ctx.outputs.executable
の事前宣言出力があります。このファイルは、DefaultInfo
を使用して指定しない限り、デフォルトの実行可能ファイルとして機能します。それ以外の場合は使用しないでください。この出力メカニズムは、分析時に実行可能ファイルの名前をカスタマイズできないため、非推奨になりました。
サンプル 実行可能ルール および test Rule です。
実行可能なルールと テストルールには、追加の 属性に加え、暗黙的に定義された属性も すべてのルール。デフォルトの 暗黙的に追加された属性は変更できませんが、回避することはできます Starlark マクロでプライベート ルールをラップして、 default:
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 ルートをパラメータとして受け取る
指定することもできます。これにより、バイナリは呼び出すバイナリに正しい標準の runfile ルートを渡すことができます。設定されていない場合、バイナリはそれが
最初のバイナリが呼び出され、隣接する runfiles ディレクトリを探します。
高度なトピック
出力ファイルのリクエスト
1 つのターゲットに複数の出力ファイルを設定できます。bazel build
コマンドが
コマンドに指定されたターゲットの出力の一部が
リクエストできます。Bazel は、リクエストされたファイルと、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
は
aspect と、そのアスペクトが適用されるルール ターゲット。
同じ出力グループを定義しないようにしてください。その場合、結果のプロバイダが統合されます。
通常、OutputGroupInfo
は、ターゲットからコンシューマのアクションに特定の種類のファイルを伝達するために使用しないでください。定義
ルール固有のプロバイダを使用してください。
構成
別のアーキテクチャ用の C++ バイナリをビルドするとします。ビルドは複雑で、複数のステップが必要な場合があります。コンパイラやコード生成ツールなどの中間バイナリは、実行プラットフォーム(ホストまたはリモート エグゼキュータ)で実行する必要があります。最終出力などの一部のバイナリは、ターゲット アーキテクチャ用にビルドする必要があります。
そのため、Bazel には「構成」という概念があります。3 つあります最上位のターゲット(コマンドラインでリクエストされたターゲット)は「target」構成でビルドされますが、実行プラットフォームで実行する必要があるツールは「exec」構成でビルドされます。ルールは、コンパイラに渡される CPU アーキテクチャを変更するなど、構成に応じて異なるアクションを生成する場合があります。場合によっては、異なる構成に同じライブラリが必要になることがあります。その場合は分析が行われ、場合によっては構築されます 複数回失敗します。
デフォルトでは、Bazel はターゲットの依存関係を つまり、遷移なしでターゲット自体が作成されます。依存関係が 使用する場合は、対応する属性を exec 構成への移行を指定しています。これにより、ツールとそのすべての情報が 実行プラットフォーム用にビルドされます
依存関係属性ごとに、cfg
を使用して、依存関係を同じ構成でビルドするか、exec 構成に移行するかを決定できます。依存関係属性に executable=True
フラグがある場合は、cfg
を設定する必要があります。
明示的に指定することもできます。これは、誤った目的のために誤ってツールを作成しないようにするためです。
できます。
例を表示
一般的に、開発時に必要になるソース、依存ライブラリ、実行可能ファイルは 同じ構成を使用できます。
ビルドの一環として実行されるツール(コンパイラやコード生成ツールなど)
exec 構成用にビルドする必要があります。この場合、cfg="exec"
を
作成します。
それ以外の場合は、テストの一部としてなど、実行時に使用される実行可能ファイルに
構成する必要があります。この場合は、属性に cfg="target"
を指定します。
cfg="target"
は実際には何もしません。これは、ルール設計者が意図を明示するのを助ける、純粋な便宜上の値です。executable=False
の場合、
つまり、cfg
は省略可能で、読みやすくする場合にのみ設定してください。
cfg=my_transition
を使用してユーザー定義の遷移を使用することもできます。これにより、ルール作成者は構成を柔軟に変更できますが、ビルドグラフが大きくなり、わかりにくくなるという欠点があります。
注: 従来、Bazel には実行プラットフォームの概念がなく、 代わりに、すべてのビルド アクションがホストマシンで実行されると見なされていました。Bazel バージョン 6.0 より前のバージョンでは、これを表す構成です コードや古いドキュメントで「ホスト」という用語が使用されている場合は、このホストを指しています。この概念的なオーバーヘッドを回避するには、Bazel 6.0 以降を使用することをおすすめします。
構成フラグメント
ルールによりアクセスできる
構成フラグメント(例:
cpp
、java
、jvm
。ただし、アクセス エラーを回避するには、必要なフラグメントをすべて宣言する必要があります。
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
host_fragments = ["java"], # Required fragments of the host 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
コマンドを実行すると、
ビルドで、特定のターゲットに対するカバレッジ計測の追加が必要になる場合があります。「
build は、インストゥルメント化されるソースファイルのリストも収集します。検討対象となるターゲットのサブセットは、--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
ルールでは、どの属性が関連する属性なのかを
InstrumentedFilesInfo
プロバイダによるカバレッジ。
coverage_common.instrumented_files_info
。
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
が返されない場合、それぞれのデフォルト テーブルが作成されます。
ツール以外の依存関係属性が設定されていない
属性スキーマの cfg
を "host"
または "exec"
)
dependency_attributes
。(属性を指定するため、これは理想的な動作ではありません。
dependency_attributes
の srcs
のように source_attributes
ではなく、
すべてのルールに対して明示的なカバレッジ構成を
必要があります。)
検証アクション
ビルドに関する情報や 検証に必要な情報は、アーティファクトでのみ利用可能 (ソースファイルまたは生成されたファイル)。この情報はアーティファクトに含まれているため、ルールはファイルを読み取ることができないため、分析時にこの検証を行うことはできません。代わりに、アクションは実行時にこの検証を行う必要があります。日時 検証が失敗するとアクションも失敗し、ビルドも失敗します。
実行される検証の例としては、静的分析、リンティング、依存関係と整合性のチェック、スタイルチェックなどがあります。
検証アクションは、部品を動かしてビルドのパフォーマンスを向上させるのにも役立ちます。 必要ないアクションを 1 つにまとめることができます。 たとえば、コンパイルと lint チェックを実行する単一のアクションを コンパイル アクションと lint チェック アクションに分けられ、その後、lint チェックが実行されます。 アクションを検証アクションとして実行し、他のアクションと並行して実行できます。
これらの「検証アクション」は他の場所で使用されるものは生成されず、 出力についてアサートするだけでよいためです。この 問題があります。検証アクションによって結果が生成されることが ルールがビルドの別の場所で使用されている場合、どのようにアクションが実行されるのでしょうか。 これまでは、検証アクションで空の文字列を出力する方法が採用されてきました。 その出力を、他の重要な入力要素に人為的に追加し、 アクションを実行します。
これは、Bazel がコンパイル アクションの実行時に常に検証アクションを実行するため機能しますが、重大な欠点があります。
検証アクションはビルドのクリティカル パスにあります。Bazel は コンパイル アクションを実行するために空の出力が必要であると判断した場合、 入力が無視されますが、コンパイル アクションでは入力が無視されます。 これにより、並列処理が減り、ビルドが遅くなります。
代わりに、ビルド内の他のアクションが コンパイル アクションを実行する場合は、検証アクションの空の出力を
java_library
のソース jar 出力など)。これは、コンパイル アクションの代わりに実行される可能性のある新しいアクションが後で追加され、空の検証出力が誤って省略された場合にも問題になります。
この問題を解決するには、Validations 出力グループを使用します。
検証出力グループ
検証出力グループは、検証アクションの使用されない出力を保持するように設計された出力グループです。これにより、他のアクションの入力に人為的に追加する必要がなくなります。
このグループは、特定のリソースに関係なく、常に出力がリクエストされる
--output_groups
フラグの値。ターゲットの状態は問いません。
たとえば、コマンドライン、依存関係として、あるいは
ターゲットの暗黙的な出力)。通常のキャッシュと増分処理は引き続き適用されます。検証アクションへの入力が変更されておらず、検証アクションが以前に成功した場合、検証アクションは実行されません。
この出力グループを使用する場合も、検証アクションでなんらかのファイルを出力する必要があります。 空のオブジェクトも作成できます。これにより、通常は出力を作成しない一部のツールをラップして、ファイルが作成されるようにする必要があります。
ターゲットの検証アクションは、次の 3 つの場合に実行されません。
- ターゲットがツールとして依存されている場合
- ターゲットが暗黙的な依存関係( 「_」で始まる属性)
- ターゲットが host または exec 構成に組み込まれているとき。
これらのターゲットには、それぞれ固有の ビルドとテストを分離し、検証の失敗を発見できるようにします。
検証出力グループを使用する
検証出力グループの名前は _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
や他のアクションへの入力には追加されません。このルールタイプのターゲットの検証アクションは、ターゲットがラベルに依存している場合、またはターゲットの暗黙的な出力のいずれかが直接的または間接的に依存している場合でも実行されます。
通常、検証アクションの出力は、Cloud Storage バケットに 他のアクションの入力には追加されず、他のアクションの入力には 並列処理のメリットを失う可能性があります。ただし、現在のところ 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
パラメータに明示的に渡します。
避けるべき Runfile の機能
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 = ...)
を指定してください。 「デフォルト」と「data」runfile は できます。たとえば、一部のルールでは、デフォルトの出力がdata_runfiles
に配置されますが、default_runfiles
には配置されません。ルールでは、data_runfiles
を使用する代わりに、デフォルトの出力を追加し、ランファイルを提供する属性(多くの場合data
)からdefault_runfiles
をマージする必要があります。DefaultInfo
からrunfiles
を取得する場合(通常は、現在のルールとその依存関係間での実行ファイルのマージの場合のみ)、DefaultInfo.data_runfiles
ではなくDefaultInfo.default_runfiles
を使用します。
以前のプロバイダからの移行
従来、Bazel プロバイダは Target
オブジェクト上の単純なフィールドでした。これらのフィールドにはドット演算子を使用してアクセスし、ルールの実装関数から返された構造体にフィールドを配置して作成しました。
このスタイルは非推奨であり、新しいコードでは使用しないでください。移行に役立つ情報については、以下をご覧ください。新しいプロバイダ メカニズムでは、名前が 防ぐことができます。データの非表示もサポートします。つまり、すべてのコードが プロバイダ シンボルを使用して取得します。
現時点では、従来のプロバイダは引き続きサポートされます。1 つのルールで、 簡単に説明します。
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 をインターリーブするために、コンシューマがどちらかの provider: 以前のプロバイダが存在するかどうかをテストします。
hasattr(target, 'foo')
、またはFooInfo in target
を使用する新しいプロバイダ。以前のプロバイダをすべてのルールから完全に削除します。