ツールチェーン

問題を報告open_in_new ソースを表示open_in_new

このページでは、ルール作成者がルールのロジックをプラットフォーム ベースのツール選択から切り離すことができるツールチェーン フレームワークについて説明します。続行する前に、ルールページとプラットフォームページを確認することをおすすめします。このページでは、ツールチェーンが必要な理由、ツールチェーンの定義方法と使用方法、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 つのものが必要です。

1. ツールまたはツールスイートの種類を表す言語固有のルール。慣例的に、このルールの名前には最後に「_ツールチェーン」が追加されます。

   1. 注: \_toolchain ルールでは、ビルド アクションを作成できません。他のルールからアーティファクトを収集し、ツールチェーンを使用するルールに転送します。このルールは、すべてのビルド アクションを作成します。

2. このルールタイプの複数のターゲット。プラットフォーム別のツールやツールスイートのバージョンを表します。

3. このようなターゲットごとに、汎用の 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 の解決手順でツールチェーンを使用できるようにするだけです。これを行うには、WORKSPACE ファイルで register_toolchains() を使用してツールチェーンを登録するか、または --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:toolchain_type 参照を //bar_tools:barc_linux_toolchain に解決します。これにより、最終的に //bar_tools:barc_linux がビルドされますが、//bar_tools:barc_windows はビルドされません。

ツールチェーンの解決

ツールチェーンを使用するターゲットごとに、Bazel のツールチェーンの解決手順でターゲットの具体的なツールチェーンの依存関係を決定します。この手順は、必要なツールチェーン タイプのセット、ターゲット プラットフォーム、使用可能な実行プラットフォームのリスト、使用可能なツールチェーンのリストを入力として受け取ります。出力には、ツールチェーン タイプごとに選択されたツールチェーンと、現在のターゲットに対して選択された実行プラットフォームが含まれます。

使用可能な実行プラットフォームとツールチェーンは、register_execution_platforms と register_toolchains を介して WORKSPACE ファイルから収集されます。追加の実行プラットフォームとツールチェーンは、コマンドラインで --extra_execution_platforms と --extra_toolchains を使用して指定することもできます。ホスト プラットフォームは、利用可能な実行プラットフォームとして自動的に含まれます。利用可能なプラットフォームとツールチェーンは、決定論のため順序付きリストとして追跡され、リスト内の前のアイテムが優先されます。

使用可能なツールチェーンのセットは、優先度順に、--extra_toolchains と register_toolchains から作成されます。

1. --extra_toolchains を使用して登録されたツールチェーンが最初に追加されます。
   1. これらの中で、最後のツールチェーンの優先度が最も高いです。
2. register_toolchains を使用して登録されたツールチェーン
   1. これらの中で、最初に言及したツールチェーンの優先度が最も高くなります。

注: :all、:* などの疑似ターゲットは /... などの疑似ターゲットは Bazel によって順序付けられ、graphic は Bazel のパッケージを使用して読み込みメカニズムを使用します。

解決手順は次のとおりです。

1. target_compatible_with 句または exec_compatible_with 句は、リスト内の各 constraint_value について、その constraint_value も明示的またはデフォルトとしてプラットフォームに存在する場合、プラットフォームに一致します。

   句で参照されない constraint_setting の constraint_value がプラットフォームにある場合、これらはマッチングに影響しません。

2. ビルドされるターゲットで exec_compatible_with 属性が指定されている場合（またはルール定義が exec_compatible_with 引数を指定している場合）、使用可能な実行プラットフォームのリストがフィルタリングされ、実行の制約に一致しないものが除外されます。

3. 使用可能なツールチェーンのリストがフィルタリングされ、現在の構成と一致しない target_settings を指定するツールチェーンが削除されます。

4. 使用可能な実行プラットフォームごとに、各ツールチェーン タイプを、その実行プラットフォームとターゲット プラットフォームと互換性のある、使用可能な最初のツールチェーン（存在する場合）に関連付けます。

5. いずれかのツールチェーン タイプと互換性のある必須ツールチェーンを見つけることができなかった実行プラットフォームは、除外されます。残りのプラットフォームのうち、最初のプラットフォームが現在のターゲットの実行プラットフォームになり、関連するツールチェーン（存在する場合）がターゲットの依存関係になります。

選択した実行プラットフォームは、ターゲットが生成するすべてのアクションを実行するために使用されます。

同じターゲットを同じビルド内の複数の構成（異なる 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