C++ 工具鍊設定

總覽

為了以正確的選項叫用編譯器，Bazel 需要一些關於編譯器內部資訊的知識，例如包含目錄和重要標記。換句話說，Bazel 需要簡化的編譯器模型，才能瞭解其運作方式。

Bazel 必須知道下列資訊：

• 是否支援精簡 LTO、模組、動態連結或 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 會使用 --cpu | --compiler 從 cc_toolchain_suite.toolchains 屬性中選取對應的項目。如果 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 規則屬性啟用 API。

功能可能會有相互依附，具體取決於指令列旗標、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 動作類型是指實作動作的 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"],
   ),
]

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 可讓您將標記綁定為用於特定用途的群組。您可以在旗標值中使用預先定義的變數指定旗標，編譯器會在將旗標新增至建構指令時展開該變數。例如：

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