平台和工具鍊規則

這組規則可讓您為要建構的特定硬體平台建立模型，並指定編譯這些平台程式碼時可能需要的特定工具。使用者應熟悉這個頁面說明的概念。

規則

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

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 架構。

引數

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",
)

引數

平台

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 做為執行平台)，系統就會在設定中設定指定旗標。

平台和可重複的旗標

部分旗標重複時會累計值，例如 --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_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" }。

引數

工具鍊

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

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

引數

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"]
)

引數