C++ 工具鍊設定

總覽

如要使用正確的選項叫用編譯器，Bazel 需要瞭解編譯器內部結構，例如 include 目錄和重要標記。換句話說，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。您可以在 @rules_cc//cc:cc_toolchain_config_lib.bzl 中找到程序中所有必要結構體的 Starlark 建構函式。

當 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 會從 cc_toolchain_suite.toolchains 屬性中選取對應的項目 (使用 --cpu | --compiler)。如果 Bazel 找不到對應項目，就會擲回錯誤。

   • 如果未指定 --compiler 選項，Bazel 會從具有 --cpu 的 cc_toolchain_suite.toolchains 屬性中選取對應項目。

   • 如未指定任何標記，Bazel 會檢查主機系統，並根據檢查結果選取 --cpu 值。請參閱檢查機制程式碼。

選取工具鍊後，Starlark 規則中的對應 feature 和 action_config 物件會控管建構的設定 (即稍後說明的項目)。這些訊息可在 Bazel 中導入完整的 C++ 功能，而不必修改 Bazel 二進位檔。C++ 規則支援多個獨特動作，詳情請參閱 Bazel 原始碼。

功能

功能是指需要指令列標記、動作、執行環境限制或依附元件變更的實體。功能可以很簡單，例如允許 BUILD 檔案選取旗標的設定 (例如 treat_warnings_as_errors)，或與 C++ 規則互動，並在編譯中加入新的編譯動作和輸入內容 (例如 header_modules 或 thin_lto)。

理想情況下，CcToolchainConfigInfo 應包含功能清單，每個功能都包含一或多個旗標群組，每個群組定義適用於特定 Bazel 動作的旗標清單。

功能會依名稱指定，因此 Starlark 規則設定可完全與 Bazel 版本脫鉤。換句話說，只要 CcToolchainConfigInfo 設定不需要使用新功能，Bazel 版本就不會影響這些設定的行為。

啟用功能的方式如下：

• 這項功能的 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 是 Starlark 結構體，可指定要在動作期間叫用的工具 (二進位檔) 和功能定義的旗標集，藉此描述 Bazel 動作。這些標記會對動作的執行作業套用限制。

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 封存檔，接著解壓縮該封存檔，產生應用程式套件和 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) 都會以單元形式展開。例如：

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，讓工具鍊更獨立。