.bzl 檔案

回報問題 。 。 。 夜間 。 。 。 7.3 。 7.2 。 。 7.1 。 7.0 。 6.5 。

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

成員

analysis_test_transition

transition analysis_test_transition(settings)

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

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

參數

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

切面

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

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

參數

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

以 _ 開頭的隱含屬性必須有預設值，且類型為 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 切面的序列； 預設值為 []
在此切面之前要傳播的切面清單。
fragments 字串的序列； 預設值為 []
切面設定目標設定片段的名稱清單。
host_fragments 字串的序列； 預設值為 []
切面在主機設定中需要的設定片段名稱清單。
toolchains sequence； 預設值為 []
如果已設定，則此規則所需的工具鍊組合。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件，任意組合。查看目前的平台以找到工具鍊，並透過 ctx.toolchain 提供給規則實作。
incompatible_use_toolchain_transition 預設值為 False
已淘汰，因此已停用，應該移除。
doc string;或 None； 預設值為 None
透過說明文件產生工具擷取切面的說明。
apply_to_generating_rules 預設值為 False
設為 true 時，如果套用至輸出檔案，就會套用至輸出檔案的產生規則。

舉例來說，假設某個切面是透過屬性 `deps` 傳播，並套用到目標 `alpha`。假設 `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
執行群組名稱 (字串) 變更為 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(direct=None, order="default", *, transitive=None)

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

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

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

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

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

參數

參數 說明
direct sequence；或 None； 預設值為 None
depset 的「direct」元素清單。
order 預設值為 "default"
新部門的周遊策略。如要查看可能的值，請參閱這篇文章。
transitive depset 的序列；或 None； 預設值為 None
模式清單，其元素將成為解碼器的間接元素。

exec_group

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

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

參數

參數 說明
toolchains sequence； 預設值為 []
這個執行群組所需的工具鍊組合。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件，任意組合。
exec_compatible_with 字串的序列； 預設值為 []
執行平台的限制清單。

module_extension

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

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

參數

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

供應商

unknown provider(doc=None, *, fields=None, init=None)

定義提供者符號，呼叫提供者可以呼叫提供者執行個體化，也可以直接做為鍵，用來從目標擷取該供應器的例項。範例：
MyInfo = provider()
...
def _my_library_impl(ctx):
    ...
    my_info = MyInfo(x = 2, y = 3)
    # my_info.x == 2
    # my_info.y == 3
    ...

如需供應商使用方法的完整指南，請參閱「規則 (供應商)」一文。

如未指定 init，系統會傳回 Provider 可呼叫值。

如果指定 init，系統會傳回 2 個元素的元組：Provider 可呼叫的值和原始建構函式可呼叫的值。詳情請參閱 規則 (自訂供應商的自訂初始化)，以及下方 init 參數的討論內容。

參數

參數 說明
doc string;或 None； 預設值為 None
可藉由說明文件產生工具擷取的供應商說明。
fields 字串的序列；或語音輸入；或 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 例項時，會像 c(**d) 一樣，透過使用 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_repo_remote_exec
與遠端執行相容，這樣就能啟用實驗模式
doc string;或 None； 預設值為 None
可透過說明文件產生工具擷取的存放區規則說明。

規則

callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])

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

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

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

參數

參數 說明
implementation 必要
實作此規則的 Starlark 函式只能包含一個參數：ctx。系統會在分析階段，為每個規則例項呼叫此函式。可存取使用者提供的屬性。必須建立動作，才能產生所有宣告的輸出內容。
test bool; 預設值為 unbound
指出這項規則是否為測試規則，亦即是否適用於 blaze test 指令。所有測試規則都會自動視為「可執行」。因此您不必為測試規則明確設定 executable = True，因此不建議使用 (不建議)。預設值為 False。詳情請參閱 規則頁面。
attrs dict; 預設值為 {}
宣告規則的所有屬性。它會從屬性名稱對應至屬性物件 (請參閱 attr 模組)。開頭為 _ 的屬性是不公開的屬性，可用來為標籤新增隱含依附元件。name 屬性為間接新增，請勿指定。以隱含方式新增 visibility、deprecation、tags、testonly 和 features 屬性，且無法覆寫。大部分規則只需要幾個屬性。為了限制記憶體用量，規則函式設有曝光事件大小上限。
outputs dict;或 None；或函式； 預設值為 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，基礎名稱則為 b.c。

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

executable bool; 預設值為 unbound
此規則是否屬於可執行檔，也就是指出它是否為 blaze run 指令的主體。預設值為 False。詳情請參閱 規則頁面。
output_to_genfiles 預設值為 False
設為 true 時，系統會在 genfiles 目錄中產生檔案，而非 bin 目錄。除非您需要此標記與現有規則相容 (例如為 C++ 產生標頭檔案時)，否則請勿設定這個標記。
fragments 字串的序列； 預設值為 []
規則所需設定片段的名稱清單。
host_fragments 字串的序列； 預設值為 []
規則在主機設定中需要的設定片段名稱清單。
_skylark_testable 預設值為 False
(實驗功能)

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

這個方法只能用來測試 Starlark 規則的分析時間行為。我們之後可能會移除這個旗標。
toolchains sequence； 預設值為 []
如果已設定，則此規則所需的工具鍊組合。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件，任意組合。查看目前的平台以找到工具鍊，並透過 ctx.toolchain 提供給規則實作。
incompatible_use_toolchain_transition 預設值為 False
已淘汰，因此已停用，應該移除。
doc string;或 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
執行群組名稱 (字串) 變更為 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;或標籤；或 string;或 None； 預設值為 None
實驗功能：許可清單的標籤，定義哪些規則可擴大這項規則。您也可以把這個參數設為 True/False，以一律允許/禁止擴充。Bazel 預設一律允許副檔名。
subrules 子規則的序列； 預設值為 []
實驗功能：這項規則使用的子規則清單。

選取

unknown select(x, no_match_error='')

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

參數

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

子規則

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

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

參數

參數 說明
implementation 函式； 必要
實作這個子規則的 Starlark 函式
attrs dict; 預設值為 {}
用來宣告子規則所有 (私人) 屬性的字典。

子規則只能包含標籤類型 (例如標籤或標籤清單) 的私人屬性。與這些標籤對應的解析值會自動由 Bazel 傳送至子規則的實作函式，做為具名引數 (因此，實作函式必須接受與屬性名稱相符的具名參數)。這些值的類型如下：

  • 具有 executable=True 的標籤屬性表示為 FilesToRunProvider
  • 具有 allow_single_file=True 的標籤屬性表示為 File
  • 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" 值一律可用，"//..." 一律會解讀為「目前存放區中的所有套件」。