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

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

action_config は、前述の特徴の関係で規定されているように、他の特徴と action_config を要求し、暗黙的に指定できます。この動作は、特徴の動作に似ています。

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

同じ toolchain 内で同じ action_name を持つ複数の action_config を定義することはできません。これにより、ツールパスのあいまいさがなくなり、action_config の意図（アクションのプロパティがツールチェーン内の 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）は、1 つのユニットとして展開されます。例:

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