全球

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

成員

全部

bool all(elements)

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

參數

參數 說明
elements required
A 字串或元素集合。

analysis_test_transition

transition analysis_test_transition(settings)

建立要套用至分析測試規則依附元件的設定轉換。這個轉場效果只能套用至含有 analysis_test = True 的規則屬性。這類規則的功能受限 (例如，依附元件樹狀結構的大小受限)，因此使用此函式建立的轉場效果，其潛在範圍會受到限制，不像使用 transition 建立的轉場效果。

這個函式主要用於協助分析測試架構核心程式庫。如需最佳做法，請參閱說明文件 (或實作方式)。

參數

參數 說明
settings required
字典，其中包含應透過此設定轉換作業設定的設定資訊。鍵是建構設定標籤，值則是新的轉換後值。所有其他設定都保持不變。用於宣告分析測試必須設定的特定設定，才能通過測試。

不限

bool any(elements)

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

參數

參數 說明
elements required
A 字串或元素集合。

archive_override

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

指定這個依附元件應來自特定位置的封存檔案 (zip、gzip 等)，而不是來自登錄。這項指示僅會在根模組中生效；換句話說，如果模組用於其他依附元件，則系統會忽略其本身的覆寫值。

參數

參數 說明
module_name required
要套用此覆寫值的 Bazel 模組依附元件名稱。
urls string; or Iterable of strings; 必須
封存檔的網址，可以是 http(s):// 或 file:// 網址。
integrity default = ''
封存檔案的預期總和檢查碼，採用子資源完整性格式。
strip_prefix default = ''
要從解壓縮檔案中移除的目錄前置字串。
patches Iterable of strings; default = []
此模組要套用的修補檔案指向標籤清單。修補檔案必須位於頂層專案的來源樹狀結構中。系統會依照清單順序套用這些規則。
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)

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

參數

參數 說明
implementation 必要
Starlark 函式，用於實作此面向，共有兩個參數：Target (要套用面向的目標) 和 ctx (建立目標的規則背景)。您可以透過 ctx.rule 欄位取得目標的屬性。這個函式會在分析階段評估，每次將某個面向套用至目標時都會評估。
attr_aspects sequence of strings; default = []
屬性名稱清單。此面向切面的內容會沿著目標屬性中指定的依附元件 (使用這些名稱) 傳播。常見的值包括 deps 和 exports。清單也可以包含單一字串 "*"，以便沿著目標的所有依附元件傳播。
attrs dict; or None; default = None
宣告各個面向的所有屬性的字典。它會將屬性名稱對應至屬性物件，例如 `attr.label` 或 `attr.string` (請參閱 attr 模組)。實作函式可使用面向實體屬性做為 ctx 參數的欄位。

以 _ 開頭的隱含屬性必須具有預設值，且型別為 label 或 label_list。

明確屬性必須是 string 類型，且必須使用 values 限制。明確屬性會限制相片集合，只允許使用具有相同名稱、類型和有效值的規則。

required_providers default = []
這個屬性可讓切面將傳播範圍限制在規則宣傳必要供應者的目標上。這個值必須是清單，且只能包含個別供應商或供應商清單，不能同時包含這兩者。舉例來說，[[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 default = []
這個屬性可讓這個面向檢查其他面向。這個值必須是清單，且只能包含個別供應商或供應商清單，不能同時包含這兩者。舉例來說，[[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 default = []
implementation 函式必須傳回的供應者清單。

如果實作函式省略傳回值中列出的任何提供者類型，則會發生錯誤。不過，實作函式可能會傳回此處未列出的其他供應工具。

清單中的每個元素都是 provider() 傳回的 *Info 物件，但舊版提供者則以其字串名稱表示。
requires sequence of Aspects; default = []
必須在這個面向前傳播的面向清單。
fragments sequence of strings; default = []
列出目標設定中所需的面向所需設定片段名稱。
host_fragments sequence of strings; default = []
主機設定中，此面向項目所需的設定片段名稱清單。
toolchains sequence; default = []
如果已設定，則為此規則所需的工具鍊集。清單可包含字串、標籤或 StarlarkToolchainTypeApi 物件，且可任意組合。系統會檢查目前的平台，並透過 ctx.toolchain 將工具鍊提供給規則實作。
incompatible_use_toolchain_transition default = False
已淘汰，不再使用，應予以移除。
doc default = ''
說明說明文件產生工具可擷取的層面。
apply_to_generating_rules default = False
如果為 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; default = []
執行平台的限制清單，適用於此面向的所有執行個體。
exec_groups dict; or None; default = None
Dict of execution group name (string) to exec_groups. 如果已設定，則可讓元件在單一例項中執行多個執行平台的動作。詳情請參閱執行群組說明文件。

bazel_dep

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

宣告對其他 Bazel 模組的直接依附元件。

參數

參數 說明
name required
要新增為直接依附元件的模組名稱。
version default = ''
要新增為直接依附元件的模組版本。
max_compatibility_level default = -1
如果要將模組新增為直接依附元件，則支援的最大 compatibility_level 為 模組的版本會暗示支援的最低相容性層級，以及未指定此屬性時的最高相容性層級。
repo_name default = ''
代表此依附元件的外部存放區名稱。預設為模組名稱。
dev_dependency default = False
如果為 true，當目前模組不是根模組，或已啟用 `--ignore_dev_dependency` 時，系統會忽略此依附元件。

繫結

None bind(name, actual=None)

警告：不建議使用 bind()。請參閱「考慮移除 bind」，進一步瞭解相關問題和替代方案。

在 //external 套件中為目標指定別名。

參數

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

bool

bool bool(x=False)

bool 類型的建構函式。如果物件為 None、False、空字串 ("")、數字 0 或空集合 (例如 ()、[])，則會傳回 False。否則，會傳回 True。

參數

參數 說明
x default = False
要轉換的變數。

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 required
包含延遲繫結值的設定片段名稱。
name required
From the configuration fragment, the name of the value to obtain.

depset

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

建立 depset。direct 參數是 depset 的直接元素清單，而 transitive 參數則是 depset 的清單，其中元素會成為所建立 depset 的間接元素。order 參數會指定將 depset 轉換為清單時，元素的傳回順序。詳情請參閱「Depset 總覽」。

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

由於以雜湊為基礎的集合會在疊代期間用於消除重複項目，因此 depset 的所有元素都應可雜湊。不過，目前並未在所有建構函式中一致檢查此不變量。使用 --incompatible_always_check_depset_elements 標記啟用一致檢查功能，這將成為日後版本的預設行為；請參閱 Issue 10313。

此外，元素目前必須是不可變動的，但這項限制日後會放寬。

建立的 depset 順序應與其 transitive depset 順序相容。"default" 順序與任何其他順序相容，所有其他順序只與自身相容。

回溯/前向相容性的注意事項。這個函式目前接受位置 items 參數。該參數已淘汰，並將在日後移除。移除後，direct 將成為 depset 函式的唯一位置參數。因此，以下兩個呼叫都具有相同效果，且可因應未來需求：

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

參數

參數 說明
direct sequence; or None; default = None
depset 的直接元素清單。
order default = "default"
新 depset 的檢索策略。如要查看可能的值，請參閱這裡。
transitive sequence of depsets; or None; default = None
depset 清單，其中元素會成為 depset 的間接元素。

dict

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

根據選用的位置引數和選用關鍵字引數集合，建立字典。如果同一個鍵重複提供多次，系統會使用最後一個值。系統會將透過關鍵字引數提供的項目視為透過位置引數提供的項目之後。

參數

參數 說明
pairs default = []
Dict 或可列舉項目，其元素長度均為 2 (鍵、值)。
kwargs required
Additional 字典項目。

dir

list dir(x)

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

參數

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

列舉

list enumerate(list, start=0)

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

參數

參數 說明
list 必須
輸入序列。
start 預設值 = 0
start index。

exec_group

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

建立執行群組，可用於在規則導入期間為特定執行平台建立動作。

參數

參數 說明
toolchains sequence; default = []
This execution group 所需的工具鍊組合。清單可包含字串、標籤或 StarlarkToolchainTypeApi 物件，且可任意組合。
exec_compatible_with sequence of strings; default = []
執行平台的限制條件清單。
copy_from_rule default = False
如果設為 true，這個執行群組就會繼承這個群組所附加的規則的工具鍊和限制。如果設為任何其他字串，則會擲回錯誤。

失敗

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

導致執行作業失敗，並顯示錯誤訊息。

參數

參數 說明
msg default = None
已淘汰：請改用位置引數。這個引數會像隱含的領先位置引數一樣運作。
attr string; or None; 預設值 = 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 是字串，則必須是有效的浮點常值，或等於 (忽略大小寫) NaN、Inf 或 Infinity，並可選擇在前方加上 + 或 - 符號。
任何其他值都會導致錯誤。如果沒有引數，float() 會傳回 0.0。

參數

參數 說明
x default = unbound
要轉換的值。

getattr

unknown getattr(x, name, default=unbound)

傳回指定名稱的結構體欄位 (如有)。如未指定，則會傳回 default (如果已指定) 或擲回錯誤。getattr(x, "foobar") 相當於 x.foobar。
getattr(ctx.attr, "myattr")
getattr(ctx.attr, "myattr", "mydefault")

參數

參數 說明
x required
屬性存取的結構體。
name required
struct 屬性的名稱。
default default = unbound
如果結構體沒有指定名稱的屬性，則會傳回這個預設值。

git_override

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

指定依附元件應來自 Git 存放區的特定修訂版本。這項指示僅會在根模組中生效；換句話說，如果模組用於其他依附元件，則系統會忽略其本身的覆寫值。

參數

參數 說明
module_name required
要套用此覆寫值的 Bazel 模組依附元件名稱。
remote required
Git 遠端存放區的網址。
commit default = ''
應簽出的提交。
patches Iterable of strings; default = []
此模組要套用的修補檔案指向標籤清單。修補檔案必須位於頂層專案的來源樹狀結構中。系統會依照清單順序套用這些規則。
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 required
屬性名稱。

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)

以 int 值的形式傳回 x。
  • 如果 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 default = unbound
用於解讀字串值的底數，預設為 10。必須介於 2 和 36 (含) 之間，或設為 0 以便偵測 x 是否為整數運算式。如果值不是字串，則不得提供此參數。

len

int len(x)

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

參數

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

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 default = []
要轉換的物件。

local_path_override

None local_path_override(module_name, path)

指定依附元件應來自本機磁碟上的特定目錄。這項指示僅會在根模組中生效；換句話說，如果模組用於其他依附元件，則系統會忽略其本身的覆寫值。

參數

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

最高

unknown max(*args)

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

參數

參數 說明
args required
The elements to be checked.

分鐘

unknown min(*args)

傳回所有指定引數中最小的一個。如果只提供一個引數，則該引數必須為非空的可枚舉項目。如果元素無法比較 (例如整數與字串)，或是未提供引數，就會發生錯誤。 
min(2, 5, 4) == 2
min([5, 6, 3]) == 3

參數

參數 說明
args required
The elements to be checked.

module

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

宣告目前 Bazel 存放區所代表的 Bazel 模組的特定屬性。這些屬性是模組的重要中繼資料 (例如名稱和版本)，或是會影響目前模組及其依附元件的行為。

最多只能呼叫一次。只有在這個模組是根模組 (也就是不會受到其他模組依附) 時，才能省略這個屬性。

參數

參數 說明
name default = ''
The name of the module. 只有在這個模組是根模組 (也就是不會受到其他模組依附) 時，才能省略。有效的模組名稱必須符合以下條件：1) 只能包含小寫英文字母 (a-z)、數字 (0-9)、半形句號 (.)、連字號 (-) 和底線 (_)；2) 開頭須為小寫英文字母；3) 結尾須為小寫英文字母或數字。
version default = ''
The version of the module. 只有在這個模組是根模組 (也就是不會受到其他模組依附) 時，才能省略。
compatibility_level default = 0
The compatibility level of the module; this should be changed every time a major incompatible change is introduced. 就 SemVer 而言，這基本上是模組的「主要版本」，但它並未嵌入版本字串本身，而是以獨立欄位的形式存在。具有不同相容性等級的模組會參與版本解析，就好像是名稱不同的模組一樣，但最終依附元件圖表不得包含多個名稱相同但相容性等級不同的模組 (除非 multiple_version_override 生效，詳情請參閱該頁面)。
repo_name default = ''
代表此模組的存放區名稱，由模組本身顯示。根據預設，存放區名稱會是模組名稱。您可以指定此值，以便為使用與模組名稱不同的專案名稱遷移作業提供便利。
bazel_compatibility Iterable of strings; default = []
Bazel 版本清單，可讓使用者宣告哪些 Bazel 版本與此模組相容。這不會影響相依項目解析，但 bzlmod 會使用這項資訊，檢查目前的 Bazel 版本是否相容。這個值的格式為以半形逗號分隔的限制值字串。支援三個限制：<=X.X.X：Bazel 版本必須等於或舊於 X.X.X。如果新版本有已知的不相容變更，就會使用這個限制。>=X.X.X：Bazel 版本必須等於或大於 X.X.X。如果您需要使用 X.X.X 之後才推出的某些功能，請使用這個選項。-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 required
實作此模組擴充功能的函式。必須採用單一參數 module_ctx。系統會在建構作業開始時呼叫這個函式一次，以判斷可用的套件集。
tag_classes default = {}
用來宣告擴充功能所使用的所有標記類別的字典。它會將標記類別名稱對應至 tag_class 物件。
doc default = ''
說明模組擴充功能，可由說明文件產生工具擷取。
environ sequence of strings; default = []
提供此模組擴充功能依附的環境變數清單。如果清單中的環境變數有所變更，擴充功能就會重新評估。
os_dependent default = False
指出這個擴充功能是否依賴作業系統
arch_dependent default = False
指出此擴充功能是否與架構相關

multiple_version_override

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

指定依附元件仍應來自登錄，但應允許多個版本並存。詳情請參閱說明文件。這項指示僅會在根模組中生效；換句話說，如果模組用於其他依附元件，則系統會忽略其本身的覆寫值。

參數

參數 說明
module_name required
要套用此覆寫值的 Bazel 模組依附元件名稱。
versions Iterable of strings; required
明確指定允許共存的版本。這些版本必須已在依附元件圖表預先選取項目中。這個模組的依附元件會「升級」至相容性層級中允許的最近較高版本，但如果依附元件的版本高於同層級中允許的任何版本，就會導致錯誤。
registry default = ''
覆寫此模組的註冊表；應使用指定的註冊表，而非從預設的註冊表清單中尋找此模組。

列印

None print(sep=" ", *args)

將 args 列印為偵錯輸出內容。前置字串為 "DEBUG"，後面接著呼叫的位置 (檔案和行號)。不過，我們並未指定將引數轉換為字串的確切方式，且這項方式隨時可能會變更。特別是，這可能與 str() 和 repr() 所執行的格式不同 (且更詳細)。

由於 print 會為使用者產生垃圾內容，因此不建議在正式版程式碼中使用 print。針對淘汰項目，請盡可能使用 fail() 產生嚴重錯誤。

參數

參數 說明
sep default = " "
物件之間的分隔符字串，預設為空格 (" ")。
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 default = ''
提供者說明，可由說明文件產生工具擷取。
fields sequence of strings; or dict; or None; 預設值 = None
如果指定此屬性，則會限制允許的欄位組合。
可能的值包括：
  • 欄位清單：
    provider(fields = ['a', 'b'])

  • 字典欄位名稱 -> 說明文件：
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
所有欄位均為選填欄位。
init callable; or None; default = None
在例項化期間，用於預先處理及驗證提供者欄位值的可選回呼。如果指定 init，provider() 會傳回 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 == 1 的 MyInfo 例項。

但如果指定 init，呼叫 P(*args, **kwargs) 會改為執行下列步驟：

  1. 回呼會以 init(*args, **kwargs) 的形式叫用，也就是使用與傳遞至 P 時完全相同的位置和關鍵字引數。
  2. init 的傳回值應為字典 d，其鍵為欄位名稱字串。否則會發生錯誤。
  3. 系統會產生新的 P 例項，就像呼叫預設建構函式，並將 d 的項目做為關鍵字引數，如 c(**d) 所示。

注意：上述步驟表示如果 *args 或 **kwargs 不符合 init 的簽章，或是 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)

使用 step 遞增值，建立從 start 到 stop 的項目清單。如果提供單一引數，項目範圍會從 0 到該元素。
range(4) == [0, 1, 2, 3]
range(3, 9, 2) == [3, 5, 7]
range(3, 0, -1) == [3, 2, 1]

參數

參數 說明
start_or_stop required
如果提供 stop，則為 start 元素的值；否則，stop 和實際開始值的值為 0
stop_or_none int; or None; default = None
optional index of the first item not to be included in the resulting list; generation of the list stops before stop is reached.
step default = 1
增量值 (預設為 1)。可能為負值。

register_execution_platforms()

None register_execution_platforms(*platform_labels)

註冊已定義的平台，以便 Bazel 在工具鍊解析期間將其用作執行平台。

參數

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

register_execution_platforms(dev_dependency)

None register_execution_platforms(dev_dependency=False, *platform_labels)

指定在選取這個模組時要註冊的已定義執行平台。應為絕對目標模式 (即以 @ 或 // 開頭)。詳情請參閱工具鍊解析。

參數

參數 說明
dev_dependency default = False
如果為 true，如果目前的模組不是根模組，或是已啟用 `--ignore_dev_dependency`，則不會註冊執行平台。
platform_labels sequence of strings; required
要註冊的平台標籤。

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 default = False
如果為 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; 預設值 = None
Dictionary 用來宣告規則的所有屬性。它會將屬性名稱對應至屬性物件 (請參閱 attr 模組)。開頭為 _ 的屬性為私有，可用於在檔案中新增對標籤的隱含依附元件 (存放區規則無法依附產生的構件)。系統會隱含新增屬性 name，因此不必指定。
local default = False
表示這項規則會從本機系統擷取所有內容，並應在每次擷取時重新評估。
environ sequence of strings; default = []
提供此存放區規則依附的環境變數清單。如果清單中的環境變數發生變更，系統會重新擷取存放區。
configure default = False
表示儲存庫會檢查系統以供設定用途
remotable default = False
實驗。這個參數仍在實驗階段，可能隨時變更。請勿依賴這項功能。您可以設定 ---experimental_repo_remote_exec
Compatible with remote execution，以實驗方式啟用這項功能。
doc default = ''
repository 規則的說明，可由說明文件產生工具擷取。

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 default = False
是否為測試規則，也就是是否可以是 blaze test 指令的主體。系統會自動將所有測試規則視為可執行；因此，不必 (且不建議) 為測試規則明確設定 executable = True。詳情請參閱「 規則」頁面。
attrs dict; or None; 預設值 = None
Dictionary 用來宣告規則的所有屬性。它會將屬性名稱對應至屬性物件 (請參閱 attr 模組)。以 _ 開頭的屬性為私有，可用於在標籤上新增隱含的依附元件。系統會隱含新增 name 屬性，因此您不必指定。系統會隱含新增 visibility、deprecation、tags、testonly 和 features 屬性，且無法覆寫。大多數規則只需要少數屬性。為限制記憶體用量，規則函式會對屬性大小設下上限。
outputs dict; or None; or function; 預設值 = None
已淘汰。這個參數已淘汰，並將在近期內移除。請勿依賴這項功能。---incompatible_no_rule_outputs_param 會停用。使用這個標記，確認您的程式碼與即將移除的標記相容。
這個參數已淘汰。請將規則遷移為改用 OutputGroupInfo 或 attr.output。

用於定義預先宣告輸出的結構定義。與 output 和 output_list 屬性不同，使用者不會為這些檔案指定標籤。如要進一步瞭解預先宣告的輸出內容，請參閱「規則」頁面。

這個引數的值是字典，或是產生字典的回呼函式。回呼的運作方式與計算依附元件屬性類似：函式的參數名稱會與規則的屬性進行比對，因此如果您使用定義 def _my_func(srcs, deps): ... 傳遞 outputs = _my_func，函式就能存取 srcs 和 deps 屬性。無論字典是直接指定或透過函式指定，都會依下列方式解讀。

字典中的每個項目都會建立預先宣告的輸出內容，其中索引鍵是 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，basename 為 b.c。

實際上，最常見的替換預留位置是 "%{name}"。舉例來說，如果目標名稱為「foo」，輸出字典 {"bin": "%{name}.exe"} 會預先宣告名為 foo.exe 的輸出項目，在實作函式中可透過 ctx.outputs.bin 存取。
executable default = False
是否將此規則視為可執行，也就是是否可做為 blaze run 指令的主體。詳情請參閱「 規則」頁面。
output_to_genfiles default = False
如果為 true，檔案會在 genfiles 目錄中產生，而非 bin 目錄。除非您需要為現有規則提供相容性 (例如產生 C++ 標頭檔案時)，否則請勿設定此標記。
fragments sequence of strings; default = []
規則在目標設定中需要的設定片段名稱清單。
host_fragments sequence of strings; default = []
主機設定中規則所需的設定片段名稱清單。
_skylark_testable default = False
(實驗功能)

如果為 true，則這項規則會透過 Actions 供應器，將其動作公開供依附此規則的規則檢查。您也可以透過呼叫 ctx.created_actions()，讓規則本身使用提供者。

這項功能僅應用於測試 Starlark 規則的分析時間行為。這個標記日後可能會移除。
toolchains sequence; default = []
如果已設定，則為此規則所需的工具鍊集。清單可包含字串、標籤或 StarlarkToolchainTypeApi 物件，且可任意組合。系統會檢查目前的平台，並透過 ctx.toolchain 將工具鍊提供給規則實作。
incompatible_use_toolchain_transition default = False
已淘汰，不再使用，應予以移除。
doc default = ''
說明規則，可供說明文件產生工具擷取。
provides default = []
implementation 函式必須傳回的供應者清單。

如果實作函式省略傳回值中列出的任何提供者類型，則會發生錯誤。不過，實作函式可能會傳回此處未列出的其他供應工具。

清單中的每個元素都是 provider() 傳回的 *Info 物件，但舊版提供者則以其字串名稱表示。
exec_compatible_with sequence of strings; default = []
執行平台的限制清單，適用於此規則類型的所有目標。
analysis_test default = False
如果為 true，則系統會將此規則視為分析測試。

注意：分析測試規則主要使用核心 Starlark 程式庫提供的基礎架構定義。如需相關指南，請參閱「測試」一節。

如果規則定義為分析測試規則，則可使用在屬性中使用 analysis_test_transition 定義的設定轉換，但會採用下列限制：

  • 這個規則的目標可能會有的間接相依項目數量有限。
  • 系統會將該規則視為測試規則 (就像設定 test=True 一樣)。這會取代 test 的值
  • 規則實作函式可能不會註冊動作。而是必須透過提供 AnalysisTestResultInfo 註冊通過/失敗結果。
build_setting BuildSetting; or None; default = None
如果已設定，則會說明這項規則是哪種類型的 build setting。請參閱 config 模組。如果設定此值，系統會自動將名為「build_setting_default」的必要屬性新增至此規則，類型則會對應至此處傳入的值。
cfg default = None
如果已設定，則會指向規則在分析前套用至自身設定的設定轉換。
exec_groups dict; or None; default = None
Dict of execution group name (string) to exec_groups. 如果設為 true，規則就能在單一目標內的多個執行平台上執行動作。詳情請參閱執行群組說明文件。
compile_one_filetype sequence of strings; or None; 預設值 = None
--compile_one_dependency 會使用：如果有多個規則會使用指定的檔案，我們應選擇這個規則而非其他規則。
name string; or None; 預設值 = None
已淘汰。這個參數已淘汰，並將在近期內移除。請勿依賴這項功能。--+incompatible_remove_rule_name_parameter 會停用。使用這個標記，確認您的程式碼與即將移除的標記相容。
已淘汰：請勿使用。

這個規則的名稱，Bazel 會瞭解這個名稱，並在記錄、native.existing_rule(...)[kind] 和 bazel query 等情境中回報。通常，這個值會與與此規則繫結的 Starlark 識別碼相同；舉例來說，名為 foo_library 的規則通常會宣告為 foo_library = rule(...)，並在 BUILD 檔案中以 foo_library(...) 的形式例項化。

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

為規則指定明確的名稱，並不會變更可對規則進行例項化的情況。

選取

unknown select(x, no_match_error='')

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

參數

參數 說明
x required
Dict，可將設定條件對應至值。每個鍵都是 標籤或標籤字串，用於識別 config_setting 或 constraint_value 例項。如要瞭解何時應使用標籤而非字串，請參閱 巨集說明文件。
no_match_error default = ''
如果沒有相符的條件，可選擇回報自訂錯誤。

single_version_override

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

指定依附元件仍應來自登錄，但應將其版本固定，或覆寫其登錄，或套用修補程式清單。這項指示僅會在根模組中生效；換句話說，如果模組用於其他依附元件，則系統會忽略其本身的覆寫值。

參數

參數 說明
module_name required
要套用此覆寫值的 Bazel 模組依附元件名稱。
version default = ''
覆寫依附元件圖表中此模組的宣告版本。換句話說，這個模組會「固定」至這個覆寫版本。如果您只想覆寫註冊表或修補程式，可以省略這個屬性。
registry default = ''
覆寫此模組的註冊表；應使用指定的註冊表，而非從預設的註冊表清單中尋找此模組。
patches Iterable of strings; default = []
此模組要套用的修補檔案指向標籤清單。修補檔案必須位於頂層專案的來源樹狀結構中。系統會依照清單順序套用這些規則。
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 default = None
在比較前套用至每個元素的選用函式。
reverse default = False
以遞減順序傳回結果。

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 default = ''
tag 類別的說明，可由說明文件產生工具擷取。

元組

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 default = ()
要轉換的物件。

類型

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 required
The object to check type of.

use_extension

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

傳回代表模組擴充功能的 Proxy 物件，可呼叫其方法來建立模組擴充功能標記。

參數

參數 說明
extension_bzl_file required
Starlark 檔案的標籤，用於定義模組擴充功能。
extension_name 必要
要使用的模組擴充功能名稱。Starlark 檔案必須匯出這個名稱的符號。
dev_dependency default = False
如果為 true，如果目前的模組不是根模組，或是已啟用 `--ignore_dev_dependency`，系統就會忽略此模組擴充功能的使用方式。
isolate default = False
實驗。這個參數仍在實驗階段，可能隨時變更。請勿依賴這項功能。您可以設定 ---experimental_isolated_extension_usages
，以實驗方式啟用此功能。如果設為 true，則模組擴充功能的這項用法將與此模組和其他模組中的所有其他用法隔離。為此用途建立的代碼不會影響其他用途，而擴充功能為此用途產生的存放區，也會與擴充功能產生的其他存放區有所區別。

這個參數目前為實驗功能，且僅適用於 --experimental_isolated_extension_usages 旗標。

use_repo

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

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

參數

參數 說明
extension_proxy 必要
「use_extension」呼叫傳回的模組擴充功能 Proxy 物件。
args 必填
The names of the repos to import.
kwargs required
Specifies certain repos to import into the scope of the current module with different names. 鍵應為在目前範圍中使用的名稱，而值應為模組擴充功能匯出的原始名稱。

顯示設定

None visibility(value)

設定目前正在初始化的 .bzl 模組的載入可見度。

模組的載入可見度會決定其他 BUILD 和 .bzl 檔案是否可以載入該模組。(這與底層 .bzl 來源檔案的目標可見度不同，後者會決定檔案是否會顯示為其他目標的依附元件)。載入可見度會在套件層級運作：如要載入模組，進行載入的檔案必須位於已授予模組可見度的套件中。無論可見性為何，模組一律會在其自身套件中載入。

每個 .bzl 檔案只能呼叫 visibility() 一次，且只能在頂層呼叫，而非在函式內呼叫。建議的樣式是將這個呼叫放在 load() 陳述式和任何用於判斷引數的簡短邏輯下方。

如果標記 --check_bzl_visibility 設為 false，載入可見度違規會發出警告，但不會導致建構失敗。

參數

參數 說明
value 必要
package_specification_strings 清單或單一 package_specification_string。

套件規格採用與 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')，則 mytarget.runfiles/baz/foo/bar 下會提供執行檔。如果未指定工作區名稱，則執行檔會建立至 bar.runfiles/foo/bar 的符號連結。

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

參數

參數 說明
name 必填
workspace 名稱。名稱開頭須為英文字母，而且只能使用英文字母、數字、底線、連字號和點。

zip

list zip(*args)

傳回 tuple 的 list，其中第 i 個元組包含各個引數序列或可枚舉項目的第 i 個元素。清單的大小與最短輸入內容相同。使用單一可枚舉引數時，會傳回 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 檔案。