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 は適切なターゲット cc_toolchain ターゲットを BUILD ファイルに基づいて作成し、 指定されたターゲットの CcToolchainConfigInfo プロバイダに cc_toolchain.toolchain_config 属性。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 は cc_toolchain_suite.toolchains からの対応するエントリ 属性を --cpu とだけ置き換えます。

   • フラグが指定されていない場合、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 で直接管理されるため、 機能固有の特性に内在する競合を管理できます。 必要があります。ツールチェーン仕様では、機能のサポートと拡張を管理する 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 つのタイプのアクションを表します。たとえば、 コンパイルやリンクの手間が省けますしかし、多対 1 の関係は アクションと Bazel アクション タイプ（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 で共有することをおすすめします。

同じ 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 アーカイブを作成するためのリンク アクション中の専用ツール そのアーカイブを解凍してアプリケーション バンドルを生成し、.plist Xcode で使用できるファイル。

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 を使用すると、フラグを特定の目的を果たすグループにバンドルできます。事前定義された変数を使用して、 これは、コンパイラがフラグを build コマンドを使用します。例:

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 機能をツールチェーンの先頭に移動します
• default_compile_flags 機能をツールチェーンの先頭に移動します
• dependency_file 機能（存在しない場合は追加）を toolchain の先頭に追加
• pic 機能（存在しない場合は追加）を toolchain の先頭に追加
• per_object_debug_info（存在しない場合）機能をツールチェーンの先頭に追加
• preprocessor_defines 機能（存在しない場合は追加）を toolchain の先頭に追加
• includes（存在しない場合）機能をツールチェーンの先頭に追加
• include_paths 機能（存在しない場合は追加）を toolchain の先頭に追加
• fdo_instrument 機能（存在しない場合は追加）を toolchain の先頭に追加
• fdo_optimize（存在しない場合）機能をツールチェーンの先頭に追加
• cs_fdo_instrument 機能（存在しない場合は追加）を toolchain の先頭に追加
• cs_fdo_optimize（存在しない場合）機能をツールチェーンの先頭に追加
• fdo_prefetch_hints（存在しない場合）機能をツールチェーンの先頭に追加
• autofdo 機能（存在しない場合は追加）を toolchain の先頭に追加
• build_interface_libraries（存在しない場合）機能をツールチェーンの先頭に追加
• dynamic_library_linker_tool（存在しない場合）機能をツールチェーンの先頭に追加
• shared_flag（存在しない場合）機能をツールチェーンの先頭に追加
• linkstamps 機能（存在しない場合は追加）を toolchain の先頭に追加
• output_execpath_flags（存在しない場合）機能をツールチェーンの先頭に追加
• runtime_library_search_directories 機能（存在しない場合は追加）を toolchain の先頭に追加
• library_search_directories（存在しない場合）機能をツールチェーンの先頭に追加
• archiver_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• libraries_to_link 機能（存在しない場合は追加）を toolchain の先頭に追加
• force_pic_flags 機能（存在しない場合は追加）を toolchain の先頭に追加
• user_link_flags（存在しない場合）機能をツールチェーンの先頭に追加
• legacy_link_flags（存在しない場合）機能をツールチェーンの先頭に追加
• static_libgcc（存在しない場合）機能をツールチェーンの先頭に追加
• fission_support（存在しない場合）機能をツールチェーンの先頭に追加
• strip_debug_symbols（存在しない場合）機能をツールチェーンの先頭に追加
• coverage（存在しない場合）機能をツールチェーンの先頭に追加
• llvm_coverage_map_format 機能（存在しない場合は追加）を toolchain の先頭に追加
• gcc_coverage_map_format（存在しない場合）機能をツールチェーンの先頭に追加
• fully_static_link（存在しない場合）機能をツールチェーンの末尾に追加
• user_compile_flags（存在しない場合）機能をツールチェーンの末尾に追加
• sysroot（存在しない場合）機能をツールチェーンの末尾に追加
• unfiltered_compile_flags（存在しない場合）機能をツールチェーンの末尾に追加
• linker_param_file（存在しない場合）機能をツールチェーンの末尾に追加
• compiler_input_flags（存在しない場合）機能をツールチェーンの末尾に追加
• compiler_output_flags 機能をツールチェーンの一番下に追加（存在しない場合）

これは機能の長いリストです。計画的には Starlark のクロスツール: できます。関心のある方は、 CppActionConfigs 本番環境のツールチェーンでは、no_legacy_features を追加して よりスタンドアロンになります