C++ ツールチェーンの構成

概要

適切なオプションでコンパイラを呼び出すには、Bazel で次の知識が必要です。 インクルード ディレクトリや重要なフラグなど、コンパイラの内部機構。 言い換えれば、Bazel では、コンパイラの簡素化されたモデルを使用して 行います。

Bazel は以下を認識する必要があります。

• コンパイラが thinLTO、モジュール、ダイナミック リンク、PIC をサポートするかどうか （位置独立コード）を使用します。
• gcc、ld、ar、objcopy などの必要なツールのパス。
• 組み込みシステムにはディレクトリが含まれています。Bazel はこれらを検証するために、 ソースファイルに含まれているすべてのヘッダーが、 BUILD ファイル。
• デフォルトの sysroot。
• コンパイル、リンク、アーカイブに使用するフラグ。
• サポートされているコンパイル モード（opt、dbg、fastbuild）に使用するフラグ。
• コンパイラが特に必要とする変数を設定します。

コンパイラが複数のアーキテクチャをサポートしている場合、Bazel で構成する必要があります。 個別に選択できます。

CcToolchainConfigInfo は、必要なレベルのリソースを提供するプロバイダです。 Bazel の C++ ルールの動作を構成する際の粒度です。デフォルトでは Bazel はビルドの CcToolchainConfigInfo を自動的に構成しますが、 手動で構成することもできます。そのためには、Starlark ルールが必要です。 CcToolchainConfigInfo を指定するもので、 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 オプション。

2. cc_toolchain_suite ターゲットが複数のツールチェーンを参照しています。「 --cpu フラグと --compiler フラグの値によって、 --cpu フラグの値のみに基づいてツールチェーンが選択されている。または、 複合の --cpu | --compiler 値に基づきます。選定プロセスは以下のとおりです。 次のようになります。

   • --compiler オプションを指定すると、Bazel は cc_toolchain_suite.toolchains からの対応するエントリ 属性を --cpu | --compiler に置き換えます。Bazel で エラーがスローされます。

   • --compiler オプションが指定されていない場合、Bazel は cc_toolchain_suite.toolchains からの対応するエントリ 属性を --cpu だけとする必要があります。

   • フラグが指定されていない場合、Bazel はホストシステムを検査し、 --cpu 値。詳しくは、 検査メカニズム コード。

ツールチェーンが選択されると、対応する feature と action_config Starlark ルール内のオブジェクトがビルドの構成（つまり、 （後述します）。これらのメッセージにより 本格的な C++ 機能を Bazel に組み込み、 Bazel バイナリ。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 つの属性は、Terraform の対応する属性と 一部の Bazel アクションで特定のフラグや機能を必要とするため、これらの機能が組み込まれています。 環境変数を使用し、不要な action_config+feature を避けることが目的 あります。通常、1 つの特徴を複数の action_config で共有することは、 推奨されます。

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

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

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

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

使用例

機能とアクションを併用して 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"],
   ),
]

これと同じ機能を、Linux ではまったく異なる方法で実装できます。 fission。または Windows の場合は、.pdb ファイルを生成します。たとえば、 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（存在しない場合）機能をツールチェーンの先頭に追加
• 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 のクロスツール: できます。関心のある方は、 CppActionConfigs, 本番環境のツールチェーンでは、no_legacy_features を追加して よりスタンドアロンになります