本節定義許多函式或建構規則通用的詞彙和概念。
目錄
- Bourne 殼層權杖化
- 標籤擴展
- 多數建構規則定義的一般屬性
- 所有建構規則通用的屬性
- 所有測試規則 (*_test) 通用的屬性
- 所有二進位規則通用的屬性 (*_binary)
- 可設定的屬性
- 隱含輸出目標
Bourne 殼層權杖化
某些規則的特定字串屬性,會根據 Bourne 殼層的代碼化規則分成多個字詞:未加引號的空格分隔每個字詞,以及使用單引號和雙引號字元和反斜線,用於避免代碼化。
這類代碼化的屬性會在本文件中的定義中明確表示。
受到「Make」變數擴充和 Bourne 殼層權杖化的屬性通常是用於將任意選項傳送至編譯器和其他工具。這類屬性的例子包括 cc_library.copts
和 java_library.javacopts
。這些替代變數可讓單一字串變數展開為設定專屬的選項字詞清單。
標籤擴展
只有極少數規則的字串屬性會受到標籤擴充:如果這些字串包含做為子字串的有效標籤 (例如 //mypkg:target
),且該標籤是目前規則宣告的必要條件,則該標籤會擴展為目標
//mypkg:target
代表的檔案路徑名稱。
範例屬性包含 genrule.cmd
和 cc_binary.linkopts
。在各情況中,詳細資料可能會因這類問題而有顯著差異,例如相對標籤是否展開、標籤會如何處理到多個檔案等。詳情請參閱規則屬性說明文件。
多數建構規則定義的一般屬性
本節說明許多建構規則定義的屬性,但並非全部。
屬性 | 說明 |
---|---|
data |
標籤清單;預設值為 這項規則在執行階段所需的檔案。可列出檔案或規則目標。通常允許任何目標。
如果新規則會處理可能會在執行階段使用其他輸入的輸入,則應定義 |
deps |
標籤清單;預設值為
此目標的依附元件。一般來說,只會列出規則目標。(雖然部分規則允許檔案直接列在 特定語言的規則通常會將列出的目標限制在特定提供者具有的項目。
指定規則類型時,目標使用
通常, |
licenses |
字串清單;不可設定;預設值為 要用於此特定目標的授權類型字串清單。這是 Bazel 不再使用的授權 API 的一部分。請勿使用此屬性。 |
srcs |
標籤清單;預設值為
套用這項規則或納入這項規則的檔案。通常會直接列出檔案,但可能會列出規則目標 (例如 特定語言專屬的規則通常會要求列出的檔案具有特定的副檔名。 |
所有建構規則通用的屬性
本節說明自動新增至所有建構規則的屬性。
屬性 | 說明 |
---|---|
compatible_with |
除了預設支援的環境之外,也可以建構這個目標的環境清單。 這是 Bazel 限制系統的一部分,可讓使用者宣告哪些目標可以彼此依附。例如,外部可部署的二進位檔不應仰賴含有公司秘密程式碼的程式庫。詳情請參閱 ConstraintSemantics。 |
deprecation |
字串;nonconfigurable;預設值為 與這個目標相關的說明警告訊息。通常用途是通知使用者目標已過時或已由其他規則取代、套件私有,或因某些原因而被視為有害。建議您納入一些參考資料 (例如網頁、錯誤編號或遷移 CL 範例),方便相關人員瞭解必須進行哪些變更才能避免訊息。如果有一個新目標可用做取代,建議您只遷移舊目標的所有使用者。
這個屬性對建構方式沒有影響,但可能會影響建構工具的診斷輸出內容。當具有 內部套件依附元件不受此警告的約束,因此舉例來說,為已淘汰的規則建構測試時,系統不會發出警告。 如果已淘汰的目標依附於另一個已淘汰的目標,則系統不會發出警告訊息。 一旦使用者停止使用,即可移除目標。 |
distribs |
字串清單;不可設定;預設值為 這個特定目標要使用的發布方法字串清單。這是 Bazel 不再使用的授權 API 的一部分。請勿使用此屬性。 |
exec_compatible_with |
執行平台中必須含有這個目標的 |
exec_properties |
字串字典;預設值為 字串字典,會新增至為這個目標選擇的平台的 如果平台和目標層級資源中同時出現某個鍵,系統會從目標擷取該值。 |
features |
feature 字串清單;預設值為 功能是字串標記,可為目標啟用或停用。功能的含義因規則本身而異。 這個 |
restricted_to |
您可以設定這個目標的環境清單,而不是預設支援的環境。
這屬於 Bazel 限制系統的一部分。詳情請參閱 |
tags |
字串清單;不可設定;預設值為
代碼可用於任何規則。測試中的標記和
如果 Bazel 在任何測試或
測試上的標記通常用於在偵錯和發布程序中為測試的角色加上註解。一般來說,標記最適合用於 C++ 和 Python 測試,因為這類測試沒有任何執行階段註解功能。使用標記和大小元素可讓您根據程式碼集檢查政策,靈活組合測試套件。
如果 Bazel 在測試規則的
|
target_compatible_with |
標籤清單;預設值為
必須存在於目標平台中的 系統會將間接依賴不相容的目標視為不相容的目標。建構和測試時也會略過這些函式。 如果清單是空白清單 (預設值),代表目標與所有平台相容。
Workspace 規則以外的所有規則都支援這個屬性。對某些規則而言,這個屬性不會有任何作用。例如,為
如要進一步瞭解不相容的目標略過動作,請參閱平台頁面。 |
testonly |
布林值;nonconfigurable;預設為
如果設為
等同於不允許
根據預設,測試 ( 這項屬性旨在意味著,目標不應包含在發布至正式版的二進位檔中。 由於測試專用範圍是在建構期間 (而非執行階段) 強制執行,並且會透過依附元件樹狀結構傳播,因此應謹慎地套用。舉例來說,在涉及要發布至實際工作環境的相同二進位檔的整合測試中,實用的虛設常式和虛構資料或許也很有用,因此可能不應標記為測試。反之,即使規則無條件覆寫到正常行為,也對這類規則而言具有危險性,因此絕對應標示為僅限測試。 |
toolchains |
允許這個目標存取的「建立變數」目標組合。這些目標可能是提供
請注意,這與工具鍊解決方案的概念不同 (後者用於平台相依設定的規則實作)。您無法使用這項屬性來確定目標會使用哪一個 |
visibility |
標籤清單;不可設定;預設值為 套件中的
目標的 |
所有測試規則 (*_test) 通用的屬性
本節說明所有測試規則的常見屬性。
屬性 | 說明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
字串清單;取決於 $(location) 和 "Make 變數" 替換,以及 Bourne 殼層權杖化;預設值為 Bazel 使用
這些引數會在 |
||||||||||||||||||||
env |
字串字典;值適用 $(location) 和 "MakeVariable" 替換,預設值為
指定
這項屬性僅適用於原生規則,例如 |
||||||||||||||||||||
env_inherit |
字串清單;預設值為 指定在
這項屬性僅適用於原生規則,例如 |
||||||||||||||||||||
size |
字串 指定測試目標的「重度」:執行測試需要花費的時間/資源。 單元測試分為「小」,整合測試為「中」,以及「大型」或「龐大」的端對端測試。Bazel 會使用大小決定預設逾時,而您可以使用 測試大小對應下列預設逾時時間,並假設本機資源用量高峰:
產生測試時,環境變數 |
||||||||||||||||||||
timeout |
字串 測試在傳回前的預期執行時間。
雖然測試的大小屬性會影響資源預估,但測試的逾時時間可以獨立設定。如果沒有明確指定,逾時時間會根據測試的大小而定。您可以使用
如果不是上述情況,則可使用 產生測試時,環境變數 |
||||||||||||||||||||
flaky |
布林值;nonconfigurable;預設值為 將測試標示為「flaky」。 如果設定的話,最多會執行測試三次;只有在每次測試失敗時才標示為失敗。根據預設,此屬性設為 False,且測試只會執行一次。請注意,一般不建議使用這項屬性,測試在維持其斷言時,應能夠穩定通過測試。 |
||||||||||||||||||||
shard_count |
小於或等於 50 的非負整數;預設值為 指定用於執行測試的平行資料分割數量。 設定後,這個值將覆寫用於決定執行測試的平行資料分割數量的任何經驗法則。請注意,對於某些測試規則,您可能需要此參數才能先啟用資料分割。另請參閱 如果測試資料分割已啟用,系統會在產生測試時將環境變數 資料分割需要測試執行器支援測試資料分割通訊協定。如果不是的話,系統很可能會在每個資料分割中執行所有測試,而這並非您想要的情況。 如要進一步瞭解資料分割,請參閱測試百科全書中的「測試資料分割」。 |
||||||||||||||||||||
local |
布林值;nonconfigurable;預設值為 強制測試在本機執行,且不採用沙箱機制。 設為 True 等同於提供「local」標記 ( |
所有二進位規則通用的屬性 (*_binary)
本節說明所有二進位規則通用的屬性。
屬性 | 說明 |
---|---|
args |
字串清單;取決於 $(location) 和 "Make variant" 替代形式,以及 Bourne shell 符記化;無法設定;預設值為
Bazel 會在
注意:在 Bazel 以外的目標上執行時 (例如在 |
env |
字串字典;值適用 $(location) 和 "Make 變數" 替代,預設值為 指定在
這項屬性僅適用於原生規則,例如
注意:在 Bazel 外部執行目標時 (例如在 |
output_licenses |
字串清單;預設值為 這個二進位檔產生的輸出檔案授權。 這是 Bazel 不再使用的授權 API 的一部分。請勿使用此屬性。 |
可設定的屬性
大部分的屬性都「可設定」,也就是說,當目標以不同方式建構時,其值可能會有所變更。具體來說,可設定的屬性可能因傳送至 Bazel 指令列的標記,或是哪個下游依附元件要求目標。舉例來說,這可用於自訂多個平台或編譯模式的目標。
以下範例針對不同的目標架構宣告不同的來源。執行 bazel build :multiplatform_lib --cpu x86
會使用 x86_impl.cc
建構目標,而替換 --cpu arm
則會改用 arm_impl.cc
。
cc_library( name = "multiplatform_lib", srcs = select({ ":x86_mode": ["x86_impl.cc"], ":arm_mode": ["arm_impl.cc"] }) ) config_setting( name = "x86_mode", values = { "cpu": "x86" } ) config_setting( name = "arm_mode", values = { "cpu": "arm" } )
select()
函式會根據目標設定符合哪些 config_setting
或 constraint_value
條件,為可設定屬性選擇不同的替代值。
Bazel 會在處理巨集之後及處理規則之前,評估可設定的屬性 (就技術上來說,在
載入和分析階段之間)。在 select()
評估前進行的任何處理,都不知道 select()
選擇哪個分支版本。舉例來說,巨集無法根據所選分支版本變更行為,而 bazel query
只能針對目標的可設定依附元件做出保守的猜測。如要進一步瞭解如何搭配規則和巨集使用 select()
,請參閱
常見問題。
在說明文件中標示為 nonconfigurable
的屬性無法使用這項功能。通常屬性無法設定,因為 Bazel 在內部需要知道其值,才能判斷如何解析 select()
。
如需詳細的總覽,請參閱「 可設定的建構屬性」一文。
隱含輸出目標
C++ 中的隱式輸出內容已淘汰,請盡量避免用於其他語言。我們目前並沒有淘汰路徑,但最終也會淘汰。
在 BUILD 檔案中定義建構規則時,您必須在套件中明確宣告新的已命名規則目標。許多建構規則函式還「間接」包含一或多個輸出檔案目標,其內容與意義會因規則而異。舉例來說,當您明確宣告 java_binary(name='foo', ...)
規則時,也會「間接」將輸出檔案的目標 foo_deploy.jar
宣告為同一套件的成員。(這項特殊目標是適合部署的獨立 Java 封存檔)。
隱含輸出目標是全域目標圖表中的一級成員。和其他目標一樣,這些目標是依照需求建構,像是在頂層建構指令中指定,或在其他建構目標的必要必要條件時。您可以在 BUILD 檔案中參照這些依附元件,並可在 bazel query
等分析工具的輸出內容中觀察。
每種建構規則的說明文件都包含特殊區段,當中詳細說明任何隱含輸出的名稱和內容,其中必須包含該類規則的宣告。
建構系統使用的兩個命名空間之間有幾項重要但有些微差異:標籤可用來識別「目標」 (可以是規則或檔案),而檔案目標則可分成來源 (或輸入) 檔案目標,以及衍生 (或輸出) 檔案目標。這些是您可以在 BUILD 檔案中提及的內容、透過指令列建構,或使用 bazel query
進行檢查;這就是「目標命名空間」。每個檔案目標都會對應到磁碟上的一個實際檔案 (「檔案系統命名空間」)。每個規則目標都可能對應到零個或多個磁碟中的實際檔案。磁碟中可能有檔案沒有相應的目標;舉例來說,C++ 編譯期間產生的 .o
物件檔案無法透過 BUILD 檔案或指令列參照。如此一來,建構工具可能會隱藏某些實作詳細資料,以致於無法執行其工作。如要進一步瞭解相關資訊,請參閱「建構概念參考資料」一文。