C++ 工具鍊設定

回報問題 查看原始碼 夜間 7.2 7.1 7.0 6.5 6.4

總覽

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

Bazel 必須知道下列資訊:

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

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

CcToolchainConfigInfo 是提供特定等級的 設定 Bazel 的 C++ 規則行為的精細程度。根據預設 Bazel 會自動為您的建構作業設定 CcToolchainConfigInfo,不過您 可讓管理員手動設定這時你需要設定星星規則 可提供 CcToolchainConfigInfo,而您需要 cc_toolchaintoolchain_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_binarycc_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 值。詳情請參閱 檢查機製程式碼

選取工具鍊後,對應的 featureaction_config 「Starlark」規則中的物件可用來管理建構作業的設定 (也就是說 項目)。這些訊息可讓您 在 Bazel 導入完整的 C++ 功能,不必修改 Bazel 二進位檔。C++ 規則支援多種專屬動作,詳細介紹如下 在 Bazel 原始碼中

功能

功能是一種需要指令列標記、動作 對執行環境的限製或依附元件變更。功能 可以是簡單的做法,例如讓 BUILD 檔案選取 或是與 C++ 規則及treat_warnings_as_errors 包括新的編譯動作和輸入至編譯內容,例如 header_modulesthin_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'
   ]),
]
特徵層級:只有在指定的必要情況下,系統才會支援這項功能 功能已啟用舉例來說,僅適用於 特定建構模式 (optdbgfastbuild)。如果 `requires` 包含多個 `feature_set` 如果滿足任何「feature_set」值,表示支援這項功能 (啟用所有指定的功能時)。
implies = ['feature']

特徵層級:這項功能隱含指定的地圖項目。 啟用功能時,也會一併啟用隱含的所有功能。 (也就是以遞迴方式運作)。

這項技巧也能透過因式分解一般功能子集 一組功能,例如消毒液的常見部分。暗示 無法停用功能。

provides = ['feature']

特徵層級:表示這個功能是相互關聯的 獨家替代功能舉例來說,所有消毒人員 請指定 provides = ["sanitizer"]

這有助於在使用者要求時列出替代方案,進而改善錯誤處理機制 啟用兩項以上互斥功能

with_features = [
  with_feature_set(
    features = ['feature-1'],
    not_features = ['feature-2'],
  ),
]
旗標設定層級。功能可以指定多個標記集。 如果指定 with_features,則標記集只會展開 如有至少一個 with_feature_set 指定 features 集合中所有的地圖項目 以及 not_features 中指定的所有功能 已停用。 如果未指定 with_features,則這個標記集將會是 。

動作

操作可讓系統靈活修改 此動作會執行,而不會假設動作是如何執行。一個 action_config 會指定動作叫用的工具二進位檔,而 feature 會指定決定該工具方式的設定 (旗標)。 所發生的行為。

功能參照動作,指出哪些 Bazel 動作 因為動作可以修改 Bazel 動作圖表。 CcToolchainConfigInfo 供應商包含含有旗標和工具的動作 例如 c++-compile系統會針對每個動作指派旗標 將這些內容與地圖項目建立關聯

每個動作名稱都代表 Bazel 執行的一種動作類型,例如 編譯或連結不過 動作和 Bazel 動作類型,其中 Bazel 動作類型指的是 Java 類別 執行動作 (例如 CppCompileAction)。我們要用 「組合器動作」和「編譯器動作」上表 CppCompileAction,但連結動作為 CppLinkAction

組合動作

動作 說明
preprocess-assemble 組合預先處理。通常用於 .S 檔案。
assemble 組合而不預先處理。通常用於 .s 檔案。

編譯器動作

動作 說明
cc-flags-make-variable CC_FLAGS 傳播至 Genrules。
c-compile 編譯為 C。
c++-compile 編譯為 C++。
c++-header-parsing 在標頭檔案上執行編譯器的剖析器,確保標頭為 獨立作業,否則會產生編譯錯誤。適用 僅適用於支援模組的工具鍊
動作 說明
c++-link-dynamic-library 連結共用程式庫,內含所有依附元件。
c++-link-nodeps-dynamic-library 連結只包含 cc_library 個來源的共用資料庫。
c++-link-executable 連結可立即執行的最終程式庫。

AR 動作

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

動作 說明
c++-link-static-library 建立靜態資料庫 (封存)。

LTO 動作

動作 說明
lto-backend ThinLTO 動作會將位元碼編譯為原生物件。
lto-index 產生全域索引的 ThinLTO 動作。

使用 action_config

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

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

屬性 說明
action_name 與這個動作對應的 Bazel 動作。 Bazel 會使用這項屬性來探索個別動作工具和執行作業 Google Cloud 就是最佳選擇
tools 要叫用的執行檔。套用至動作的工具會是 清單中第一項工具以及符合該功能的 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定必須提供預設值。
flag_sets 適用於一組動作的旗標清單。與 而不是每個特徵的分數
env_sets 適用於一組動作的環境限制清單。 與地圖項目相同。

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

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

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

使用工具建構函式

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

欄位 說明
path 相關工具的路徑 (相對於目前位置)。
with_features 列出至少一項特徵集的清單 才能使用這項工具

對於指定的 action_config,系統只會套用一個 tool 套用至 Bazel 動作的工具路徑和執行需求已選取工具 逐一檢查 action_configtools 屬性,直到工具為止 找到符合功能設定的 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 可讓您將標記分成不同群組, 目標。您可以在預先定義的變數中指定標記 ,編譯器會在將標記新增到 建構指令例如:

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_availableexpand_if_not_availableexpand_if_trueexpand_if_falseexpand_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 建構變數的參照。

變數 動作 說明
source_file compile 要編譯的來源檔案。
input_file 長條 要去除的構件。
output_file compile 編譯輸出。
output_assembly_file compile 輸出的組合檔案。僅適用於 compile 動作會發出組合文字,通常在使用 --save_temps 標記。內容與 output_file
output_preprocess_file compile 預先處理的輸出內容。僅適用於編譯 只會預先處理來源檔案的動作,通常是在 --save_temps 標記。內容與 output_file
includes compile 編譯器所需的檔案序列 依據條件納入編譯來源
include_paths compile 編譯器所屬的序列目錄 使用 #include<foo.h> 搜尋包含的標頭 和 #include "foo.h"
quote_include_paths compile -iquote 序列包括: 編譯器在哪些目錄中搜尋包含的標頭 #include "foo.h"
system_include_paths compile -isystem 序列包括: 編譯器在哪些目錄中搜尋包含的標頭 #include <foo.h>
dependency_file compile 編譯器產生的 .d 依附元件檔案。
preprocessor_defines compile defines 的序列,例如 --DDEBUG
pic compile 將輸出內容編譯為無關程式碼。
gcov_gcno_file compile gcov 涵蓋率檔案。
per_object_debug_info_file compile 個別物件的偵錯資訊 (.dwp) 檔案。
stripotps 長條 stripopts 的序列。
legacy_compile_flags compile 舊版標記的順序 CROSSTOOL 欄位,例如 compiler_flag optional_compiler_flagcxx_flagoptional_cxx_flag
user_compile_flags compile copt 規則屬性或 --copt--cxxopt--conlyopt 旗標。
unfiltered_compile_flags compile unfiltered_cxx_flag 舊版 CROSSTOOL 欄位,或 unfiltered_compile_flags功能。這些內容不會套用篩選條件 nocopts 規則屬性。
sysroot sysroot
runtime_library_search_directories 連結 連結器執行階段搜尋路徑中的項目 (通常是 並用 -rpath 旗標設定)。
library_search_directories 連結 連結器搜尋路徑中的項目 (通常使用 -L 旗標)。
libraries_to_link 連結 提供檔案連結做為連結器叫用中輸入內容的旗標。
def_file_path 連結 在具有 MSVC 的 Windows 上使用防禦檔案的位置。
linker_param_file 連結 bazel 建立的連結器參數檔案位置 超過指令列長度限制
output_execpath 連結 連結器輸出內容的執行路徑。
generate_interface_library 連結 "yes""no",取決於介面程式庫是否應 。
interface_library_builder_path 連結 介面程式庫建構工具工具的路徑。
interface_library_input_path 連結 介面程式庫 ifso 建構工具的輸入內容。
interface_library_output_path 連結 使用 ifso 建構工具產生介面程式庫的路徑。
legacy_link_flags 連結 來自舊版 CROSSTOOL 欄位的連結器標記。
user_link_flags 連結 來自 --linkopt 的連結器標記 或 linkopts 屬性。
linkstamp_paths 連結 提供連結 tamp 路徑的建構變數。
force_pic 連結 如出現此變數,表示 PIC/PIE 程式碼應該 (已傳遞 Bazel 選項「--force_pic」)。
strip_debug_symbols 連結 出現這個變數表示 都必須移除符號。
is_cc_test 連結 資訊是否屬實,目前使用的是cc_test 連結動作,否則傳回 false。
is_using_fission compile, link 若有此變數,則表示入侵 (每個物件的偵錯資訊) 就會啟動。偵錯資訊會顯示在 .dwo 檔案中 (共 .o 個檔案),以及編譯器和連結器需要知道這一點。
fdo_instrument_path compile, link 儲存 FDO 檢測設定檔的目錄路徑。
fdo_profile_path compile FDO 設定檔的路徑。
fdo_prefetch_hints_path compile 快取預先擷取設定檔的路徑。
csfdo_instrument_path compile, link 儲存情境機密 FDO 的目錄路徑 檢測設定檔。

知名功能

以下為各項功能及其啟用方式的參考資訊 條件。

功能 說明文件
opt | dbg | fastbuild 預設依據編譯模式啟用。
static_linking_mode | dynamic_linking_mode 預設根據連結模式啟用。
per_object_debug_info 如果指定 supports_fission 功能且已指定 您可以在 --fission 標記。
supports_start_end_lib 如果已啟用 (且已設定 --start_end_lib 選項),則 Bazel 不會連結至靜態資料庫,而是使用 --start-lib/--end-lib 個用來連結物件的連結器選項 這能加快建構速度,因為 Bazel 不需要建構 靜態程式庫
supports_interface_shared_libraries 已啟用 (且--interface_shared_objects選項為 Bazel 就會連結 linkstatic 設為 否 (預設為 cc_test) 相較於介面共用 程式庫進而加快漸進式重新連結的速度。
supports_dynamic_linker 啟用後,C++ 規則會知道工具鍊可以產生共用項目 程式庫
static_link_cpp_runtimes 如果啟用,Bazel 就會在靜態連結中以靜態方式連結 C++ 執行階段 模式和動態連結模式搭配使用文物 cc_toolchain.static_runtime_libcc_toolchain.dynamic_runtime_lib 屬性 (視 連結模式)。
supports_pic 啟用後,工具鍊會知道要將 PIC 物件用於動態程式庫。 需要 PIC 編譯時,都會存在 `pic` 變數。如未啟用 根據預設,並且會傳遞「--force_pic」,則 Bazel 會要求「supports_pic」 確認是否已啟用該功能如果這項功能遺失或無法 `--force_pic` 則無法使用。
static_linking_mode | dynamic_linking_mode 預設根據連結模式啟用。
no_legacy_features 防止 Bazel 將舊版功能新增至 C++ 設定 (如果有的話)如需 功能。

舊版功能修補邏輯

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, 工具鍊的特性