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 によって実行される 1 つのタイプのアクション（コンパイルやリンクなど）を表します。ただし、アクションと Bazel アクション タイプの間には多対一の関係があります。Bazel アクション タイプは、アクションを実装する Java クラス（CppCompileAction など）を指します。特に、下の表の「アセンブラ アクション」と「コンパイラ アクション」は CppCompileAction ですが、リンク アクションは CppLinkAction です。

アセンブラのアクション

コンパイラ アクション

リンクの操作

AR アクション

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

LTO アクション

action_config の使用

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

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 で使用可能なアプリケーション バンドルと .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（存在しない場合）機能をツールチェーンの先頭に追加
• per_object_debug_info 機能（存在しない場合は追加）を toolchain の先頭に追加
• preprocessor_defines 機能（存在しない場合は追加）を toolchain の先頭に追加
• includes 機能（存在しない場合は追加）を toolchain の先頭に追加
• include_paths 機能（存在しない場合は追加）を toolchain の先頭に追加
• fdo_instrument（存在しない場合）機能をツールチェーンの先頭に追加
• fdo_optimize（存在しない場合）機能をツールチェーンの先頭に追加
• cs_fdo_instrument 機能（存在しない場合は追加）を toolchain の先頭に追加
• cs_fdo_optimize 機能（存在しない場合は追加）を toolchain の先頭に追加
• fdo_prefetch_hints 機能（存在しない場合は追加）を toolchain の先頭に追加
• autofdo（存在しない場合）機能をツールチェーンの先頭に追加
• build_interface_libraries（存在しない場合）機能をツールチェーンの先頭に追加
• dynamic_library_linker_tool 機能（存在しない場合は追加）を toolchain の先頭に追加
• shared_flag 機能（存在しない場合は追加）を toolchain の先頭に追加
• linkstamps 機能（存在しない場合は追加）を toolchain の先頭に追加
• output_execpath_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• runtime_library_search_directories 機能（存在しない場合は追加）を toolchain の先頭に追加
• library_search_directories（存在しない場合）機能をツールチェーンの先頭に追加
• archiver_flags（存在しない場合）機能をツールチェーンの先頭に追加
• libraries_to_link 機能（存在しない場合は追加）を toolchain の先頭に追加
• force_pic_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• user_link_flags（存在しない場合）機能をツールチェーンの先頭に追加
• legacy_link_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• static_libgcc（存在しない場合）機能をツールチェーンの先頭に追加
• fission_support 機能（存在しない場合は追加）を toolchain の先頭に追加
• strip_debug_symbols 機能（存在しない場合は追加）を toolchain の先頭に追加
• coverage 機能（存在しない場合は追加）を toolchain の先頭に追加
• llvm_coverage_map_format（存在しない場合）機能をツールチェーンの先頭に追加
• 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 を追加してツールチェーンをよりスタンドアロンにすることを検討してください。