成員
- analysis_test_transition
- aspect
- configuration_field
- depset
- exec_group
- module_extension
- 供應商
- repository_rule
- 規則
- 選取
- 子規則
- tag_class
- 瀏覽權限
analysis_test_transition
transition analysis_test_transition(settings)
建立要套用至分析測試規則依附元件的設定轉換。這項轉換作業僅適用於含有 analysis_test = True
的規則屬性。這類規則在功能中受到限制 (例如依附元件樹狀結構的大小有限),因此相較於使用 transition()
建立的轉場效果,使用這個函式建立的轉場效果可能受限。
這項功能主要用來促進分析測試架構核心程式庫。如要瞭解最佳做法,請參閱說明文件 (或其實作)。
參數
參數 | 說明 |
---|---|
settings
|
dict;必要 包含配置設定相關資訊的字典,此設定轉換應指定這些設定。鍵是建構設定標籤,值則是轉換後的新值。所有其他設定則維持不變。您可以使用這個選項宣告通過分析測試才能通過的具體配置設定。 |
切面
Aspect aspect(implementation, attr_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])建立新切面。此函式的結果必須儲存在全域值中。詳情請參閱切面簡介。
參數
參數 | 說明 |
---|---|
implementation
|
function;必要 實作這個切面的 Starlark 函式,其中包含兩個參數:Target (套用切面的目標) 和 ctx (目標建立來源的規則結構定義)。目標屬性可透過 ctx.rule 欄位使用。此函式會在分析階段期間,針對對於目標的每個切面套用評估。 |
attr_aspects
|
「字串」的 sequence;預設值為 [] 屬性名稱清單。切面會透過這些名稱的目標屬性中指定的依附元件傳播。常見的值包括 deps 和 exports 。該清單也可以包含單一字串 "*" ,用於反映目標的所有依附元件。 |
attrs
|
dict;
預設值為 {} 用於宣告切面所有屬性的字典。它會從屬性名稱對應至屬性物件,例如「attr.label」或「attr.string」(請參閱 attr 模組)。切面屬性可做為 ctx 參數欄位的實作函式使用。以 明確屬性必須包含 |
required_providers
|
sequence;預設值為 [] 。這個屬性可限制僅對規則通告必要供應商的目標。值必須是包含個別供應商或供應商清單的清單,但不能同時包含兩者。例如, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 無效。未巢狀的供應商清單會自動轉換為一份包含一份供應商清單的清單。也就是說, 如要讓某些規則 (例如 |
required_aspect_providers
|
sequence;預設值為 [] 。這個屬性允許這個面向檢查其他切面。值必須是包含個別供應商或供應商清單的清單,但不能同時包含兩者。例如, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 無效。未巢狀的供應商清單會自動轉換為一份包含一份供應商清單的清單。也就是說, 如要讓這個面向顯示其他部分 (例如 |
provides
|
sequence;預設值為 [] 這是實作函式必須傳回的提供者清單。 如果實作函式在傳回值中略過此處列出的任何供應者類型,就會發生錯誤。但實作函式可能會傳回這裡未列出的其他供應商。 清單的每個元素都是 |
requires
|
切面的 sequence;預設為 [] 在此切面之前必須傳播的切面清單。 |
fragments
|
序列共 字串;預設值為 [] 切面在目標設定中使用的設定片段名稱清單。 |
host_fragments
|
sequence 字串;預設為 [] 切面在主機設定中需要的設定片段名稱清單。 |
toolchains
|
sequence;預設為 [] 如果已設定,則此規則需要的一系列工具鍊。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件,任意組合。查看目前的平台以找到工具鍊,並透過 ctx.toolchain 提供給規則實作。 |
incompatible_use_toolchain_transition
|
bool;預設值為 False 已淘汰,因此已停用,應予以移除。 |
doc
|
string; 或 None ;預設為 None 說明文件產生工具可擷取的切面說明。 |
apply_to_generating_rules
|
bool;預設值為 False 如果設為 true,將切面套用至輸出檔案時,會改為套用至輸出檔案的產生規則。 舉例來說,假設 `beta` 透過屬性 `deps` 以傳輸方式傳播,並套用到目標 `alpha`。假設 `alpha` 有 `deps = [':beta_output']`,其中 `beta_output` 是目標 `beta` 的宣告輸出內容。如果是 `alpha` 切面,則 `alpha` 會將目標 `alpha_rules` 做為其中一個 `deps=True` 切面。如果 `alpha` 切面會將其目標 `alpha_rules`。 預設為 False。 |
exec_compatible_with
|
字串的 sequence;預設為 [] 執行平台的限制清單,適用於該切面的所有執行個體。 |
exec_groups
|
dict; 或 None ;
根據預設為 None 執行群組名稱 (字串) 到 exec_group s。如果設定這個項目,讓切面在單一執行個體內的多個執行平台中執行動作。詳情請參閱執行群組說明文件。 |
subrules
|
「Subrule」的 sequence;預設為 [] 實驗功能:此方面使用的子規則清單。 |
configuration_field
LateBoundDefault configuration_field(fragment, name)參照 label 類型的屬性的遲交預設值。如果必須先建構設定才能判斷值,則值為「延遲」。使用這個值的屬性都必須設為不公開。
使用範例:
定義規則屬性:
'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))
在規則實作中存取:
def _rule_impl(ctx): foo_info = ctx.attr._foo ...
參數
參數 | 說明 |
---|---|
fragment
|
string;必要 包含延遲值的設定片段名稱。 |
name
|
string;必要 從設定片段中取得的值名稱。 |
露點
depset depset(direct=None, order="default", *, transitive=None)建立 depset。
direct
參數是 Depset 的直接元素清單,而 transitive
參數是一系列依附元件,其元素會成為所建立 Depset 的間接元素。將 Depset 轉換為清單時,元素傳回的順序是由 order
參數指定。詳情請參閱「Depsets 總覽」。depset 的所有元素 (直接和間接) 都必須屬於相同類型,如 type(x)
運算式所取得。
由於雜湊式集是用於在疊代期間刪除重複項目,因此解碼集的所有元素都必須可供雜湊處理。不過,目前並非所有建構函式中都會以一致的方式檢查這個不變數。請使用 --incompatible_always_check_depset_elements 標記啟用一致的檢查功能,這在日後版本中將是預設行為;請參閱問題 10313。
此外,元素目前必須為不可變動,但這項限制日後將會放寬。
所建立 Depset 的順序應與 transitive
解碼器的順序相容。"default"
訂單與其他訂單相容,所有其他訂單都只能與自己相容。
參數
參數 | 說明 |
---|---|
direct
|
序列; 或 None ;預設值為 None 直接直接直接元素元素。 |
order
|
string;預設為 "default" 新依附元件的周遊策略。如要查看可能的值,請參閱這裡。 |
transitive
|
depset 的 sequence;或是 None ;預設為 None 這個依附元件清單將含有元素將成為 Depset 的間接元素。 |
exec_group
exec_group exec_group(toolchains=[], exec_compatible_with=[])建立執行群組,用於在導入規則時,為特定執行平台建立動作。
參數
參數 | 說明 |
---|---|
toolchains
|
sequence;預設值為 [] 這個執行群組所需的工具鍊組合。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件,任意組合。 |
exec_compatible_with
|
字串的 sequence;預設為 [] 執行平台的限制清單。 |
module_extension
unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)建立新的模組擴充功能。將其儲存為全域值,以匯出並用於具有
use_extension
的 MODULE.bazel 檔案。
參數
參數 | 說明 |
---|---|
implementation
|
可呼叫;必要 實作此模組擴充功能的函式。必須使用單一參數 module_ctx 。系統會在建構開始時呼叫此函式,藉此決定可用的存放區組合。 |
tag_classes
|
dict;預設值為 {} 這個字典會宣告擴充功能使用的所有標記類別。從標記類別的名稱對應至 tag_class 物件。 |
doc
|
string; 或 None ;預設為 None 模組擴充功能的說明,可透過說明文件產生工具擷取。 |
environ
|
字串的 sequence;預設值為 [] 提供這個模組擴充功能依附的環境變數。如果這份清單中的環境變數有所變更,系統會重新評估擴充功能。 |
os_dependent
|
bool;預設值為 False 表示這項擴充功能是否與 OS 無關 |
arch_dependent
|
bool;預設值為 False 表示這項擴充功能是否相依於架構 |
provider
unknown provider(doc=None, *, fields=None, init=None)定義提供者符號,此函式的結果必須儲存在全域值中。呼叫提供者可以呼叫提供者執行個體化,也可以直接做為鍵,用來從目標擷取該供應器的例項。範例:
MyInfo = provider() ... def _my_library_impl(ctx): ... my_info = MyInfo(x = 2, y = 3) # my_info.x == 2 # my_info.y == 3 ...
如需供應商使用方法的完整指南,請參閱「規則 (供應商)」一文。
如未指定 init
,系統會傳回 Provider
可呼叫值。
如果指定 init
,系統會傳回 2 個元素的元組:Provider
可呼叫的值和原始建構函式可呼叫的值。詳情請參閱 規則 (自訂供應商的自訂初始化作業),以及下方 init
參數的討論內容。
參數
參數 | 說明 |
---|---|
doc
|
string; 或 None ;預設值為 None 這是可透過說明文件產生工具擷取的提供者說明。 |
fields
|
字串的 sequence;或 dict 或 None ;預設值為 None 。如果指定,則會限制允許使用的欄位組合。 可能的值包括:
|
init
|
可呼叫;或 None ;預設為 None 可選擇的回呼,用於預先處理及在例項化期間驗證供應器的欄位值。如果指定 init ,provider() 會傳回 2 個元素的元組:一般提供者符號和原始建構函式。具體說明如下。如需一目了然的討論和用途,請參閱「規則 (自訂供應商初始化)」一文。 讓
init 回呼的情況下,呼叫符號 P 本身會做為對預設建構函式函式 c 的呼叫;換句話說,P(*args, **kwargs) 會傳回 c(*args, **kwargs) 。舉例來說,MyInfo = provider() m = MyInfo(foo = 1)會直接使 m 成為帶有 m.foo == 1 的 MyInfo 例項。但在指定
注意:上述步驟表示,如果 如此一來, 指定 MyInfo, _new_myinfo = provider(init = ...) |
repository_rule
callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)建立新的存放區規則。將其儲存在全域值中,以便從
module extension
實作函式載入及呼叫,或供 use_repo_rule
使用。
參數
參數 | 說明 |
---|---|
implementation
|
可呼叫;必要 實作這項規則的函式。必須有單一參數 repository_ctx 。系統會在每個規則執行個體的載入階段呼叫這個函式。 |
attrs
|
dict;或 None ;預設為 None 字典,用於宣告規則的所有屬性。它會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。開頭為 _ 的屬性屬於私人性質,可用於為檔案加上標籤的隱含依附元件 (存放區規則無法依附於產生的成果)。系統會以隱含方式新增 name 屬性,請勿指定。
|
local
|
bool;預設值為 False 表示這項規則會從本機系統擷取所有資料,並在每次擷取時重新評估。 |
environ
|
「字串」的 sequence;預設值為 [] 已淘汰。此參數已淘汰。請遷移至 repository_ctx.getenv 。提供這個存放區規則依附的環境變數清單。如果這份清單中的環境變數有所變更,系統就會重新擷取存放區。 |
configure
|
bool;預設值為 False 表示存放區正在檢查系統,以便用於設定 |
remotable
|
bool;預設值為 False 實驗功能。這項參數仍在實驗階段,隨時可能變更。請勿仰賴這項功能。你可以透過設定 --experimental_repo_remote_exec 與遠端執行相容, |
doc
|
string; 或 None ;預設值為 None 這是可透過說明文件產生工具擷取的存放區規則說明。 |
規則
callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])建立新規則,可從 BUILD 檔案或巨集呼叫以建立目標。
您必須將規則指派給 .bzl 檔案中的全域變數,全域變數的名稱為規則名稱。
測試規則的名稱必須以 _test
結尾,其餘規則則不得使用這個後置字串。(這項限制僅適用於規則,不適用於其目標)。
參數
參數 | 說明 |
---|---|
implementation
|
function;必要 實作這項規則的 Starlark 函式只能包含一個參數:ctx。系統會在分析階段,為每個規則例項呼叫此函式。可存取使用者提供的屬性。必須建立動作,產生所有宣告的輸出內容。 |
test
|
bool;預設值為 unbound 這個規則是否為測試規則,即是否適用於 blaze test 指令。所有測試規則都會自動視為「可執行」;您不必為測試規則明確設定 executable = True ,因此不需要 (不建議) 採取這種做法。預設值為 False 。詳情請參閱 規則頁面。 |
attrs
|
dict;預設為 {} 字典,用於宣告規則的所有屬性。它會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。開頭為 _ 的屬性是不公開的屬性,可用來為標籤新增隱含依附元件。name 屬性為間接新增,請勿指定。以隱含方式新增 visibility 、deprecation 、tags 、testonly 和 features 屬性,且無法覆寫。大部分規則只需要幾個屬性。為限制記憶體用量,可宣告的屬性數量有上限。 |
outputs
|
dict; 或 None ;
or function;
default is None 淘汰。此參數已淘汰,並將在近期內移除。請勿仰賴這項功能。這項功能已停用 --incompatible_no_rule_outputs_param 。請使用這個標記確認您的程式碼是否與即將移除的程式碼相容。此參數已淘汰。遷移規則,改為使用 OutputGroupInfo 或 attr.output 。定義預先宣告輸出內容的結構定義。有別於 這個引數的值可以是字典或產生字典的回呼函式。回呼的運作方式與計算的依附元件屬性類似:函式的參數名稱會與規則屬性進行比對,舉例來說,如果您傳遞 字典中的每個項目都會建立一個預先宣告的輸出,其中鍵是 ID,值是決定輸出標籤的字串範本。在規則的實作函式中,ID 會成為欄位名稱,用於存取
在實務上,最常見的替換預留位置是 |
executable
|
bool;預設值為 unbound 指出這項規則是否為執行檔,亦即是否屬於 blaze run 指令。預設值為 False 。詳情請參閱 規則頁面。 |
output_to_genfiles
|
bool;預設值為 False 如果設為 true,檔案會在 genfiles 目錄中產生,而非 bin 目錄。除非您需要此標記與現有規則相容 (例如為 C++ 產生標頭檔案時),否則請勿設定這個標記。 |
fragments
|
序列共 字串;預設值為 [] 規則所需的設定片段名稱清單,在目標設定中加入規則。 |
host_fragments
|
序列共 字串;預設值為 [] 主機設定所需的設定片段名稱清單。 |
_skylark_testable
|
bool;預設值為 False (實驗功能) 如果設為 true,這項規則就會透過 Actions 供應器提供依附該規則的規則進行檢查動作。提供者也可以呼叫 ctx.created_actions(),以存取規則本身。這個方法只能用來測試 Starlark 規則的分析時間行為。我們日後可能會移除這個旗標。 |
toolchains
|
sequence;預設為 [] 如果已設定,則此規則需要的一系列工具鍊。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件,任意組合。查看目前的平台以找到工具鍊,並透過 ctx.toolchain 提供給規則實作。 |
incompatible_use_toolchain_transition
|
bool;預設值為 False 已淘汰,因此已停用,應予以移除。 |
doc
|
string; 或 None ;預設為 None 說明文件產生工具可擷取的規則說明。 |
provides
|
sequence;預設值為 [] 這是實作函式必須傳回的提供者清單。 如果實作函式在傳回值中略過此處列出的任何供應者類型,就會發生錯誤。但實作函式可能會傳回這裡未列出的其他供應商。 清單的每個元素都是 |
exec_compatible_with
|
字串的 sequence;預設為 [] 執行平台的限制清單,適用於該規則類型的所有目標。 |
analysis_test
|
bool;預設值為 False 如果設為 true,系統會將這項規則視為分析測試。 注意:分析測試規則主要是使用 Starlark 核心程式庫中的基礎架構定義。詳情請參閱「測試」一節。 如果將規則定義為分析測試規則,則可對其屬性使用透過 analysis_test_transition 定義的設定轉換,但選擇加入一些限制:
|
build_setting
|
BuildSetting」或 None ;預設值為 None 如果已設定,請說明這項規則的 build setting 類型。請參閱 config 模組。如果設定這項政策,系統會自動將名為「build_setting_default」的必要屬性加入這項規則,並將與此處傳入的值相對應的類型。
|
cfg
|
預設值為 None 如果已設定這項政策,指向設定轉換效果時,系統會在分析前將規則套用至自身設定。 |
exec_groups
|
dict; 或 None ;
根據預設為 None 執行群組名稱 (字串) 到 exec_group s。如果設定這項功能,規則就能在單一目標內的多個執行平台上執行動作。詳情請參閱執行群組說明文件。 |
initializer
|
預設值為 None 實驗功能:Salark 函式會初始化規則屬性。 系統會針對每個規則執行個體,於載入時呼叫此函式。系統會使用 其必須從屬性名稱傳回字典到所需的值。未傳回的屬性不會受到影響。如果傳回 系統會先評估初始化器,再評估屬性定義中指定的預設值。因此,如果初始化器簽章中的參數包含預設值,該參數會覆寫屬性定義中的預設值 (除非傳回 同樣地,如果初始化器簽章中的參數沒有預設值,該參數就會成為必要參數。在這種情況下,建議您省略屬性定義中的預設/必要設定。 建議您針對未處理的屬性使用 如果是擴充規則,則所有初始化器都會從子項到祖系呼叫繼續。每個初始化器只會傳遞已知的公開屬性。 |
parent
|
預設值為 None 實驗功能:擴充的 Stalark 規則。設定公開屬性時,系統會合併和宣傳的供應商。這項規則符合父項的 executable 和 test 。fragments 、toolchains 、exec_compatible_with 和 exec_groups 的值已合併。可能不會設定舊版或已淘汰的參數。系統會在此規則的傳入設定後,套用傳入設定轉換 (父項的 cfg )。 |
extendable
|
bool; 或 Label;,或 string; 或 None ;預設值為 None 實驗功能:許可清單,定義哪些規則可以擴充這項規則。您也可以把這個參數設為 True/False,以一律允許/禁止擴充。Bazel 預設一律允許擴充功能。 |
subrules
|
「Subrule」的 sequence;預設值為 [] 實驗功能:這項規則使用的子規則清單。 |
選取
unknown select(x, no_match_error='')
select()
是使規則屬性「可設定」的輔助函式。詳情請參閱「建構百科全書」。
參數
參數 | 說明 |
---|---|
x
|
dict;必要 將設定條件對應至值的 指示。每個鍵都是用於識別 config_setting 或 constraint_value 執行個體的標籤或標籤字串。如要瞭解使用標籤 (而非字串) 的時機,請參閱巨集說明文件。 |
no_match_error
|
string;預設值為 '' 如果沒有任何條件相符,即可回報選用的自訂錯誤。 |
子規則
Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])建構子規則的新例項。這個函式的結果必須儲存在全域變數中才能使用。
參數
參數 | 說明 |
---|---|
implementation
|
function;必要 實作這個子規則的 Starlark 函式 |
attrs
|
dict;預設值為 {} 這個字典會宣告子規則的所有 (私人) 屬性。 子規則只能包含標籤類型 (例如標籤或標籤清單) 的私人屬性。與這些標籤對應的解析值會自動由 Bazel 傳送至子規則的實作函式,做為具名引數 (因此,實作函式必須接受與屬性名稱相符的具名參數)。這些值的類型如下:
|
toolchains
|
sequence;預設為 [] 如果已設定,則這個子規則需要一組工具鍊。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件,任意組合。查看目前的平台後即可找到工具鍊,並透過 ctx.toolchains 提供給子規則實作。 |
fragments
|
字串的 sequence;預設為 [] 在目標設定中,子規則所需的設定片段名稱清單。 |
subrules
|
Subrule 的 sequence;預設值為 [] 這個子規則所需的其他子規則清單。 |
tag_class
tag_class tag_class(attrs={}, *, doc=None)建立新的 tag_class 物件,定義標記類別的屬性結構定義,該標記類別是模組擴充功能可使用的資料物件。
參數
參數 | 說明 |
---|---|
attrs
|
dict;
預設值為 {} 這是宣告此標記類別所有屬性的字典。它會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。 |
doc
|
string; 或 None ;預設值為 None 這是可透過說明文件產生工具擷取的標記類別說明。 |
顯示設定
None
visibility(value)
設定目前初始化 .bzl 模組的載入顯示設定。
模組的載入瀏覽權限可控管其他 BUILD 和 .bzl 檔案是否能夠載入該模組。(這與基礎 .bzl 來源檔案的目標瀏覽權限不同,用於控管該檔案是否顯示為其他目標的依附元件)。載入瀏覽權限僅適用於套件層級:如要載入模組,執行載入作業的檔案必須存放在具備模組瀏覽權限的套件中。無論模組的瀏覽權限為何,模組一律可在其專屬套件中載入。
每個 .bzl 檔案只能呼叫 visibility()
一次,且只能在頂層 (而非函式中) 呼叫。建議的樣式是將此呼叫放在 load()
陳述式下方,以及確定引數所需的任何簡短邏輯下方。
如果 --check_bzl_visibility
旗標設為 false,載入瀏覽權限違規事件時,系統會發出警告,但不會失敗版本。
參數
參數 | 說明 |
---|---|
value
|
必要 套件規格字串清單,或單一套件規格字串。 套件規格的格式與
不允許使用「@」語法;所有規格皆根據目前模組的存放區解譯。 如果 請注意,旗標 |