平台與工具鍊規則

回報問題open_in_new 查看原始碼open_in_new

我們有一組規則，可讓您針對要建構的特定硬體平台建立模型，並指定這些平台編譯程式碼所需的特定工具。請熟悉此處說明的概念。

規則

• constraint_setting
• constraint_value
• 平台
• 工具鍊
• toolchain_type

constraint_setting

查看規則來源open_in_new

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	Name; required 此目標的專屬名稱。
default_constraint_value	Name; optional; nonconfigurable 這項設定的預設值，如果未指定任何值，即可使用這項資訊。如果有這個屬性，其指向的 constraint_value 必須在與此 constraint_setting 相同的套件中定義。 如果限制設定含有預設值，則每當平台未包含該設定的任何限制值，就會與平台已指定預設值的相同。否則，如果沒有預設值，系統就會將該平台視為限制設定。在這種情況下，平台不會與任何需要針對該設定值限制的限制條件清單 (例如 config_setting) 進行比對。

constraint_value

查看規則來源open_in_new

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_64、arm 等項目的替代方案。

引數

屬性
name	Name; required 此目標的專屬名稱。
constraint_setting	Label; required; nonconfigurable 這個 constraint_value 的 constraint_setting 是可能的選項。

平台

查看規則來源open_in_new

platform(name, constraint_values, deprecation, distribs, exec_properties, features, licenses, parents, remote_execution_properties, tags, testonly, visibility)

此規則定義了一個新平台，其命名限制選項集合 (例如 CPU 架構或編譯器版本)，用於說明執行建構作業的哪個部分。詳情請參閱「平台」頁面。

範例

這會定義一個平台，用於說明在 ARM 上執行任何環境的環境。

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

平台沿用設定

平台可以使用 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_properties 和 exec_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	Name; required 此目標的專屬名稱。
constraint_values	List of labels; optional; nonconfigurable 這個平台所包含的限制條件選項組合。為了讓平台套用至特定環境，該環境至少要有此清單中的值。 此清單中的每個 constraint_value 都必須用於不同的 constraint_setting。例如，您無法定義要求 CPU 架構同時設為 @platforms//cpu:x86_64 和 @platforms//cpu:arm 的平台。
exec_properties	Dictionary: String -> String; optional 影響行動執行動作的字串字串。Bazel 不會嘗試解讀此資料，系統會將其視為透過遠端執行通訊協定的「平台」欄位轉送的不透明資料。這包括父項平台 exec_properties 屬性中的所有資料。 如果子項和上層平台定義了相同的鍵，系統將保留該子的值。系統會將與空白字串值相關聯的任何鍵從字典中移除。此屬性是已淘汰的 remote_execution_properties 的完整替代項目。
parents	List of labels; optional; nonconfigurable 這個平台應沿用的 platform 目標標籤。雖然這項屬性是一份清單，但不應有一個平台。所有未直接在這個平台上設定的 constraint_settings，都可以在上層平台中找到。詳情請參閱「平台繼承」一節。
remote_execution_properties	String; optional 已淘汰。請改用 exec_properties 屬性。 用來設定遠端執行平台的字串，實際建構不會嘗試解讀，系統會將其視為不是由特定 SpawnRunner 使用的不透明資料。您可以利用父項平台的「PARENT_REMOTE_EXECUTION_PROPERTIES}」，加入父項平台的「remote_execution_properties」屬性資料。詳情請參閱平台繼承一節。

工具鍊

查看規則來源open_in_new

toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

這項規則會宣告特定工具鍊的類型和限制，以便在工具鍊解析度期間選取。詳情請參閱工具鍊頁面。

引數

屬性
name	Name; required 此目標的專屬名稱。
exec_compatible_with	List of labels; optional; nonconfigurable 執行平台必須滿足的 constraint_value 清單，才能針對該平台中的目標建築物選取這項工具。
target_compatible_with	List of labels; optional; nonconfigurable 目標平台必須滿足的 constraint_value 清單，才能將這個工具鍊用於該平台的目標建築物。
target_settings	List of labels; optional 目標配置必須滿足的 config_setting 清單，才能在工具鍊解析期間選取這個工具鍊。
toolchain	Name; required 代表選取這個工具鍊時，可用工具或工具組的目標。
toolchain_type	Label; required; nonconfigurable toolchain_type 目標的標籤，代表這個工具鍊所扮演的角色。

工具鍊類型

查看規則來源open_in_new

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	Name; required 此目標的專屬名稱。