C++ 工具鍊設定

總覽

Bazel 為了使用正確的選項叫用編譯器，您必須對 例如包含目錄和重要標記 換句話說，Bazel 需要簡化過的編譯器模型，才能瞭解 正常運作。

Bazel 必須知道下列資訊：

• 編譯器是否支援 thinLTO、模組、動態連結或 PIC (放置獨立程式碼)。
• 必要工具的路徑，例如 gcc、ld、ar、objcopy 等。
• 內建系統包含目錄。Bazel 需要這些資訊才能驗證 來源檔案中包含的所有標頭都已正確宣告 BUILD 檔案。
• 預設的 sysroot。
• 用於編譯、連結和封存的旗標。
• 支援編譯模式 (opt、dbg、Fastbuild) 使用的標記。
• 建立編譯器特別需要的變數。

如果編譯器支援多種架構，Bazel 必須設定 所以需要分開管理

CcToolchainConfigInfo 是提供特定等級的 設定 Bazel 的 C++ 規則行為的精細程度。根據預設 Bazel 會自動為您的建構作業設定 CcToolchainConfigInfo，不過您 可讓管理員手動設定這時你需要設定星星規則 可提供 CcToolchainConfigInfo，而您需要 cc_toolchain 的 toolchain_config 屬性套用至您的規則。 您可以呼叫CcToolchainConfigInfo cc_common.create_cc_toolchain_config_info()。 您可以在 @rules_cc//cc:cc_toolchain_config_lib.bzl。

當 C++ 目標進入分析階段時，Bazel 會選擇適當的 根據 BUILD 檔案設定 cc_toolchain 目標，然後取得 「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 目標 使用 Terraform 將 Bazel 傳送至目標 --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」規則中的物件可用來管理建構作業的設定 (也就是說 項目)。這些訊息可讓您 在 Bazel 導入完整的 C++ 功能，不必修改 Bazel 二進位檔。C++ 規則支援多種專屬動作，詳細介紹如下 在 Bazel 原始碼中。

功能

功能是一種需要指令列標記、動作 對執行環境的限製或依附元件變更。功能 可以是簡單的做法，例如讓 BUILD 檔案選取 或是與 C++ 規則及treat_warnings_as_errors 包括新的編譯動作和輸入至編譯內容，例如 header_modules或thin_lto。

在理想情況下，CcToolchainConfigInfo 包含功能清單，且每個 功能是由一或多個標記群組所組成，每個標記群組各定義一份標記清單 適用於特定 Bazel 動作的指令

地圖項目需要依名稱指定，這可讓 Starlark 完全分離 規則設定換句話說，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 執行的一種動作類型，例如 編譯或連結不過 動作和 Bazel 動作類型，其中 Bazel 動作類型指的是 Java 類別 執行動作 (例如 CppCompileAction)。我們要用 「組合器動作」和「編譯器動作」上表 CppCompileAction，但連結動作為 CppLinkAction。

組合動作

編譯器動作

連結動作

AR 動作

AR 動作會透過 ar 將物件檔案組合成封存庫 (.a 檔案) 並將部分語義編碼為名稱

LTO 動作

使用 action_config

action_config 是說明 Bazel 的 Starlark 結構 方法是指定在動作期間要叫用的工具 (二進位) 和 由功能定義這些旗標會將限制套用至動作的

action_config() 建構函式包含下列參數：

action_config 可能要求且隱含其他功能， action_config 由 特徵關係這項行為 與此功能類似

最後兩個屬性與 因為部分 Bazel 動作需要特定標記 環境變數，目標是避免不必要的 action_config+feature 配對。一般來說，在多個 action_config 間共用單一功能的做法通常是

使用同一個 action_name 可定義多個 action_config 在同一工具鍊中調整設定這可避免工具路徑發生模稜兩可的情況 並強制執行 action_config 背後的意圖，也就是動作的屬性 會在工具鍊的單一位置提供清楚的說明。

使用工具建構函式

action_config 可以透過 tools 參數指定一組工具。 tool() 建構函式會採用下列參數：

對於指定的 action_config，系統只會套用一個 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 (
        config_name = ACTION_NAMES.cpp_link_executable,
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                tool_path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            tool (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(
                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_file_path}"],
)

本例中的標記內容會由輸出檔案路徑取代。 該動作的作用

標記群組會按照建構指令的順序展開至建構指令 在清單中，從上到下、由左到右

適用於新增至建構作業時，需要在不同值重複值的旗標 指令，標記群組可以疊代 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 (如果尚未顯示) 功能
• 在工具鍊頂端新增 symbol_counts (如果尚未顯示) 功能
• 在工具鍊頂端新增 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， 工具鍊的特性