平台和工具鍊規則

回報問題 敬上 查看原始碼 。 。 。 。 。 。 夜間7.37.2 。 。 7.17.06.5

有這套規則 就能用特定硬體平台建立模型 建構並指定可能需要為這些平台編譯程式碼所需的特定工具。 使用者應熟悉這裡說明的概念。

規則

constraint_setting

查看規則來源
constraint_setting(name, default_constraint_value, deprecation, distribs, features, licenses, tags, testonly, visibility)

這項規則是用來導入新的限制類型,這類限制類型可以由平台指定值。 舉例來說,您可以定義名為「glibc_version」的 constraint_setting代表 讓平台安裝不同版本的 glibc 程式庫。 詳情請參閱 平台頁面。

每個 constraint_setting 都有一組可供擴充的 constraint_value 秒。通常在同一個套件中定義,但有時也會 不同的套件會為現有設定引進新的值。舉例來說 設定 @platforms//cpu:cpu 時,您可以使用自訂值加以擴充, 針對模糊的 CPU 架構定義平台。

引數

屬性
name

名稱;必選

此目標的專屬名稱。

default_constraint_value

名稱無法設定;預設為 None

這項設定的預設值;如未指定值,會使用這個標籤。如果這是 屬性時,constraint_value就必須在 與這個 constraint_setting 相同的套件

如果限制設定有預設值,則只要平台不包含 任何限制值,會與平台指定 預設值。否則,如果沒有預設值,會考量該限制設定 沒有指定的版本在這種情況下,平台不會與任何 需要特定值的限制清單 (例如 config_setting) 查看該設定

constraint_value

查看規則來源
constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)
敬上 這項規則會針對特定限制類型採用新的值。 詳情請參閱 平台頁面。

範例

下列指令會為預先定義的 constraint_value 建立新的可能值 CPU 架構

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)
敬上 接著,平台可以宣告採用 mips 架構做為 x86_64arm 等。

引數

屬性
name

名稱;必選

此目標的專屬名稱。

constraint_setting

標籤無法設定;必選

constraint_valueconstraint_setting

平台

查看規則來源
platform(name, constraint_values, deprecation, distribs, exec_properties, features, flags, licenses, parents, remote_execution_properties, required_settings, tags, testonly, visibility)

這項規則會定義新的平台,也就是一組已命名的限制選項 (例如 CPU 架構或編譯器版本) 介紹 哪些部分可以執行 詳情請參閱「平台」頁面。

範例

這定義了一個平台,用來說明在 ARM 中執行 Linux 的任何環境。

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

平台旗標

平台可以使用 flags 屬性指定要新增的標記清單 那麼只要該平台做為目標平台 (也就是 --platforms 旗標)。

從平台設定的旗標優先順序最高,並覆寫任何先前設定的旗標 值,然後透過指令列、rc 檔案或轉換指令進行轉換。

範例

platform(
    name = "foo",
    flags = [
        "--dynamic_mode=fully",
        "--//bool_flag",
        "--no//package:other_bool_flag",
    ],
)

這會定義名為 foo 的平台,當這是目標平台時 (因為 使用者指定 --platforms//:foo,因為轉場效果 //command_line_option:platforms 標記給 ["//:foo"],或 //:foo 是用於執行平台),則系統會在 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定

平台和可重複的標記

某些標記會在重複時累積值,例如 --features--copt,任何以 config.string(repeatable = True) 建立的 Starlark 旗標。 這些標記與設定平台的標記不相容,也就是說,所有先前標記 的值會遭到移除,並以平台的值覆寫。

例如,在下列平台下,叫用 build --platforms=//:repeat_demo --features feature_a --features feature_b 的最終結果會是 --feature 標記為 ["feature_c", "feature_d"],移除功能 設定憑證

platform(
    name = "repeat_demo",
    flags = [
        "--features=feature_c",
        "--features=feature_d",
    ],
)

因此,我們不建議在 flags 屬性中使用可重複的標記。

平台繼承

平台可以使用 parents 屬性指定要使用的其他平台 限制值的來源雖然 parents 屬性採用清單,但不包含 目前支援多個值,指定多個父項會是錯誤。

在平台中檢查限制設定的值時,請先直接設定這些值 系統會檢查 (透過 constraint_values 屬性),然後檢查限制值 父系物件父項平台鏈會以遞迴方式不斷向上擴充。如此一來 直接在平台上設定的值會覆寫父項上設定的值。

平台會繼承父項平台的 exec_properties 屬性。 父項和子平台 exec_properties 中的字典項目 合併計算 如果相同的鍵同時出現在父項和子項的 exec_properties 中, 系統會使用子項的值如果子平台將空字串指定為值, 就會取消設定

平台也可沿用 (已淘汰) 的 remote_execution_properties 屬性 來自上層平台注意:新程式碼應改用 exec_properties。 下方所述的邏輯是為了與舊版行為相容,但將會移除 設定 remote_execution_platform 的邏輯如下: 就是上層平台:

  1. 如未在子平台上設定 remote_execution_property,父項的 系統將使用 remote_execution_properties
  2. 如果子平台已設定 remote_execution_property,且含有 常值字串 {PARENT_REMOTE_EXECUTION_PROPERTIES},該巨集將 替換成父項 remote_execution_property 屬性的內容。
  3. 如果 remote_execution_property 已在子平台上設定,且不包含 巨集,子項的 remote_execution_property 將會保持不變。

由於 remote_execution_properties 已淘汰且將逐步停用, remote_execution_propertiesexec_properties位於相同的地點 不得使用繼承鏈結。 偏好使用 exec_properties 取代已淘汰 remote_execution_properties

範例:限制值

platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)

在這個範例中,子平台具備下列屬性:

  • child_a 限制值 @platforms//os:linux (沿用) 以及 @platforms//cpu:x86_64 (直接在平台設定)。
  • child_b 從父項繼承所有限制值,且未設定任何 基礎架構

範例:執行屬性

platform(
    name = "parent",
    exec_properties = {
      "k1": "v1",
      "k2": "v2",
    },
)
platform(
    name = "child_a",
    parents = [":parent"],
)
platform(
    name = "child_b",
    parents = [":parent"],
    exec_properties = {
      "k1": "child"
    }
)
platform(
    name = "child_c",
    parents = [":parent"],
    exec_properties = {
      "k1": ""
    }
)
platform(
    name = "child_d",
    parents = [":parent"],
    exec_properties = {
      "k3": "v3"
    }
)

在這個範例中,子平台具備下列屬性:

  • child_a 繼承了「exec_properties」且不會設定自己的物件。
  • child_b 繼承父項的 exec_properties 並覆寫父項的 k1 的值。其 exec_properties 會是: { "k1": "child", "k2": "v2" }
  • child_c 繼承父項的 exec_properties 且未設定 k1。其 exec_properties 會是: { "k2": "v2" }
  • child_d 會繼承父項的 exec_properties,並新增 資源。其 exec_properties 會是: { "k1": "v1", "k2": "v2", "k3": "v3" }

引數

屬性
name

名稱;必選

此目標的專屬名稱。

constraint_values

標籤清單;無法設定;預設為 []

這個平台包含的限制選項組合。為了建立平台 要套用至指定的環境,環境至少要有這份清單中的值。

這份清單中的每個 constraint_value 都必須是不同 constraint_setting。舉例來說,您無法定義需要 設為 @platforms//cpu:x86_64@platforms//cpu:arm

exec_properties

字典:字串 ->String;不可設定;預設為 {}

此字串對應,會影響動作的遠端執行方式。Bazel 不會嘗試 您可以將這個值視為不透明資料,透過 [平台] 欄位 遠端執行通訊協定。 這也包括來自父項平台 exec_properties 屬性的任何資料。 如果子項平台和父項平台定義了相同鍵,系統會保留子項的值。不限 與空字串相關聯的鍵會從字典中移除。 這項屬性會取代已淘汰的 remote_execution_properties
flags

字串清單;不可設定;預設為 []

將在這個平台用做目標平台時,系統會啟用的標記清單 資源配置只能使用可在轉場效果中設定的標記。
parents

標籤清單;無法設定;預設為 []

這個平台應繼承的 platform 目標標籤。雖然 屬性接受清單,不可出現多個平台。不限 如果未直接在這個平台上設定 constraint_settings,可在父項平台中找到。 詳情請參閱平台沿用設定一節。
remote_execution_properties

String;不可設定;預設為 ""

已淘汰。請改用 exec_properties 屬性。 用來設定遠端執行平台的字串。實際建構作業不會嘗試 解釋後就會視為不透明資料,可供特定 SpawnRunner 使用 這可能包含來自父項平台「remote_execution_properties」的資料屬性、 使用「{PARENT_REMOTE_EXECUTION_PROPERTIES}」巨集。詳情請參閱 平台沿用設定
required_settings

標籤清單;預設為 []

目標設定必須滿足的 config_setting 清單 ,以便在工具鍊解析期間將這個平台用做執行平台。 必要設定不會沿用來自上層平台的設定。

工具鍊

查看規則來源
toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

這項規則會宣告特定工具鍊的類型和限制,以便選取該工具鍊 工具鍊解析期間詳情請參閱 工具鍊網頁 詳細資料。

引數

屬性
name

名稱;必選

此目標的專屬名稱。

exec_compatible_with

標籤清單;無法設定;預設為 []

執行平台必須滿足的 constraint_value 清單 才能在該平台上為目標建築選取這個工具鍊。
target_compatible_with

標籤清單;無法設定;預設為 []

目標平台必須滿足的 constraint_value 清單 這樣這個工具鍊才能為該平台的目標建構項目選取。
target_settings

標籤清單;預設為 []

目標設定必須滿足的 config_setting 清單 才能在工具鍊解析期間選取此工具鍊。
toolchain

名稱;必選

代表此目標所提供的實際工具或工具套件 已選取工具鍊。
toolchain_type

標籤無法設定;必選

toolchain_type 目標的標籤,代表此角色的角色 工具鍊提供。

toolchain_type

查看規則來源
toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

此規則定義了新型工具鍊,代表一種工具類別, 擔任相同角色

詳情請參閱工具鍊頁面。

範例

這會定義自訂規則的工具鍊類型,

toolchain_type(
    name = "bar_toolchain_type",
)

這可用於 bzl 檔案。

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)

引數

屬性
name

名稱;必選

此目標的專屬名稱。