.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 例項時，會像 c(**d) 一樣，透過使用 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，基礎名稱則為 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 傳送至子規則的實作函式，做為具名引數 (因此，實作函式必須接受與屬性名稱相符的具名參數)。這些值的類型如下：

• 具有 executable=True 的標籤屬性表示為 FilesToRunProvider
• 具有 allow_single_file=True 的標籤屬性表示為 File
• 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" 值一律可用，"//..." 一律會解讀為「目前存放區中的所有套件」。