Attr

每日 · 9.2 · 9.1 · 9.0 · 8.7 · 8.6
這是頂層模組，用於定義規則或構面的屬性結構定義。每個函式都會傳回代表單一屬性結構定義的物件。這些物件會做為 rule() 和 aspect() 的 attrs 字典引數值。

如要進一步瞭解如何定義及使用屬性，請參閱「規則」頁面。

成員

bool

Attribute attr.bool(default=False, doc=None, mandatory=False)

為布林屬性建立結構定義。對應的 ctx.attr 屬性類型為 bool。

參數

參數 說明
default 預設值為 False
如果例項化規則時未提供這項屬性的值，則要使用的預設值。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。

int

Attribute attr.int(default=0, doc=None, mandatory=False, values=[])

為整數屬性建立結構定義。值必須在帶正負號的 32 位元範圍內。對應的 ctx.attr 屬性類型為 int。

參數

參數 說明
default 預設值為 0
如果例項化規則時未提供這項屬性的值，則要使用的預設值。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。
values int 的序列； 預設值為 []
屬性的允許值清單。如果提供任何其他值，系統就會發出錯誤。

int_list

Attribute attr.int_list(mandatory=False, allow_empty=True, *, default=[], doc=None)

為整數清單屬性建立結構定義。每個元素都必須在帶正負號的 32 位元範圍內。

參數

參數 說明
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。
allow_empty 預設值為 True
如果屬性可以為空，則為 True。
default sequence of ints; default is []
A default value to use if no value for this attribute is given when instantiating the rule.
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。

標籤

Attribute attr.label(default=None, doc=None, executable=False, allow_files=None, allow_single_file=None, mandatory=False, providers=[], allow_rules=None, cfg=None, aspects=[], flags=[])

建立標籤屬性的結構定義。這是依附元件屬性。

這項屬性包含不重複的 Label 值。如果提供字串來取代 Label，系統會使用標籤建構函式轉換字串。標籤路徑的相對部分 (包括可能已重新命名的存放區) 會根據已例項化的目標套件解析。

在分析期間 (規則實作函式內)，從 ctx.attr 擷取屬性值時，標籤會替換為對應的 Target。這可讓您存取目前目標依附元件的供應商。

除了普通來源檔案，這類屬性通常也用於參照工具 (例如編譯器)。這類工具會視為依附元件，就像來源檔案一樣。如要避免使用者每次在 BUILD 檔案中使用規則時都必須指定工具的標籤，您可以將標準工具的標籤硬式編碼為這個屬性的 default 值。如要禁止使用者覆寫這個預設值，可以為屬性指派底線開頭的名稱，將屬性設為私有。詳情請參閱「規則」頁面。

參數

參數 說明
default Label；或 string；或 LateBoundDefault；或 NativeComputedDefault；或 function；或 None；預設值為 None
。如果例項化規則時未提供這個屬性的值，則使用預設值。使用字串或 Label 函式指定預設值，例如 attr.label(default = "//a:b")。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
executable 預設值為 False
如果依附元件必須可執行，則為 True。也就是說，標籤必須參照可執行檔，或輸出可執行檔的規則。使用 ctx.executable.<attribute_name> 存取標籤。
allow_files bool；或 sequence 的 string；或 None；預設值為 None
是否允許 File 目標。可以是 True、False (預設值) 或允許的副檔名清單 (例如 [".cc", ".cpp"])。
allow_single_file 預設為 None
這與 allow_files 類似，但限制是標籤必須對應單一 File。如要存取，請前往 ctx.file.<attribute_name>。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。
providers 預設值為 []
必須提供這個屬性中出現的任何依附元件。

這個引數的格式為提供者清單的清單，也就是 provider() 傳回的 *Info 物件 (如果是舊版提供者，則為其字串名稱)。依附元件必須傳回至少一個內部清單中提及的「所有」供應器。為方便起見，這個引數也可以是單層供應商清單，在這種情況下，該清單會包裝在一個外部清單中，且只包含一個元素。規則的 provides 參數「不一定」要宣傳這些供應商，但我們建議您這麼做。

allow_rules 字串的序列；或 None； 預設值為 None
允許哪些規則目標 (類別名稱)。這項功能已淘汰 (僅保留相容性)，請改用供應商。
cfg 預設值為屬性的 None
Configuration。可以是 "exec" (表示依附元件是為 execution platform 建構)，也可以是 "target" (表示依附元件是為 target platform 建構)。舉例來說，在建構行動應用程式時，target platform 是 Android 或 iOS，而 execution platform 則是 Linux、macOS 或 Windows。如果 executable 為 True，則必須提供這項參數，以免在目標設定中意外建構主機工具。"target" 沒有語意效果，因此除非有助於釐清意圖，否則請勿在 executable 為 False 時設定。
aspects sequence of Aspects; default is []
Aspects that should be applied to the dependency or dependencies specified by this attribute.
flags 字串序列；預設為 []
已淘汰，將會移除。

label_keyed_string_dict

Attribute attr.label_keyed_string_dict(allow_empty=True, *, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], flags=[], mandatory=False, cfg=None, aspects=[])

為保存字典的屬性建立結構定義，其中鍵為標籤，值為字串。這是依附元件屬性。

這項屬性包含不重複的 Label 值。如果提供字串來取代 Label，系統會使用標籤建構函式轉換字串。標籤路徑的相對部分 (包括可能已重新命名的存放區) 會根據已例項化的目標套件解析。

在分析期間 (規則實作函式內)，從 ctx.attr 擷取屬性值時，標籤會替換為對應的 Target。這樣您就能存取目前目標依附元件的供應商。

參數

參數 說明
allow_empty 預設值為 True
如果屬性可以為空，則為 True。
default dict 或 function； 預設值為 {}
如果例項化規則時未提供這個屬性的值，則要使用的預設值。請使用字串或 Label 函式指定預設值，例如 attr.label_keyed_string_dict(default = {"//a:b": "value", "//a:c": "string"})。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
allow_files bool；或 sequence 的 string；或 None；預設值為 None
是否允許 File 目標。可以是 True、False (預設值) 或允許的副檔名清單 (例如 [".cc", ".cpp"])。
allow_rules 字串的序列；或 None； 預設值為 None
允許哪些規則目標 (類別名稱)。這項功能已淘汰 (僅保留相容性)，請改用供應商。
providers 預設值為 []
必須提供這個屬性中出現的任何依附元件。

這個引數的格式為提供者清單的清單，也就是 provider() 傳回的 *Info 物件 (如果是舊版提供者，則為其字串名稱)。依附元件必須傳回至少一個內部清單中提及的「所有」供應器。為方便起見，這個引數也可以是單層供應商清單，在這種情況下，該清單會包裝在一個外部清單中，且只包含一個元素。規則的 provides 參數「不一定」要宣傳這些供應商，但我們建議您這麼做。

flags 字串序列；預設為 []
已淘汰，將會移除。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。
cfg 預設值為屬性的 None
Configuration。可以是 "exec" (表示依附元件是為 execution platform 建構)，也可以是 "target" (表示依附元件是為 target platform 建構)。舉例來說，在建構行動應用程式時，target platform 是 Android 或 iOS，而 execution platform 則是 Linux、macOS 或 Windows。
aspects sequence of Aspects; default is []
Aspects that should be applied to the dependency or dependencies specified by this attribute.

label_list

Attribute attr.label_list(allow_empty=True, *, default=[], doc=None, allow_files=None, allow_rules=None, providers=[], flags=[], mandatory=False, cfg=None, aspects=[])

為標籤清單屬性建立結構定義。這是依附元件屬性。對應的 ctx.attr 屬性會是 list 類型的 Targets。

這項屬性包含不重複的 Label 值。如果提供字串來取代 Label，系統會使用標籤建構函式轉換字串。標籤路徑的相對部分 (包括可能已重新命名的存放區) 會根據已例項化的目標套件解析。

在分析期間 (規則實作函式內)，從 ctx.attr 擷取屬性值時，標籤會替換為對應的 Target。這樣您就能存取目前目標依附元件的供應商。

參數

參數 說明
allow_empty 預設值為 True
如果屬性可以為空，則為 True。
default 標籤的序列；或函式； 預設值為 []
如果例項化規則時未提供這個屬性的值，則要使用的預設值。請使用字串或 Label 函式指定預設值，例如 attr.label_list(default = ["//a:b", "//a:c"])。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
allow_files bool；或 sequence 的 string；或 None；預設值為 None
是否允許 File 目標。可以是 True、False (預設值) 或允許的副檔名清單 (例如 [".cc", ".cpp"])。
allow_rules 字串的序列；或 None； 預設值為 None
允許哪些規則目標 (類別名稱)。這項功能已淘汰 (僅保留相容性)，請改用供應商。
providers 預設值為 []
必須提供這個屬性中出現的任何依附元件。

這個引數的格式為提供者清單的清單，也就是 provider() 傳回的 *Info 物件 (如果是舊版提供者，則為其字串名稱)。依附元件必須傳回至少一個內部清單中提及的「所有」供應器。為方便起見，這個引數也可以是單層供應商清單，在這種情況下，該清單會包裝在一個外部清單中，且只包含一個元素。規則的 provides 參數「不一定」要宣傳這些供應商，但我們建議您這麼做。

flags 字串序列；預設為 []
已淘汰，將會移除。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。
cfg 預設值為屬性的 None
Configuration。可以是 "exec" (表示依附元件是為 execution platform 建構)，也可以是 "target" (表示依附元件是為 target platform 建構)。舉例來說，在建構行動應用程式時，target platform 是 Android 或 iOS，而 execution platform 則是 Linux、macOS 或 Windows。
aspects sequence of Aspects; default is []
Aspects that should be applied to the dependency or dependencies specified by this attribute.

output

Attribute attr.output(doc=None, mandatory=False)

為輸出 (標籤) 屬性建立結構定義。

這項屬性包含不重複的 Label 值。如果提供字串來取代 Label，系統會使用標籤建構函式轉換字串。標籤路徑的相對部分 (包括可能已重新命名的存放區) 會根據已例項化的目標套件解析。

在分析時，可以使用 ctx.outputs 擷取對應的 File。

參數

參數 說明
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。

output_list

Attribute attr.output_list(allow_empty=True, *, doc=None, mandatory=False)

為輸出清單屬性建立結構定義。

這項屬性包含不重複的 Label 值。如果提供字串來取代 Label，系統會使用標籤建構函式轉換字串。標籤路徑的相對部分 (包括可能已重新命名的存放區) 會根據已例項化的目標套件解析。

在分析時，可以使用 ctx.outputs 擷取對應的 File。

參數

參數 說明
allow_empty 預設值為 True
如果屬性可以為空，則為 True。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。

字串

Attribute attr.string(default='', doc=None, mandatory=False, values=[])

為 字串屬性建立結構定義。

參數

參數 說明
default string 或 NativeComputedDefault；預設值為 ''
如果例項化規則時未提供這個屬性的值，則使用預設值。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。
values 字串的序列； 預設值為 []
屬性的允許值清單。如果提供任何其他值，系統就會發出錯誤。

string_dict

Attribute attr.string_dict(allow_empty=True, *, default={}, doc=None, mandatory=False)

為保存字典的屬性建立結構定義，其中的鍵和值都是字串。

參數

參數 說明
allow_empty 預設值為 True
如果屬性可以為空，則為 True。
default 預設值為 {}
如果例項化規則時未提供這項屬性的值，則要使用的預設值。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。

string_keyed_label_dict

Attribute attr.string_keyed_label_dict(allow_empty=True, *, default={}, doc=None, allow_files=None, allow_rules=None, providers=[], flags=[], mandatory=False, cfg=None, aspects=[])

為屬性建立結構定義，該屬性的值為字典，其中鍵是字串，值是標籤。這是依附元件屬性。

這項屬性包含不重複的 Label 值。如果提供字串來取代 Label，系統會使用標籤建構函式轉換字串。標籤路徑的相對部分 (包括可能已重新命名的存放區) 會根據已例項化的目標套件解析。

在分析期間 (規則實作函式內)，從 ctx.attr 擷取屬性值時，標籤會替換為對應的 Target。這樣您就能存取目前目標依附元件的供應商。

參數

參數 說明
allow_empty 預設值為 True
如果屬性可以為空，則為 True。
default dict 或 function； 預設值為 {}
如果例項化規則時未提供這個屬性的值，則要使用的預設值。請使用字串或 Label 函式指定預設值，例如 attr.string_keyed_label_dict(default = {"foo": "//a:b", "bar": "//a:c"})。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
allow_files bool；或 sequence 的 string；或 None；預設值為 None
是否允許 File 目標。可以是 True、False (預設值) 或允許的副檔名清單 (例如 [".cc", ".cpp"])。
allow_rules 字串的序列；或 None； 預設值為 None
允許哪些規則目標 (類別名稱)。這項功能已淘汰 (僅保留相容性)，請改用供應商。
providers 預設值為 []
必須提供這個屬性中出現的任何依附元件。

這個引數的格式為提供者清單的清單，也就是 provider() 傳回的 *Info 物件 (如果是舊版提供者，則為其字串名稱)。依附元件必須傳回至少一個內部清單中提及的「所有」供應器。為方便起見，這個引數也可以是單層供應商清單，在這種情況下，該清單會包裝在一個外部清單中，且只包含一個元素。規則的 provides 參數「不一定」要宣傳這些供應商，但我們建議您這麼做。

flags 字串序列；預設為 []
已淘汰，將會移除。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。
cfg 預設值為屬性的 None
Configuration。可以是 "exec" (表示依附元件是為 execution platform 建構)，也可以是 "target" (表示依附元件是為 target platform 建構)。舉例來說，在建構行動應用程式時，target platform 是 Android 或 iOS，而 execution platform 則是 Linux、macOS 或 Windows。
aspects sequence of Aspects; default is []
Aspects that should be applied to the dependency or dependencies specified by this attribute.

string_list

Attribute attr.string_list(mandatory=False, allow_empty=True, *, default=[], doc=None)

為字串清單屬性建立結構定義。

參數

參數 說明
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。
allow_empty 預設值為 True
如果屬性可以為空，則為 True。
default 字串的序列；或 NativeComputedDefault； 預設值為 []
如果例項化規則時未提供這個屬性的值，則使用預設值。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。

string_list_dict

Attribute attr.string_list_dict(allow_empty=True, *, default={}, doc=None, mandatory=False)

為保存字典的屬性建立結構定義，其中鍵為字串，值為字串清單。

參數

參數 說明
allow_empty 預設值為 True
如果屬性可以為空，則為 True。
default 預設值為 {}
如果例項化規則時未提供這項屬性的值，則要使用的預設值。
doc string；或 None；預設為 None
可由文件生成工具擷取的屬性說明。
mandatory 預設值為 False
。如果為 true，則必須明確指定值 (即使有 default 也一樣)。