全球

在全域環境中註冊的物件、函式和模組。

成員

全部

bool all(elements)

如果所有元素評估為 True 或集合為空白,則傳回 true。系統會透過 bool 函式將元素轉換為布林值。
all(["hello", 3, True]) == True
all([-1, 0, 1]) == False

參數

參數 說明
elements 必要
字串或元素集合。

analysis_test_transition

transition analysis_test_transition(settings)

建立要套用至分析測試規則依附元件的設定轉換。這項轉換作業僅適用於含有 analysis_test = True 的規則屬性。這類規則在功能中受到限制 (例如依附元件樹狀結構的大小有限),因此相較於使用轉換建立的轉場效果,使用此函式建立的轉場效果可能有限。

這項功能主要用來促進分析測試架構核心程式庫。如要瞭解最佳做法,請參閱說明文件 (或其導入作業)。

參數

參數 說明
settings 必要
包含配置設定相關資訊的字典,這個設定轉換應指定這些設定。鍵是建構設定標籤,值則是轉換後的新值。所有其他設定則維持不變。您可以使用此程式碼,宣告分析測試必須完成某些設定才能通過。

不限

bool any(elements)

如果至少有一個元素評估為 True,則傳回 true。系統會透過 bool 函式將元素轉換為布林值。
any([-1, 0, 1]) == True
any([False, 0, ""]) == False

參數

參數 說明
elements 必要
字串或元素集合。

archive_override

None archive_override(module_name, urls, integrity='', strip_prefix='', patches=[], patch_cmds=[], patch_strip=0)

指定這項依附元件應來自特定位置的封存檔案 (zip、gzip 等),而非註冊資料庫。這個指令只會在根模組中生效;換句話說,如果模組做為其他依附元件使用模組,系統會忽略本身的覆寫值。

參數

參數 說明
module_name 必要
要套用此覆寫值的 Bazel 模組依附元件名稱。
urls string; or Iterable of strings; 必要
封存內容的網址;可以是 http(s):// 或 file:// URL。
integrity 預設 = '
封存檔案的預期總和檢查碼,採用子資源完整性格式。
strip_prefix 預設 = '
要從已擷取檔案中移除的目錄前置字串。
patches Iterable of strings; 預設 = []
標籤清單,指向要套用至這個模組的修補程式檔案。修補型檔案必須存在於頂層專案的來源樹狀結構中。這些規則會按照清單順序套用。
patch_cmds Iterable of strings; 預設 = []
套用修補程式後,要套用到 Linux/Macos 的 Bash 指令序列。
patch_strip 預設 = 0
與 Unix 修補程式的 --strip 引數相同。

切面

Aspect aspect(implementation, attr_aspects=[], attrs=None, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc='', *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None)

建立新切面。此函式的結果必須儲存在全域值中。詳情請參閱切面簡介

參數

參數 說明
implementation 必要
實作此切面的 Starlark 函式,其中包含兩個參數:Target (套用切面的目標) 和 ctx (目標的建立規則結構定義)。目標屬性可透過 ctx.rule 欄位使用。此函式會在分析階段中,針對對於目標的每個切面套用評估。
attr_aspects sequence of strings; 預設 = []
屬性名稱清單。切面會透過這些名稱的目標屬性中指定的依附元件傳播。常見的值包括 depsexports。該清單也可以包含單一字串 "*",用於反映目標的所有依附元件。
attrs dict; or None; 預設值 = 無
用於宣告切面所有屬性的字典。它會從屬性名稱對應至屬性物件,例如「attr.label」或「attr.string」(請參閱 attr 模組)。切面屬性可做為 ctx 參數欄位的實作函式使用。

_ 開頭的隱含屬性必須有預設值,且類型為 labellabel_list

明確屬性必須包含 string 類型,且必須使用 values 限制。明確屬性會限制切面,只能搭配名稱、類型和有效值的屬性 (根據限制) 的規則使用。

required_providers 預設 = []
這項屬性可限制只在規則中宣傳必要供應商的目標。值必須是包含個別供應商或供應商清單的清單,但不能同時包含兩者。例如,[[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 無效。

未巢狀的供應商清單會自動轉換為一份包含一份供應商清單的清單。也就是說,[FooInfo, BarInfo] 會自動轉換為 [[FooInfo, BarInfo]]

如要讓某些規則 (例如 some_rule) 目標可顯示,some_rule 必須宣傳至少其中一份供應商名單中的所有供應商。舉例來說,如果切面的 required_providers[[FooInfo], [BarInfo], [BazInfo, QuxInfo]],則只有在 some_rule 提供 FooInfo *或* BarInfo *或* BazInfo *和* QuxInfo 時,此切面才會看到 some_rule 目標。

required_aspect_providers 預設 = []
這項屬性可用來檢查其他方面。值必須是包含個別供應商或供應商清單的清單,但不能同時包含兩者。例如,[[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 無效。

未巢狀的供應商清單會自動轉換為一份包含一份供應商清單的清單。也就是說,[FooInfo, BarInfo] 會自動轉換為 [[FooInfo, BarInfo]]

如要讓這個面向顯示其他部分 (例如 other_aspect),other_aspect 必須提供至少其中一份清單中的所有供應商。在 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 範例中,只有在 other_aspect 提供 FooInfo「或」BarInfo *或* BazInfo「和」QuxInfo 的情況下,這個切面才會看到 other_aspect

provides 預設 = []
實作函式必須傳回的提供者清單。

如果實作函式在傳回值中略過此處列出的任何供應者類型,就會發生錯誤。但實作函式可能會傳回這裡未列出的其他供應商。

清單的每個元素都是 provider() 傳回的 *Info 物件,但舊版供應器會改以其字串名稱表示。

requires sequence of Aspects; 預設 = []
在此切面之前要傳播的切面清單。
fragments sequence of strings; 預設 = []
切面設定目標設定片段的名稱清單。
host_fragments sequence of strings; 預設 = []
切面在主機設定中需要的設定片段名稱清單。
toolchains sequence; 預設 = []
如果已設定,則此規則所需的工具鍊組合。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件,任意組合。查看目前的平台以找到工具鍊,並透過 ctx.toolchain 提供給規則實作。
incompatible_use_toolchain_transition 預設值 = 否
已淘汰,因此已停用,應該移除。
doc 預設 = '
透過說明文件產生工具擷取切面的說明。
apply_to_generating_rules 預設值 = 否
設為 true 時,如果套用至輸出檔案,就會套用至輸出檔案的產生規則。

舉例來說,假設某個切面是透過屬性 `deps` 傳播,並套用到目標 `alpha`。假設 `alpha` 有 `deps = [':beta_output']`,其中 `beta_output` 是目標 `beta` 的宣告輸出內容。假設 `beta` 的目標 `charlie` 是其中一個 `deps`。如果切面的 `apply_to_generating_rules=True`,表示特徵會透過 `alpha`、`beta` 和 `charlie` 傳播。如果為 False,切面只會套用至 `alpha`。

預設為 False。

exec_compatible_with sequence of strings; 預設 = []
執行平台的限制清單,適用於這個方面的所有執行個體。
exec_groups dict; or None; 預設值 = 無
執行群組名稱 (字串) 變更為 exec_group。如果設定這個項目,讓切面在單一執行個體內的多個執行平台中執行動作。詳情請參閱執行群組說明文件

bazel_dep

None bazel_dep(name, version='', max_compatibility_level=-1, repo_name='', dev_dependency=False)

宣告另一個 Bazel 模組的直接依附元件。

參數

參數 說明
name 必要
要新增為直接依附元件的模組名稱。
version 預設 = '
要新增為直接依附元件的模組版本。
max_compatibility_level 預設 = -1
支援新增做為直接依附元件的模組支援的最大 compatibility_level 值。模組版本會隱含支援的最低 compatible_level,以及如未指定屬性,則為最大值。
repo_name 預設 = '
代表此依附元件的外部存放區名稱。此為預設模組的名稱。
dev_dependency 預設值 = 否
如果設為 true,當目前的模組不是根模組或已啟用 `--ignore_dev_dependency` 時,系統會忽略這個依附元件。

繫結

None bind(name, actual=None)

警告:我們不建議使用 bind()。如要進一步瞭解相關問題和替代方案,請參閱考慮移除繫結一文。

//external 套件中的目標提供別名。

參數

參數 說明
name 必要
「//external」下方的標籤做為別名名稱
actual string; or None; 預設值 = 無
要別名的實際標籤

bool

bool bool(x=False)

布林值類型的建構函式。如果物件是 NoneFalse、空白字串 ("")、數字 0 或空白集合 (例如 ()[]),就會傳回 False。如果沒有,則會傳回 True

參數

參數 說明
x 預設值 = 否
要轉換的變數。

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 必要
包含延遲值的設定片段名稱。
name 必要
從設定片段中取得的值名稱。

露點

depset depset(direct=None, order="default", *, transitive=None)

建立 depsetdirect 參數是 Depset 的直接元素清單,而 transitive 參數是一系列依附元件,其元素會成為所建立 Depset 的間接元素。將 Depset 轉換為清單時,元素傳回的順序是由 order 參數指定。詳情請參閱「Depsets 總覽」。

depset 的所有元素 (直接和間接) 都必須屬於相同類型,如 type(x) 運算式所取得。

由於雜湊式集是用於在疊代期間刪除重複項目,因此解碼集的所有元素都必須可供雜湊處理。不過,目前並非所有建構函式中都會以一致的方式檢查這個不變數。使用 --incompatible_always_check_depset_elements 標記啟用一致的檢查功能;這將成為日後版本中的預設行為;請參閱問題 10313

此外,元素目前不得變動,但這項限制日後將會放寬。

所建立 Depset 的順序應與 transitive 解碼器的順序相容。「"default"」訂單與其他訂單相容,所有其他訂單都只能與自己相容。

回溯相容性注意事項。這個函式目前接受位置 items 參數。此類別已淘汰且將於日後移除,且在移除 direct 後,將成為 depset 函式的唯一位置參數。因此,下列兩項呼叫都是對等且未來的呼叫,能夠確保使用者因應未來的需求:

depset(['a', 'b'], transitive = [...])
depset(direct = ['a', 'b'], transitive = [...])

參數

參數 說明
direct sequence; or None; 預設值 = 無
依附元件的直接元素清單。
order 預設 =「預設」
新部門的周遊策略。如要查看可能的值,請參閱這篇文章
transitive sequence of depsets; or None; 預設值 = 無
模式清單,其元素將成為解碼器的間接元素。

語音輸入

dict dict(pairs=[], **kwargs)

根據選用的位置引數和一組選用的關鍵字引數,建立字典。如果有多個同一個鍵,系統會採用最後一個值。凡是透過位置引數提供的項目,由關鍵字引數提供的項目都會視為來自。

參數

參數 說明
pairs 預設 = []
dict 或可疊代且元素每個長度為 2 (鍵、值) 的元素。
kwargs 必要
其他項目的字典。

dir

list dir(x)

會傳回字串清單:參數物件的屬性名稱和方法。

參數

參數 說明
x 必要
要檢查的物件。

列舉

list enumerate(list, start=0)

傳回一組配對 (兩個元素元組),含索引 (int) 和輸入序列中的項目。
enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]

參數

參數 說明
list 必要
輸入序列
start 預設 = 0
起始索引。

exec_group

exec_group exec_group(toolchains=[], exec_compatible_with=[], copy_from_rule=False)

建立執行群組,以便在導入規則時,為特定執行平台建立動作。

參數

參數 說明
toolchains sequence; 預設 = []
這個執行群組所需的工具鍊組合。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件,任意組合。
exec_compatible_with sequence of strings; 預設 = []
執行平台的限制清單。
copy_from_rule 預設值 = 否
如果設為 true,這個 exec 群組會沿用這個群組附加規則的工具鍊和限制。如果設為任何其他字串,則會發生錯誤。

失敗

None fail(msg=None, attr=None, *args)

導致執行作業失敗並發生錯誤。

參數

參數 說明
msg 預設值 = 無
已淘汰:改用位置引數。此引數就像隱含的位置引數。
attr string; or None; 預設值 = 無
已淘汰。使用包含這個字串的選用前置字元,加入錯誤訊息中。
args 必要
顯示在錯誤訊息中的值清單,採用 debugPrint (預設等同於 str ) 格式並以空格彙整。

float

float float(x=unbound)

以浮點值傳回 x。
  • 如果 x 已經是浮點值,float 會傳回不變。
  • 如果 x 是布林值,float 會傳回 1.0 代表 True,然後傳回 0.0 代表 False。
  • 如果 x 是 int,float 會傳回最接近 x 的有限浮點值;如果規模過大,就會傳回錯誤。
  • 如果 x 是字串,則必須是有效的浮點常值,或與 NaNInfInfinity 相同 (忽略大小寫) 至 NaNInfInfinity,也可選擇在前面加上 +- 符號。
如果設為其他值,就會發生錯誤。沒有引數時,float() 會傳回 0.0。

參數

參數 說明
x 預設值 = 未繫結
要轉換的值。

getattr

unknown getattr(x, name, default=unbound)

傳回指定名稱的結構體欄位 (如有)。如果不是,則會傳回 default (如有指定) 或引發錯誤。getattr(x, "foobar") 等於 x.foobar
getattr(ctx.attr, "myattr")
getattr(ctx.attr, "myattr", "mydefault")

參數

參數 說明
x 必要
存取其屬性的結構。
name 必要
結構體屬性的名稱。
default 預設值 = 未繫結
結構體沒有指定名稱的屬性時,要傳回的預設值。

git_override

None git_override(module_name, remote, commit='', patches=[], patch_cmds=[], patch_strip=0)

指定依附元件應來自某個 Git 存放區的特定修訂版本。這個指令只會在根模組中生效;換句話說,如果模組做為其他依附元件使用模組,系統會忽略本身的覆寫值。

參數

參數 說明
module_name 必要
要套用此覆寫值的 Bazel 模組依附元件名稱。
remote 必要
遠端 Git 存放區的網址。
commit 預設 = '
應結帳的修訂版本。
patches Iterable of strings; 預設 = []
標籤清單,指向要套用至這個模組的修補程式檔案。修補型檔案必須存在於頂層專案的來源樹狀結構中。這些規則會按照清單順序套用。
patch_cmds Iterable of strings; 預設 = []
套用修補程式後,要套用到 Linux/Macos 的 Bash 指令序列。
patch_strip 預設 = 0
與 Unix 修補程式的 --strip 引數相同。

hasattr

bool hasattr(x, name)

如果物件 x 具有指定 name 的屬性或方法,則傳回 True,否則傳回 False。範例:
hasattr(ctx.attr, "myattr")

參數

參數 說明
x 必要
要檢查的物件。
name 必要
屬性的名稱。

hash

int hash(value)

傳回字串的雜湊值。計算方法是使用與 Java 的 String.hashCode() 相同的演算法,也就是:
s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1]
目前不支援對字串以外的值進行雜湊處理。

參數

參數 說明
value 必要
要雜湊的字串值。

int

int int(x, base=unbound)

傳回 x 做為 int 值。
  • 如果 x 已經是 int,int 會傳回不變。
  • 如果 x 是布林值,int 會傳回 1 代表 True,然後傳回 0 代表 False。
  • 如果 x 是字串,則必須採用 <sign><prefix><digits> 格式。<sign>"+""-" 或空白 (解釋為正數)。<digits> 是介於 0 到 base 到 1 之間的一串數字,其中字母 a-z (或相等的 A-Z) 會用做 10 到 35 的數字。在 base 為 2/8/16 的情況下,<prefix> 為選用項目,可能分別為 0b/0o/0x (或同等的值為 0B/0O/0X)。如果 base 是這些底數以外的其他值或特殊值 0,則前置碼必須留空。在 base 為 0 的情況下,如果使用任何前置字元,系統會將字串解讀為整數常值。在此情況下,系統會選擇 2/8/10/16 其中一個底數 (如有使用任何前置字元)。如果 base 為 0,則不使用前置字元,且有超過一個數字,開頭的數字不得為 0;以免八進位和小數混淆字串所代表的數字大小必須落在 int 類型的允許範圍內。
  • 如果 x 是浮點值,int 會傳回浮點值的整數值,四捨五入為零。如果 x 並非有限 (NaN 或無限大),就會發生錯誤。
如果 x 是任何其他類型,或值是不符合上述格式的字串,這個函式就會失敗。與 Python 的 int 函式不同,這個函式不允許零引數,且不允許字串引數使用多餘的空白字元。

範例:

int("123") == 123
int("-123") == -123
int("+123") == 123
int("FF", 16) == 255
int("0xFF", 16) == 255
int("10", 0) == 10
int("-0x10", 0) == -16
int("-0x10", 0) == -16
int("123.456") == 123

參數

參數 說明
x 必要
要轉換的字串。
base 預設值 = 未繫結
用來解譯字串值的基數;預設值為 10。必須介於 2 至 36 (含) 之間,或是 0 用於偵測底數,就像 x 是整數常值。如果值不是字串,就不能提供此參數。

len

int len(x)

傳回字串、序列 (例如清單或元組)、dict 或其他可疊代項目的長度。

參數

參數 說明
x 必要
要回報長度的值。

list

list list(x=[])

傳回所含元素與指定的可疊代值相同的新清單。
list([1, 2]) == [1, 2]
list((2, 3, 2)) == [2, 3, 2]
list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4]

參數

參數 說明
x 預設 = []
要轉換的物件。

local_path_override

None local_path_override(module_name, path)

指定依附元件應來自本機磁碟上的特定目錄。這個指令只會在根模組中生效;換句話說,如果模組做為其他依附元件使用模組,系統會忽略本身的覆寫值。

參數

參數 說明
module_name 必要
要套用此覆寫值的 Bazel 模組依附元件名稱。
path 必要
模組所在目錄的路徑。

最高

unknown max(*args)

傳回所有指定引數中最大的一個。如果只提供一個引數,就必須是不可空白的可疊代項目。如果元素無法比較 (例如 int 字串),或沒有指定引數,就會發生錯誤。
max(2, 5, 4) == 5
max([5, 6, 3]) == 6

參數

參數 說明
args 必要
要檢查的元素。

分鐘

unknown min(*args)

傳回所有指定引數中的最小一個。如果只提供一個引數,其必須為不可空白的可疊代項目。如果元素無法比較 (例如 int 與字串),或未設定引數時就會發生錯誤。
min(2, 5, 4) == 2
min([5, 6, 3]) == 3

參數

參數 說明
args 必要
要檢查的元素。

module

None module(name='', version='', compatibility_level=0, repo_name='', bazel_compatibility=[])

宣告目前 Bazel 存放區所代表 Bazel 模組的某些屬性。這些屬性是模組的基本中繼資料 (例如名稱和版本),或影響目前模組及其相依項目的行為。

最多不應呼叫一次。只有在這個模組為根模組時,才可以省略它 (如同同理,如果不以其他模組依附該模組)。

參數

參數 說明
name 預設 = '
模組的名稱,只有在這個模組為根模組時,才可以省略 (就像同好,不需要由其他模組依附該模組)。有效的模組名稱必須:1) 只能包含小寫英文字母 (a 至 z)、數字 (0 至 9)、半形句號 (.)、連字號 (-) 和底線 (_);2) 以小寫英文字母開頭;3) 結尾須為小寫英文字母或數字。
version 預設 = '
模組的版本。只有在這個模組為根模組時,才可以省略 (就像同好,不需要由其他模組依附該模組)。
compatibility_level 預設 = 0
模組的相容性等級;每次推出重大不相容的變更時,應該都會變更。這基本上就是「主要版本」,但該模組不會嵌入版本字串本身,而是以獨立欄位的形式存在。相容性等級不同的模組就像是模組有不同名稱的模組,一樣採用版本解析方式,但最終依附元件圖表不能包含多個名稱相同,但相容性等級不同的模組 (除非 multiple_version_override 生效,詳情請參閱此處)。
repo_name 預設 = '
代表這個模組的存放區名稱,如模組本身所示。根據預設,存放區的名稱是模組名稱。如果專案使用某個存放區名稱,但該存放區名稱與模組名稱不同,您可以指定這個值,以便更輕鬆地遷移專案。
bazel_compatibility Iterable of strings; 預設 = []
bazel 版本清單,可讓使用者宣告與這個模組相容的 Bazel 版本。這項設定「不會」影響依附元件解析,但 bzlmod 會使用這項資訊來檢查您目前的 Bazel 版本是否相容。這個值是某些限制值的字串,並以半形逗號分隔,支援三個限制:<=X.X.X:Bazel 版本必須等於或早於 X.X.X。在新版本中有已知的不相容變更時使用。>=X.X.X:Bazel 版本必須等於或高於 X.X.X。當您依賴某些只能在 X.X.X 之後才能使用的功能時,才會使用 Bazel。-X.X.X:Bazel 版本 X.X.X 不相容。當 X.X.X 中有錯誤讓您中斷,但在後續版本中已修正時可使用。

module_extension

unknown module_extension(implementation, *, tag_classes={}, doc='', environ=[], os_dependent=False, arch_dependent=False)

建立新的模組擴充功能。將其儲存為全域值,以便匯出並用於 MODULE.bazel 檔案。

參數

參數 說明
implementation 必要
實作這個模組擴充功能的函式。必須使用單一參數 module_ctx。系統會在建構開始時呼叫此函式,藉此決定一組可用的存放區。
tag_classes default = {}
字典,用於宣告擴充功能使用的所有標記類別。從標記類別的名稱對應至 tag_class 物件。
doc 預設 = '
模組擴充功能的說明,可透過說明文件產生工具擷取。
environ sequence of strings; 預設 = []
提供這個模組擴充功能依附的環境變數。如果這份清單中的環境變數有所變更,系統會重新評估擴充功能。
os_dependent 預設值 = 否
指出這項擴充功能是否與 OS 相關
arch_dependent 預設值 = 否
指出這項擴充功能是否取決於架構

multiple_version_override

None multiple_version_override(module_name, versions, registry='')

指定依附元件應仍來自註冊資料庫,但應允許同時存在多個版本。詳情請參閱說明文件。這個指令只會在根模組中生效;換句話說,如果模組做為其他依附元件使用模組,系統會忽略本身的覆寫值。

參數

參數 說明
module_name 必要
要套用此覆寫值的 Bazel 模組依附元件名稱。
versions Iterable of strings; 必要
明確指定可同時存在的版本。這些版本必須已列在依附元件圖表預先選取項目中。這個模組的依附元件將「已升級」至於相容性等級中最接近的可用版本,如果依附元件的版本高於在相同相容性等級的任何可用版本,就會造成錯誤。
registry 預設 = '
覆寫此模組的登錄檔;而非從預設登錄檔清單中找到這個模組,則應使用指定的登錄檔。

列印

None print(sep=" ", *args)

args 列印為偵錯輸出內容。並在前面加上 "DEBUG" 字串和這個呼叫的位置 (檔案和行號)。未指定引數轉換為字串的確切方式,而且可能隨時變更。具體來說,該記錄可能會與 str()repr() 的格式設定不同,甚至更加詳細。

我們不建議在正式版程式碼中使用 print,因為該程式碼會向使用者顯示垃圾內容。如要淘汰,請盡可能使用 fail() 處理重大錯誤。

參數

參數 說明
sep 預設值 =「「
」 物件之間的分隔符字串,預設值為空格 (「 」)。
args 必要
要列印的物件。

供應商

unknown provider(doc='', *, 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 預設 = '
可藉由說明文件產生工具擷取的供應商說明。
fields sequence of strings; or dict; or None; 預設值 = 無
如果指定,則會限制允許的欄位組合。
可能的值包括:
  • 欄位清單:
    provider(fields = ['a', 'b'])

  • 字典欄位名稱 ->說明文件:
    provider(
           fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
所有欄位均為選填。
init callable; or None; 預設值 = 無
選用的回呼,用於預先處理及驗證供應器的欄位值。如果指定 initprovider() 會傳回 2 個元素的元組:一般提供者符號和原始建構函式

詳細說明如下:如需直覺的討論和用途,請參閱規則 (自訂供應商初始化)

P 成為透過呼叫 provider() 建立的提供者符號。從概念上,P 例項的產生方式是呼叫預設建構函式函式 c(*args, **kwargs),而該函式會執行以下作業:

  • 如果 args 非空白,就會發生錯誤。
  • 如果在呼叫 provider() 時指定 fields 參數,且 kwargs 包含 fields 中未列出的任何鍵,就會發生錯誤。
  • 否則,c 會傳回 kwargs 中每個 k: v 項目的新例項,也就是名為 k 且值為 v 的欄位。
在「沒有」指定 init 回呼的情況下,對符號 P 的呼叫本身將做為對預設建構函式函式 c 的呼叫。換句話說,P(*args, **kwargs) 會傳回 c(*args, **kwargs)。例如:
MyInfo = provider()
m = MyInfo(foo = 1)
會直接使 m 成為帶有 m.foo == 1MyInfo 執行個體。

但在指定 init 的情況下,呼叫 P(*args, **kwargs) 會改為執行下列步驟:

  1. 回呼會被叫用為 init(*args, **kwargs),也就是與傳遞至 P 完全相同的位置和關鍵字引數。
  2. init 的傳回值應為字典 d,其索引鍵為欄位名稱字串。否則就會發生錯誤。
  3. 產生新的 P 例項時,會像 c(**d) 一樣,透過使用 d 的項目呼叫預設建構函式做為關鍵字引數,藉此產生一個新的例項。

注意:上述步驟表示,如果 *args**kwargsinit 的簽名不符、init 主體的評估作業失敗 (或許刻意透過呼叫 fail()),或是 init 的傳回值與預期的結構定義不符,就會發生錯誤。

如此一來,init 回呼允許位置引數和任意邏輯來進行預先處理和驗證,將一般的供應器建構一般化。但「不會」允許規避允許的 fields 清單。

指定 init 時,provider() 的傳回值會成為元組 (P, r),其中 r原始建構函式。事實上,r 的行為與上述預設建構函式函式 c 的行為完全相同。一般而言,r 會繫結至名稱前置字串為底線的變數,因此只有目前的 .bzl 檔案可直接存取變數:

MyInfo, _new_myinfo = provider(init = ...)

範圍

sequence range(start_or_stop, stop_or_none=None, step=1)

建立清單,其中項目從 startstop,並以 step 為單位遞增。如果提供單一引數,項目的範圍從 0 到該元素。
range(4) == [0, 1, 2, 3]
range(3, 9, 2) == [3, 5, 7]
range(3, 0, -1) == [3, 2, 1]

參數

參數 說明
start_or_stop 必要
如果提供停止,起始元素的值,否則為停靠站,實際開始值則為 0
stop_or_none int; or None; 預設值 = 無
「不」包含在結果清單中的第一個項目選用索引。並在到達 stop前停止。
step 預設 = 1
遞增 (預設值為 1)。但可能是負值。

register_execution_platforms()

None register_execution_platforms(*platform_labels)

註冊已定義的平台,讓 Bazel 在工具鍊解析期間,將平台用做執行平台

參數

參數 說明
platform_labels sequence of strings; 必要
要註冊的平台標籤。

register_execution_platforms(dev_dependency)

None register_execution_platforms(dev_dependency=False, *platform_labels)

選取這個模組時,指定要登錄已定義的執行平台。必須是絕對目標模式 (例如開頭為 @//)。詳情請參閱工具鍊解決方案

參數

參數 說明
dev_dependency 預設值 = 否
如果設為 true,如果目前的模組不是根模組,或已啟用 `--ignore_dev_dependency`,系統就不會註冊執行平台。
platform_labels sequence of strings; 必要
要註冊的平台標籤。

register_toolchains()

None register_toolchains(*toolchain_labels)

註冊已定義的工具鍊,以便 Bazel 在工具鍊解析期間使用這項工具。請參閱定義註冊工具鍊的範例。

參數

參數 說明
toolchain_labels sequence of strings; 必要
要註冊的工具鍊標籤。

register_toolchains(dev_dependency)

None register_toolchains(dev_dependency=False, *toolchain_labels)

選取這個模組時,指定要註冊的已定義的工具鍊。必須是絕對目標模式 (例如開頭為 @//)。詳情請參閱工具鍊解決方案

參數

參數 說明
dev_dependency 預設值 = 否
如果設為 true,且目前的模組不是根模組,或已啟用 `--ignore_dev_dependency`,系統就不會註冊工具鍊。
toolchain_labels sequence of strings; 必要
要註冊的工具鍊標籤。

repository_rule

callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc='')

建立新的存放區規則。將其儲存為全域值,以便系統從 WORKSPACE 檔案載入及呼叫該值。

參數

參數 說明
implementation 必要
執行這項規則的函式必須有單一參數 repository_ctx。系統會在每個規則執行個體的載入階段呼叫此函式。
attrs dict; or None; 預設值 = 無
宣告規則的所有屬性。它會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。開頭為 _ 的屬性屬於私人性質,可用於為檔案加上標籤的隱含依附元件 (存放區規則無法依附於產生的成果)。name 屬性為間接新增,請勿指定。
local 預設值 = 否
指出這項規則會擷取本機系統中的所有內容,每次擷取時都應重新評估。
environ sequence of strings; 預設 = []
提供這個存放區規則依附的環境變數清單。如果這份清單中的環境變數有所變更,系統就會重新擷取存放區。
configure 預設值 = 否
表示存放區為了設定目的檢查系統
remotable 預設值 = 否
實驗功能。這項參數仍在實驗階段,隨時可能變更。請勿仰賴這項功能。你可以設定 ---experimental_repo_remote_exec
與遠端執行相容,這樣就能啟用實驗模式
doc 預設 = '
可透過說明文件產生工具擷取的存放區規則說明。

Repr

string repr(x)

將任何物件轉換為字串表示。這對偵錯很有幫助。
repr("ab") == '"ab"'

參數

參數 說明
x 必要
要轉換的物件。

已撤銷

list reversed(sequence)

傳回新的未凍結清單,其中包含原始可疊代序列的元素 (以反向順序排列)。
reversed([3, 5, 4]) == [4, 5, 3]

參數

參數 說明
sequence 必要
要反轉的可疊代序列 (例如清單)。

規則

callable rule(implementation, test=False, attrs=None, outputs=None, executable=False, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc='', *, provides=[], exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, compile_one_filetype=None, name=None)

建立新規則,可從 BUILD 檔案或巨集呼叫以建立目標。

規則必須指派給 .bzl 檔案中的全域變數;全域變數的名稱是規則名稱

測試規則的名稱必須以 _test 結尾,其餘規則則不得使用這個後置字串。(這項限制僅適用於規則,不適用於其目標)。

參數

參數 說明
implementation 必要
實作此規則的 Starlark 函式只能包含一個參數:ctx。系統會在分析階段,為每個規則例項呼叫此函式。可存取使用者提供的屬性。必須建立動作,才能產生所有宣告的輸出內容。
test 預設值 = 否
此規則是否為測試規則,即是否適用於 blaze test 指令。所有測試規則都會自動視為「可執行」。因此您不必為測試規則明確設定 executable = True,因此不建議使用 (不建議)。詳情請參閱 規則頁面
attrs dict; or None; 預設值 = 無
宣告規則的所有屬性。它會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。開頭為 _ 的屬性是不公開的屬性,可用來為標籤新增隱含依附元件。name 屬性為間接新增,請勿指定。以隱含方式新增 visibilitydeprecationtagstestonlyfeatures 屬性,且無法覆寫。大部分規則只需要幾個屬性。為了限制記憶體用量,規則函式設有曝光事件大小上限。
outputs dict; or None; or function; 預設值 = 無
已淘汰,此參數已淘汰,並將在近期內移除。請勿仰賴這項功能。這項功能已停用 ---incompatible_no_rule_outputs_param。請使用這個標記確認您的程式碼是否與即將移除的程式碼相容。
此參數已淘汰。遷移規則,改為使用 OutputGroupInfoattr.output

定義預先宣告輸出內容的結構定義。有別於 outputoutput_list 屬性,使用者不會指定這些檔案的標籤。如要進一步瞭解預先宣告的輸出內容,請參閱規則頁面

這個引數的值可以是字典或產生字典的回呼函式。回呼的運作方式與計算的依附元件屬性類似:函式的參數名稱會與規則屬性進行比對,舉例來說,如果您傳遞 outputs = _my_func 具有定義 def _my_func(srcs, deps): ...,該函式便可以存取 srcsdeps 屬性。無論字典是直接指定或透過函式指定,都會解讀如下。

字典中的每個項目都會建立一個預先宣告的輸出,其中鍵是 ID,值是決定輸出標籤的字串範本。在規則的實作函式中,ID 會成為欄位名稱,用於存取 ctx.outputs 中的輸出內容 File。輸出的標籤與規則具有相同的套件,而在產生套件之後的部分,則是用 ATTR 屬性的值以字串取代 "%{ATTR}" 格式的每個預留位置:

  • 字串類型的屬性會完整替換。
  • 標籤類型的屬性在套件後成為標籤的一部分,並減去副檔名。舉例來說,標籤 "//pkg:a/b.c" 會變成 "a/b"
  • 輸出類型的屬性會在套件之後成為標籤的一部分,包括副檔名 (如上例為 "a/b.c")。
  • 在預留位置中使用的所有清單類型屬性 (例如 attr.label_list) 都必須包含一個元素。轉換與非清單版本相同 (attr.label)。
  • 其他屬性類型不得出現在預留位置中。
  • 特殊的非屬性預留位置 %{dirname}%{basename} 會展開為規則標籤的這些部分,不含其套件。例如 "//pkg:a/b.c" 中的 dirname 為 a,基礎名稱則為 b.c

在實務上,最常見的替換預留位置是 "%{name}"。舉例來說,對於名為「foo」的目標,輸出字典 {"bin": "%{name}.exe"} 會預先宣告名為 foo.exe 的輸出內容,其可在實作函式中以 ctx.outputs.bin 存取。

executable 預設值 = 否
此規則是否屬於可執行檔,亦即是否適用於 blaze run 指令。詳情請參閱 規則頁面
output_to_genfiles 預設值 = 否
設為 true 時,系統會在 genfiles 目錄中產生檔案,而非 bin 目錄。除非您需要此標記與現有規則相容 (例如為 C++ 產生標頭檔案時),否則請勿設定這個標記。
fragments sequence of strings; 預設 = []
規則所需設定片段的名稱清單。
host_fragments sequence of strings; 預設 = []
規則在主機設定中需要的設定片段名稱清單。
_skylark_testable 預設值 = 否
(實驗功能)

如果設為 true,這項規則會透過動作供應商,向依附規則的規則顯示檢查動作。提供者也可以呼叫 ctx.created_actions(),以存取規則本身。

這個方法只能用來測試 Starlark 規則的分析時間行為。我們之後可能會移除這個旗標。
toolchains sequence; 預設 = []
如果已設定,則此規則所需的工具鍊組合。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件,任意組合。查看目前的平台以找到工具鍊,並透過 ctx.toolchain 提供給規則實作。
incompatible_use_toolchain_transition 預設值 = 否
已淘汰,因此已停用,應該移除。
doc 預設 = '
可藉由文件產生工具擷取的規則說明。
provides 預設 = []
實作函式必須傳回的提供者清單。

如果實作函式在傳回值中略過此處列出的任何供應者類型,就會發生錯誤。但實作函式可能會傳回這裡未列出的其他供應商。

清單的每個元素都是 provider() 傳回的 *Info 物件,但舊版供應器會改以其字串名稱表示。

exec_compatible_with sequence of strings; 預設 = []
執行平台上的限制清單,適用於該規則類型的所有目標。
analysis_test 預設值 = 否
如果為 true,系統會將這項規則視為分析測試。

注意:分析測試規則主要是使用 Starlark 核心程式庫中的基礎架構定義。詳情請參閱「測試」一節。

如果將規則定義為分析測試規則,則可對其屬性使用透過 analysis_test_transition 定義的設定轉換,但選擇加入一些限制:

  • 這項規則的目標數量受限於可能擁有的遞移依附元件數量。
  • 系統會將這項規則視為測試規則 (就像已設定 test=True 一樣)。這會取代 test 的值
  • 規則實作函式可能無法登錄動作。而是必須透過提供 AnalysisTestResultInfo 註冊通過/失敗結果。
build_setting BuildSetting; or None; 預設值 = 無
如果已設定,請說明這項規則的 build setting 類型。請參閱 config 模組。如果設定了這項政策,就必須使用名為「build_setting_default」的必要屬性會自動加入這項規則,並將與此處傳入的值相對應的類型。
cfg 預設值 = 無
如果已設定,請指向設定轉換效果,規則會在分析前套用至其設定。
exec_groups dict; or None; 預設值 = 無
執行群組名稱 (字串) 變更為 exec_group。如果設定這項功能,規則就能在單一目標內的多個執行平台上執行動作。詳情請參閱執行群組說明文件
compile_one_filetype sequence of strings; or None; 預設值 = 無
由 --compile_one_dependency 構成:如有多項規則使用指定檔案,應優先選擇這項規則。
name string; or None; 預設值 = 無
已淘汰,此參數已淘汰,並將在近期內移除。請勿仰賴這項功能。這項功能已停用 --+incompatible_remove_rule_name_parameter。請使用這個標記確認您的程式碼是否與即將移除的程式碼相容。
已淘汰:不使用。

這項規則的名稱,可由 Bazel 解讀,並回報在記錄、native.existing_rule(...)[kind]bazel query 等環境中。通常和繫結這項規則的 Starlark 識別碼相同;舉例來說,名為 foo_library 的規則通常會宣告為 foo_library = rule(...),並在 BUILD 檔案中例項化為 foo_library(...)

如果省略這個參數,則會將規則名稱設為第一個在宣告 .bzl 模組中要繫結至這項規則的 Starlark 全域變數名稱。因此,如果名稱是 foo_libraryfoo_library = rule(...) 就不需要指定此參數。

指定規則的明確名稱並不會改變您允許規則例項的位置。

選取

unknown select(x, no_match_error='')

select() 是使規則屬性「可設定」的輔助函式。詳情請參閱「建構百科全書」。

參數

參數 說明
x 必要
將設定條件對應至值的 。每個鍵都是用於識別 config_setting 或 constraint_value 執行個體的標籤或標籤字串。如要瞭解使用標籤 (而非字串) 的時機,請參閱巨集說明文件
no_match_error 預設 = '
如果沒有符合條件,要回報的自訂錯誤 (選用)。

single_version_override

None single_version_override(module_name, version='', registry='', patches=[], patch_cmds=[], patch_strip=0)

指定依附元件應仍來自登錄檔,但其版本應固定,或是已覆寫登錄檔,或是套用修補程式清單。這個指令只會在根模組中生效;換句話說,如果模組做為其他依附元件使用模組,系統會忽略本身的覆寫值。

參數

參數 說明
module_name 必要
要套用此覆寫值的 Bazel 模組依附元件名稱。
version 預設 = '
覆寫依附元件圖表中此模組的宣告版本。換句話說,這個模組會「固定」這個覆寫版本如果只想覆寫登錄檔或修補程式,則可省略這項屬性。
registry 預設 = '
覆寫此模組的登錄檔;而非從預設登錄檔清單中找到這個模組,則應使用指定的登錄檔。
patches Iterable of strings; 預設 = []
標籤清單,指向要套用至這個模組的修補程式檔案。修補型檔案必須存在於頂層專案的來源樹狀結構中。這些規則會按照清單順序套用。
patch_cmds Iterable of strings; 預設 = []
套用修補程式後,要套用到 Linux/Macos 的 Bash 指令序列。
patch_strip 預設 = 0
與 Unix 修補程式的 --strip 引數相同。

sorted

list sorted(iterable, *, key=None, reverse=False)

傳回新的排序清單,其中包含提供的可疊代序列的所有元素。如果任何元素 x、y 不能用 x < 進行比較,可能會發生錯誤Y 鍵。除非反向引數為 True,否則元素會按遞增順序排序,在這種情況下,會由遞減順序排列。 排序功能穩定:所比較的元素會保持原始相對順序。
sorted([3, 5, 4]) == [3, 4, 5]

參數

參數 說明
iterable 必要
要排序的可疊代序列。
key 預設值 = 無
在比較前套用至每個元素的選用函式。
reverse 預設值 = 否
依遞減順序傳回結果。

str

string str(x)

將任何物件轉換成字串。很適合用於偵錯。
str("ab") == "ab"
str(8) == "8"

參數

參數 說明
x 必要
要轉換的物件。

tag_class

tag_class tag_class(attrs={}, *, doc='')

建立新的 tag_class 物件,定義標記類別的屬性結構定義,該標記類別是模組擴充功能可使用的資料物件。

參數

參數 說明
attrs default = {}
用來宣告此標記類別所有屬性的字典。它會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。
doc 預設 = '
可透過文件產生工具擷取的標記類別說明。

元組

tuple tuple(x=())

傳回元素與指定的可疊代值具有相同元素的元組。
tuple([1, 2]) == (1, 2)
tuple((2, 3, 2)) == (2, 3, 2)
tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4)

參數

參數 說明
x 預設 = ()
要轉換的物件。

類型

string type(x)

傳回其引數的類型名稱。很適合用於偵錯和類型檢查。範例:
type(2) == "int"
type([1]) == "list"
type(struct(a = 2)) == "struct"
這個函式日後可能會變更。如要編寫與 Python 相容的程式碼,並確保程式碼能因應未來趨勢,請只用來比較回傳值:
if type(x) == type([]):  # if x is a list

參數

參數 說明
x 必要
要檢查類型的物件。

use_extension

module_extension_proxy use_extension(extension_bzl_file, extension_name, *, dev_dependency=False, isolate=False)

傳回代表模組擴充功能的 Proxy 物件。即可叫用 方法,建立模組擴充功能標記。

參數

參數 說明
extension_bzl_file 必要
定義模組副檔名的 Starlark 檔案標籤。
extension_name 必要
要使用的模組擴充功能名稱。具有此名稱的符號必須由 Starlark 檔案匯出。
dev_dependency 預設值 = 否
設為 true 時,如果目前的模組不是根模組,或已啟用 `--ignore_dev_dependency`,系統會忽略這個模組擴充功能的用法。
isolate 預設值 = 否
實驗功能。這項參數仍在實驗階段,隨時可能變更。請勿仰賴這項功能。你可以透過設定 ---experimental_isolated_extension_usages 以實驗性方式啟用該功能
設為 true 時,此模組擴充功能的使用情形將與此模組及其他模組的其他所有用途區隔開來。這麼做的標記不會影響其他用途,而且這項用量的擴充功能產生的存放區會與擴充功能產生的所有其他存放區不同。

這個參數目前處於實驗階段,只能搭配標記 --experimental_isolated_extension_usages 使用。

use_repo

None use_repo(extension_proxy, *args, **kwargs)

將指定模組擴充功能產生的一或多個存放區匯入目前模組的範圍。

參數

參數 說明
extension_proxy 必要
use_extension 呼叫傳回的模組擴充功能 Proxy 物件。
args 必要
要匯入的存放區名稱。
kwargs 必要
使用不同名稱指定要匯入至目前模組範圍的特定存放區。鍵應為在目前範圍中使用的名稱,而值應為模組擴充功能匯出的原始名稱。

顯示設定

None visibility(value)

設定目前初始化 .bzl 模組的載入顯示設定。

模組的載入瀏覽權限可控管其他 BUILD 和 .bzl 檔案是否能夠載入該模組。(這與基礎 .bzl 來源檔案的目標瀏覽權限不同,用於控管該檔案是否顯示為其他目標的依附元件)。載入瀏覽權限僅適用於套件層級:如要載入模組,執行載入作業的檔案必須存放在具備模組瀏覽權限的套件中。無論模組的瀏覽權限為何,模組一律可在其專屬套件中載入。

每個 .bzl 檔案只能呼叫 visibility() 一次,且只能在頂層 (而非函式中) 呼叫。建議的樣式是將此呼叫放在 load() 陳述式下方,以及確定引數所需的任何簡短邏輯下方。

如果 --check_bzl_visibility 旗標設為 false,載入瀏覽權限違規事件時,系統會發出警告,但不會失敗版本。

參數

參數 說明
value 必要
套件規格字串清單,或單一套件規格字串。

套件規格的格式與 package_group 相同,但不允許使用排除套件規格。也就是說,規格可能包含以下格式:

  • "//foo"//foo 套件
  • "//foo/..."//foo 套件及其所有子套件。
  • "public""private":分別顯示所有套件或不含套件

「@」語法;所有規格都會根據目前模組的存放區解譯。

如果 value 是字串清單,授予這個模組瀏覽權限的套件組合,就是每個規格代表的套件聯集。(空白清單的效果與 private 相同)。如果 value 是單一字串,則會將其視為單例模式清單 [value]

請注意,旗標 --incompatible_package_group_has_public_syntax--incompatible_fix_package_group_reporoot_syntax 對這個引數沒有任何影響。"public""private" 值一律可用,"//..." 一律會解讀為「目前存放區中的所有套件」。

工作區

None workspace(name)

這個函式只能用於 WORKSPACE 檔案,且必須在 WORKSPACE 檔案中的所有其他函式之前宣告。每個 WORKSPACE 檔案都應有 workspace 函式。

設定這個工作區的名稱。工作區名稱應為專案的 Java 套件樣式說明,並使用底線做為分隔符,例如 github.com/bazelbuild/bazel 應使用 com_github_bazelbuild_bazel。

這個名稱會用於儲存存放區執行檔案的目錄。舉例來說,如果本機存放區中有執行檔 foo/bar,且 WORKSPACE 檔案包含 workspace(name = 'baz'),則 runfile 會顯示在 mytarget.runfiles/baz/foo/bar 底下。如未指定工作區名稱,runfile 就會連結至 bar.runfiles/foo/bar

遠端存放區規則名稱必須是有效的工作區名稱。舉例來說,您可以讓 maven_jar(name = 'foo') 而非 maven_jar(name = 'foo%bar'),因為 Bazel 會嘗試為包含 workspace(name = 'foo%bar')maven_jar 寫入 WORKSPACE 檔案。

參數

參數 說明
name 必要
工作區名稱名稱只能使用英文字母、數字、底線、破折號和半形句號,而且開頭須為英文字母。

zip

list zip(*args)

傳回 tuplelist,其中 i-th tuple 包含每個引數序列或可疊代項目中的 i-th 元素。這個清單具有最短的輸入值。只要使用一個可疊代引數,就會傳回 1 個元組的清單。如果不使用引數,就會傳回空白清單。範例:
zip()  # == []
zip([1, 2])  # == [(1,), (2,)]
zip([1, 2], [3, 4])  # == [(1, 3), (2, 4)]
zip([1, 2], [3, 4, 5])  # == [(1, 3), (2, 4)]

參數

參數 說明
args 必要
將清單轉換為 ZIP 檔案