このページではツールチェーン フレームワークについて説明します。ツールチェーン フレームワークを使用すると、ルールの作成者はプラットフォーム ベースのツールの選択からルールロジックを切り離すことができます。続行する前に、ルールとプラットフォームのページを読むことをおすすめします。このページでは、ツールチェーンが必要な理由、ツールチェーンを定義して使用する方法、プラットフォームの制約に基づいて Bazel が適切なツールチェーンを選択する方法について説明します。
目的
まず、ツールチェーンで解決できる問題を見ていきましょう。たとえば、プログラミング言語「bar」をサポートするルールを作成するとします。bar_binary
ルールは、barc
コンパイラを使用して *.bar
ファイルをコンパイルします。このコンパイラは、ワークスペースで別のターゲットとしてビルドされるツールです。bar_binary
ターゲットを記述するユーザーはコンパイラへの依存関係を指定する必要はないので、プライベート属性としてルール定義に追加することで、暗黙的な依存関係になります。
bar_binary = rule(
implementation = _bar_binary_impl,
attrs = {
"srcs": attr.label_list(allow_files = True),
...
"_compiler": attr.label(
default = "//bar_tools:barc_linux", # the compiler running on linux
providers = [BarcInfo],
),
},
)
//bar_tools:barc_linux
はすべての bar_binary
ターゲットの依存関係になったため、どの bar_binary
ターゲットよりも先にビルドされます。他の属性と同様に、ルールの実装関数からアクセスできます。
BarcInfo = provider(
doc = "Information about how to invoke the barc compiler.",
# In the real world, compiler_path and system_lib might hold File objects,
# but for simplicity they are strings for this example. arch_flags is a list
# of strings.
fields = ["compiler_path", "system_lib", "arch_flags"],
)
def _bar_binary_impl(ctx):
...
info = ctx.attr._compiler[BarcInfo]
command = "%s -l %s %s" % (
info.compiler_path,
info.system_lib,
" ".join(info.arch_flags),
)
...
ここでの問題は、コンパイラのラベルが bar_binary
にハードコードされているにもかかわらず、ビルド対象のプラットフォームとビルド対象のプラットフォーム(それぞれ「ターゲット プラットフォーム」と「実行プラットフォーム」)に応じて、ターゲットごとに異なるコンパイラが必要になることです。また、ルールの作成者は、使用可能なツールとプラットフォームをすべて把握しているとは限らないため、ルールの定義にこれらをハードコードすることはできません。
理想的ではない解決策は、_compiler
属性を非公開にしないことで、ユーザーに負担をかけることです。このようにして、プラットフォームごとに異なるターゲットをビルドできるようにハードコードできます。
bar_binary(
name = "myprog_on_linux",
srcs = ["mysrc.bar"],
compiler = "//bar_tools:barc_linux",
)
bar_binary(
name = "myprog_on_windows",
srcs = ["mysrc.bar"],
compiler = "//bar_tools:barc_windows",
)
このソリューションは、select
を使用してプラットフォームに基づいて compiler
を選択することで改善できます。
config_setting(
name = "on_linux",
constraint_values = [
"@platforms//os:linux",
],
)
config_setting(
name = "on_windows",
constraint_values = [
"@platforms//os:windows",
],
)
bar_binary(
name = "myprog",
srcs = ["mysrc.bar"],
compiler = select({
":on_linux": "//bar_tools:barc_linux",
":on_windows": "//bar_tools:barc_windows",
}),
)
しかし、これは面倒で、bar_binary
ユーザー一人ひとりに依頼しなければならない作業量が少しだけ多くなります。ワークスペース全体でこのスタイルを一貫して使用していない場合、ビルドは単一プラットフォームでは正常に動作しますが、マルチプラットフォームのシナリオに拡張すると失敗します。また、既存のルールやターゲットを変更せずに、新しいプラットフォームやコンパイラのサポートを追加する問題にも対応していません。
ツールチェーン フレームワークは、別のレベルの間接性を追加することで、この問題を解決します。基本的に、ルールがターゲット ファミリー(ツールチェーン タイプ)の一部と抽象的な依存関係を持つことを宣言します。Bazel は、該当するプラットフォーム制約に基づいて、これを特定のターゲット(ツールチェーン)に自動的に解決します。ルール作成者もターゲット作成者も、使用可能なプラットフォームとツールチェーンの完全なセットを知る必要はありません。
ツールチェーンを使用するルールを作成する
ツールチェーン フレームワークでは、ルールはツールに直接依存するのではなく、ツールチェーン タイプに依存します。ツールチェーン タイプは、複数のプラットフォームで同じ役割を果たすツールのクラスを表す単純なターゲットです。たとえば、バーコンパイラを表す型を宣言できます。
# By convention, toolchain_type targets are named "toolchain_type" and
# distinguished by their package path. So the full path for this would be
# //bar_tools:toolchain_type.
toolchain_type(name = "toolchain_type")
前のセクションのルール定義は、コンパイラを属性として取り込む代わりに、//bar_tools:toolchain_type
ツールチェーンを使用することを宣言するように変更されています。
bar_binary = rule(
implementation = _bar_binary_impl,
attrs = {
"srcs": attr.label_list(allow_files = True),
...
# No `_compiler` attribute anymore.
},
toolchains = ["//bar_tools:toolchain_type"],
)
実装関数は、ツールチェーン タイプをキーとして使用し、ctx.attr
ではなく ctx.toolchains
でこの依存関係にアクセスするようになりました。
def _bar_binary_impl(ctx):
...
info = ctx.toolchains["//bar_tools:toolchain_type"].barcinfo
# The rest is unchanged.
command = "%s -l %s %s" % (
info.compiler_path,
info.system_lib,
" ".join(info.arch_flags),
)
...
ctx.toolchains["//bar_tools:toolchain_type"]
は、ツールチェーンの依存関係が解決されたターゲット Bazel の ToolchainInfo
プロバイダを返します。ToolchainInfo
オブジェクトのフィールドは、基になるツールのルールによって設定されます。次のセクションでは、BarcInfo
オブジェクトをラップする barcinfo
フィールドが存在するようにこのルールを定義します。
ツールチェーンをターゲットに解決する Bazel の手順については、以下をご覧ください。実際には、候補ツールチェーンの領域全体ではなく、解決されたツールチェーン ターゲットのみが bar_binary
ターゲットの依存関係になります。
必須およびオプションのツールチェーン
デフォルトでは、上記のように、ルールがベアラベルを使用してツールチェーン型の依存関係を表現している場合、ツールチェーン タイプは必須と見なされます。必須のツールチェーン タイプに対応するツールチェーン(下記のツールチェーンの解決策を参照)を Bazel が見つけられない場合、エラーとなり分析が停止します。
代わりに、次のように、オプションのツールチェーン タイプの依存関係を宣言することもできます。
bar_binary = rule(
...
toolchains = [
config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = False),
],
)
オプションのツールチェーン タイプを解決できない場合、分析は続行され、ctx.toolchains["//bar_tools:toolchain_type"]
の結果は None
になります。
config_common.toolchain_type
関数は、デフォルトで必須となっています。
以下の形式を使用できます。
- 必須のツールチェーン タイプ:
toolchains = ["//bar_tools:toolchain_type"]
toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type")]
toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = True)]
- オプションのツールチェーン タイプ:
toolchains = [config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = False)]
bar_binary = rule(
...
toolchains = [
"//foo_tools:toolchain_type",
config_common.toolchain_type("//bar_tools:toolchain_type", mandatory = False),
],
)
同じルールでフォームを組み合わせることもできます。ただし、同じツールチェーン タイプが複数回リストされている場合、最も厳密なバージョンが使用されます(必須のバージョンがオプションよりも厳格になります)。
ツールチェーンを使用するアスペクトの記述
アスペクトはルールと同じツールチェーン API にアクセスできます。必要なツールチェーン タイプを定義し、コンテキストを介してツールチェーンにアクセスし、ツールチェーンを使用して新しいアクションを生成できます。
bar_aspect = aspect(
implementation = _bar_aspect_impl,
attrs = {},
toolchains = ['//bar_tools:toolchain_type'],
)
def _bar_aspect_impl(target, ctx):
toolchain = ctx.toolchains['//bar_tools:toolchain_type']
# Use the toolchain provider like in a rule.
return []
ツールチェーンの定義
特定のツールチェーン タイプのツールチェーンを定義するには、次の 3 つが必要です。
ツールやツールスイートの種類を表す言語固有のルール。慣例により、このルール名には末尾に「_ツールチェーン」が付きます。
- 注:
\_toolchain
ルールではビルド アクションを作成できません。代わりに、他のルールからアーティファクトを収集し、ツールチェーンを使用するルールに転送します。このルールにより、すべてのビルド アクションが作成されます。
- 注:
さまざまなプラットフォームのツールスイートのバージョンを表す、このルールタイプの複数のターゲット。
そのようなターゲットごとに汎用
toolchain
ルールの関連ターゲット。ツールチェーン フレームワークで使用されるメタデータを提供します。このtoolchain
ターゲットは、このツールチェーンに関連付けられたtoolchain_type
も参照します。つまり、特定の_toolchain
ルールを任意のtoolchain_type
に関連付けることができます。この_toolchain
ルールを使用するtoolchain
インスタンスでのみ、ルールがtoolchain_type
に関連付けられます。
実行例における bar_toolchain
ルールの定義は次のとおりです。この例ではコンパイラしかありませんが、リンカーなどの他のツールもその下でグループ化できます。
def _bar_toolchain_impl(ctx):
toolchain_info = platform_common.ToolchainInfo(
barcinfo = BarcInfo(
compiler_path = ctx.attr.compiler_path,
system_lib = ctx.attr.system_lib,
arch_flags = ctx.attr.arch_flags,
),
)
return [toolchain_info]
bar_toolchain = rule(
implementation = _bar_toolchain_impl,
attrs = {
"compiler_path": attr.string(),
"system_lib": attr.string(),
"arch_flags": attr.string_list(),
},
)
ルールは ToolchainInfo
プロバイダを返す必要があります。これは、使用ルールが ctx.toolchains
とツールチェーン タイプのラベルを使用して取得するオブジェクトになります。ToolchainInfo
は、struct
と同様に、任意のフィールド値のペアを保持できます。ToolchainInfo
に追加するフィールドの正確な仕様は、ツールチェーン タイプに明記する必要があります。この例では、上で定義したスキーマを再利用するために、値が BarcInfo
オブジェクトにラップされて返されます。このスタイルは、検証やコードの再利用に役立ちます。
特定の barc
コンパイラのターゲットを定義できるようになりました。
bar_toolchain(
name = "barc_linux",
arch_flags = [
"--arch=Linux",
"--debug_everything",
],
compiler_path = "/path/to/barc/on/linux",
system_lib = "/usr/lib/libbarc.so",
)
bar_toolchain(
name = "barc_windows",
arch_flags = [
"--arch=Windows",
# Different flags, no debug support on windows.
],
compiler_path = "C:\\path\\on\\windows\\barc.exe",
system_lib = "C:\\path\\on\\windows\\barclib.dll",
)
最後に、2 つの bar_toolchain
ターゲットの toolchain
定義を作成します。これらの定義は、言語固有のターゲットをツールチェーン タイプにリンクし、ツールチェーンが特定のプラットフォームに適している場合に Bazel に指示する制約情報を提供します。
toolchain(
name = "barc_linux_toolchain",
exec_compatible_with = [
"@platforms//os:linux",
"@platforms//cpu:x86_64",
],
target_compatible_with = [
"@platforms//os:linux",
"@platforms//cpu:x86_64",
],
toolchain = ":barc_linux",
toolchain_type = ":toolchain_type",
)
toolchain(
name = "barc_windows_toolchain",
exec_compatible_with = [
"@platforms//os:windows",
"@platforms//cpu:x86_64",
],
target_compatible_with = [
"@platforms//os:windows",
"@platforms//cpu:x86_64",
],
toolchain = ":barc_windows",
toolchain_type = ":toolchain_type",
)
上記の相対パス構文を使用すると、これらの定義がすべて同じパッケージ内にあることが示唆されますが、ツールチェーン タイプ、言語固有のツールチェーン ターゲット、toolchain
定義ターゲットをすべて別のパッケージに含めることができない理由はありません。
実際の例については、go_toolchain
をご覧ください。
ツールチェーンと構成
ルール作成者にとって重要な問題は、bar_toolchain
ターゲットの分析時に、どのような構成が認識され、依存関係にどの遷移を使用するかです。上記の例では文字列属性を使用していますが、Bazel リポジトリ内の他のターゲットに依存する複雑なツールチェーンではどうなるでしょうか。
bar_toolchain
のより複雑なバージョンを見てみましょう。
def _bar_toolchain_impl(ctx):
# The implementation is mostly the same as above, so skipping.
pass
bar_toolchain = rule(
implementation = _bar_toolchain_impl,
attrs = {
"compiler": attr.label(
executable = True,
mandatory = True,
cfg = "exec",
),
"system_lib": attr.label(
mandatory = True,
cfg = "target",
),
"arch_flags": attr.string_list(),
},
)
attr.label
の使用方法は標準ルールの場合と同じですが、cfg
パラメータの意味は若干異なります。
ツールチェーンの解決によるターゲット(「親」)からツールチェーンへの依存関係では、「ツールチェーン遷移」と呼ばれる特別な構成遷移が使用されます。ツールチェーンの遷移では、実行プラットフォームが親のツールチェーンと同じになるように強制される点を除き、構成はそのまま維持されます(そうしないと、ツールチェーンのツールチェーンの解決で任意の実行プラットフォームが選択され、必ずしも親と同じになるとは限りません)。これにより、ツールチェーンの exec
依存関係も親のビルド アクションで実行できるようになります。cfg =
"target"
を使用する(または「target」がデフォルトであるため cfg
を指定しない)ツールチェーンの依存関係は、親と同じターゲット プラットフォームに対してビルドされます。これにより、ツールチェーン ルールは、ライブラリ(上記の system_lib
属性)とツール(compiler
属性)の両方を必要とするビルドルールに貢献できます。システム ライブラリは最終的なアーティファクトにリンクされているため、同じプラットフォーム向けにビルドする必要がありますが、コンパイラはビルド中に呼び出されるツールであり、実行プラットフォームで実行できる必要があります。
ツールチェーンを使用した登録とビルド
この時点ですべてのビルディング ブロックが組み立てられます。必要なのは、Bazel の解決手順でツールチェーンを使用できるようにするだけです。これを行うには、register_toolchains()
を使用して MODULE.bazel
ファイルでツールチェーンを登録するか、--extra_toolchains
フラグを使用してツールチェーンのラベルをコマンドラインに渡します。
register_toolchains(
"//bar_tools:barc_linux_toolchain",
"//bar_tools:barc_windows_toolchain",
# Target patterns are also permitted, so you could have also written:
# "//bar_tools:all",
# or even
# "//bar_tools/...",
)
ターゲット パターンを使用してツールチェーンを登録する場合、個々のツールチェーンの登録順序は次のルールによって決まります。
- パッケージのサブパッケージで定義されたツールチェーンは、パッケージ自体で定義されたツールチェーンの前に登録されます。
- パッケージ内では、ツールチェーンは名前の辞書順で登録されます。
これで、ツールチェーン タイプに依存するターゲットをビルドすると、ターゲット プラットフォームと実行プラットフォームに基づいて適切なツールチェーンが選択されるようになります。
# my_pkg/BUILD
platform(
name = "my_target_platform",
constraint_values = [
"@platforms//os:linux",
],
)
bar_binary(
name = "my_bar_binary",
...
)
bazel build //my_pkg:my_bar_binary --platforms=//my_pkg:my_target_platform
Bazel は、@platforms//os:linux
があるプラットフォームで //my_pkg:my_bar_binary
がビルドされていることを認識するため、//bar_tools:barc_linux_toolchain
への //bar_tools:toolchain_type
参照が解決されます。これにより、最終的に //bar_tools:barc_linux
がビルドされますが、//bar_tools:barc_windows
はビルドされません。
ツールチェーンの解像度
ツールチェーンを使用するターゲットごとに、Bazel のツールチェーンの解決手順により、ターゲットの具体的なツールチェーンの依存関係が決定されます。このプロシージャは、必要なツールチェーン タイプのセット、ターゲット プラットフォーム、使用可能な実行プラットフォームのリスト、使用可能なツールチェーンのリストを入力として受け取ります。出力は、ツールチェーン タイプごとに選択されたツールチェーンと、現在のターゲットに選択された実行プラットフォームです。
使用可能な実行プラットフォームとツールチェーンは、MODULE.bazel
ファイルで register_execution_platforms
と register_toolchains
の呼び出しを介して外部依存関係グラフから収集されます。--extra_execution_platforms
と --extra_toolchains
を使用して、追加の実行プラットフォームとツールチェーンをコマンドラインで指定することもできます。ホスト プラットフォームは、使用可能な実行プラットフォームとして自動的に含まれます。利用可能なプラットフォームとツールチェーンは、決定論のための順序付きリストとして追跡され、リスト内の以前のアイテムが優先されます。
使用可能なツールチェーンのセットは、優先順位順に --extra_toolchains
と register_toolchains
から作成されます。
--extra_toolchains
を使用して登録されたツールチェーンが最初に追加されます。(これらの内では、最後のツールチェーンが最も優先順位が最も高くなります)。- 推移的外部依存関係グラフで
register_toolchains
を使用して登録されたツールチェーンは、次の順序で並べられます(これらの中で、最初のツールチェーンが最優先されます)。- ルート モジュールによって登録されたツールチェーン(ワークスペース ルートの
MODULE.bazel
など)。 - ユーザーの
WORKSPACE
ファイルに登録されているツールチェーン(そこから呼び出されるマクロを含む) - ルート以外のモジュールによって登録されたツールチェーン(ルート モジュールによって指定された依存関係とその依存関係など)
- 「WORKSPACE サフィックス」に登録されたツールチェーン。これは、Bazel インストールにバンドルされている特定のネイティブ ルールでのみ使用されます。
- ルート モジュールによって登録されたツールチェーン(ワークスペース ルートの
注: :all
、:*
、/...
などの疑似ターゲットは、辞書順で Bazel のパッケージ ロード メカニズムで並べ替えられます。
解決手順は次のとおりです。
target_compatible_with
句またはexec_compatible_with
句は、リスト内の各constraint_value
に(明示的に、またはデフォルトとして)そのconstraint_value
も含まれている場合、プラットフォームに一致します。プラットフォームに、句で参照されていない
constraint_setting
のconstraint_value
がある場合、これらはマッチングには影響しません。ビルド中のターゲットで
exec_compatible_with
属性が指定されている場合(またはルール定義でexec_compatible_with
引数が指定されている場合)、使用可能な実行プラットフォームのリストはフィルタされ、実行制約に一致しないものが削除されます。使用可能なツールチェーンのリストがフィルタされ、現在の構成と一致しない
target_settings
を指定するツールチェーンがすべて削除されます。使用可能な実行プラットフォームごとに、各ツールチェーン タイプを、この実行プラットフォームとターゲット プラットフォームと互換性のある最初に使用可能なツールチェーン(存在する場合)に関連付けます。
ツールチェーン タイプのいずれかに対応する必須ツールチェーンを検出できなかった実行プラットフォームは除外されます。残りのプラットフォームのうち、最初のプラットフォームが現在のターゲットの実行プラットフォームになり、関連するツールチェーン(存在する場合)がターゲットの依存関係になります。
選択した実行プラットフォームは、ターゲットが生成するすべてのアクションの実行に使用されます。
同じビルド内の複数の構成(異なる CPU など)で同じターゲットをビルドできる場合、解決手順はターゲットの各バージョンに独立して適用されます。
ルールで実行グループを使用する場合、各実行グループはツールチェーンの解決を個別に行い、それぞれに独自の実行プラットフォームとツールチェーンがあります。
ツールチェーンのデバッグ
既存のルールにツールチェーン サポートを追加する場合は、--toolchain_resolution_debug=regex
フラグを使用します。このフラグは、ツールチェーンの解決中に、正規表現変数に一致するツールチェーン タイプまたはターゲット名の詳細を出力します。.*
を使用すると、すべての情報を出力できます。Bazel は、解決プロセスでチェックしてスキップするツールチェーンの名前を出力します。
ツールチェーン解決による cquery
依存関係を確認するには、cquery
の --transitions
フラグを使用します。
# Find all direct dependencies of //cc:my_cc_lib. This includes explicitly
# declared dependencies, implicit dependencies, and toolchain dependencies.
$ bazel cquery 'deps(//cc:my_cc_lib, 1)'
//cc:my_cc_lib (96d6638)
@bazel_tools//tools/cpp:toolchain (96d6638)
@bazel_tools//tools/def_parser:def_parser (HOST)
//cc:my_cc_dep (96d6638)
@local_config_platform//:host (96d6638)
@bazel_tools//tools/cpp:toolchain_type (96d6638)
//:default_host_platform (96d6638)
@local_config_cc//:cc-compiler-k8 (HOST)
//cc:my_cc_lib.cc (null)
@bazel_tools//tools/cpp:grep-includes (HOST)
# Which of these are from toolchain resolution?
$ bazel cquery 'deps(//cc:my_cc_lib, 1)' --transitions=lite | grep "toolchain dependency"
[toolchain dependency]#@local_config_cc//:cc-compiler-k8#HostTransition -> b6df211