.bzl 檔案

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

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

宣告的屬性會將 None 轉換為預設值。

未巢狀的供應商清單會自動轉換為包含一個供應商清單的清單。也就是說，[FooInfo, BarInfo] 會自動轉換為 [[FooInfo, BarInfo]]。

如要讓部分規則 (例如 some_rule) 的目標對象對某個面向可見，some_rule 必須宣傳至少一個必要供應者清單中的所有供應者。舉例來說，如果某個面向的 required_providers 為 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]]，則只有在 some_rule 提供 FooInfo、或 BarInfo，或是或 BazInfo 和 QuxInfo 時，這個面向才能看到 some_rule 目標。

未巢狀的供應商清單會自動轉換為包含一個供應商清單的清單。也就是說，[FooInfo, BarInfo] 會自動轉換為 [[FooInfo, BarInfo]]。

如要讓其他面向 (例如 other_aspect) 對此面向可見，other_aspect 必須提供至少一個清單中的所有供應者。在 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 的範例中，只有在 other_aspect 提供 FooInfo、或 BarInfo，或同時提供 BazInfo 和 QuxInfo 時，這個面向才能看到 other_aspect。

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

清單中的每個元素都是 provider() 傳回的 *Info 物件，但舊版提供者會以其字串名稱表示。如果規則的目標用於宣告必要提供者的目標的依附元件，則不必在此指定該提供者。只要實作函式傳回即可。不過，雖然這不是必要條件，但我們建議您指定該值。不過，aspect 的 required_providers 欄位需要指定供應者。

舉例來說，假設某個層面會透過屬性 `deps` 傳播，並套用至目標 `alpha`。假設 `alpha` 有 `deps = [':beta_output']`，其中 `beta_output` 是目標 `beta` 的已宣告輸出內容。假設 `beta` 有目標 `charlie` 做為其中一個 `deps`。如果層面為 `apply_to_generating_rules=True`，則層面會透過 `alpha`、`beta` 和 `charlie` 傳播。如果為 False，則層面只會傳播至 `alpha`。

預設為 False。

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

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

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

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

以下 API 無法在巨集實作函式和其傳遞呼叫的任何 Starlark 函式中使用：

• package()，licenses()
• environment_group()
• native.glob() – 您可以改為透過標籤清單屬性，將 glob 傳入巨集
• native.subpackages()
• (僅限於規則終結器中使用，請參閱下方的 finalizer) native.existing_rules()、 native.existing_rule()
• (適用於 WORKSPACE 執行緒) workspace()、 register_toolchains()、 register_execution_platforms()、 bind()、存放區規則例項化

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

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

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

如果 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 預設值。

與一般符號巨集不同，規則終結器可能會呼叫 native.existing_rule() 和 native.existing_rules()，以查詢目前套件中定義的非終結器規則目標集。請注意，native.existing_rule() 和 native.existing_rules() 無法存取任何規則定義器 (包括這個定義器) 定義的目標。

• 欄位清單：
  

  provider(fields = ['a', 'b'])

• 字典欄位名稱 -> 說明文件：
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

以下提供詳細說明。如需直覺的討論和用途，請參閱「規則 (供應者的自訂初始化作業)」。

讓 P 為呼叫 provider() 所建立的供應工具符號。概念上來說，P 的例項會透過呼叫預設建構函式 c(*args, **kwargs) 產生，而該函式會執行以下操作：

• 如果 args 非空白，就會發生錯誤。
• 如果在呼叫 provider() 時指定 fields 參數，且 kwargs 包含 fields 中未列出的任何鍵，就會發生錯誤。
• 否則，c 會傳回新例項，其中 kwargs 中的每個 k: v 項目都包含名為 k 的欄位，且值為 v。

MyInfo = provider()
m = MyInfo(foo = 1)

但如果指定 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 = ...)

宣告的屬性會將 None 轉換為預設值。

宣告的屬性會將 None 轉換為預設值。

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

這個引數的值是字典，或是產生字典的回呼函式。回呼的運作方式與計算依附元件屬性類似：函式的參數名稱會與規則的屬性進行比對，因此如果您使用定義 def _my_func(srcs, deps): ... 傳遞 outputs = _my_func，函式就能存取 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 存取。

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

清單中的每個元素都是 provider() 傳回的 *Info 物件，但舊版提供者會以其字串名稱表示。如果規則的目標用於宣告必要提供者的目標的依附元件，則不必在此指定該提供者。只要實作函式傳回即可。不過，雖然這不是必要條件，但我們建議您指定該值。不過，aspect 的 required_providers 欄位需要指定供應者。

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

如果規則定義為分析測試規則，則可使用在屬性中使用 analysis_test_transition 定義的設定轉換，但會採用下列限制：

• 這個規則的目標可能會有的間接相依項目數量有限。
• 系統會將該規則視為測試規則 (就像設定 test=True 一樣)。這會取代 test 的值
• 規則實作函式可能不會註冊動作。而是必須透過提供 AnalysisTestResultInfo 註冊通過/失敗結果。

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

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

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

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

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

在延伸規則的情況下，所有初始化器都會從子項開始，依序呼叫至祖系。每個初始化器只會傳遞其瞭解的公開屬性。

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

• FilesToRunProvider 適用於標籤屬性，且含有 executable=True
• File 適用於標籤屬性，且含有 allow_single_file=True
• Target 適用於所有其他標籤屬性
• [Target] 適用於所有標籤清單屬性

請注意，與 rule()、aspect() 和 repository_rule() 不同，宣告的屬性不會將 None 轉換為預設值。如要使用預設值，呼叫端必須完全省略該屬性。

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