建置檔案

回報問題 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

可在 BUILD 檔案中使用的函式。如要瞭解其他函式和建構規則 (也可用於 BUILD 檔案)，請參閱「建構百科全書」。

成員

depset

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

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

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

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

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

所建立 Depset 的順序應與 transitive 解碼器的順序相容。"default" 順序與任何其他順序相容，所有其他順序只與自身相容。

參數

參數 說明
direct sequence 或 None；預設為 None
。depset 的直接元素清單。
order 預設值為 "default"
新模式的周遊策略。如要查看可能的值，請參閱這裡。
transitive depset 的序列；或 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()。

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

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

結果值代表屬性值如下：

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

請盡量避免使用此函式。這會導致 BUILD 檔案變得脆弱且依序依賴。此外，請注意，這與將規則屬性值從內部格式轉換為 Starlark 的其他兩種轉換方式略有不同：一種是運算預設值使用，另一種是 ctx.attr.foo 使用。

參數

參數 說明
name required
目標的名稱。

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()。

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

注意：請盡量避免使用這個函式。這會導致 BUILD 檔案變得脆弱且依序依賴。此外，如果設定 --noincompatible_existing_rules_immutable_view 標記，這個函式可能會非常耗費資源，尤其是在迴圈中呼叫時。

exports_files

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

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

參數

參數 說明
srcs 字串的 sequence；必要
要匯出的檔案清單。
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 字串的序列；預設為 []
。 您要排除的 glob 模式清單。
exclude_directories 預設值為 1
標記是否要排除目錄。
allow_empty 預設值為 unbound
Glob 模式是否允許不相符。如果「allow_empty」為 False，每個個別 include 模式都必須相符，且最終結果也必須為非空白 (排除「排除」模式的相符項目之後)。

module_name

string module_name()

與此套件所在的 repo 相關聯的 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。

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 檔案和該檔案直接或間接呼叫的巨集時呼叫；例如，可能不會在規則實作函式中呼叫。

這個函式的結果與 Label 值相同，如果將指定字串傳遞至 BUILD 檔案中宣告的目標標籤值屬性，也會產生相同的結果。

使用注意事項：這個函式與 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 required
Dict，可將設定條件對應至值。每個鍵都是用於識別 config_setting 或 constraint_value 執行個體的標籤或標籤字串。如要瞭解使用標籤 (而非字串) 的時機，請參閱巨集說明文件。
no_match_error 預設值為 ''
如果沒有任何條件符合，可回報自訂錯誤。

子檔案包

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

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

參數

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