本節定義許多函式或建構規則通用的詞彙和概念。
目錄
- Bourne 殼層權杖化
- 展開標籤
- 由大多數建構規則定義的一般屬性
- 所有建構規則通用的屬性
- 所有測試規則通用的屬性 (*_test)
- 所有二元規則通用的屬性 (*_binary)
- 可設定的屬性
- 隱式輸出目標
Bourne 殼層權杖化
某些規則中的某些字串屬性會根據 Bourne 殼層的權杖化規則分割為多個字詞:未加引號的空格分隔不同字詞,並使用單引號和雙引號字元和反斜線做為避免權杖化。
適用這項權杖化的屬性會在本文件的定義中明確指出。
適用「Make」變數擴充和 Bourne 殼層權杖化的屬性,通常會用來將任意選項傳遞至編譯器和其他工具。這類屬性的例子包括 cc_library.copts
和 java_library.javacopts
。搭配使用這些替代變數,可讓單一字串變數展開為設定專屬的選項字詞清單。
標籤擴展
少數規則的部分字串屬性必須套用標籤:如果這些字串包含做為子字串 (例如 //mypkg:target
) 的有效標籤,而該標籤是目前規則的先宣告條件,則該標籤會擴充為由 target
//mypkg:target
所代表檔案的路徑名稱。
範例屬性包括 genrule.cmd
和 cc_binary.linkopts
。在每個情況下,詳細資料可能會有極大差異,像是:是否展開相對標籤、如何處理展開為多個檔案的標籤等。詳情請參閱規則屬性說明文件。
由大多數建構規則定義的一般屬性
本節說明由許多建構規則定義的屬性,但並非全部。
屬性 | 說明 |
---|---|
data |
這項規則在執行階段所需的檔案。可以列出檔案或規則目標。通常允許任何目標。
如果新規則處理的輸入可能會在執行階段使用其他輸入,則應定義 |
deps |
這個目標的依附元件。通常應該只列出規則目標。(雖然部分規則允許檔案直接列於 語言專屬規則通常只會將列出的目標限制在具有特定提供者的使用者。
使用
大多數情況下, |
licenses |
要用於這個特定目標的授權類型字串清單。這是 Bazel 已不再使用的授權 API 的一部分。請勿使用此屬性。 |
srcs |
這項規則處理或納入的檔案。一般而言,系統會直接列出檔案,但可以列出規則目標 (例如 語言專屬的規則通常需要列出的檔案副檔名。 |
所有建構規則通用的屬性
本節說明以隱含方式新增到所有建構規則的屬性。
屬性 | 說明 |
---|---|
compatible_with |
除了預設支援的環境之外,您還可以建立此目標的環境清單。 這是 Bazel 限制系統的一部分,可讓使用者宣告哪些目標可以或不能彼此相依。舉例來說,可部署的外部二進位檔不應仰賴包含公司密碼的程式庫。詳情請參閱 ConstraintSemantics。 |
deprecation |
與這個目標相關的說明警告訊息。 通常用於通知使用者目標已過時、遭到其他規則取代、僅供套件使用,或可能基於某些原因而被視為有害。建議您加入一些參考資料 (例如網頁、錯誤編號或遷移 CL 範例),方便員工瞭解收到訊息前需要哪些變更,才能避免收到相關訊息。如果有新的目標可做為替換用的新目標,建議您只遷移舊目標的所有使用者。
這項屬性不會影響項目的建構方式,但可能會影響建構工具的診斷輸出內容。當具有 套件內依附元件不受這項警告影響,因此,即使建構已淘汰規則的測試,也不會收到警告。 如果已淘汰的目標依附於其他已淘汰的目標,系統不會發出警告訊息。 一旦使用者停止使用目標,即可移除其目標。 |
distribs |
要用於此特定目標的發布方法字串清單。這是 Bazel 已不再使用的授權 API 的一部分。請勿使用此屬性。 |
exec_compatible_with |
此目標執行平台中必須存在的 |
exec_properties |
字串字典,會新增至已為此目標選取的平台 如果平台和目標層級屬性中都存在一個鍵,系統會從目標中擷取該值。 |
features |
功能是可在目標中啟用或停用的字串標記。特徵的意義會因規則本身而異。 這個 |
restricted_to |
您可建立這個目標的環境清單,而非預設支援環境。
此為 Bazel 限制系統的一部分。詳情請參閱 |
tags |
標記可用於任何規則。測試上的標記和
Bazel 會在任何測試或
測試中的標記通常用於在偵錯和發布程序中為測試角色加上註解。一般而言,標記最適用於 C++ 和 Python 測試,因為缺少任何執行階段註解能力。使用標記和大小元素時,您可以依據程式碼集簽入政策,靈活組合測試套件。
如果 Bazel 在測試規則的
|
target_compatible_with |
必須出現在目標平台中的 會間接依附於不相容目標的目標本身會視為不相容。建構及測試時也會略過這些測試。 空白清單 (預設值) 表示目標與所有平台相容。
工作區規則以外的所有規則都支援這項屬性。對部分規則而言,這個屬性不會有任何作用。舉例來說,為
如要進一步瞭解不相容的目標略過功能,請參閱平台頁面。 |
testonly |
如果為 True,則只有測試專用的目標 (例如測試) 可以依附這個目標。
同樣地,非
根據預設,測試 ( 這個屬性的用途是目標不應包含在已發布至正式版的二進位檔中。 由於測試只會在建構時間強制執行,而非執行階段,並且會透過依附元件樹狀結構傳播,因此您應審慎套用。舉例來說,適用於單元測試的虛設常式和假造可能也很有幫助,涉及的整合測試涉及將發布至實際工作環境的相同二進位檔,因此不應標示為測試專用。相反地,如果規則即使連進來危險,可能就應該標示為「僅供測試」,或許因為它們會無條件覆寫正常行為。 |
toolchains |
允許存取這個目標的「建立變數」目標組合。這些目標都是規則的執行個體,可為 Bazel 內建的工具鍊類型提供
請注意,這與工具鍊解析的概念不同,後者為平台相關設定的規則實作會使用。您無法使用這項屬性來判斷目標要使用哪個特定的 |
visibility |
目標上的 |
所有測試規則通用的屬性 (*_test)
本節說明所有測試規則通用的屬性。
屬性 | 說明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Bazel 使用
這些引數會在 |
||||||||||||||||||||
env |
指定在
這項屬性僅適用於原生規則,例如 |
||||||||||||||||||||
env_inherit |
指定在
這項屬性僅適用於原生規則,例如 |
||||||||||||||||||||
size |
指定測試目標的「核心」:執行需要多少時間/資源。 單元測試屬於「小」,整合測試為「中」,端對端測試則為「大」或「龐大」。Bazel 會根據大小來決定預設逾時時間,您可以使用 測試大小會對應至下列預設逾時值,並假設本機資源用量尖峰:
產生測試時,系統會將環境變數 |
||||||||||||||||||||
timeout |
在傳回前執行測試的預期時間長度。
雖然測試的大小屬性會控制資源估算,但測試的逾時功能可以獨立設定。如果未明確指定,逾時時間會以測試的大小為依據。您可以使用
針對以上情況以外的時間,您可以使用 產生測試時,環境變數 |
||||||||||||||||||||
flaky |
將測試標示為不穩定。 如果已設定,可執行測試最多三次,只有在每次都失敗時才會將其標示為失敗。這項屬性的預設值為 False,且測試只會執行一次。請注意,我們一般不建議使用此屬性;如果測試保留,就應該可靠地通過測試。 |
||||||||||||||||||||
shard_count |
指定用於執行測試的平行資料分割數量。 這個值會覆寫任何經驗法則,用於決定用於執行測試的平行資料分割數量。請注意,在某些測試規則中,一開始可能需要這個參數才能啟用資料分割。另請參閱 如果啟用測試資料分割,產生測試時,環境變數 如要進行資料分割,測試執行器必須支援測試資料分割通訊協定。如果不是的話,很有可能會在每個資料分割中執行每項測試,這並非您要的結果。 如要進一步瞭解資料分割,請參閱測試百科全書中的測試資料分割。 |
||||||||||||||||||||
local |
強制不採用沙箱機制,在本機執行測試。 設為 True 等同於提供「local」標記 ( |
所有二進位規則通用的屬性 (*_binary)
本節說明所有二元規則通用的屬性。
屬性 | 說明 |
---|---|
args |
Bazel 會在透過
注意:當您在 Bazel 以外的地方執行目標時 (例如在 |
env |
指定在
這項屬性僅適用於原生規則,例如
注意:當您在 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 檔案或指令列參照。如此一來,建構工具可能會隱藏特定工作方式的實作詳細資料。詳情請參閱 BUILD 概念參考資料。