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 アクション タイプの間には多対 1 の関係があります。Bazel アクション タイプは、アクション（CppCompileAction など）を実装する Java クラスを指します。具体的には、以下の表の「アセンブラ アクション」と「コンパイラ アクション」は 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 で共有することをおすすめします。

同じツールチェーン内で同じ action_name を使用して複数の action_config を定義することはできません。これにより、ツールパスのあいまいさが回避され、action_config の背後にある意図（アクションのプロパティがツールチェーン内の 1 つの場所に明確に記述されている）が強制されます。

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

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

特定の action_config に対して、1 つの tool のみがツールパスと実行要件を Bazel アクションに適用します。ツールは、機能構成に一致する 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 機能をツールチェーンの先頭に移動
• default_compile_flags 機能をツールチェーンの先頭に移動
• ツールチェーンの先頭に dependency_file 機能を追加します（存在しない場合）
• ツールチェーンの先頭に pic 機能を追加します（存在しない場合）
• ツールチェーンの先頭に per_object_debug_info 機能を追加します（存在しない場合）
• ツールチェーンの先頭に preprocessor_defines 機能を追加します（存在しない場合）
• ツールチェーンの先頭に includes 機能を追加します（存在しない場合）
• ツールチェーンの先頭に include_paths 機能を追加します（存在しない場合）
• ツールチェーンの先頭に fdo_instrument 機能を追加します（存在しない場合）
• ツールチェーンの先頭に fdo_optimize 機能を追加します（存在しない場合）
• ツールチェーンの先頭に cs_fdo_instrument 機能を追加します（存在しない場合）
• ツールチェーンの先頭に cs_fdo_optimize 機能を追加します（存在しない場合）
• ツールチェーンの先頭に fdo_prefetch_hints 機能を追加します（存在しない場合）
• ツールチェーンの先頭に autofdo 機能を追加します（存在しない場合）
• ツールチェーンの先頭に build_interface_libraries 機能を追加します（存在しない場合）
• ツールチェーンの先頭に dynamic_library_linker_tool 機能を追加します（存在しない場合）
• ツールチェーンの先頭に shared_flag 機能を追加します（存在しない場合）
• ツールチェーンの先頭に linkstamps 機能を追加します（存在しない場合）
• ツールチェーンの先頭に output_execpath_flags 機能を追加します（存在しない場合）
• ツールチェーンの先頭に runtime_library_search_directories 機能を追加します（存在しない場合）
• ツールチェーンの先頭に library_search_directories 機能を追加します（存在しない場合）
• ツールチェーンの先頭に archiver_flags 機能を追加します（存在しない場合）
• ツールチェーンの先頭に libraries_to_link 機能を追加します（存在しない場合）
• ツールチェーンの先頭に force_pic_flags 機能を追加します（存在しない場合）
• ツールチェーンの先頭に user_link_flags 機能を追加します（存在しない場合）
• ツールチェーンの先頭に legacy_link_flags 機能を追加します（存在しない場合）
• ツールチェーンの先頭に static_libgcc 機能を追加します（存在しない場合）
• ツールチェーンの先頭に fission_support 機能を追加します（存在しない場合）
• ツールチェーンの先頭に strip_debug_symbols 機能を追加します（存在しない場合）
• ツールチェーンの先頭に coverage 機能を追加します（存在しない場合）
• ツールチェーンの先頭に llvm_coverage_map_format 機能を追加します（存在しない場合）
• ツールチェーンの先頭に gcc_coverage_map_format 機能を追加します（存在しない場合）
• ツールチェーンの一番下に 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 を追加してツールチェーンをさらにスタンドアロンにすることを検討してください。