.bzl 檔案

回報問題 夜間 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

所有 .bzl 檔案中都有全域方法。

成員

analysis_test_transition

transition analysis_test_transition(settings)

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

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

參數

參數 說明
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=[])

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

參數

參數 說明
implementation 必要
實作這個層面的 Starlark 函式，且只有兩個參數：Target (套用層面的目標) 和 ctx (目標建立依據的規則環境)。目標的屬性可透過 ctx.rule 欄位取得。在將某個層面套用至目標的分析階段，系統會評估這個函式。
attr_aspects sequence of strings; default is []
List of attribute names. 這個層面會沿著目標屬性中指定的依附元件傳播，常見的值包括 deps 和 exports。清單也可以包含單一字串 "*"，沿著目標的所有依附元件傳播。
attrs dict； 預設值為 {}
這個字典會宣告層面的所有屬性。這會將屬性名稱對應至屬性物件，例如 `attr.label` 或 `attr.string` (請參閱 attr 模組)。實作函式可將 Aspect 屬性做為 ctx 參數的欄位。

以 _ 開頭的隱含屬性必須有預設值，且類型為 label 或 label_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 物件，但舊版供應商會以字串名稱表示。如果規則的目標做為宣告必要供應商的目標的依附元件，則不必在此指定該供應商。實作函式傳回該值即可。不過，即使這並非必要，我們仍建議您指定這項屬性。不過，方面的 required_providers 欄位確實需要在此指定供應商。

requires sequence of Aspects; default is []
List of aspects required to be propagated before this aspect.
fragments 字串序列； 預設為 []
目標設定中，構面所需的設定片段名稱清單。
host_fragments 字串的序列； 預設為 []
這個層面在主機設定中需要的設定片段名稱清單。
toolchains sequence； 預設為 []
如果已設定，這項規則需要的一組工具鍊。清單可包含 String、Label 或 StarlarkToolchainTypeApi 物件，且可任意組合。系統會檢查目前的平台，找出工具鍊，並透過 ctx.toolchain 提供給規則實作項目。
incompatible_use_toolchain_transition 預設值為 False
已淘汰，不再使用，應移除。
doc 字串；或 None; 預設為 None
可由文件生成工具擷取的層面說明。
apply_to_generating_rules 預設值為 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 字串的序列； 預設為 []
適用於這個層面所有例項的執行平台限制清單。
exec_groups dict 或 None； 預設為 None
執行群組名稱 (字串) 的 Dict，對應至 exec_groups。如果已設定，可讓構面在單一例項內，對多個執行平台執行動作。詳情請參閱執行群組說明文件。
subrules 子規則的序列； 預設為 []
實驗：這個層面使用的子規則清單。

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 的間接元素。將 depset 轉換為清單時，傳回元素的順序是由 order 參數指定。詳情請參閱「Depsets 總覽」。

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

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

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

建立的 depsets 順序應與 transitive depsets 的順序相容。"default" 訂單可與任何其他訂單合併，其他訂單則只能與自身合併。

參數

參數 說明
direct 序列；或 None； 預設為 None
deps 集合的直接元素清單。
order 預設值為 "default"
新 deps 集合的遍歷策略。如要查看可能的值，請參閱這裡。
transitive depset 的 sequence；或 None。 預設為 None
元素會成為 depset 間接元素的 depset 清單。

exec_group

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

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

參數

參數 說明
toolchains sequence; default is []
This execution group requires this set of toolchains. 清單可包含 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 字串；或 None; 預設為 None
模組擴充功能的說明，可由文件產生工具擷取。
environ sequence of strings; default is []
Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated.
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 字串的序列；或 dict；或 None； 預設為 None
如果指定，則會限制允許的欄位集。
可能的值包括：
  • 欄位清單：
    provider(fields = ['a', 'b'])

  • 字典欄位名稱 -> 說明文件：
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
所有欄位均為選填。
init 可呼叫；或 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 = ...)

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 字串的序列； 預設為 []
已淘汰。此參數已淘汰。請改用 repository_ctx.getenv。
提供這個存放區規則依附的環境變數清單。如果該清單中的環境變數有所變更，系統會重新擷取存放區。
configure 預設為 False
指出存放區會檢查系統是否用於設定
remotable 預設值為 False
Experimental。這項參數仍在實驗階段，因此隨時可能變動。因此請勿依賴這項功能。您可以設定 ---experimental_repo_remote_exec
Compatible with remote execution
doc 字串；或 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; default is unbound
Whether this rule is a test rule, that is, whether it may be the subject of a blaze test command. 所有測試規則都會自動視為可執行，因此不必 (也不建議) 為測試規則明確設定 executable = True。預設值為 False。詳情請參閱 規則頁面。
attrs dict； 預設為 {}
字典，用於宣告規則的所有屬性。這個對應會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。以 _ 開頭的屬性為私有屬性，可用於新增標籤的隱含依附元件。系統會隱含新增 name 屬性，因此不得指定。系統會隱含新增 visibility、deprecation、tags、testonly 和 features 屬性，且無法覆寫。大多數規則只需要少數屬性。為限制記憶體用量，規則函式會對 attrs 的大小設下上限。
outputs dict；或 None；或 function； 預設為 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 bool; default is unbound
Whether this rule is considered executable, that is, whether it may be the subject of a blaze run command. 預設值為 False。詳情請參閱 規則頁面。
output_to_genfiles 預設為 False
如果為 true，系統會在 genfiles 目錄中產生檔案，而非 bin 目錄。除非您需要此標記來與現有規則相容 (例如為 C++ 產生標頭檔時)，否則請勿設定此標記。
fragments 字串的序列； 預設為 []
規則在目標設定中需要的設定片段名稱清單。
host_fragments 字串的序列； 預設為 []
主機設定中規則所需的設定片段名稱清單。
_skylark_testable 預設值為 False
(實驗功能)

如果為 true，這項規則會透過 Actions 提供者公開其動作，供依附於該規則的規則檢查。呼叫 ctx.created_actions() 時，規則本身也會提供這個供應器。

這項功能僅適用於測試 Starlark 規則的分析時間行為。這項標記日後可能會移除。
toolchains sequence； 預設為 []
如果已設定，這項規則需要的一組工具鍊。清單可包含 String、Label 或 StarlarkToolchainTypeApi 物件，且可任意組合。系統會檢查目前的平台，找出工具鍊，並透過 ctx.toolchain 提供給規則實作項目。
incompatible_use_toolchain_transition 預設值為 False
已淘汰，不再使用，應移除。
doc 字串；或 None; 預設值為 None
可由文件產生工具擷取的規則說明。
provides 預設值為 []
實作函式必須傳回的供應商清單。

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

清單中的每個元素都是 provider() 傳回的 *Info 物件，但舊版供應商會以字串名稱表示。如果規則的目標做為宣告必要供應商的目標的依附元件，則不必在此指定該供應商。實作函式傳回該值即可。不過，即使這並非必要，我們仍建議您指定這項屬性。不過，方面的 required_providers 欄位確實需要在此指定供應商。

exec_compatible_with 字串的序列； 預設為 []
執行平台限制清單，適用於這個規則類型的所有目標。
analysis_test 預設值為 False
如果為 true，則這項規則會視為分析測試。

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

如果規則定義為分析測試規則，即可在其屬性上使用 analysis_test_transition 定義的設定轉換，但會受到一些限制：

  • 這項規則的目標可擁有的遞移依附元件數量有限。
  • 這項規則會視為測試規則 (如同設定 test=True)。這會取代 test 的值
  • 規則實作函式可能不會註冊動作。而是必須透過提供 AnalysisTestResultInfo 註冊通過/失敗結果。
build_setting BuildSetting；或 None； 預設為 None
如果已設定，則說明這項規則的 build setting 類型。請參閱 config 模組。如果設定此值，系統會自動將名為「build_setting_default」的必要屬性新增至這項規則，並根據這裡傳遞的值設定對應類型。
cfg 預設值為 None
如果已設定，則指向規則將套用至自身設定的設定轉換 (分析前)。
exec_groups dict 或 None； 預設為 None
執行群組名稱 (字串) 的 Dict，對應至 exec_groups。如果設定此項，規則就能在單一目標內的多個執行平台執行動作。詳情請參閱執行群組說明文件。
initializer 預設值為 None
實驗功能：初始化規則屬性的 Stalark 函式。

系統會在載入規則的每個執行個體時呼叫函式。系統會使用 name 和規則定義的公開屬性值 (而非一般屬性，例如 tags) 呼叫這個函式。

這個函式必須傳回從屬性名稱到所需值的字典。未傳回的屬性不受影響。如果傳回 None 做為值，系統會使用屬性定義中指定的預設值。

系統會先評估初始值，再評估屬性定義中指定的預設值。因此，如果初始化程式簽章中的參數包含預設值，系統會覆寫屬性定義中的預設值 (傳回 None 的情況除外)。

同樣地，如果初始值設定工具簽章中的參數沒有預設值，該參數就會變成必要參數。在這種情況下，建議您省略屬性定義中的預設/必要設定。

對於未處理的屬性，建議使用 **kwargs。

如果是擴充規則，系統會從子項到祖先呼叫所有初始值設定器。每個初始設定程式只會傳遞它所知的公開屬性。

parent 預設值為 None
實驗功能：要擴充的 Stalark 規則。設定後，系統會合併公開屬性和宣傳的供應商。規則會比對父項的 executable 和 test。系統會合併 fragments、toolchains、exec_compatible_with 和 exec_groups 的值。您可能無法設定舊版或已淘汰的參數。系統會在套用這項規則的傳入設定後，套用上層的傳入設定轉換 cfg。
extendable bool；或 Label；或 string；或 None； 預設值為 None
實驗功能：許可清單的標籤，用於定義可擴充這項規則的規則。您也可以將這項政策設為 True/False，一律允許/禁止延長期限。Bazel 預設一律允許擴充功能。
subrules sequence of Subrules; default is []
Experimental: List of subrules used by this rule.

選取

unknown select(x, no_match_error='')

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

參數

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

子規則

Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])

建構子規則的新例項。這個函式的結果必須儲存在全域變數中，才能使用。

參數

參數 說明
implementation function; required
The Starlark function implementing this subrule
attrs dict； 預設為 {}
用來宣告子規則所有 (私有) 屬性的字典。

子規則只能有標籤型別 (即標籤或標籤清單) 的私人屬性。Bazel 會自動將這些標籤對應的已解析值，以具名引數的形式傳遞至子規則的實作函式 (因此實作函式必須接受與屬性名稱相符的具名參數)。這些值的類型如下：

  • 標籤屬性的 FilesToRunProvider，並使用 executable=True
  • 標籤屬性的 File，並使用 allow_single_file=True
  • Target (適用於所有其他標籤屬性)
  • [Target] 所有標籤清單屬性
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 必要
套件規格字串清單或單一套件規格字串。

套件規格的格式與 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" 值一律可用，且 "//..." 一律會解讀為「目前存放區中的所有套件」。