平台

回報問題 查看來源

Bazel 可以使用許多不同版本的建構工具 (例如連結器和編譯器),在各種硬體、作業系統和系統設定中建構及測試程式碼。為協助管理這種複雜性,Bazel 有「限制」和「平台」的概念。限制是指建構或實際工作環境可能的維度,例如 CPU 架構、是否存在 GPU,或系統安裝的編譯器版本。平台是這些限制的一組已命名選項,代表可在某些環境中提供的特定資源。

將環境建立為平台模型可協助 Bazel 自動為建構動作選取適當的工具鍊。平台也可以與 config_setting 規則搭配使用,以寫入可設定屬性

Bazel 可辨識平台可能提供的三個角色:

  • Host:Bazel 本身的執行平台。
  • Execution:在這個平台,建構工具會執行建構動作,產生中繼和最終輸出內容。
  • 「Target」:儲存並執行最終輸出內容的平台。

Bazel 支援下列與平台相關的建構情境:

  • 單一平台建構 (預設):主機、執行和目標平台相同。例如,在 Intel x64 CPU 上執行的 Ubuntu 建構 Linux 執行檔。

  • 跨編譯版本:主機和執行平台相同,但目標平台不同。例如在 MacBook Pro 上執行的 macOS 上建構 iOS 應用程式。

  • 多平台版本:主機、執行和目標平台皆為不同。

定義限制和平台

BUILD 檔案中,使用 constraint_settingconstraint_value 規則來定義平台可能選擇的空間。constraint_setting 會建立新維度,constraint_value 則會建立指定維度的新值;這些維度一起有效定義列舉和可能的值。例如,下列 BUILD 檔案程式碼片段導入了系統 glibc 版本的限制,其中包含兩個可能的值。

constraint_setting(name = "glibc_version")

constraint_value(
    name = "glibc_2_25",
    constraint_setting = ":glibc_version",
)

constraint_value(
    name = "glibc_2_26",
    constraint_setting = ":glibc_version",
)

您可在工作區中為不同的套件定義限制及其值。這些物件會由標籤參照,並受一般的瀏覽權限控制項影響。如果瀏覽權限允許,您就可以自行定義現有限制的值,以擴展現有的限制設定。

platform 規則會導入新的平台,該平台設有特定限制值。以下程式碼會建立名為 linux_x86 的平台,表示該平台描述在 x86_64 架構 (採用 2.25 版 glibc 版本) 上執行 Linux 作業系統的任何環境。(如要進一步瞭解 Bazel 的內建限制,請參閱下文)。

platform(
    name = "linux_x86",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
        ":glibc_2_25",
    ],
)

大致上實用的限制和平台

為了維持生態系統的一致性,Bazel 團隊會維護一個存放區,其中針對最常見的 CPU 架構和作業系統設有限制定義。這些範例均位於 https://github.com/bazelbuild/platforms

Bazel 隨附下列特殊平台定義:@local_config_platform//:host。這是自動偵測的主機平台值,代表系統在執行 Bazel 時,自動偵測的主機平台值。

指定建構作業的平台

您可以使用下列指令列標記,為建構作業指定主機和目標平台:

  • --host_platform - 預設為 @bazel_tools//platforms:host_platform
  • --platforms - 預設為 @bazel_tools//platforms:target_platform

略過不相容的目標

針對特定目標平台進行建構時,建議略過無法在該平台上有效的目標。舉例來說,在含有 //... 的 Linux 機器中建構時,Windows 裝置驅動程式可能會產生大量編譯器錯誤。使用 target_compatible_with 屬性告知 Bazel 哪個目標平台限制了程式碼。

這項屬性的最簡單用途,會將目標限制在單一平台。系統不會針對不符合所有限制的平台建構目標。以下範例將 win_driver_lib.cc 限制為 64 位元 Windows。

cc_library(
    name = "win_driver_lib",
    srcs = ["win_driver_lib.cc"],
    target_compatible_with = [
        "@platforms//cpu:x86_64",
        "@platforms//os:windows",
    ],
)

:win_driver_lib 與使用 64 位元 Windows 建構,且與所有其他項目不相容。不相容性等同於遞移性。任何間接依賴不相容目標的目標都會視為不相容。

在什麼情況下會略過目標?

如果目標被視為不相容且包含在建構中做為目標模式擴展的一部分,就會略過目標。舉例來說,以下兩個叫用會略過在目標模式擴充中發現的任何不相容目標。

$ bazel build --platforms=//:myplatform //...
$ bazel build --platforms=//:myplatform //:all

如果使用 --expand_test_suites 的指令列指定 test_suite,系統會略過 test_suite 中不相容的測試。也就是說,指令列上的 test_suite 目標的運作方式與 :all... 類似。使用 --noexpand_test_suites 會禁止展開作業,導致含有不相容測試的 test_suite 目標也不相容。

在指令列中明確指定不相容的目標會產生錯誤訊息和失敗的建構。

$ bazel build --platforms=//:myplatform //:target_incompatible_with_myplatform
...
ERROR: Target //:target_incompatible_with_myplatform is incompatible and cannot be built, but was explicitly requested.
...
FAILED: Build did NOT complete successfully

較能表達的限制

如要在表示限制方面享有更多彈性,請使用沒有任何平台符合的 @platforms//:incompatible constraint_value

select()@platforms//:incompatible 搭配使用,即可表達更複雜的限制。例如,可用來實作基本 OR 邏輯。以下內容標示了與 macOS 和 Linux 相容,但沒有其他平台的程式庫。

cc_library(
    name = "unixish_lib",
    srcs = ["unixish_lib.cc"],
    target_compatible_with = select({
        "@platforms//os:osx": [],
        "@platforms//os:linux": [],
        "//conditions:default": ["@platforms//:incompatible"],
    }),
)

上述可以解釋如下:

  1. 指定 macOS 時,目標沒有任何限制。
  2. 指定 Linux 時,目標沒有任何限制。
  3. 否則,目標會包含 @platforms//:incompatible 限制。由於 @platforms//:incompatible 不屬於任何平台,因此目標被認定為不相容。

如要讓限制更清楚易讀,請使用 skylibselects.with_or()

您可以透過類似方式表達不相容性,以下範例說明與 ARM「以外」所有項目相容的程式庫。

cc_library(
    name = "non_arm_lib",
    srcs = ["non_arm_lib.cc"],
    target_compatible_with = select({
        "@platforms//cpu:arm": ["@platforms//:incompatible"],
        "//conditions:default": [],
    ],
)

使用 bazel cquery 偵測不相容的目標

您可以使用 bazel cquery Starlark 輸出格式中的 IncompatiblePlatformProvider,區分不相容的目標與相容目標。

可用來篩除不相容的指定目標。以下範例只會列印相容目標的標籤。系統不會列印不相容的目標。

$ cat example.cquery

def format(target):
  if "IncompatiblePlatformProvider" not in providers(target):
    return target.label
  return ""


$ bazel cquery //... --output=starlark --starlark:file=example.cquery

已知問題

不相容的目標會忽略瀏覽權限限制