.bzl 檔案

回報問題 Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

所有 .bzl 檔案中可用的全域方法。

成員

analysis_test_transition

transition analysis_test_transition(settings)

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

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

參數

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

切面

Aspect aspect(implementation, attr_aspects=[], toolchains_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 function； 必要
Starlark 函式，用於實作此面向，共有兩個參數：Target (要套用面向的目標) 和 ctx (建立目標的規則背景)。您可以透過 ctx.rule 欄位取得目標的屬性。這個函式會在分析階段評估，每次將某個面向套用至目標時都會評估。
attr_aspects 字串序列；預設為 []
。屬性名稱清單。此面向切面的內容會沿著目標屬性中指定的依附元件 (使用這些名稱) 傳播。常見的值包括 deps 和 exports。清單也可以包含單一字串 "*"，以便沿著目標的所有依附元件傳播。
toolchains_aspects sequence；預設為 []
。工具鍊類型的清單。此切面會傳播至與這些工具鍊類型相符的目標工具鍊。
attrs dict； 預設為 {}
宣告各個面向的所有屬性的字典。它會將屬性名稱對應至屬性物件，例如 attr.label 或 attr.string (請參閱 attr 模組)。實作函式可使用面向實體屬性做為 ctx 參數的欄位。

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

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

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

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

清單中的每個元素都是 provider() 傳回的 *Info 物件，但舊版提供者會以其字串名稱表示。如果規則的目標用於宣告必要提供者的目標的依附元件，則不必在此指定該提供者。只要實作函式傳回即可。不過，雖然這不是必要條件，但我們建議您指定該值。不過，aspect 的 required_providers 欄位需要指定提供者。
requires 切面的序列；預設為 []
。 必須在這個切面之前傳播的切面清單。
fragments 字串的序列；預設為 []
。 列出子項在目標設定中所需的設定片段名稱。
host_fragments 字串的序列；預設值為 []
。 主機設定中，此面向主機的元素所需的設定片段名稱清單。
toolchains sequence； 預設為 []
如果已設定，則為此面向性質所需的工具鍊組合。清單可包含字串、標籤或 StarlarkToolchainTypeApi 物件，且可任意組合。系統會檢查目前的平台，並透過 ctx.toolchain 將工具鍊提供給面向實作。
incompatible_use_toolchain_transition bool；預設值為 False
。已淘汰，不再使用，應予以移除。
doc string 或 None； 預設為 None
說明說明文件產生工具可擷取的層面。
apply_to_generating_rules bool； 預設為 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_group 的字典。如果已設定，則可讓元件在單一例項中執行多個執行平台的動作。詳情請參閱執行群組說明文件。
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 string; 必填
從設定片段取得的值名稱。

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" 訂單與任何其他訂單相容，所有其他訂單只與自身相容。

參數

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

exec_group

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

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

參數

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

exec_transition

transition exec_transition(implementation, inputs, outputs)

用於定義執行轉換的 transition() 專用版本。如需最佳做法，請參閱說明文件 (或實作方式)。只能透過 Bazel 內建項目使用。

參數

參數 說明
implementation 可呼叫的函式； 必填
inputs 字串序列； 必要
outputs 字串序列； 必要

巨集

macro macro(implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)

定義符號巨集，可在 BUILD 檔案或巨集 (舊版或符號) 中呼叫，用於定義目標 (可能有多個)。

macro(...) 傳回的值必須指派至 .bzl 檔案中的全域變數；全域變數的名稱會是巨集符號的名稱。

如需使用符號巨集的完整指南，請參閱「巨集」。

參數

參數 說明
implementation function； 必要
實作此巨集的 Starlark 函式。巨集屬性的值會以關鍵字引數的形式傳遞至實作函式。實作函式至少必須有兩個命名參數 name 和 visibility，如果巨集繼承屬性 (請參閱下方的 inherit_attrs)，則必須有 **kwargs 殘留關鍵字參數。

依慣例，實作函式應為任何宏需要檢查、修改或傳遞至非「main」目標的屬性提供命名參數，而「大量」繼承的屬性會傳遞至「main」目標，且不會變更，會以 **kwargs 的形式傳遞。

實作函式不得傳回值。而是透過呼叫規則或巨集符號，由實作函式宣告目標。

任何目標或內部符號巨集的名稱 (由符號巨集 (包括巨集的實作函式以遞迴方式呼叫的任何 Starlark 函式) 宣告) 必須等於 name (這稱為「主要」目標)，或以 name 開頭，後面接分隔符字元 ("_"、"-" 或 ".") 和字串後置字元。(您可以宣告違反此命名配置的目標，但無法建構、設定或依附這些目標)。

根據預設，由符號巨集 (包括巨集的實作函式間接呼叫的任何 Starlark 函式) 宣告的目標，僅會顯示在包含定義巨集的 .bzl 檔案的套件中。如要宣告外部可見的目標 (包括符號巨集的呼叫端)，實作函式必須適當設定 visibility，通常是將 visibility = visibility 傳遞至所呼叫的規則或巨集符號。

以下 API 無法在巨集實作函式和其傳遞呼叫的任何 Starlark 函式中使用：
attrs dict；預設為 {}
。 這個字典包含巨集支援的屬性，類似於 rule.attrs。鍵是屬性名稱，值則是屬性物件，例如 attr.label_list(...) (請參閱 attr 模組) 或 None。None 項目表示巨集沒有該名稱的屬性，即使它會透過 inherit_attrs 繼承一個屬性 (請見下方說明) 也一樣。

特殊的 name 屬性已預先宣告，因此不得納入字典。visibility 屬性名稱是保留字，不得納入字典。

名稱開頭為 _ 的屬性為私有屬性，無法在規則的呼叫位置傳遞。這類屬性可指派預設值 (如 attr.label(default="//pkg:foo"))，以便在標籤上建立隱含的依附元件。

為限制記憶體用量，可宣告的屬性數量有上限。

inherit_attrs rule；或 macro；或 string；或 None； 預設為 None
規則符號、巨集符號或內建常用屬性清單的名稱 (請見下方說明)，巨集應從中繼承屬性。

如果 inherit_attrs 設為字串 "common"，巨集就會繼承所有 Starlark 規則使用的通用規則屬性定義。

請注意，如果 rule() 或 macro() 的傳回值未指派至 .bzl 檔案中的全域變數，則該值未註冊為規則或巨集符號，因此無法用於 inherit_attrs。

繼承機制的運作方式如下：

  1. 特殊的 name 和 visibility 屬性永遠不會繼承；
  2. 隱藏屬性 (名稱開頭為 "_") 一律不會繼承；
  3. 在 attrs 字典中已定義名稱的屬性永遠不會繼承 (attrs 中的項目優先；請注意，項目可能會設為 None，以確保在巨集中不會定義該名稱的屬性)。
  4. 所有其他屬性都會從規則或巨集繼承，並有效合併至 attrs 字典。

繼承非必要屬性時，系統會將屬性的預設值覆寫為 None，無論原始規則或巨集中指定的屬性為何。這可確保巨集將屬性值轉送至包裝規則或巨集的例項時 (例如傳入未修改的 **kwargs)，在外部巨集的呼叫中缺少的值，也會在內部規則或巨集的呼叫中缺少 (因為將 None 傳入屬性時，系統會將其視為省略屬性)。這一點很重要，因為省略屬性與傳遞明確的預設值，兩者在語意上有微妙的差異。具體來說，某些 bazel query 輸出格式不會顯示省略的屬性，且只有在省略值時才會執行計算的預設值。如果巨集需要檢查或修改繼承的屬性 (例如，在繼承的 tags 屬性中新增值)，您必須確保在巨集的實作函式中處理 None 情況。

舉例來說，以下巨集會繼承 native.cc_library 的所有屬性，但 cxxopts (已從屬性清單中移除) 和 copts (已提供新定義) 除外。在附加其他標記之前，也會檢查繼承 tags 屬性的預設 None 值。

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

如果已設定 inherit_attrs，則巨集的實作函式「必須」包含 **kwargs 殘留關鍵字參數。

依照慣例，巨集應將未經覆寫的繼承屬性傳遞至「main」規則或巨集包裝的巨集符號，而不會有所變動。通常，大多數的繼承屬性在實作函式的參數清單中不會有參數，而是會直接透過 **kwargs 傳遞。如果巨集需要將這些屬性傳遞至「main」和非「main」目標，則實作函式可為某些繼承屬性 (通常是 tags 和 testonly) 提供明確的參數，這麼做會比較方便。不過，如果巨集也需要檢查或操作這些屬性，則必須小心處理非必要繼承屬性的 None 預設值。
finalizer bool；預設為 False
。 指出這個巨集是否為規則完成器，也就是在所有非完成器目標定義完成後，在套件載入結束時評估的巨集，不論其在 BUILD 檔案中的實際位置為何。

與一般符號巨集不同，規則終結器可能會呼叫 native.existing_rule() 和 native.existing_rules()，以查詢目前套件中定義的非終結器規則目標集。請注意，native.existing_rule() 和 native.existing_rules() 無法存取任何規則定義器 (包括這個定義器) 定義的目標。
doc string 或 None； 預設為 None
說明可由說明文件產生工具擷取的巨集。

module_extension

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

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

參數

參數 說明
implementation callable; required
實作此模組擴充功能的函式。必須採用單一參數 module_ctx。系統會在建構作業開始時呼叫這個函式一次，以判斷可用的套件集。
tag_classes dict；預設為 {}
。這是用來宣告擴充功能所使用的所有標記類別的字典。它會將標記類別名稱對應至 tag_class 物件。
doc 字串或 None；預設為 None
。 說明可由說明文件產生工具擷取的模組擴充功能。
environ 字串的序列；預設為 []
。提供此模組擴充功能依附的環境變數清單。如果清單中的環境變數有所變更，擴充功能就會重新評估。
os_dependent bool； 預設值為 False
指出這個擴充功能是否依賴作業系統
arch_dependent bool； 預設值為 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 字串或 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 例項，就像呼叫預設建構函式，並將 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)

建立新的存放區規則。將其儲存在全域值中，以便從 module_extension() 實作函式載入及呼叫，或由 use_repo_rule() 使用。

參數

參數 說明
implementation 可呼叫的函式； 必填
實作此規則的函式。必須有單一參數 repository_ctx。系統會在載入階段為規則的每個例項呼叫此函式。
attrs dict 或 None；預設為 None
。用來宣告存放區規則的所有屬性。它會將屬性名稱對應至屬性物件 (請參閱 attr 模組)。開頭為 _ 的屬性為私有，可用於在檔案中新增對標籤的隱含依附元件 (存放區規則無法依附產生的構件)。系統會隱含新增屬性 name，因此不必指定。

宣告的屬性會將 None 轉換為預設值。
local bool； 預設值為 False
表示此規則會從本機系統擷取所有內容，並應在每次擷取時重新評估。
environ 字串的序列；預設值為 []
。已淘汰。這個參數已淘汰。請改為遷移至 repository_ctx.getenv。
會提供此存放區規則依附的環境變數清單。如果清單中的環境變數發生變更，系統會重新擷取存放區。
configure bool； 預設值為 False
表示存放區會檢查系統以便設定
remotable bool；預設值為 False
。實驗功能。這個參數仍在實驗階段，可能隨時變更。請勿依賴這項功能。您可以設定 --experimental_repo_remote_exec
Compatible with remote execution，以實驗方式啟用這項功能。
doc 字串或 None；預設為 None
。 Repository 規則的說明，可由說明文件產生工具擷取。

規則

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=[], dependency_resolution_rule=False, 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；因此，不必 (且不建議) 為測試規則明確設定 executable = True。預設值為 False。詳情請參閱「 規則」頁面。
attrs dict； 預設為 {}
。 用來宣告規則所有屬性的字典。它會將屬性名稱對應至屬性物件 (請參閱 attr 模組)。以 _ 開頭的屬性為私有，可用於在標籤上新增隱含的依附元件。系統會隱含新增屬性 name，因此您不必指定這項屬性。系統會隱含新增 visibility、deprecation、tags、testonly 和 features 屬性，且無法覆寫。大多數規則只需要少數屬性。為限制記憶體用量，可宣告的屬性數量設有上限。

宣告的屬性會將 None 轉換為預設值。
outputs 字典；或 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，basename 為 b.c。

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

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

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

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

清單中的每個元素都是 provider() 傳回的 *Info 物件，但舊版提供者會以其字串名稱表示。如果規則的目標用於宣告必要提供者的目標的依附元件，則不必在此指定該提供者。只要實作函式傳回即可。不過，雖然這不是必要條件，但我們建議您指定該值。不過，aspect 的 required_providers 欄位需要指定提供者。
dependency_resolution_rule bool；預設值為 False
。如果設定此值，規則可透過在 Materializers 中標示為可用的屬性，成為依附元件。設定此標記的規則中，每個屬性都必須標示為在 Materializers 中可用。這樣一來，標示為「已過時」的規則就不會依附未標示為「已過時」的規則。
exec_compatible_with 字串的序列；預設為 []
。 執行平台的限制清單，適用於此規則類型的所有目標。
analysis_test bool； 預設為 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_group 的字典。如果設為 true，規則就能在單一目標內的多個執行平台上執行動作。詳情請參閱執行群組說明文件。
initializer 預設為 None
Experimental：Stalark 函式會初始化規則的屬性。

系統會在載入時為每個規則例項呼叫這個函式。這個方法會使用 name 和規則定義的公開屬性值 (而非泛型屬性，例如 tags) 進行呼叫。

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

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

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

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

在延伸規則的情況下，所有初始化器都會從子項開始，依序呼叫上層。每個初始化器只會傳遞其瞭解的公開屬性。
parent 預設為 None
Experimental：擴充的 Stalark 規則。設定後，系統會合併公開屬性和宣傳的供應商。規則會比對父項中的 executable 和 test。系統會合併 fragments、toolchains、exec_compatible_with 和 exec_groups 的值。您可能無法設定舊版或已淘汰的參數。父項的傳入設定轉換 cfg 會在 thisrule 的傳入設定後套用。
extendable bool；或標籤；或字串；或 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 function； 必要
Starlark 函式，用於實作此子規則
attrs dict； 預設為 {}
用於宣告子規則的所有 (私人) 屬性的字典。

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

  • FilesToRunProvider 適用於標籤屬性，且含有 executable=True
  • File 適用於標籤屬性，且含有 allow_single_file=True
  • Target 適用於所有其他標籤屬性
  • [Target] 適用於所有標籤清單屬性
toolchains sequence； 預設為 []
如果已設定，則為此子規則所需的工具鍊組合。清單可包含字串、標籤或 StarlarkToolchainTypeApi 物件，且可任意組合。系統會檢查目前的平台，並透過 ctx.toolchains 將工具鍊提供給子規則實作。請注意，如果設定了這個參數，就必須在使用規則中啟用 AEG。如果您尚未遷移至 AEG，請參閱 https://bazel.build/extending/auto-exec-groups#migration-aegs。
fragments 字串的序列；預設為 []
。 列出子規則在目標設定中所需的設定片段名稱。
subrules 子規則的序列；預設值為 []
。 列出這個子規則所需的其他子規則。

tag_class

tag_class tag_class(attrs={}, *, doc=None)

建立新的 tag_class 物件，為類別的代碼定義屬性架構，這些代碼是模組擴充功能可使用的資料物件。

參數

參數 說明
attrs dict； 預設為 {}
用於宣告此標記類別的所有屬性的字典。它會將屬性名稱對應至屬性物件 (請參閱 attr 模組)。

請注意，與 rule()、aspect() 和 repository_rule() 不同，宣告的屬性不會將 None 轉換為預設值。如要使用預設值，呼叫端必須完全省略該屬性。
doc string 或 None；預設為 None
。 可由說明文件產生工具擷取的標記類別說明。

顯示設定

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