原生

支援原生規則和其他套件輔助函式的內建模組。所有原生規則在本單元中會顯示為函式,例如native.cc_library。請注意,原生模組只能在載入階段中使用 (例如巨集,不適用於規則導入)。屬性會忽略 None 值,並將其視為未設定的屬性。
您還可以使用下列函式:

成員

existing_rule

unknown native.existing_rule(name)

傳回類似字典的不可變物件,該物件會說明在此執行緒套件中執行個體化的規則屬性;如果名稱沒有規則執行個體,則傳回 None

此處的「類似字典物件」意指一個非常不可變的物件 x,支援類似字典的疊代、len(x)name in xx[name]x.get(name)x.items()x.keys()x.values()

如果已設定 --noincompatible_existing_rules_immutable_view 標記,系統會改為傳回具有相同內容的新可變動字典。

產生的結果會包含每個屬性的項目,但私有屬性 (名稱開頭不是字母) 和一些無法呈現的舊版屬性類型除外。此外,字典中包含規則例項的 namekind (例如 'cc_binary') 項目。

結果值代表屬性值如下:

  • 系統將以原樣呈現 str、int 和 bool 類型的屬性。
  • 針對同一套件中的目標,標籤會轉換為 ':foo' 形式的字串,對於其他套件中的目標,則會轉換為 '//pkg:name' 形式的字串。
  • 清單會以元組表示,且字典會轉換為可變動的新字典。這些元素的元素會以遞迴方式轉換。
  • 傳回 select 值時,其內容會依上述說明轉換。
  • 規則建立期間未指定任何值,且已計算其預設值的屬性會從結果中排除。(直到分析階段才能計算運算預設值)。

請盡量避免使用這個函式。這使得 BUILD 檔案既流暢又有順序。另請注意,這與內部形式至 Starlark 的兩種規則屬性值有細微差異:運算預設值使用,另一個用於 ctx.attr.foo

參數

參數 說明
name 必要
目標的名稱。

existing_rules

unknown native.existing_rules()

傳回不可變的 dict 類物件,描述目前在這個執行緒套件中執行個體化的規則。每個類似 dict 物件的項目會將規則執行個體的名稱對應到 existing_rule(name) 傳回的結果。

此處的「類似字典物件」意指一個非常不可變的物件 x,支援類似字典的疊代、len(x)name in xx[name]x.get(name)x.items()x.keys()x.values()

如果已設定 --noincompatible_existing_rules_immutable_view 標記,系統會改為傳回具有相同內容的新可變動字典。

注意:請盡量避免使用這個函式。這使得 BUILD 檔案既流暢又有順序。此外,如果設定 --noincompatible_existing_rules_immutable_view 旗標,此函式的成本可能相當高昂,尤其是在迴圈內呼叫時。

exports_files

None native.exports_files(srcs, visibility=None, licenses=None)

指定這個套件的哪個檔案匯出至其他套件。

參數

參數 說明
srcs sequence of strings; 必要
要匯出的檔案清單。
visibility sequence; or None; 預設值 = 無
可以指定瀏覽權限宣告。指定的目標將可看到這些檔案。如未指定瀏覽權限,每個套件都能看到檔案。
licenses sequence of strings; or None; 預設值 = 無
需要指定的授權。

Glob

sequence native.glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)

Glob 會傳回目前套件中每個檔案的可變動清單清單,且之排序如下:
  • 比對 include 中的至少一個模式。
  • 不符合 exclude 中的任何模式 (預設為 [])。
,瞭解如何調查及移除這項存取權。 如果已啟用 exclude_directories 引數 (設為 1),結果會省略類型目錄的檔案 (預設值為 1)。

參數

參數 說明
include sequence of strings; 預設 = []
要納入的 glob 模式清單。
exclude sequence of strings; 預設 = []
要排除的 glob 模式清單。
exclude_directories 預設 = 1
旗標是否要排除目錄。
allow_empty 預設值 = 未繫結
我們是否允許 glob 模式比對任何內容。如果「allow_empty」為 False,每個個別 include 模式都必須相符,且最終結果也必須為非空白 (排除「Exclude」模式的相符結果後)。

module_name

string native.module_name()

與這個套件的存放區相關聯的 Bazel 模組名稱。如果這個套件來自 WORKSPACE 中定義的存放區,而非 MODULE.bazel,這裡會是空的。針對模組擴充功能產生的存放區,這是代管擴充功能的模組名稱。與 module_ctx.modules 中顯示的 module.name 欄位相同。 可能會傳回 None

module_version

string native.module_version()

與這個套件相關聯的存放區相關聯的 Bazel 模組版本。如果這個套件來自 WORKSPACE 中定義的存放區,而非 MODULE.bazel,這裡會是空的。對模組擴充功能產生的存放區而言,這是代管擴充功能的模組版本。與 module_ctx.modules 中顯示的 module.version 欄位相同。 可能會傳回 None

package_group

None native.package_group(name, packages=[], includes=[])

這個函式會定義一組套件,並為群組指派標籤。您可以在 visibility 屬性中參照這個標籤。

參數

參數 說明
name 必要
這項規則的專屬名稱。
packages sequence of strings; 預設 = []
此群組中套件的完整列舉。
includes sequence of strings; 預設 = []
包含的其他套件群組。

package_name

string native.package_name()

接受評估的套件名稱,不含存放區名稱。例如,在 BUILD 檔案 some/package/BUILD 中,其值將是 some/package。如果 BUILD 檔案呼叫了 .bzl 檔案中定義的函式,package_name() 會與呼叫端的 BUILD 檔案套件相符。

package_relative_label

Label native.package_relative_label(input)

根據目前初始化的套件 (也就是執行目前巨集的 BUILD 檔案),將輸入字串轉換為 Label 物件。如果輸入內容已是 Label,則會傳回不變。

只有在評估 BUILD 檔案及其直接或間接呼叫時,才能呼叫此函式。可能不會 (例如) 規則實作函式呼叫。

此函式的結果會與透過將指定字串傳遞至 BUILD 檔案中所宣告目標的標籤值屬性所產生的 Label 值相同。

使用注意事項:這個函式與 Label() 的差異,在於 Label() 使用呼叫該檔案的 .bzl 檔案套件的內容,而非 BUILD 檔案的套件。如要參照以硬式編碼方式寫入巨集的固定目標 (例如編譯器),請使用 Label()。當您需要將 BUILD 檔案提供的標籤字串正規化為 Label 物件時,請使用 package_relative_label()。(在 BUILD 檔案或呼叫 .bzl 檔案以外的套件環境中,無法將字串轉換為 Label。因此,外部巨集最好一律將標籤物件傳遞至內部巨集,而不是標籤字串)。

參數

參數 說明
input string; or Label; 必要
輸入標籤字串或標籤物件。如果傳遞 Label 物件,系統會依原樣傳回該物件。

repo_name

string native.repo_name()

含有目前正在評估套件的存放區正規名稱,無開頭符號。

repository_name

string native.repository_name()

實驗功能。此 API 仍在實驗階段,隨時可能變更。請勿仰賴這項功能。您可以藉由設定 --+incompatible_enable_deprecated_label_apis
,以實驗性方式啟用此功能。最好改用 repo_name,因為這個方法不包含開頭的符號,但運作方式相同。

含有目前正在評估套件的存放區標準名稱,前面加上一個簽名 (@)。舉例來說,WORKSPACE 群組 local_repository(name='local', path=...) 呼叫的套件中已存在,該套件會設為 @local。在主要存放區的套件中,會設為 @

子套件

sequence native.subpackages(include, exclude=[], allow_empty=False)

傳回目前套件每個直接子套件的新可變動清單,無論檔案系統目錄深度為何。傳回的清單經過排序,且包含與目前套件相關的子套件名稱。建議您優先使用 bazel_skylib.subpackages 模組中的方法,不要直接呼叫這個函式。

參數

參數 說明
include sequence of strings; 必要
要納入子套件掃描作業的 glob 模式清單。
exclude sequence of strings; 預設 = []
要從子套件掃描作業中排除的 glob 模式清單。
allow_empty 預設值 = 否
指出呼叫傳回空白清單時是否會失敗。根據預設,空白清單代表 BUILD 檔案中的潛在錯誤,其中呼叫 subpackages() 非常嚴重。如果設為 true,這個函式將可成功執行。