ツールチェーン

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。
問題を報告 ソースを表示

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

このソリューションを改善するには、プラットフォームに基づいて compilerselect で選択します。

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),
    ],
)

同じルール内でフォームを混在させて一致させることもできます。ただし、同じツールチェーン タイプが複数回リストされる場合は、最も厳格なバージョンが使用されます。この場合、required はオプションよりも厳密です。

ツールチェーンを使用する側面の作成

アスペクトは、ルールと同じツールチェーン 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. ツールまたはツールスイートの種類を表す言語固有のルール。慣例により、このルールの名前には接尾辞「_toolchain」が付けられます。

    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" を使用するツールチェーンの依存関係(またはターゲットがデフォルトであるため cfg が指定されていない依存関係)は、親と同じターゲット プラットフォーム用にビルドされます。これにより、ツールチェーン ルールで、ライブラリ(上記の system_lib 属性)とツール(compiler 属性)の両方が必要なビルドルールに貢献できます。システム ライブラリは最終的なアーティファクトにリンクされているため、同じプラットフォーム向けにビルドする必要がありますが、コンパイラはビルド時に呼び出されるツールであり、実行プラットフォームで実行できる必要があります。

ツールチェーンへの登録とビルド

この時点ですべてのビルディング ブロックが組み立てられ、ツールチェーンを Bazel の解決手順で使用できるようにする必要があります。これを行うには、register_toolchains() を使用して WORKSPACE ファイルでツールチェーンを登録するか、--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",
)

ツールチェーン タイプに依存するターゲットをビルドすると、ターゲットと実行プラットフォームに基づいて適切なツールチェーンが選択されます。

# 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 のツールチェーンの解決手順によって、ターゲットの具体的なツールチェーンの依存関係が決定されます。この手順では、一連の必要なツールチェーン タイプ、ターゲット プラットフォーム、使用可能な実行プラットフォームのリスト、使用可能なツールチェーンのリストを入力として使用します。出力は、ツールチェーン タイプごとに選択されたツールチェーンと、現在のターゲットに選択された実行プラットフォームです。

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

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

  1. target_compatible_with または exec_compatible_with 句は、リスト内の各 constraint_value に対して constraint_value が(明示的またはデフォルトとして)指定されている場合に、プラットフォームに一致します。

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

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

  3. 使用可能な実行プラットフォームごとに、各ツールチェーン タイプを、この実行プラットフォームおよびターゲット プラットフォームと互換性のある最初のツールチェーン(ある場合)に関連付けます。

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

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

同じビルド内の複数の構成(異なる 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