建置檔案

回報問題 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

BUILD 檔案中提供的方法。如需其他函式和建構規則，請參閱「建構百科全書」，這些函式和規則也可用於 BUILD 檔案。

成員

depset

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

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

deps 集合的所有元素 (直接和間接) 都必須是相同類型，如運算式 type(x) 取得的類型。

由於系統會在疊代期間使用以雜湊為基礎的集合來排除重複項目，因此 depset 的所有元素都應可雜湊。不過，目前並非所有建構函式都會持續檢查這項不變量。使用 --incompatible_always_check_depset_elements 旗標啟用一致性檢查；這將是未來版本的預設行為；請參閱問題 10313。

此外，元素目前必須是不可變動的，但這項限制將在日後放寬。

建立的 depsets 順序應與 transitive depsets 的順序相容。"default" 訂單可與任何其他訂單合併，其他訂單則只能與自身合併。

參數

參數 說明
direct 序列；或 None； 預設為 None
deps 集合的直接元素清單。
order 字串； 預設為 "default"
新 deps 集合的遍歷策略。如要查看可能的值，請參閱這裡。
transitive depset 的 sequence；或 None。 預設為 None
元素會成為 depset 間接元素的 depset 清單。

existing_rule

unknown existing_rule(name)

傳回不可變更的類字典物件，描述在這個執行緒套件中例項化的規則屬性；如果不存在該名稱的規則例項，則傳回 None。

這裡的「不可變動的類似字典物件」是指支援類似字典的疊代、x、len(x)、name in x、x[name]、x.get(name)、x.items()、x.keys() 和 x.values() 的深度不可變動物件。

結果會包含每個屬性的項目，但名稱開頭不是字母的私有屬性，以及少數無法表示的舊版屬性類型除外。此外，字典也包含規則例項的 name 和 kind 項目 (例如 '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 x、x[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 字串序列；或 None； 預設為 None
要指定的授權。

glob

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

Glob 會傳回目前套件中每個檔案的新可變動排序清單，這些檔案符合下列條件：
  • 符合 include 中的至少一個模式。
  • 與 exclude 中的任何模式都不相符 (預設為 [])。
如果啟用 exclude_directories 引數 (設為 1)，結果會省略目錄類型的檔案 (預設為 1)。

參數

參數 說明
include 字串的序列； 預設值為 []
要納入的 glob 模式清單。
exclude 字串的序列； 預設值為 []
要排除的 glob 模式清單。
exclude_directories int; 預設為 1
是否要排除目錄的旗標。
allow_empty 預設值為 unbound
是否允許 glob 模式不比對任何內容。如果 `allow_empty` 為 False，則每個個別的包含模式都必須相符，且最終結果不得為空 (排除 `exclude` 模式的相符項目後)。

module_name

string module_name()

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

module_version

string module_version()

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

包裹

unknown package(**kwargs)

宣告適用於套件中每項規則的中繼資料。在套件 (BUILD 檔案) 中，最多只能呼叫一次。如果呼叫，則應是 BUILD 檔案中的第一個呼叫，緊接在 load() 陳述式之後。

參數

參數 說明
kwargs 必要
請參閱「建構百科全書」中的 package() 函式，瞭解適用的引數。

package_default_visibility

List package_default_visibility()

傳回正在評估的套件預設顯示設定。這是 package() 的 default_visibility 參數值，擴充後包含套件本身。

package_group

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

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

參數

參數 說明
name 字串； 必要
這項規則的專屬名稱。
packages 字串的序列； 預設為 []
這個群組中所有套件的完整列舉。
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 物件，系統會原封不動地傳回該物件。

repo_name

string repo_name()

含有目前正在評估的套件的存放區正式名稱，開頭不得有 @ 符號。

repository_name

string repository_name()

實驗功能。這項 API 仍在實驗階段，因此隨時可能變更。因此請勿依賴這項功能。您可以設定 --+incompatible_enable_deprecated_label_apis
Deprecated.，以實驗性質啟用這項功能。建議改用 repo_name，這個函式不會包含多餘的前置 @ 符號，但行為與其他函式相同。

存放目前評估套件的存放區正式名稱，並加上單一 @ 符號 (@) 前置字元。舉例來說，在由 WORKSPACE 節 local_repository(name='local', path=...) 呼叫而建立的套件中，這個值會設為 @local。在主要存放區的套件中，這項設定會設為 @。

選取

unknown select(x, no_match_error='')

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

參數

參數 說明
x dict; required
A dict that maps configuration conditions to values. 每個鍵都是 Label 或標籤字串，用於識別 config_setting 或 constraint_value 例項。如要瞭解何時應使用標籤而非字串，請參閱巨集說明文件。
no_match_error 字串； 預設為 ''
如果沒有符合的條件，則回報選用的自訂錯誤。

子檔案包

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

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

參數

參數 說明
include 字串的序列； 必要
要在子封包掃描中納入的 glob 模式清單。
exclude 字串的序列； 預設為 []
要從子封裝掃描中排除的 glob 模式清單。
allow_empty bool; 預設為 False
如果呼叫傳回空白清單，是否會失敗。根據預設，空白清單表示 BUILD 檔案中可能發生錯誤，因為對 subpackages() 的呼叫是多餘的。設為 true 可讓這項函式在該情況下成功運作。