這組規則可讓您模擬要建構的特定硬體平台,並指定可能需要用來為這些平台編譯程式碼的特定工具。使用者應熟悉這裡所述的概念。
規則
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
|
這項設定的預設值標籤,如果未提供值,系統會使用這個標籤。如果有這個屬性,則所指向的 constraint_value 必須與這個 constraint_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_64
、arm
等的替代方案。
引數
屬性 | |
---|---|
name |
名稱 (必填) 這個目標的專屬名稱。 |
constraint_setting
|
這個 constraint_value 是可能的 constraint_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
用於執行平台),則會在設定中設定指定的標記。
平台和可重複的標記
部分旗標會在重複時累積值,例如 --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
的邏輯如下:
-
如果子平台未設定
remote_execution_property
,系統會使用父項的remote_execution_properties
。 -
如果
remote_execution_property
是在子平台上設定,且包含字面字串 {PARENT_REMOTE_EXECUTION_PROPERTIES},則該巨集會替換為父項remote_execution_property
屬性的內容。 -
如果
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 |
名稱 (必填) 這個目標的專屬名稱。 |
constraint_values
|
這個平台包含的限制條件選項組合。平台要套用至特定環境,該環境至少必須具備此清單中的值。 這份清單中的每個 |
exec_properties
|
字典:字串 -> 字串;不可設定;預設為 exec_properties 屬性的任何資料。如果子平台和父平台定義相同的鍵,系統會保留子平台的值。任何與空白字串值相關聯的鍵都會從字典中移除。這項屬性是 remote_execution_properties 的完整替代項目。 |
flags
|
字串清單;不可設定;預設為 |
parents
|
這個平台應繼承的 platform 目標標籤。雖然屬性會採用清單,但平台不應超過一個。任何未在這個平台上直接設定的 constraint_settings 都會在父項平台中找到。詳情請參閱「平台繼承」一節。 |
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)
這項規則定義了新類型的工具鍊,也就是簡單的目標,代表一類工具,可為不同平台提供相同的功能。
詳情請參閱「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 |
名稱 (必填) 這個目標的專屬名稱。 |