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 属性をルールに指定する必要があります。cc_common.create_cc_toolchain_config_info() を呼び出して CcToolchainConfigInfo を作成できます。プロセスで必要なすべての構造体の 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 アクション タイプは、アクション（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 ペアを回避することが目的であるため、これらの属性が含まれています。通常は、複数の action_config で 1 つの特徴を共有することをおすすめします。

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

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

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

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

使用例

機能とアクションを組み合わせて使用すると、さまざまなクロス プラットフォーム セマンティクスで 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 を追加してツールチェーンをよりスタンドアロンにすることを検討してください。