全域

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

成員

全部

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 的規則屬性。這類規則的功能受到限制 (例如，依附元件樹狀結構的大小有限)，因此與使用 transition 建立的轉場效果相比，使用這項函式建立的轉場效果潛在範圍有限。

這項函式的主要用途是輔助 Analysis Test Framework 核心程式庫。如需最佳做法，請參閱說明文件 (或實作方式)。

參數

參數 說明
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:// 網址。
integrity default = ''
封存檔案的預期總和檢查碼，以子資源完整性格式表示。
strip_prefix default = ''
從解壓縮的檔案中移除的目錄前置字串。
patches Iterable of strings； 預設值 = []
指向要套用至此模組的修補程式檔案的標籤清單。修補程式檔案必須位於頂層專案的來源樹狀結構中。系統會依清單順序套用規則。
patch_cmds Iterable of strings; default = []
修補程式套用後，要在 Linux/macOS 上套用的 Bash 指令序列。
patch_strip default = 0
與 Unix patch 的 --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
A dictionary declaring all the attributes of the aspect. 它會將屬性名稱對應至屬性物件，例如 `attr.label` 或 `attr.string` (請參閱 attr 模組)。實作函式可將 Aspect 屬性做為 ctx 參數的欄位。

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

明確屬性必須為 string 類型，且必須使用 values 限制。明確屬性會限制只能使用具有相同名稱、類型和有效值的規則，且這些值符合限制條件。

required_providers default = []
This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its 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 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 = []
實作函式必須傳回的供應商清單。

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

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

requires sequence of Aspects； default = []
List of aspects required to be propagated before this aspect.
fragments sequence of strings; default = []
List of names of configuration fragments that the aspect requires in target configuration.
host_fragments sequence of strings; default = []
List of names of configuration fragments that the aspect requires in host configuration.
toolchains sequence; default = []
如果已設定，這項規則需要的一組工具鍊。清單可包含 String、Label 或 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 = []
A list of constraints on the execution platform that apply to all instances of this aspect.
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 必要
要新增為直接依附元件的模組名稱。
version default = ''
要新增為直接依附元件的模組版本。
max_compatibility_level default = -1
模組可新增為直接依附元件，支援的最大 compatibility_level。模組版本代表支援的最低 compatibility_level，如果未指定這項屬性，則代表支援的最高 compatibility_level。
repo_name default = ''
代表這個依附元件的外部存放區名稱。這預設是模組的名稱。
dev_dependency default = False
如果為 true，且目前模組不是根模組或啟用 `--ignore_dev_dependency`，系統就會忽略這項依附元件。

繫結

None bind(name, actual=None)

警告：不建議使用 bind()。如要深入瞭解相關問題和替代方案，請參閱「考慮移除繫結」。

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

參數

參數 說明
name 必要
'//external' 下方的標籤，做為別名
actual string; or None; default = None
The real label to be aliased

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

depset

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

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

deps 集合的所有元素 (直接和間接) 都必須是相同類型，如運算式 type(x) 所取得。

由於系統會在疊代期間使用以雜湊為基礎的集合來排除重複項目，因此 depset 的所有元素都應可雜湊化。不過，目前並非所有建構函式都會持續檢查這項不變量。使用 --incompatible_always_check_depset_elements 標記啟用一致性檢查，這將是未來版本的預設行為；請參閱問題 10313。

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

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

回溯/前向相容性注意事項。這個函式目前接受位置 items 參數。這項功能已淘汰，日後會移除，移除後 direct 將成為 depset 函式的唯一位置參數。因此，下列兩個呼叫方式的效果相同，且可因應未來變化：

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

參數

參數 說明
direct sequence; or None; default = None
A list of direct elements of a depset.
order default = "default"
新 deps 集合的遍歷策略。如要查看可能的值，請參閱這裡。
transitive sequence of depsets; or None; default = None
depsset 清單，其中的元素會成為 depsset 的間接元素。

dict

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

從選用的位置引數和選用的關鍵字引數集建立 dictionary。如果同一個鍵出現多次，系統會使用最後一個值。透過關鍵字引數提供的項目，會視為在透過位置引數提供的項目之後。

參數

參數 說明
pairs default = []
字典，或元素長度皆為 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 default = 0
起始索引。

exec_group

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

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

參數

參數 說明
toolchains sequence; default = []
這個執行群組所需的一組工具鍊。清單可包含 String、Label 或 StarlarkToolchainTypeApi 物件，且可任意組合。
exec_compatible_with sequence of strings; default = []
A list of constraints on the execution platform.
copy_from_rule default = False
如果設為 true，這個執行群組會繼承所屬規則的工具鍊和限制。如果設為任何其他字串，系統會擲回錯誤。

失敗

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

Causes execution to fail with an error.

參數

參數 說明
msg default = None
已淘汰：請改用位置引數。這個引數的作用類似於隱含的前置位置引數。
attr string; or None; default = None
Deprecated. 導致含有這個字串的選用前置字串新增至錯誤訊息。
args 必要
以 debugPrint (預設相當於 str) 格式設定的值清單，並以空格分隔，會顯示在錯誤訊息中。

浮點數

float float(x=unbound)

以浮點值形式傳回 x。
  • 如果 x 已經是浮點數，float 會傳回未變更的值。
  • 如果 x 是布林值，float 會針對 True 傳回 1.0，針對 False 傳回 0.0。
  • 如果 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 必要
struct 屬性的名稱。
default default = unbound
如果結構體沒有指定名稱的屬性，要傳回的預設值。

git_override

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

指定依附元件應來自 Git 存放區的特定提交內容。這項指令只會在根模組中生效；換句話說，如果模組做為其他模組的依附元件，系統會忽略其本身的覆寫。

參數

參數 說明
module_name 必要
要套用這項覆寫的 Bazel 模組依附元件名稱。
remote 必填
遠端 Git 存放區的網址。
commit default = ''
應簽出的提交。
patches Iterable of strings； 預設值 = []
指向要套用至此模組的修補程式檔案的標籤清單。修補程式檔案必須位於頂層專案的來源樹狀結構中。系統會依清單順序套用規則。
patch_cmds Iterable of strings; default = []
修補程式套用後，要在 Linux/macOS 上套用的 Bash 指令序列。
patch_strip default = 0
與 Unix patch 的 --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。
  • 如果 x 已經是 int，int 會傳回未變更的值。
  • 如果 x 是布林值，int 會針對 True 傳回 1，針對 False 傳回 0。
  • 如果 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 之間 (含 2 和 36)，或為 0，以便偵測基底，如同 x 是整數常值。如果值不是字串，請勿提供這項參數。

len

int len(x)

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

參數

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

local_path_override

None local_path_override(module_name, path)

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

參數

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

max

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 default = ''
模組名稱。只有當這個模組是根模組時 (也就是不會依附於其他模組)，才能省略這個屬性。有效的模組名稱必須：1) 只能包含小寫字母 (a-z)、數字 (0-9)、半形句點 (.)、連字號 (-) 和底線 (_)；2) 以小寫字母開頭；3) 以小寫字母或數字結尾。
version default = ''
模組版本。只有當這個模組是根模組時 (也就是不會依附於其他模組)，才能省略這項設定。
compatibility_level default = 0
模組的相容性層級；每當導入不相容的重大變更時，就應變更此值。就 SemVer 而言，這基本上是模組的「主要版本」，但它並非內嵌在版本字串本身，而是以獨立欄位存在。相容性等級不同的模組會參與版本解析，就像是名稱不同的模組一樣，但最終的依附元件圖表不得包含名稱相同但相容性等級不同的多個模組 (除非 multiple_version_override 生效；詳情請參閱該處)。
repo_name default = ''
代表這個模組的存放區名稱，模組本身會看到這個名稱。根據預設，存放區名稱是模組名稱。如果專案使用的存放區名稱與模組名稱不同，可以指定這個屬性，方便遷移。
bazel_compatibility Iterable of strings; default = []
使用者可在此宣告與這個模組相容的 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 必要
實作這個模組擴充功能的函式。必須採用單一參數 module_ctx。建構開始時，系統會呼叫一次函式，判斷可用的 repo 集合。
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 必要
要套用這項覆寫的 Bazel 模組依附元件名稱。
versions Iterable of strings； 必要
明確指定允許共存的版本。這些版本必須已存在於預先選取的依附元件圖表中。這個模組的依附元件會「升級」至相同相容性層級中，最接近的較高允許版本；如果依附元件的版本高於相同相容性層級中的任何允許版本，就會導致錯誤。
registry default = ''
覆寫這個模組的登錄檔；系統不會從預設登錄檔清單中尋找這個模組，而是使用指定的登錄檔。

列印

None print(sep=" ", *args)

以偵錯輸出形式列印 args。開頭會加上 "DEBUG" 字串，以及這個呼叫的位置 (檔案和行號)。引數轉換為字串的確切方式未指定，且隨時可能變更。特別是，這項格式可能與 str() 和 repr() 執行的格式不同 (且更詳細)。

由於 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; default = None
如要限制允許的欄位集，請指定這個參數。
可能的值包括：
  • 欄位清單：
    provider(fields = ['a', 'b'])

  • 字典欄位名稱 -> 說明文件：
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
所有欄位均為選填欄位。
init callable; or None；預設值為 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 必要
如果提供停止值，則為開始元素的值；否則為停止值，實際開始值為 0
stop_or_none int; or None; default = None
要從結果清單中排除的第一個項目 (選用索引)；系統會在達到 stop 之前停止產生清單。
step default = 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 default = False
如果為 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 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; default = None
dictionary to declare all the attributes of the rule. 這個對應關係會從屬性名稱對應至屬性物件 (請參閱 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 = ''
可由文件生成工具擷取的存放區規則說明。

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; default = None
dictionary to declare all the attributes of the rule. 這個對應關係會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。以 _ 開頭的屬性為私有屬性，可用於新增對標籤的隱含依附元件。系統會隱含新增 name 屬性，因此不得指定。系統會隱含新增 visibility、deprecation、tags、testonly 和 features 屬性，且無法覆寫。大多數規則只需要少數屬性。為限制記憶體用量，規則函式會對 attrs 的大小設下上限。
outputs dict; or None; or function; default = None
已淘汰。這項參數已淘汰，並將在近期內移除。因此請勿依賴這項功能。---incompatible_no_rule_outputs_param 可將其停用，請使用這個標記，確認程式碼與即將移除的項目相容。
這個參數已淘汰。請改用 OutputGroupInfo 或 attr.output 遷移規則。

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

這個引數的值可以是字典，也可以是產生字典的回呼函式。回呼的運作方式與計算出的依附屬性類似：函式的參數名稱會與規則的屬性相符，因此舉例來說，如果您傳遞 outputs = _my_func 並定義 def _my_func(srcs, deps): ...，函式就能存取 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 = []
如果已設定，這項規則需要的一組工具鍊。清單可包含 String、Label 或 StarlarkToolchainTypeApi 物件，且可任意組合。系統會檢查目前的平台，並透過 ctx.toolchain 將工具鍊提供給規則實作項目。
incompatible_use_toolchain_transition default = False
已淘汰，不再使用，應移除。
doc default = ''
可由文件生成工具擷取的規則說明。
provides default = []
實作函式必須傳回的供應商清單。

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

清單中的每個元素都是 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. 如果設定此項，規則就能在單一目標內的多個執行平台執行動作。詳情請參閱執行群組說明文件。
compile_one_filetype sequence of strings; or None; default = None
Used by --compile_one_dependency: if multiple rules consume the specified file, should we choose this rule over others.
name string; or None; default = 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 必要
將設定條件對應至值的字典。每個鍵都是 Label 或標籤字串，用於識別 config_setting 或 constraint_value 例項。如要瞭解何時應使用標籤而非字串，請參閱巨集說明文件。
no_match_error default = ''
Optional custom error to report if no condition matches.

single_version_override

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

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

參數

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

已排序

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

傳回新的排序清單，其中包含所提供可疊代序列的所有元素。如果任何一對元素 x、y 無法使用 x < y 比較，可能會發生錯誤。除非 reverse 引數為 True，否則元素會依遞增順序排序，如果是 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 = ''
可由文件生成工具擷取的標記類別說明。

元組

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 必要
要檢查類型的物件。

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 default = False
如果為 true，且目前模組不是根模組或已啟用 `--ignore_dev_dependency`，系統就會忽略這個模組擴充功能的使用情形。
isolate default = False
實驗功能。這項參數仍在實驗階段，因此隨時可能變動。因此請勿依賴這項功能。您可以將 ---experimental_isolated_extension_usages 設為 true，以實驗性質啟用這項功能。如果設為 true，這個模組擴充功能的用法會與這個模組和其他模組的所有其他用法隔離。
為此用途建立的標記不會影響其他用途，且擴充功能為此用途產生的存放區，與擴充功能產生的所有其他存放區不同。

這項參數目前為實驗性質，且僅適用於 --experimental_isolated_extension_usages 旗標。

use_repo

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

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

參數

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

顯示設定

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')，則執行檔會位於 mytarget.runfiles/baz/foo/bar 下方。如果未指定工作區名稱，執行檔會符號連結至 bar.runfiles/foo/bar。

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

參數

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

zip

list zip(*args)

傳回 list 的 tuple，其中第 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 檔案。