.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 物件，但舊版提供者會以其字串名稱表示。如果規則的目標用於宣告必要提供者的目標的依附元件，則不必在此指定該提供者。只要實作函式傳回即可。不過，雖然這不是必要條件，但我們建議您指定該值。不過，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。

• 欄位清單：
  

  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 屬性不同，使用者不會為這些檔案指定標籤。如要進一步瞭解預先宣告的輸出內容，請參閱「規則」頁面。

這個引數的值是字典，或是產生字典的回呼函式。回呼的運作方式與計算依附元件屬性類似：函式的參數名稱會與規則的屬性進行比對，舉例來說，如果您傳遞 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 物件，但舊版提供者會以其字串名稱表示。如果規則的目標用於宣告必要提供者的目標的依附元件，則不必在此指定該提供者。只要實作函式傳回即可。不過，雖然這不是必要條件，但我們建議您指定該值。不過，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] 適用於所有標籤清單屬性

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