C++ ツールチェーンの構成

概要

適切なオプションでコンパイラを呼び出すには、Bazel がコンパイラの内部（インクルード ディレクトリや重要なフラグなど）に関する知識を必要とします。つまり、Bazel はコンパイラの動作を理解するために、コンパイラの簡素化されたモデルを必要とします。

Bazel は次の情報を把握する必要があります。

• コンパイラが thinLTO、モジュール、動的リンク、PIC（位置独立コード）をサポートしているかどうか。
• 必要なツール（gcc、ld、ar、objcopy など）のパス。
• 組み込みのシステム インクルード ディレクトリ。Bazel は、ソースファイルに含まれているすべてのヘッダーが BUILD ファイルで正しく宣言されていることを検証するために、これらを必要とします。
• デフォルトの sysroot。
• コンパイル、リンク、アーカイブに使用するフラグ。
• サポートされているコンパイル モード（opt、dbg、fastbuild）に使用するフラグ。
• コンパイラで特に必要な変数を作成します。

コンパイラが複数のアーキテクチャをサポートしている場合は、Bazel でそれらを個別に構成する必要があります。

CcToolchainConfigInfo は、Bazel の C++ ルールの動作を構成するために必要なレベルの粒度を提供するプロバイダです。デフォルトでは、Bazel はビルドの CcToolchainConfigInfo を自動的に構成しますが、手動で構成することもできます。そのためには、CcToolchainConfigInfo を提供する Starlark ルールが必要で、cc_toolchain の toolchain_config 属性をルールに指す必要があります。CcToolchainConfigInfo は cc_common.create_cc_toolchain_config_info() を呼び出して作成できます。このプロセスで必要となるすべての構造体の Starlark コンストラクタは、@rules_cc//cc:cc_toolchain_config_lib.bzl にあります。

C++ ターゲットが分析フェーズに入ると、Bazel は BUILD ファイルに基づいて適切な cc_toolchain ターゲを選択し、cc_toolchain.toolchain_config 属性で指定されたターゲットから CcToolchainConfigInfo プロバイダを取得します。cc_toolchain ターゲットは、この情報を CcToolchainProvider を介して C++ ターゲットに渡します。

たとえば、cc_binary や cc_library などのルールによってインスタンス化されるコンパイル アクションやリンク アクションには、次の情報が必要です。

• 使用するコンパイラまたはリンカー
• コンパイラ/リンカーのコマンドライン フラグ
• --copt/--linkopt オプションを介して渡される構成フラグ
• 環境変数
• アクションが実行されるサンドボックスで必要なアーティファクト

サンドボックスで必要なアーティファクトを除く上記のすべての情報は、cc_toolchain が参照する Starlark ターゲットで指定されます。

サンドボックスに送信されるアーティファクトは、cc_toolchain ターゲットで宣言されます。たとえば、cc_toolchain.linker_files 属性を使用して、サンドボックスに送信するリンカー バイナリとツールチェーン ライブラリを指定できます。

ツールチェーンの選択

ツールチェーンの選択ロジックは次のように動作します。

1. ユーザーは BUILD ファイルで cc_toolchain_suite ターゲットを指定し、--crosstool_top オプションを使用して Bazel をターゲットに指します。

2. cc_toolchain_suite ターゲットは複数のツールチェーンを参照します。--cpu フラグと --compiler フラグの値によって、--cpu フラグの値のみに基づいて、または結合 --cpu | --compiler 値に基づいて、どのツールチェーンが選択されるかが決まります。選定プロセスは次のとおりです。

   • --compiler オプションが指定されている場合、Bazel は --cpu | --compiler を使用して cc_toolchain_suite.toolchains 属性から対応するエントリを選択します。Bazel が対応するエントリを見つけられない場合は、エラーがスローされます。

   • --compiler オプションが指定されていない場合、Bazel は --cpu のみを使用して cc_toolchain_suite.toolchains 属性から対応するエントリを選択します。

   • フラグが指定されていない場合、Bazel はホストシステムを検査し、検出結果に基づいて --cpu 値を選択します。検査メカニズムのコードをご覧ください。

ツールチェーンを選択すると、Starlark ルール内の対応する feature オブジェクトと action_config オブジェクトがビルドの構成（後述の項目）を管理します。これらのメッセージを使用すると、Bazel バイナリを変更せずに、Bazel で完全な C++ 機能を実装できます。C++ ルールは、Bazel ソースコードで詳細に説明されている複数の一意のアクションをサポートしています。

機能

機能とは、コマンドライン フラグ、アクション、実行環境の制約、依存関係の変更を必要とするエンティティです。機能は、BUILD ファイルが treat_warnings_as_errors などのフラグの構成を選択できるようにする、C++ ルールを操作して、header_modules や thin_lto などの新しいコンパイル アクションと入力をコンパイルに含めるなど、単純なものにできます。

理想的には、CcToolchainConfigInfo に機能のリストが含まれています。各機能は 1 つ以上のフラググループで構成され、各グループは特定の Bazel アクションに適用されるフラグのリストを定義します。

機能は名前で指定されるため、Starlark ルール構成と Bazel リリースを完全に分離できます。つまり、新しい機能の使用を必要としない限り、Bazel のリリースは CcToolchainConfigInfo 構成の動作に影響しません。

機能は次のいずれかの方法で有効にします。

• 特徴の enabled フィールドが true に設定されている。
• Bazel またはルールのオーナーが明示的に有効にします。
• ユーザーは、--feature Bazel オプションまたは features ルール属性で有効にします。

機能には相互依存関係があり、コマンドライン フラグ、BUILD ファイル設定、その他の変数に依存する場合があります。

特徴の関係

通常、依存関係は Bazel で直接管理されます。Bazel は、要件を適用し、ビルドで定義された機能の性質に固有の競合を管理します。ツールチェーン仕様では、機能のサポートと拡張を管理する Starlark ルール内で直接使用できる、よりきめ細かい制約を指定できます。具体的には、次のとおりです。

requires = [
   feature_set (features = [
       'feature-name-1',
       'feature-name-2'
   ]),
]

implies = ['feature']

provides = ['feature']

with_features = [
  with_feature_set(
    features = ['feature-1'],
    not_features = ['feature-2'],
  ),
]

操作

アクションを使用すると、アクションの実行方法を想定することなく、アクションの実行条件を柔軟に変更できます。action_config は、アクションが呼び出すツール バイナリを指定します。一方、feature は、アクションが呼び出されたときにそのツールの動作を決定する構成（フラグ）を指定します。

機能はアクションを参照して、影響を受ける Bazel アクションを通知します。これは、アクションが Bazel アクショングラフを変更できるためです。CcToolchainConfigInfo プロバイダには、c++-compile など、フラグとツールが関連付けられているアクションが含まれています。フラグは、特徴に関連付けることで各アクションに割り当てられます。

各アクション名は、コンパイルやリンクなど、Bazel が実行する単一のアクション タイプを表します。ただし、アクションと Bazel アクション タイプの間には多対一の関係があります。Bazel アクション タイプは、アクションを実装する Java クラス（CppCompileAction など）を指します。特に、下の表の「アセンブラ アクション」と「コンパイラ アクション」は CppCompileAction ですが、リンク アクションは CppLinkAction です。

アセンブラのアクション

コンパイラ アクション

リンクの操作

AR アクション

AR アクションは、ar を介してオブジェクト ファイルをアーカイブ ライブラリ（.a ファイル）にアセンブルし、一部のセマンティクスを名前にエンコードします。

LTO アクション

action_config の使用

action_config は、アクション中に呼び出すツール（バイナリ）と、機能で定義されたフラグのセットを指定して、Bazel アクションを記述する Starlark 構造体です。これらのフラグは、アクションの実行に制約を適用します。

action_config() コンストラクタには、次のパラメータがあります。

action_config は、前述の特徴の関係に従って、他の特徴と action_config を必要としたり、暗黙的に指定したりできます。この動作は、特徴の動作に似ています。

最後の 2 つの属性は、特徴の対応する属性と重複しています。一部の Bazel アクションには特定のフラグまたは環境変数が必要であり、不要な action_config+feature ペアを回避することを目的としているため、これらの属性が含まれています。通常、1 つの特徴を複数の action_config で共有することをおすすめします。

同じ toolchain 内で同じ action_name を持つ複数の action_config を定義することはできません。これにより、ツールパスの曖昧さが解消され、action_config の背後にある意図（アクションのプロパティが toolchain の 1 か所で明確に記述されていること）が適用されます。

ツールのコンストラクタを使用する

action_config は、tools パラメータを使用して一連のツールを指定できます。tool() コンストラクタは次のパラメータを取ります。

特定の action_config の場合、ツールパスと実行要件を Bazel アクションに適用するのは 1 つの tool のみです。ツールは、特徴構成に一致する with_feature が設定されたツールが見つかるまで、action_config の tools 属性を反復処理することで選択されます（詳細については、このページの上部にある特徴の関係をご覧ください）。ツールリストの最後に、空の特徴量構成に対応するデフォルト ツールを追加する必要があります。

使用例

特徴とアクションを組み合わせて、さまざまなクロスプラットフォーム セマンティクスで Bazel アクションを実装できます。たとえば、macOS でデバッグ シンボルを生成するには、コンパイル アクションでシンボルを生成し、リンク アクション中に専用のツールを呼び出して圧縮された dsym アーカイブを作成し、そのアーカイブを解凍して Xcode で使用できる App Bundle と .plist ファイルを作成する必要があります。

Bazel では、このプロセスは次のように実装できます。ここで、unbundle-debuginfo は Bazel アクションです。

load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            tool (path = "toolchain/mac/ld"),
        ],
    ),
]

features = [
    feature(
        name = "generate-debug-symbols",
        flag_sets = [
            flag_set (
                actions = [
                    ACTION_NAMES.c_compile,
                    ACTION_NAMES.cpp_compile
                ],
                flag_groups = [
                    flag_group(
                        flags = ["-g"],
                    ),
                ],
            )
        ],
        implies = ["unbundle-debuginfo"],
   ),
]

この同じ機能は、fission を使用する Linux と、.pdb ファイルを生成する Windows で、まったく異なる方法で実装できます。たとえば、fission ベースのデバッグ シンボル生成の実装は次のようになります。

load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        name = ACTION_NAMES.cpp_compile,
        tools = [
            tool(
                path = "toolchain/bin/gcc",
            ),
        ],
    ),
]

features = [
    feature (
        name = "generate-debug-symbols",
        requires = [with_feature_set(features = ["dbg"])],
        flag_sets = [
            flag_set(
                actions = [ACTION_NAMES.cpp_compile],
                flag_groups = [
                    flag_group(
                        flags = ["-gsplit-dwarf"],
                    ),
                ],
            ),
            flag_set(
                actions = [ACTION_NAMES.cpp_link_executable],
                flag_groups = [
                    flag_group(
                        flags = ["-Wl", "--gdb-index"],
                    ),
                ],
            ),
      ],
    ),
]

フラググループ

CcToolchainConfigInfo を使用すると、フラグを特定の目的のグループにバンドルできます。フラグ値内で事前定義された変数を使用してフラグを指定できます。このフラグは、ビルドコマンドにフラグを追加するときにコンパイラによって展開されます。次に例を示します。

flag_group (
    flags = ["%{output_execpath}"],
)

この場合、フラグの内容はアクションの出力ファイルパスに置き換えられます。

フラググループは、リストに表示される順序（上から下、左から右）で、ビルドコマンドに展開されます。

ビルドコマンドに追加するときに異なる値で繰り返す必要があるフラグの場合、フラググループは list 型の変数を反復処理できます。たとえば、型が list の変数 include_path は次のようになります。

flag_group (
    iterate_over = "include_paths",
    flags = ["-I%{include_paths}"],
)

は、include_paths リスト内のパス要素ごとに -I<path> に展開されます。フラググループ宣言の本体にあるすべてのフラグ（または flag_group）は、単位として展開されます。次に例を示します。

flag_group (
    iterate_over = "include_paths",
    flags = ["-I", "%{include_paths}"],
)

は、include_paths リスト内のパス要素ごとに -I <path> に展開されます。

変数は複数回繰り返すことができます。次に例を示します。

flag_group (
    iterate_over = "include_paths",
    flags = ["-iprefix=%{include_paths}", "-isystem=%{include_paths}"],
)

は次のように展開されます。

-iprefix=<inc0> -isystem=<inc0> -iprefix=<inc1> -isystem=<inc1>

変数は、ドット表記を使用してアクセスできる構造に対応できます。次に例を示します。

flag_group (
    flags = ["-l%{libraries_to_link.name}"],
)

構造体はネスト可能で、シーケンスを含めることもできます。名前の競合を回避し、明示的に指定するには、フィールドの完全パスを指定する必要があります。次に例を示します。

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flags = ["-l%{libraries_to_link.shared_libraries.name}"],
        ),
    ],
)

条件付き拡張

フラググループは、expand_if_available、expand_if_not_available、expand_if_true、expand_if_false、expand_if_equal 属性を使用して、特定の変数またはそのフィールドの存在に基づく条件付き展開をサポートしています。次に例を示します。

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flag_groups = [
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--whole_archive"],
                ),
                flag_group (
                    flags = ["-l%{libraries_to_link.shared_libraries.name}"],
                ),
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--no_whole_archive"],
                ),
            ],
        ),
    ],
)

CcToolchainConfigInfo リファレンス

このセクションでは、C++ ルールを正常に構成するために必要なビルド変数、機能、その他の情報を紹介します。

CcToolchainConfigInfo ビルド変数

以下は、CcToolchainConfigInfo ビルド変数のリファレンスです。

よく知られた機能

以下に、機能とその有効化条件を示します。

レガシー機能のパッチ適用ロジック

Bazel は、下位互換性を確保するために、ツールチェーンの機能に次の変更を適用します。

• legacy_compile_flags 機能を toolchain の上部に移動
• default_compile_flags 機能を toolchain の上部に移動
• dependency_file 機能（存在しない場合は追加）を toolchain の先頭に追加
• pic 機能（存在しない場合は追加）を toolchain の先頭に追加
• per_object_debug_info 機能（存在しない場合は追加）を toolchain の先頭に追加
• preprocessor_defines 機能（存在しない場合は追加）を toolchain の先頭に追加
• includes 機能（存在しない場合は追加）を toolchain の先頭に追加
• include_paths 機能（存在しない場合は追加）を toolchain の先頭に追加
• fdo_instrument 機能（存在しない場合は追加）を toolchain の先頭に追加
• fdo_optimize 機能（存在しない場合は追加）を toolchain の先頭に追加
• cs_fdo_instrument 機能（存在しない場合は追加）を toolchain の先頭に追加
• cs_fdo_optimize 機能（存在しない場合は追加）を toolchain の先頭に追加
• fdo_prefetch_hints 機能（存在しない場合は追加）を toolchain の先頭に追加
• autofdo 機能（存在しない場合は追加）を toolchain の先頭に追加
• build_interface_libraries 機能（存在しない場合は追加）を toolchain の先頭に追加
• dynamic_library_linker_tool 機能（存在しない場合は追加）を toolchain の先頭に追加
• shared_flag 機能（存在しない場合は追加）を toolchain の先頭に追加
• linkstamps 機能（存在しない場合は追加）を toolchain の先頭に追加
• output_execpath_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• runtime_library_search_directories 機能（存在しない場合は追加）を toolchain の先頭に追加
• library_search_directories 機能（存在しない場合は追加）を toolchain の先頭に追加
• archiver_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• libraries_to_link 機能（存在しない場合は追加）を toolchain の先頭に追加
• force_pic_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• user_link_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• legacy_link_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• static_libgcc 機能（存在しない場合は追加）を toolchain の先頭に追加
• fission_support 機能（存在しない場合は追加）を toolchain の先頭に追加
• strip_debug_symbols 機能（存在しない場合は追加）を toolchain の先頭に追加
• coverage 機能（存在しない場合は追加）を toolchain の先頭に追加
• llvm_coverage_map_format 機能（存在しない場合は追加）を toolchain の先頭に追加
• gcc_coverage_map_format 機能（存在しない場合は追加）を toolchain の先頭に追加
• fully_static_link 機能をツールチェーンの一番下に追加（存在しない場合）
• user_compile_flags 機能をツールチェーンの一番下に追加（存在しない場合）
• sysroot 機能をツールチェーンの一番下に追加（存在しない場合）
• unfiltered_compile_flags 機能をツールチェーンの一番下に追加（存在しない場合）
• linker_param_file 機能をツールチェーンの一番下に追加（存在しない場合）
• compiler_input_flags 機能をツールチェーンの一番下に追加（存在しない場合）
• compiler_output_flags 機能をツールチェーンの一番下に追加（存在しない場合）

機能のリストは長くなります。Starlark での Crosstool が完了したら、これらを削除する予定です。詳しくは、CppActionConfigs の実装をご覧ください。本番環境のツールチェーンの場合は、no_legacy_features を追加してツールチェーンをよりスタンドアロンにすることを検討してください。