BazelCon 2024 註冊現已開放！

本頁面由 Cloud Translation API 翻譯而成。

使用平台進行建構

Bazel 精密支援建立平台與「工具鍊」。如要將這項功能與實際專案整合程式碼擁有者、規則維護人員和核心 Bazel 開發人員之間進行協調。

本頁將概述平台的用途，並說明如何利用平台進行建構。

tl;dr：支援 Bazel 的平台和工具鍊 API，但這些 API 無法運作直到所有語言規則、select() 和其他舊版參考資料為止已更新。這項工作仍在持續進行中。最終，所有版本都是以平台為基礎。請參閱下方說明，瞭解建構作業的適用範圍。

如需更正式的說明文件，請參閱：

背景

我們推出平台和工具鍊，將軟體方式經過標準化 專案會指定不同機器為目標，並使用合適的語言工具建構應用程式。

Bazel 的原因是。是激發靈感觀察語言維護者已經在廣告中執行過這項動作後發現以隨機方式或不相容的方式運作舉例來說，C++ 規則會使用 --cpu 和 --crosstool_top 設定建構作業的目標 CPU 和 C++ 工具鍊。在這兩種正確的模型中一個「平台」。歷史上嘗試這樣做會使得建構不準確，甚至造成模型出錯。這些旗標也無法控制 Java 編譯，因為後者會自行演變獨立介面與 --java_toolchain。

Bazel 適用於大型的多語言多平台專案。這個需要針對這些概念提供更多原則支援，包括清楚明確的 API 鼓勵語言和專案的互通性這些全新 API 就是。

遷移

平台和工具鍊 API 只有在專案實際使用時才會運作。這個專案的規則邏輯、工具鍊、依附元件 select()都必須提供支援。這項遷移作業須循序漸進確保所有專案及其依附元件都能正常運作。

舉例來說，Bazel 的 C++ 規則支援平台。但 Apple 規則則不會。您的 C++ 專案可能不在乎 Apple。但有些人有可能。以下內容對全球所有 C++ 版本啟用平台可能還不安全。

本頁其餘部分會說明遷移順序，以及遷移方式和時間找出專案所需的資源

目標

當所有專案使用以下格式建構時，Bazel 的平台遷移作業即告完成：

bazel build //:myproject --platforms=//:myplatform

這表示：

專案使用的規則可以從下列來源推斷出正確的工具鍊 //:myplatform。
專案依附元件使用的規則可以推論正確的工具鍊 //:myplatform起。
必須是專案支援//:myplatform或專案支援舊版 API (例如 --crosstool_top)。
//:myplatform 個參考資料 [常見宣告][通用平台宣告]{: .external} CPU、OS 和其他支援自動跨專案的一般概念相容性。
所有相關專案」 select() 秒瞭解 //:myplatform 隱含的機器屬性。
//:myplatform 是在專案的明確位置定義，而且可重複使用存放區。如果是專案專屬平台，則可將存放區放在所有專案找出可能使用這個平台的工具

達成這個目標後，舊的 API 將立即移除。接著，是專案選擇平台和工具鍊的標準方式

我該使用平台嗎？

如果只是要建構或交叉編譯專案，請遵循請參閱專案正式說明文件

如果您是專案、語言或工具鍊的維護人員，您最終會希望支援新的 API您是否等待全球遷移作業完成或者根據您的特定價值 / 費用需求，提早選擇加入計畫：

值

你可以select()，或選擇特定屬性的工具鍊而不是 --cpu 等硬式編碼旗標例如多個 CPU 可支援相同的指令集。
較正確的版本。如果您在上述範例中使用 --cpu 執行 select()，則新增支援相同指令集的新 CPU，select() 但系統卻無法辨識新的 CPU不過平台上的 select() 仍然正確。
更簡便的使用者體驗。所有專案都瞭解： --platforms=//:myplatform。不需要設定多個特定語言旗標
語言設計更簡潔。所有語言都會共用同一個定義 API 工具鍊、使用工具鍊，以及為平台選擇適當的工具鍊。
目標可略過建構和測試階段。

費用

未支援平台的相依專案可能無法自動運作與您的資訊互動
這些項目可能需要額外的暫時性維護。
如要同時使用新版和舊版 API，需要更謹慎的使用者指引，避免混淆
常見屬性的標準定義，例如 OS 和 CPU 仍在更新中，可能需要額外的初始貢獻。
語言特定工具鍊的標準定義仍在不斷演變，因此可能需要額外的初始貢獻

API 審查

platform 是一組 constraint_value 個目標：

platform(
    name = "myplatform",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

constraint_value 是指機器資源。具有相同「種類」的值會歸入同一個 constraint_setting：

constraint_setting(name = "os")
constraint_value(
    name = "linux",
    constraint_setting = ":os",
)
constraint_value(
    name = "mac",
    constraint_setting = ":os",
)

toolchain 是星形規則。結果屬性宣告語言的工具 (例如 compiler = "//mytoolchain:custom_gcc")。其供應商會需要使用這些工具建立規則

工具鍊會宣告可供他們使用的 constraint_value 機器目標 (target_compatible_with = ["@platforms//os:linux"]) 和他們的工具可以執行時間： (exec_compatible_with = ["@platforms//os:mac"]).

建構 $ bazel build //:myproject --platforms=//:myplatform 時，Bazel 會自動選擇可在建構機器上執行的工具鍊建構 //:myplatform 的二進位檔。這就是「工具鍊解決方案」。

可用的工具鍊組合可在 WORKSPACE 中註冊，包括： register_toolchains或新增 --extra_toolchains 的指令列。

詳情請參閱這裡。

狀態

目前的平台支援因語言而異。Bazel 的所有主要規則平台不過這項程序需要一些時間才能完成。這有三個主要原因：

您必須更新規則邏輯，才能從新的工具鍊取得工具資訊 API (ctx.toolchains)，並停止讀取舊版設定，例如 --cpu和--crosstool_top。這個過程相對簡單。
工具鍊維護工具必須定義工具鍊，並使其可存取使用者 (位於 GitHub 存放區和 WORKSPACE 項目中)。從技術上來說，這項作業就這麼簡單，但必須聰明地幫助使用者輕鬆上手

您也必須提供平台定義 (除非您針對同一部機器建構應用程式) Bazel 會在這些情況下執行。一般來說，專案應定義自己的平台。
請務必遷移現有專案。select() 和轉換也需要已遷移。這是最大的挑戰。對模型訓練作業來說多語言專案 (如果「所有」語言無法讀取，可能會失敗) --platforms)。

如要設計新的規則組合，您必須支援來自自訂機器學習模型但不想花時間從頭調整機器學習參數這會自動使規則與其他項目相容並隨著平台 API 逐步提高價值也越來越普及

常見的平台屬性

各專案通用的平台屬性 (例如 OS 和 CPU) 應該是在標準的集中位置宣告這有助於推動跨專案以及跨語言相容性

舉例來說，如果 MyApp 在 constraint_value 上有 select() @myapp//cpus:arm和 SomeCommonLib 的 select() 開啟 @commonlib//constraints:arm，會觸發他們的「實驗組」不相容的模式標準。

全域通用屬性是在 @platforms 存放區 (因此，上述範例的標準標籤為 @platforms//cpu:arm)。請在相應語言的存放區中宣告常見的語言語言。

預設平台

一般來說，專案擁有者應平台，描述選擇要建構的機器類型然後再透過 --platforms。

如未設定 --platforms，Bazel 會預設使用代表 platform 本機建構機器這是在 @local_config_platform//:host 自動產生因此不需要明確定義這會對應至本機電腦的OS 和 CPU，其中宣告了 constraint_value @platforms。

C++

如果在設定程式碼之後，Bazel 的 C++ 規則會使用平台來選取工具鍊 --incompatible_enable_cc_toolchain_resolution (#7260)。

這表示您可以使用下列指令設定 C++ 專案：

bazel build //:my_cpp_project --platforms=//:myplatform

而不是舊版：

bazel build //:my_cpp_project` --cpu=... --crosstool_top=...  --compiler=...

如果您的專案是純 C++，而不依賴非 C++ 專案，您可以使用安全管理平台、select 和轉場效果相容。詳情請見 #7260 和如需更多指引，請參閱「設定 C++ 工具鍊」。

這個模式預設為停用。這是因為 Apple 專案仍使用 --cpu 和 --crosstool_top 設定 C++ 依附元件 (範例)。因此這取決於遷移至平台的 Apple 規則。

Java

Bazel 的 Java 規則會使用平台。

這會取代舊版旗標 --java_toolchain、--host_java_toolchain --javabase和--host_javabase。

如要瞭解如何使用設定標記，請參閱 Bazel 和 Java 手冊。詳情請參閱設計文件。

如果您仍在使用舊版標記，請按照問題 #7849 中的遷移程序操作。

Android

設定程式碼時，Bazel 的 Android 規則會利用平台來選取工具鍊 --incompatible_enable_android_toolchain_resolution。

這項功能預設為停用。但遷移作業已順利進行。

Apple

Bazel 的 Apple 規則尚未支援特定平台可選取 Apple 工具鍊。

也不支援平台支援的 C++ 依附元件，因為這類元件會使用舊版 --crosstool_top，用於設定 C++ 工具鍊。在此之前可將 Apple 專案與支援插電的 C++ 與平台對應 (範例)。

其他語言

Bazel 的 Rust 規則完整支援平台。
Bazel 的 Go 規則完整支援平台 (瞭解詳情)。

如要為新語言設計規則，請使用平台選擇您語言的工具鍊。詳情請參閱工具鍊說明文件，取得完整的逐步操作說明。

`select()`

專案可select() constraint_value 個目標，但尚未完成平台。這是刻意設計，讓 select() 盡可能支援各種變數盡可能部署機器包含 ARM 專用來源的程式庫應支援「所有」ARM 機器，除非有更具體的理由。

如要選取一或多個 constraint_value，請使用：

config_setting(
    name = "is_arm",
    constraint_values = [
        "@platforms//cpu:arm",
    ],
)

這相當於在 --cpu 上選擇的傳統方式：

config_setting(
    name = "is_arm",
    values = {
        "cpu": "arm",
    },
)

詳情請參閱這篇文章。

--cpu、--crosstool_top 等的 select 無法辨識--platforms。時間將專案遷移至平台，您必須將專案轉換為 constraint_values：或使用平台對應來支援調整過兩種樣式

轉場

星形轉場效果變更標記建構圖表的各個部分如果專案採用設定 --cpu、--crossstool_top 或其他舊版旗標， --platforms不會看到這些變更。

將專案遷移至平台時，您必須轉換各項變更，例如 return { "//command_line_option:cpu": "arm" }對return { "//command_line_option:platforms": "//:my_arm_platform" }或使用平台對應，以在遷移期間支援兩種樣式。視窗。

目前的平台使用方式

如果只是要建構或交叉編譯專案，請遵循參閱完整說明文件而是取決於語言和專案維護人員確定整合平台的方式和時機，以及可帶來的價值。

如果您是專案、語言或工具鍊維護人員，但您的建構作業沒有但除了支援全球遷移作業)：

翻轉「使用平台」為專案語言加上旗標 (1)) 做任何需要的測試，看看您關注的專案是否值得一試工作。
如果您重視的專案仍依附於舊版旗標，例如 --cpu 和 --crosstool_top，將其與 --platforms 搭配使用：
```
bazel build //:my_mixed_project --platforms==//:myplatform --cpu=... --crosstool_top=...
```
這會有一些維護成本 (您必須手動確認設定比對)。但在沒有消音的情況下轉場效果。
撰寫平台對應來支援兩種樣式，方法是：將 --cpu 樣式設定對應至相應的平台，反之亦然。

平台對應

平台對應是暫時性的 API，可用來建立平台導向的舊版邏輯會同時存在於同一個版本中視窗。

平台對應是將 platform() 對應至分別是對應一組舊版旗標或是反向標記例如：

platforms:
  # Maps "--platforms=//platforms:ios" to "--cpu=ios_x86_64 --apple_platform_type=ios".
  //platforms:ios
    --cpu=ios_x86_64
    --apple_platform_type=ios

flags:
  # Maps "--cpu=ios_x86_64 --apple_platform_type=ios" to "--platforms=//platforms:ios".
  --cpu=ios_x86_64
  --apple_platform_type=ios
    //platforms:ios

  # Maps "--cpu=darwin --apple_platform_type=macos" to "//platform:macos".
  --cpu=darwin
  --apple_platform_type=macos
    //platforms:macos

Bazel 會使用這個憑證來保證所有設定 (包括平台與在整個建構過程中都會套用舊版 UI 轉場效果。

根據預設，Bazel 會讀取叢集內 platform_mappings 檔案的對應關係。您也可以設定 --platform_mappings=//:my_custom_mapping。

詳情請見這裡，瞭解完整的詳細資料。

問題

如需一般支援，或對遷移時程有任何疑問，請洽詢 bazel-discuss@googlegroups.com 或相關規則的擁有者

至於平台/工具鍊 API 的設計和發展討論，聯絡資訊 bazel-dev@googlegroups.com。