.bzl 檔案

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

明確屬性必須為 string 類型，且必須使用 values 限制。明確屬性會限制層面，只能搭配具有相同名稱、類型和有效值的規則使用，且須符合限制條件。

系統會自動將未巢狀化的供應商清單，轉換為包含一個供應商清單的清單。也就是說，[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。

• 欄位清單：
  

  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 = ...)

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

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