平台和工具鍊規則

回報問題open_in_new 查看原始碼open_in_new Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

規則

• 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	名稱 (必填) 這個目標的專屬名稱。
default_constraint_value	名稱；不可設定；預設為 None 這項設定的預設值；如未指定值，會使用這個標籤。如果有這個屬性，則所指向的 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	名稱；必填 這個目標的專屬名稱。
constraint_setting	標籤；不可設定；必要 此 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 中執行 Linux 的任何環境。

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」，且不會設定本身的「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。舉例來說，您無法定義要求 CPU 架構同時具備 @platforms//cpu:x86_64 和 @platforms//cpu:arm 的平台。
exec_properties	字典：字串 -> 字串；不可設定；預設為 {} 字串對應，會影響遠端執行動作的方式。Bazel 不會嘗試解讀此內容，而是將其視為透過遠端執行通訊協定的 Platform 欄位轉送的非公開資料。包括來自父項平台的 exec_properties 屬性的任何資料。 如果子平台和父平台定義相同的鍵，系統會保留子平台的值。任何與空白字串值相關聯的鍵都會從字典中移除。這個屬性會完全取代已淘汰的 remote_execution_properties。
parents	標籤清單；無法設定；預設為 [] 這個平台應繼承的 platform 目標標籤。雖然屬性會採用清單，但平台不應超過一個。任何未在這個平台上直接設定的 constraint_settings 都會在父項平台中找到。詳情請參閱「平台繼承」一節。
remote_execution_properties	字串；不可設定；預設值為 "" 已淘汰。請改用 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	名稱；必填 這個目標的專屬名稱。
exec_compatible_with	標籤清單；無法設定；預設為 [] 執行平台必須滿足的 constraint_value 清單，才能為該平台上的目標建構選取這個工具鍊。
target_compatible_with	標籤清單；無法設定；預設為 [] 目標平台必須滿足的 constraint_value 清單，才能為該平台的目標建構作業選取此工具鍊。
target_settings	標籤清單；預設為 [] 目標設定必須滿足的 config_setting 清單，才能在工具鏈解析期間選取這個工具鏈。
toolchain	名稱；必填 目標代表選取此工具鍊後可用的實際工具或工具套件。
toolchain_type	標籤；不可設定；必要 toolchain_type 目標的標籤，代表這個工具鏈提供的角色。

toolchain_type

查看規則來源open_in_new

toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

這項規則定義了新類型的工具鍊，也就是簡單的目標，代表一類工具，可為不同平台提供相同的功能。

詳情請參閱「Toolchains」頁面。

範例

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

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	名稱；必填 這個目標的專屬名稱。