.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 物件，但舊版供應商會以字串名稱表示。如果規則的目標做為宣告必要供應商的目標的依附元件，則不必在此指定該供應商。實作函式傳回該值即可。不過，即使這並非必要，我們仍建議您指定這項屬性。不過，方面的 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。

按照慣例，巨集需要檢查、修改或傳遞至非「主要」目標的任何屬性，實作函式都應為這些屬性提供具名參數，而將傳遞至「主要」目標且不會變更的「大量」繼承屬性，則會以 **kwargs 形式傳遞。

實作函式不得傳回值。實作函式會呼叫規則或巨集符號，藉此「宣告目標」。

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

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

巨集實作函式和它遞移呼叫的任何 Starlark 函式，都無法使用下列 API：

• package()、licenses()
• environment_group()
• native.glob() – 相反地，您可能會透過標籤清單屬性將 glob 傳遞至巨集。
• native.subpackages()
• (僅允許在規則最終化程式中使用，請參閱下方的 finalizer) native.existing_rules(), native.existing_rule()
• (適用於 WORKSPACE 執行緒) workspace(), register_toolchains(), register_execution_platforms(), bind(), repository rule instantiation

特別的 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 dict。

如果繼承非必要屬性，無論原始規則或巨集指定的值為何，屬性的預設值都會覆寫為 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 剩餘關鍵字參數。

按照慣例，巨集應將未經覆寫的繼承屬性，不變地傳遞至巨集包裝的「主要」規則或巨集符號。一般來說，大多數的繼承屬性在實作函式的參數清單中不會有參數，只會透過 **kwargs 傳遞。如果巨集需要將這些屬性傳遞至「主要」和非「主要」目標，實作函式可為某些繼承屬性 (最常見的是 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 屬性不同，使用者不會指定這些檔案的標籤。如要進一步瞭解預先宣告的輸出內容，請參閱「規則頁面」。

這個引數的值可以是字典，也可以是產生字典的回呼函式。回呼的運作方式與計算出的依附屬性類似：系統會比對函式的參數名稱與規則的屬性，因此舉例來說，如果您傳遞 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 存取。

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

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

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

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

• 這項規則的目標可擁有的遞移依附元件數量有限。
• 這項規則會視為測試規則 (如同設定 test=True)。這會取代 test 的值
• 規則實作函式可能不會註冊動作。而是必須透過提供 AnalysisTestResultInfo 註冊通過/失敗結果。

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

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

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

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

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

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

子規則只能有標籤型別 (即標籤或標籤清單) 的私人屬性。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" 值一律可用，且 "//..." 一律會解讀為「目前存放區中的所有套件」。