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 アクション タイプは、アクションを実装する 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 で共有することをおすすめします。

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

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

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

特定の action_config に対して、単一の 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 を追加することを検討してください。