本節定義多個常見詞彙和概念 許多函式或建構規則
目錄
- Bourne 殼層權杖化
- 標籤擴展
- 多數建構規則定義的一般屬性
- 所有建構規則通用的屬性
- 所有測試規則 (*_test) 通用的屬性
- 所有二進位規則通用的屬性 (*_binary)
- 可設定的屬性
- 隱含輸出目標
Bourne 殼層權杖化
某些規則的特定字串屬性會分成多個 Bourne 殼層的權杖化規則來修正字詞: 無引號的空格分隔每個字詞、以及單字和 雙引號字元和反斜線 符記化
需符合此符記化條件的屬性如下: 在本文件中的定義加以明確表示。
屬於「廠牌」的屬性變數擴展和 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 |
String;不可設定;預設為 與這個目標相關的說明警告訊息。 通常用於通知使用者目標已過時 或受到其他規則取代、為套件專用,或 但可能因為某些原因而被視為有害建議你附上 一些參考資料 (例如網頁、錯誤編號或遷移 CL 範例),因此 也很容易知道必須進行哪些變更,才能避免這個訊息。 如果有一個新目標可做為替換品使用, 建議您只遷移舊目標的所有使用者。
這個屬性對建構方式沒有影響,但
可能會影響建構工具的診斷輸出。建構工具會發出
如果規則包含 就此警告而言,內部套件依附元件不受此警告的規範, 舉例來說,為已淘汰的規則建立測試時, 那麼網站會收到警告 如果已淘汰的目標依附於其他已淘汰的目標,則系統不會發出警告 發出的訊息。 一旦使用者停止使用,即可移除目標。 |
distribs |
字串清單;不可設定;
預設為 這個特定目標要使用的發布方法字串清單。 這是 Bazel 不再使用的授權 API 的一部分。錯誤做法 即可。 |
exec_compatible_with |
一系列
|
exec_properties |
字串字典;預設值為 字串字典,會新增至為這個目標選擇的平台的 如果平台和目標層級資源中同時出現某個鍵,系統會從目標擷取該值。 |
features |
feature 字串清單;預設為 功能是字串標記,可為目標啟用或停用。 功能的意義取決於規則本身。 這個 |
restricted_to |
這個目標可以建構的環境清單,而不是 支援預設環境
這屬於 Bazel 限制系統的一部分。詳情請見
|
tags |
字串清單;不可設定;
預設為
代碼可用於任何規則。測試和測試中的代碼
Bazel 發現以下項目時,會修改沙箱程式碼的行為
任何測試或
測試上的標記通常用於為 偵錯和發布流程標記對於 C++ 和 Python 通常最為實用 測試,缺少任何執行階段註解功能。使用代碼和大小 元素提供根據程式碼集來組合測試套件的靈活性 入住政策。
Bazel 會修改測試執行行為,前提是該測試在
測試規則的
|
target_compatible_with |
標籤清單;預設為
一系列
間接依賴不相容的目標本身 視為不相容建構和測試時,也會略過這些 KPI。 如果空白清單 (預設) 代表目標相容 與所有平台互動
Workspace 規則以外的所有規則都支援這項設定
屬性。
對某些規則而言,這個屬性不會有任何作用。例如指定
詳情請參閱 平台 頁面,進一步瞭解不相容的目標略過。 |
testonly |
布林值;不可設定;預設為
如果設為
等同於不允許
測試 ( 這個屬性是用來表示目標不得 包含在發布正式版的二進位檔中。 因為測試只會在建構期間強制執行,而非執行時間,並傳播 穿過依附性樹狀結構,應該謹慎地應用。適用對象 例如虛設常式和虛構資料 您對於進行整合測試也相當實用 包含即將發布到正式版的相同二進位檔 因此不應標示為「test only」相反地 即使沒有條件也沒關係 覆寫正常行為,應確實標示為 testonly。 |
toolchains |
這個目標的「建立變數」的一組目標
。這些目標就是由系統提供
請注意,這與
工具鍊解決方案
處理各平台設定的規則。您無法使用這個項目
屬性決定是哪些特定 |
visibility |
標籤清單;
無法設定;
預設值為
目標的 |
所有測試規則 (*_test) 通用的屬性
本節說明所有測試規則的常見屬性。
屬性 | 說明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
字串清單;取決於
$(location)和
「設為變數」替代,以及
Bourne 殼層權杖化;預設值為 Bazel 會在發生什麼情況時,將指令列引數傳遞至目標
以
這些引數會在任何 |
||||||||||||||||||||
env |
字串字典;取決於
$(location)和
「設為變數」替代;預設為
指定執行測試時要設定的其他環境變數
這項屬性僅適用於原生規則,例如 |
||||||||||||||||||||
env_inherit |
字串清單;預設值為 指定要繼承自
外部環境 (當
這項屬性僅適用於原生規則,例如 |
||||||||||||||||||||
size |
字串 指定測試目標的「重度」:執行測試需要花費的時間/資源。 單元測試分為「小」,整合測試為「中」,端對端測試則為「大型」或
「巨大」Bazel 會使用這個大小決定預設逾時,您可以使用
測試大小對應至下列預設的逾時時間,並假設本機資源是高峰值 用法:
環境變數
|
||||||||||||||||||||
timeout |
字串 測試在傳回前的預期執行時間。
測試的大小屬性會影響資源估算,
逾時。如果沒有明確指定
逾時取決於測試大小。測試
逾時可使用
如果不是上述時間,可使用
環境變數
將設定「 |
||||||||||||||||||||
flaky |
布林值;不可設定;
預設為 將測試標示為「容易」。 如果已設定,最多會執行測試三次,只有在測試失敗時才標示為失敗 失敗。此屬性預設為 False,而測試為 執行一次請注意,一般不建議使用這項屬性。 但測試應該穩定通過其斷言。 |
||||||||||||||||||||
shard_count |
小於或等於 50 的非負整數;預設值為 指定平行資料分割數量 以便執行測試 設定後,此值會覆寫任何用來判定
以及執行測試的平行資料分割。請注意,在部分測試中
可能需要用到這個參數,才能啟用資料分割功能
一開始就做出決定另請參閱 如果測試資料分割已啟用,系統會在產生測試時將環境變數 資料分割需要測試執行器來支援測試資料分割通訊協定。 如果不是的話,則很可能會在每個資料分割中執行所有測試; 並非您想要的 詳情請見 測試資料分割 。 |
||||||||||||||||||||
local |
布林值;不可設定;
預設為 強制測試在本機執行,且不採用沙箱機制。 設為 True 等同於提供「local」代碼
( |
所有二進位規則通用的屬性 (*_binary)
本節說明所有二進位規則通用的屬性。
屬性 | 說明 |
---|---|
args |
字串清單;取決於
$(location)和
「設為變數」替代,以及
Bourne 殼層權杖化;
無法設定;
預設值為
Bazel 會在執行時傳遞至目標的指令列引數
透過
注意:執行目標時不會傳遞引數
在 Bazel 之外 (例如,手動在
|
env |
字串字典;取決於
$(location)和
「設為變數」替代;預設為 指定要在目標:
由
這項屬性僅適用於原生規則,例如
注意:執行目標時不會設定環境變數
在 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
等分析工具的輸出結果。
對於每種建構規則,規則的說明文件都包含 這個特殊章節,詳細說明任何隱含 輸出結果會包含該類規則的宣告。
兩個核心指標
兩個建構系統使用的命名空間:
labels 可識別目標,
可以是規則或檔案,而檔案目標則可劃分成
來源 (或輸入) 檔案目標和衍生 (或輸出) 檔案
目標。您可以在 BUILD 檔案中提及以下內容
透過指令列建構,或使用 bazel query
進行檢查。
這是目標命名空間每個檔案目標都會對應至
改為磁碟中的一個實際檔案 (「檔案系統命名空間」);每項規則
目標可能會對應到零,或是磁碟上的實際檔案。
磁碟中可能可能有檔案沒有相應的目標。的
例如:C++ 編譯期間產生的 .o
物件檔案
無法從 BUILD 檔案或指令列參照。
這樣一來,建構工具可能會隱藏某些實作詳細資料
它的運作方式如需詳細說明,請參閱
BUILD 概念參考資料。