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