建置檔案

7.3 · 7.2 · 7.1 · 7.0 · 6.5

可在 BUILD 檔案中使用的函式。另請參閱「建構百科全書」瞭解可用於 BUILD 檔案中的額外函式和建構規則。

成員

depset

depset depset(direct=None, order="default", *, transitive=None)

建立 depsetdirect 參數是 depset 的直接元素清單,而 transitive 參數則是 depset 的清單,其中元素會成為所建立 depset 的間接元素。將 Depset 轉換為清單時,元素傳回的順序是由 order 參數指定。詳情請參閱「Depsets 總覽」。

depset 的所有元素 (直接和間接) 都必須屬於相同類型,如 type(x) 運算式所取得。

由於以雜湊為基礎的集合會在疊代期間用於消除重複項目,因此 depset 的所有元素都應可雜湊。不過,目前並未在所有建構函式中一致檢查此不變量。使用 --incompatible_always_check_depset_elements 標記啟用一致檢查功能,這將成為日後版本的預設行為;請參閱 Issue 10313

此外,元素目前必須為不可變動,但這項限制日後將會放寬。

建立的 depset 順序應與其 transitive depset 順序相容"default" 順序與任何其他順序相容,所有其他順序只與自身相容。

參數

參數 說明
direct sequenceNone;預設為 None
。depset 的直接元素清單。
order string;預設為 "default"
新依附元件的周遊策略。如要查看可能的值,請參閱這裡
transitive depset序列;或 None; 預設為 None
depset 清單,其元素會成為 depset 的間接元素。

existing_rule

unknown existing_rule(name)

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

在此,不可變動的字典類型物件是指深層不可變動的物件 x,可支援字典類型的疊代作業、len(x)name in xx[name]x.get(name)x.items()x.keys()x.values()

結果包含每個屬性的項目,但私人屬性 (名稱不以字母開頭) 和幾個無法表示的舊版屬性類型除外。此外,字典還包含規則例項的 namekind 項目 (例如 'cc_binary')。

結果值代表屬性值如下:

  • 系統將以原樣呈現 str、int 和 bool 類型的屬性。
  • 標籤會轉換為字串,如果是同一個套件中的目標,則為 ':foo' 格式;如果是不同套件中的目標,則為 '//pkg:name' 格式。
  • 清單會以元組表示,且字典會轉換為可變動的新字典。其元素會以相同方式遞迴轉換。
  • 傳回 select 值時,其內容會依上述說明轉換。
  • 在規則例項化期間未指定值,且系統已計算出預設值的屬性,會從結果中排除。(計算的預設值必須在分析階段後才能計算)。

請盡可能只在 規則完成器符號巨集的實作函式中使用這個函式。不建議在其他情境中使用此函式,且在未來的 Bazel 版本中會停用此函式;這會導致 BUILD 檔案變得脆弱且依序依賴。另請注意,這與內部形式至 Starlark 的兩種規則屬性值有細微差異:運算預設值使用,另一個轉換 ctx.attr.foo

參數

參數 說明
name 字串; 必要
目標名稱。

existing_rules

unknown existing_rules()

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

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

請盡可能只在 規則完成器符號巨集的實作函式中使用這個函式。不建議在其他情境中使用此函式,且將在未來的 Bazel 版本中停用;這會導致 BUILD 檔案變得脆弱且依序依賴。

exports_files

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

指定屬於此套件且要匯出至其他套件的檔案清單。

參數

參數 說明
srcs string序列; 必要
要匯出的檔案清單。
visibility sequence;或 None; 預設為 None
您可以指定可見度宣告。指定的目標就能看到這些檔案。如果未指定可見度,則所有套件都能看到這些檔案。
licenses 字串sequence;或 None;預設值為 None
要指定授權。

glob

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

Glob 會傳回目前套件中每個檔案的新、可變更、已排序清單,這些檔案必須符合下列條件:
  • 比對 include 中的至少一個模式。
  • 不符合 exclude 中的任何模式 (預設為 [])。
如果啟用 exclude_directories 引數 (設為 1),系統就會從結果中略過目錄類型檔案 (預設為 1)。

參數

參數 說明
include 字串序列;預設為 []
。 您要納入的 glob 模式清單。
exclude 字串sequence;預設為 []
要排除的 glob 模式清單。
exclude_directories int; 預設為 1
標示是否要排除目錄。
allow_empty 預設值為 unbound
Glob 模式是否允許不相符。如果 `allow_empty` 為 False,則每個個別的加入模式都必須符合某個項目,且最終結果也必須非空白 (排除 `exclude` 模式的符合項目後)。

module_name

string module_name()

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

module_version

string module_version()

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

package_group

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

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

參數

參數 說明
name 字串; 必填
此規則的專屬名稱。
packages 「字串」的 sequence;預設為 []
這個群組中套件的完整列舉。
includes 字串序列;預設為 []
。 此套件中包含的其他套件群組。

package_name

string package_name()

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

package_relative_label

Label package_relative_label(input)

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

這個函式只能在評估 BUILD 檔案和該檔案直接或間接呼叫的巨集時呼叫;例如,可能不會在規則實作函式中呼叫。

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

使用說明:這個函式與 Label() 的差異在於,Label() 會使用呼叫它的 .bzl 檔案套件的背景資訊,而非 BUILD 檔案的套件。如需參照已硬式編碼至巨集中的固定目標 (例如編譯器),請使用 Label()。如需將 BUILD 檔案提供的標籤字串標準化為 Label 物件,請使用 package_relative_label()。(在 BUILD 檔案或呼叫 .bzl 檔案以外的套件環境中,無法將字串轉換為 Label。因此,外部巨集應一律優先將 Label 物件傳遞至內部巨集,而非標籤字串。)

參數

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

repo_name

string repo_name()

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

repository_name

string repository_name()

Experimental。這個 API 仍在實驗階段,可能隨時變更。請勿依賴這項功能。您可以藉由設定 --+incompatible_enable_deprecated_label_apis
,以實驗性方式啟用此功能。建議改用 repo_name,因為它不含多餘的前置 @ 符號,但在其他方面運作方式相同。

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

選取

unknown select(x, no_match_error='')

select() 是輔助函式,可讓規則屬性可設定。詳情請參閱「建構百科全書」。

參數

參數 說明
x 字典; 必要
字典,可將設定條件對應至值。每個鍵都是 標籤或標籤字串,用於識別 config_setting 或 constraint_value 例項。如要瞭解使用標籤 (而非字串) 的時機,請參閱巨集說明文件
no_match_error 字串;預設為 ''
。 如果沒有任何條件符合,可選擇回報自訂錯誤。

子檔案包

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

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

參數

參數 說明
include 字串序列; 必要
Glob 模式清單,用於在子套件掃描中加入。
exclude 字串sequence;預設為 []
要從子套件掃描作業中排除的 glob 模式清單。
allow_empty bool; 預設為 False
。 如果呼叫傳回空白清單,是否失敗。根據預設,空白清單表示 BUILD 檔案中對 subpackages() 的呼叫是多餘的,因此可能發生錯誤。將其設為 true 可讓這個函式在這種情況下成功。