規則
別名
查看規則來源alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias
規則會建立另一個可參照的規則名稱。
別名僅適用於「一般」目標。請特別注意,package_group
和 test_suite
不能以別名顯示。
別名規則有自己的瀏覽權限宣告。在所有其他方面,其行為類似它所參照的規則 (例如,忽略別名的測試項目,改用參照規則的僅供測試性),但有一些細微例外情況:
-
如果在指令列上提及別名,則不會執行測試。如要定義執行參照測試的別名,請在其
tests
屬性中使用具有單一目標的test_suite
規則。 -
定義環境群組時,不支援
environment
規則的別名。也不支援--target_environment
指令列選項。
範例
filegroup( name = "data", srcs = ["data.txt"], ) alias( name = "other", actual = ":data", )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
actual
|
|
config_setting
查看規則來源config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)
符合預期設定狀態 (以建構標記或平台限製表示),用於觸發可設定屬性。如要瞭解如何使用這項規則,請參閱選取和 可設定屬性。
範例
以下程式碼會比對所有設定 --compilation_mode=opt
或 -c opt
的建構 (透過指令列明確執行或透過 .bazelrc 檔案隱含):
config_setting( name = "simple", values = {"compilation_mode": "opt"} )
下列是與指定 ARM 並套用自訂定義 FOO=bar
(例如 bazel build --cpu=arm --define FOO=bar ...
) 的所有建構相符:
config_setting( name = "two_conditions", values = { "cpu": "arm", "define": "FOO=bar" } )
以下程式碼會比對所有設定使用者定義的旗標
--//custom_flags:foo=1
(無論是透過指令列明確執行,還是以 .bazelrc 檔案為隱含):
config_setting( name = "my_custom_flag_is_set", flag_values = { "//custom_flags:foo": "1" }, )
以下條件是針對以 x86_64 架構和 glibc 2.25 版本為平台指定目標的所有建構 (假設存在具有標籤 //example:glibc_2_25
的 constraint_value
)。請注意,如果平台定義了兩個限制以外的其他限制值,則仍會相符。
config_setting( name = "64bit_glibc_2_25", constraint_values = [ "@platforms//cpu:x86_64", "//example:glibc_2_25", ] )
Notes
- 如果多個
config_setting
符合目前的設定狀態,請參閱 select 一節。 - 對於支援簡寫形式的標記 (例如,
--compilation_mode
與-c
),values
定義必須使用完整表單。這兩種格式會自動比對任一形式的叫用。 -
如果標記取得多個值 (例如
--copt=-Da --copt=-Db
或清單類型的 Starlark 標記),如果"a"
顯示在實際清單中的任何位置,values = { "flag": "a" }
就會相符。values = { "myflag": "a,b" }
的運作方式相同:符合--myflag=a --myflag=b
、--myflag=a --myflag=b --myflag=c
、--myflag=a,b
和--myflag=c,b,a
。確切的語意會因標記而異。舉例來說,--copt
不支援同一個執行個體中的多個值:--copt=a,b
會產生["a,b"]
,而--copt=a --copt=b
會產生["a", "b"]
,因此values = { "copt": "a,b" }
與前者相符,但後者與後者不符。不過,--ios_multi_cpus
(適用於 Apple 規則) 會:-ios_multi_cpus=a,b
和ios_multi_cpus=a --ios_multi_cpus=b
都會產生["a", "b"]
。請檢查旗標定義並仔細測試您的條件,以確認實際結果。 - 如果您需要定義並非透過內建建構標記建立的條件,請使用
Starlark 定義的標記。您也可以使用
--define
,但這麼做提供的支援較弱,因此不建議使用。如要查看更多討論內容,請按這裡。 - 避免在不同套件中重複使用相同的
config_setting
定義。而是參照標準套件中定義的常見config_setting
。 values
、define_values
和constraint_values
可以在同一個config_setting
中的任意組合使用,但每個config_setting
都必須設定至少一個組合。
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
constraint_values
|
constraint_values 組合,才能與此 config_setting 相符。(在此不考慮執行平台)。系統會忽略平台已忽略的任何額外限制值。詳情請參閱
可設定的建構屬性一文。如果兩個 |
define_values
|
values 相同,特別是 --define 旗標。
這表示: config_setting( name = "a_and_b", values = { "define": "a=1", "define": "b=2", }) 無法使用,因為同一個鍵 ( config_setting( name = "a_and_b", define_values = { "a": "1", "b": "2", }) 正確比對
|
flag_values
|
values 相同,但適用於
使用者定義的建構標記。
這是獨立的屬性,因為使用者定義的標記會參照為標籤,內建標記則參照為任意字串。 |
values
|
這項規則會沿用 為方便起見,系統會將設定值指定為建構標記 (不含前面的 如果未在指令列明確設定旗標,則會使用其預設值。如果索引鍵在字典中多次出現,系統只會使用最後一個執行個體。如果索引鍵參照的標記可在指令列上多次設定 (例如
|
檔案群組
查看規則來源filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)
使用 filegroup
為一組目標提供一個方便的名稱。以便其他規則參照。
建議使用 filegroup
,而非直接參照目錄。
後者沒有關係,因為建構系統無法完全掌握目錄下的所有檔案,因此檔案變更時可能無法重新建構。與 glob 搭配使用時,filegroup
可以確保建構系統明確知道所有檔案。
範例
如要建立包含兩個來源檔案的 filegroup
,請
filegroup( name = "mygroup", srcs = [ "a_file.txt", "some/subdirectory/another_file.txt", ], )
或者,您也可以使用 glob
建立測試資料目錄:
filegroup( name = "exported_testdata", srcs = glob([ "testdata/*.dat", "testdata/logs/**/*.log", ]), )
如要使用這些定義,請使用任何規則的標籤參照 filegroup
。
cc_library( name = "my_library", srcs = ["foo.cc"], data = [ "//my_package:exported_testdata", "//my_package:mygroup", ], )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
srcs
|
常見的做法是使用 glob 運算式的結果做為 |
data
|
以 |
output_group
|
「輸出群組」是在目標的實作中指定的目標輸出成果類別。 |
Genquery
查看規則來源genquery(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)
genquery()
會執行以 Blaze 查詢語言指定的查詢,並將結果傾印到檔案中。
為了讓版本維持一致,這項查詢只能造訪 scope
屬性中指定的目標轉換性關閉。如果 strict
未指定或為 true,違反這項規則的查詢就會失敗在執行期間執行 (如果 strict
為 false,系統則會略過警告範圍以外的目標)。如要確保這種情況不會發生,最簡單的方法就是在範圍中提及與查詢運算式相同的標籤。
此處和指令列之間唯一允許的查詢,是這裡不允許含有萬用字元目標規格 (例如 //pkg:*
或 //pkg:all
) 的查詢。原因可能有兩個:第一,因為 genquery
必須指定範圍,防止查詢在轉換後暫時關閉,以影響其輸出內容;第二,因為 BUILD
檔案不支援萬用字元依附元件 (例如,不允許 deps=["//a/..."]
)。
使用 --order_output=full
排序 Genquery 的輸出,以便強制執行確定性輸出。
輸出檔案的名稱是規則的名稱。
範例
這個範例會將指定目標的間接關閉標籤清單寫入檔案。
genquery( name = "kiwi-deps", expression = "deps(//kiwi:kiwi_lib)", scope = ["//kiwi:kiwi_lib"], )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
expression
|
a/BUILD 中此屬性的標籤 :b 將參照目標 //:b 。 |
opts
|
bazel query 的指令列選項。此處不允許部分查詢選項:--keep_going 、--query_file 、--universe_scope 、--order_results 和 --order_output 。在這裡未指定的選項會具有其預設值,就像 bazel query 指令列一樣。 |
scope
|
|
strict
|
|
產生規則
查看規則來源genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)
genrule
會使用使用者定義的 Bash 指令產生一個或多個檔案。
Gen 規則 是一般的建構規則,沒有該工作沒有具體規則時可用。
例如,您可以執行 Bash 單行模式。不過,如果您需要編譯 C++ 檔案,請繼續使用現有的 cc_*
規則,因為所有繁重的作業都已為您完成。
請注意,genrule 需要殼層來解讀指令引數。 此外,您可以輕鬆參照 PATH 上的任意程式,但這會導致指令本身不具標準,而且可能無法重現。如果只需要執行單一工具,請考慮改用 run_binary。
請勿使用 genrule 執行測試。測試和測試結果有特殊分配,包括快取政策和環境變數。一般來說,必須在建構完成後和目標架構上執行,而在建構和執行架構 (在兩者中) 可能會執行 genrule。如果您需要一般用途測試規則,請使用 sh_test
。
跨平台程式碼的考量要素
請參閱使用者手冊,進一步瞭解跨平台程式碼編譯。
雖然 genrule 會在建構期間執行,但輸出內容通常會在建構作業結束後用於部署或測試。以適用於微控制器編譯 C 程式碼的範例為例:編譯器接受 C 來源檔案,並產生在微控制器上執行的程式碼。產生的程式碼顯然無法在用於建構程式碼的 CPU 上執行,但 C 編譯器 (如果從原始碼編譯) 本身必須執行。
建構系統會使用執行設定來說明執行建構作業的機器,以及透過目標設定來說明執行建構作業的機器。這項功能可以設定個別檔案,並將對應的檔案分隔成不同的目錄,以免發生衝突。
針對 gen 規則,建構系統會確保依附元件的建構正確:如有必要,系統會針對目標設定建構 srcs
,為exec 設定建構 tools
,並將輸出視為目標設定。同時還會提供
「Make」變數,Gengen 指令可傳遞至對應的工具。
實際上,genrule 並未定義 deps
屬性:其他內建規則會在規則之間傳遞語言相關的中繼資訊,自動判斷如何處理相依規則,但這項自動化作業無法進行這項自動化作業。Gen 規則 僅用於檔案和執行檔案層級。
特殊情況
執行編譯編譯:在某些情況下,建構必須執行 gen 規則,才能在輸出期間執行輸出。舉例來說,如果 genrule 建立了一些自訂編譯器,而後來又有其他 genrule 使用其中第一個自訂編譯器,那麼第一個編譯器必須產生執行檔採用輸出設定,因為編譯器在其他規則中會執行編譯器。在此情況下,建構系統會自動執行正確作業:針對執行設定 (而非目標設定),建構第一個通用規則的 srcs
和 outs
。如需詳細資訊,請參閱使用手冊。
JDK 與 C++ 工具:如要使用 JDK 或 C++ 編譯器套件的工具,建構系統會提供一組變數。詳情請參閱「Make」變數。
Genrule 環境
genrule 指令是由 Bash 殼層執行。這個殼層設定為使用指令或管道失敗時,使用 set -e -o pipefail
執行失敗。
建構工具會在經過處理的處理環境中執行 Bash 指令,該指令僅定義 PATH
、PWD
、TMPDIR
等核心變數。為確保建構作業可重現,使用者殼層環境定義的大多數變數不會傳遞至 genrule 的指令。然而,Bazel (而非 Blaze) 則會傳遞使用者 PATH
環境變數的值。如果變更 PATH
值,Bazel 將在下次建構作業時重新執行指令。
genrule 指令不應存取網路,但以目前來說,無法連結屬於子項本身的程序,但目前並未強制執行。
建構系統會在執行 genrule 之前自動刪除任何現有的輸出檔案,但建立必要的上層目錄。萬一發生故障,系統會一併移除任何輸出檔案。
一般建議
- 請確保由 genrule 執行的工具具有確定性和已知性。它們不應將時間戳記寫入輸出內容,而且應該針對集合和對應使用穩定順序,並且只將相對檔案路徑寫入輸出內容,而非絕對路徑。違反這項規則會導致非預期的建構行為 (Bazel 不會重新建立預期的規則),並降低快取效能。
- 廣泛使用
$(location)
來輸出、工具及來源。由於不同的設定會輸出輸出檔案,因此 genrule 無法依賴硬式編碼和/或絕對路徑。 - 請撰寫常見的 Starlark 巨集,以便在多個位置使用相同或非常相似的基因。如果 genrule 相當複雜,請考慮以指令碼或 Starlark 規則實作。如此可提升可讀性和測試能力。
- 確認結束代碼已正確表示 產生規則的成敗,
- 請勿將資訊訊息寫入 stdout 或 stderr。雖然偵錯功能很有用,但很容易造成雜訊;成功的 Ge 規則應該是靜音。另一方面,失敗的 genrule 應該能夠發出良好的錯誤訊息。
$$
evaluates to a$
, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such asls $(dirname $x)
, one must escape it thus:ls $$(dirname $$x)
。- 避免建立符號連結和目錄。Bazel 不會複製由 genrule 建立的目錄/符號連結結構,而且會檢查目錄的依附元件檢查作業沒有問題。
- 在其他規則中參照 genrule 時,您可以使用 genrule 的標籤或個別輸出檔案的標籤。有時其中一種方法比較容易理解,有時另一種方法:在使用規則的
srcs
中參照名稱時,會避免無意擷取其他規則的輸出,但如果生成規則產生許多輸出,這可能會很慢。
範例
這個範例會產生 foo.h
。沒有任何來源,因為指令不會接收任何輸入內容。這個指令執行的「二進位檔」是與 genrule 相同的套件中的 Perl 指令碼。
genrule( name = "foo", srcs = [], outs = ["foo.h"], cmd = "./$(location create_foo.pl) > \"$@\"", tools = ["create_foo.pl"], )
以下範例說明如何使用 filegroup
和其他 genrule
的輸出內容。請注意,您也可以使用 $(SRCS)
取代明確的 $(location)
指令;這個範例會使用後者來示範。
genrule( name = "concat_all_files", srcs = [ "//some:files", # a filegroup with multiple files in it ==> $(locations) "//other:gen", # a genrule with a single output ==> $(location) ], outs = ["concatenated.txt"], cmd = "cat $(locations //some:files) $(location //other:gen) > $@", )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 您可以在其他 BUILD 規則的 srcs 或 deps 區段中依名稱參照此規則。如果規則會產生來源檔案,則應使用 srcs 屬性。 |
srcs
|
此屬性不適合列出
建構系統會在確認 genrule 指令前建立這些必備條件;這些版本是以與原始建構要求相同的設定建構。這些命令的檔案名稱可用於指令在 |
outs
|
輸出檔案不得跨套件邊界。輸出檔案名稱會被視為相對於套件。
如果設定了
genrule 指令應會在預定位置建立每個輸出檔案。
您可以使用 |
cmd
|
$(location)
和「Make」變數的值。
cmd_bash 、cmd_ps 和 cmd_bat 都不適用,則即為備用設定。
如果指令列長度超出平台限制 (Linux/macOS 為 64K,Windows 為 8K),接著 genrule 會將指令寫入指令碼,並執行該指令碼。這適用於所有 cmd 屬性 ( |
cmd_bash
|
此屬性的優先順序高於 |
cmd_bat
|
此屬性的優先順序高於
|
cmd_ps
|
此屬性的優先順序高於
為了讓 Powershell 更易於使用,且較不容易出錯,請先在 genrule 中執行以下命令來設定環境,然後再執行 Powershell 指令。
|
exec_tools
|
tools 。
|
executable
|
如果將這個標記設為 True,代表輸出是執行檔,可以使用 系統不支援為產生的執行檔宣告資料依附元件。 |
local
|
如果設為 True,這個選項會強制要求
這相當於提供「local」做為標記 ( |
message
|
系統會在執行這個建構步驟時列印進度訊息。訊息預設為「產生輸出內容」(或同義詞),不過您可以提供更明確的訊息。在 |
output_licenses
|
common attributes
|
output_to_bindir
|
如果設為 True,這個選項會將輸出檔案寫入 |
tools
|
建構系統會在確認 genrule 指令前建立這些必備條件;這些建構是使用「exec」(執行) 設定所建構的,因為這類工具是在建構過程中執行。可使用
任何要由 |
測試套件
查看規則來源test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)
test_suite
會定義對人類來說「實用」的一組測試。這可讓專案定義一組測試,例如「測試前必須執行的測試」、「我們的專案的壓力測試」或「所有小型測試」。blaze test
指令會遵循這種組織方式:針對 blaze test //some/test:suite
這類叫用,Blaze 會先以 //some/test:suite
目標,傳輸所有測試目標 (也就是所謂的「test_suite 擴充」),然後 Blaze 建構並測試這些目標。
範例
用於執行目前套件中所有小測試的測試套件。
test_suite( name = "small_tests", tags = ["small"], )
執行一組指定測試的測試套件:
test_suite( name = "smoke_tests", tests = [ "system_unittest", "public_api_unittest", ], )
針對目前套件未執行所有測試的測試套件執行。
test_suite( name = "non_flaky_test", tags = ["-flaky"], )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
tags
|
如果代碼的開頭是「-」字元,系統就會將其視為負值。先前的「-」字元不算是標記的一部分,因此「-small」的套件標記與測試的「小」大小相符。所有其他的標記都是正標記。 為了讓代碼更明確,代碼也可能以「+」字元開頭,系統不會評估代碼文字的一部分。而只會讓人更容易閱讀正面和負面。 只有符合所有正面標記和無排除標記的測試規則才會納入測試套件。請注意,這並不代表系統略過已篩選測試中的依附元件錯誤;已略過測試的依附元件仍屬於合法 (例如未受瀏覽權限限制封鎖)。
針對
請注意,系統會將測試的
如果您需要 |
tests
|
這裡可以接受任何
如未指定 |