.bzl 檔案

回報問題

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

舉例來說，假設 `beta` 透過屬性 `deps` 以傳輸方式傳播，並套用到目標 `alpha`。假設 `alpha` 有 `deps = [':beta_output']`，其中 `beta_output` 是目標 `beta` 的宣告輸出內容。如果是 `alpha` 切面，則 `alpha` 會將目標 `alpha_rules` 做為其中一個 `deps=True` 切面。如果 `alpha` 切面會將其目標 `alpha_rules`。

預設為 False。
exec_compatible_with 字串的 sequence；預設為 []
執行平台的限制清單，適用於該切面的所有執行個體。
exec_groups dict; 或 None； 根據預設為 None
執行群組名稱 (字串) 到 exec_groups。如果設定這個項目，讓切面在單一執行個體內的多個執行平台中執行動作。詳情請參閱執行群組說明文件。
subrules 「Subrule」的 sequence；預設為 []
實驗功能：此方面使用的子規則清單。

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 序列; 或 None；預設值為 None
直接直接直接元素元素。
order 預設值為 "default"
新模式的周遊策略。如要查看可能的值，請參閱這裡。
transitive depset 的 sequence；或是 None；預設為 None
這個依附元件清單將含有元素將成為 Depset 的間接元素。

exec_group

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

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

參數

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

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 字串的 sequence；預設值為 []
提供這個模組擴充功能依附的環境變數。如果這份清單中的環境變數有所變更，系統會重新評估擴充功能。
os_dependent 預設值為 False
表示這項擴充功能是否與 OS 相容
arch_dependent 預設值為 False
表示這項擴充功能是否取決於架構

provider

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 字串的 sequence；或 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 例項時，會像 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 「字串」的 sequence；預設值為 []
已淘汰。此參數已淘汰。請遷移至 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; or function; default is 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 字串的 sequence；預設為 []
執行平台的限制清單，適用於該規則類型的所有目標。
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
實驗功能：Salark 函式會初始化規則屬性。

系統會針對每個規則執行個體，於載入時呼叫此函式。系統會使用 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 「Subrule」的 sequence；預設值為 []
實驗功能：這項規則使用的子規則清單。

選取

unknown select(x, no_match_error='')

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

參數

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

子規則

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

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

參數

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

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

  • 具有 executable=True 的標籤屬性表示為 FilesToRunProvider
  • 具有 allow_single_file=True 的標籤屬性表示為 File
  • Target 用於所有其他標籤屬性
  • 所有標籤清單屬性的「[Target]」
toolchains sequence；預設為 []
如果已設定，則這個子規則需要一組工具鍊。清單中可包含 String、Label 或 StarlarkToolchainTypeApi 物件，任意組合。查看目前的平台後即可找到工具鍊，並透過 ctx.toolchains 提供給子規則實作。
fragments 字串的 sequence；預設為 []
在目標設定中，子規則所需的設定片段名稱清單。
subrules Subrule 的 sequence；預設值為 []
這個子規則所需的其他子規則清單。

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