規則
別名
查看規則來源alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias
規則會建立可以指稱規則的名稱。
別名僅適用於「regular」目標。尤其是 package_group
和 test_suite
無法使用別名。
在大型存放區中,重新命名目標需要變更名稱時,別名或許能派上用場 對大量檔案所做的變更您也可以使用別名規則 select 函式呼叫則可重複使用該邏輯 有多個目標。
別名規則有專屬的瀏覽權限宣告。在所有其他情況下 就像參照規則一樣 (例如,系統會忽略「在別名上」的測試;僅供測試使用) 所參照的規則),但有些微狀況除外:
-
如果指令列中提及別名,測試就不會執行。如何定義別名
執行參照的測試,請使用
test_suite
規則只有一項目標tests
屬性。 -
定義環境群組時,
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 版 (假設存在具有標籤的 constraint_value
)
//example:glibc_2_25
。請注意,如果平台定義了
限制值
config_setting( name = "64bit_glibc_2_25", constraint_values = [ "@platforms//cpu:x86_64", "//example:glibc_2_25", ] )在這些情況下,您可以在建構中變更設定,例如, 您必須為與依附元件不同的平台建構目標。也就是說
config_setting
與頂層指令列旗標不相符 (仍可能相符)
和一些建構目標
附註
- 請參閱選取,瞭解如果多個元素之間會引發多個事件,
config_setting
個符合目前的設定狀態。 - 適用於支援簡寫表單的旗標 (例如
--compilation_mode
與-c
) 和values
定義必須使用完整格式。系統會自動列出 比對叫用內容 -
如果標記採用多個值 (例如
--copt=-Da --copt=-Db
或清單類型) Starlark 旗標),則values = { "flag": "a" }
會比對"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
|
字典:字串 ->String;不可設定;預設為 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
|
字典:字串 ->String;不可設定;預設為 這項規則會繼承已配置的目標設定
在 為方便起見,設定值會指定為建構旗標 (不含
上述的 如果指令列沒有明確設定標記,系統會使用其預設值。
如果索引鍵在字典中多次出現,則只會使用最後一個例項。
如果鍵參照的旗標,且可在指令列上多次設定 (例如
|
檔案群組
查看規則來源filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)
使用 filegroup
以收集一組目標的輸出內容
標籤。
filegroup
無法取代指令列或指令列中的清單目標
某個規則的屬性,因為目標包含
這些輸出內容並未以相同的方式收集。但在非常多元化的領域中
例如:在 Genrule 的 srcs
屬性中,或者
*_binary 規則的 data
屬性。
建議您使用 filegroup
,不要直接參照目錄。
後者非常不聲音,因為建構系統無法完整瞭解所有檔案
因此無法在這些檔案變更時重建。與
glob,filegroup
可以確保所有檔案都
讓建構系統知道的具體專案
範例
如要建立含有兩個來源檔案的 filegroup
,請執行下列步驟:
filegroup( name = "mygroup", srcs = [ "a_file.txt", "//a/library:target", "//a/binary:target", ], )
或者,使用 glob
修復 testdata 目錄:
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
|
String;預設值為 「輸出群組」是目標的輸出構件類別, 特定規則的實作 |
Genquery
查看規則來源genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)
genquery()
會執行
Bazel 查詢語言並轉儲結果
複製到檔案中
為保持一致建構作業,該查詢只能造訪
scope
中指定的目標遞移性封閉
屬性。如果發生下列情況,違反這項規則的查詢就無法執行
strict
未指定或為 true (如果 strict
為 false,
超出範圍的目標時,系統會略過並發出警告)。
要避免這種情況發生,最簡單的方法就是
和查詢運算式一樣
此處允許的查詢和指令的唯一差異
這一行指的是包含萬用字元目標規格的查詢 (例如
//pkg:*
或 //pkg:all
) 不在此限。
造成這種情況有兩個原因:首先,因為 genquery
可指定範圍,避免發生在
影響輸出結果其次,因為 BUILD
個檔案
不支援萬用字元依附元件 (例如 deps=["//a/..."]
。
模型的輸出內容會按照字母順序排序,以強制執行確定性輸出。
但 --output=graph|minrank|maxrank
或 somepath
是用於當做頂層函式
輸出檔案名稱是規則名稱。
範例
這個範例會在 指定的是檔案的目標
genquery( name = "kiwi-deps", expression = "deps(//kiwi:kiwi_lib)", scope = ["//kiwi:kiwi_lib"], )
引數
屬性 | |
---|---|
name |
名稱;必選 此目標的專屬名稱。 |
compressed_output
|
布林值;預設值為 True ,則查詢輸出內容會以 GZIP 檔案格式寫入。你可以使用這項設定
,避免 Bazel 記憶體用量突然攀升,如果查詢輸出量預期會很大。Bazel
已預先壓縮過超過 220 個位元組的查詢輸出內容
此設定的值,因此設為 True 可能無法減少保留
堆積。但可讓 Bazel 在寫入輸出檔案時略過「解壓縮」。
可能會耗用大量記憶體
|
expression
|
String;必選 要執行的查詢。與指令列和 BUILD 檔案中的其他位置相比, 這裡的標籤會根據工作區的根目錄進行解析。舉例來說,a/BUILD 檔案中的屬性 :b 會參照
目標//:b 。
|
opts
|
字串清單;預設值為 bazel query 的選項部分查詢選項不允許使用
此處:--keep_going 、--query_file 、--universe_scope
--order_results 和--order_output 。此處未指定選項
也會有預設值,就像在 bazel query 指令列中一樣。
|
scope
|
標籤清單;必選 查詢的範圍。查詢不允許在遞移性之外的觸控目標 取代這些目標。 |
strict
|
布林值;預設值為 |
Genrule
查看規則來源genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)
genrule
會透過使用者定義的 Bash 指令產生一或多個檔案。
Genrules 是一般建構規則,可在工作沒有特定規則時使用。
舉例來說,您可以執行 Bash 單行程式碼。如果您需要編譯 C++ 檔案,請
至現有 cc_*
規則,因為所有繁重工作已完成
不必確保憑證管理是否適當
因為 Google Cloud 會為您管理安全性
請注意,genrule 需要殼層來解讀指令引數, 輕鬆參照 PATH 上的任意程式,但這使 指令無意義,可能無法重現 如果只需要執行單一工具,建議使用 run_binary 。
如同任何其他動作,genrules 建立的動作不應假設
工作目錄;所有 Bazel 保證就是其宣告的輸入內容可在
$(location)
為標籤傳回的路徑。舉例來說,如果動作是在
在沙箱或遠端執行方面,沙箱或遠端執行作業的實作將決定
工作目錄如果是直接執行 (使用 standalone
策略),
目錄將是執行根目錄,也就是 bazel info execution_root
的結果。
請勿使用 genrule 執行測試。測試和檢測作業有特殊分配方式
當中包含快取政策和環境變數測試通常需要執行
並在建構完成後並在目標架構上執行 Genrules
和 exec 架構 (可能不同)如果您需要一般用途
測試規則,請使用 sh_test
。
跨平台程式碼編譯注意事項
請參閱使用手冊,進一步瞭解相關資訊 跨平台程式碼編譯
雖然 Genrules 在建構期間執行,其輸出內容通常是在建構後用於部署、部署 進行測試。以針對微控制器編譯 C 程式碼的範例:編譯器接受 C 並產生在微控制器上執行的程式碼。產生的是顯而易見的程式碼 無法在建構該檔案的 CPU 上執行,但 C 編譯器 (如果是從原始碼編譯而來) 這項功能
建構系統會使用 exec 設定,描述執行建構作業的機器 和目標設定,用於說明建構作業的輸出內容 。這項服務提供設定上述各項選項的選項 請將對應的檔案嵌入個別目錄以避免衝突
針對 Genrules,建構系統會確保正確建構依附元件:
系統會針對 target 設定建構 srcs
(如有必要)。
系統會針對 exec 設定建構 tools
,並將輸出內容視為
適用於 target 設定它也提供
「廠牌」變數。
Genrule 刻意並未定義 deps
屬性:其他內建規則使用
在規則之間傳遞的語言相關中繼資訊,以自動判斷
會處理相依規則,但 Genrules 無法採用這種自動化程度。Genrules 工作
只需要在檔案和執行檔案層級進行這項作業
特殊情況
Exec-exec 編譯:在某些情況下,建構系統需要執行 Genrule,讓
輸出內容也可以在建構期間執行舉例來說,如果 Genrule 會建構自訂編譯器
之後另一個 Genrule 會使用這個金鑰
exec 設定,因為這就是編譯器在其他 Genrule 中的位置在本例中
建構系統會自動執行正確的操作:建構 srcs
第 1 個 Genrule 中的 outs
,而不是目標
此外還會從 0 自動調整資源配置
您完全不必調整資源調度設定詳情請參閱使用手冊
資訊
JDK 與C++ 工具:如要使用 JDK 或 C++ 編譯器套件 (建構系統) 中的工具 會提供一組變數。請參閱「廠牌」變數: 詳細資料。
Genrule 環境
genrule 指令是由設定失敗的 Bash 殼層執行
或使用 set -e -o pipefail
來處理管道失敗
建構工具會在經過清理的程序環境中執行 Bash 指令
只會定義 PATH
、PWD
、
TMPDIR
和另外一些服務。
為了確保建構作業可重現,大多數在使用者殼層中定義的變數
環境不會傳遞至 genrule 的指令不過,Bazel (但非
Blaze) 會傳遞使用者 PATH
環境變數的值。
任何變更 PATH
的值都會導致 Bazel 重新執行指令
下個建構作業的執行進度
除非連線至以下程序,否則 Genrule 指令不會存取網路 子項,但系統目前不會強制執行這項指令。
建構系統會自動刪除現有的任何輸出檔案,但建立任何必要的父項 執行 genrule 等並在作業失敗時移除所有輸出檔案。
一般建議
- 要確保 Genrule 執行的工具具有確定性與隱密性,不應寫入 輸出內容的時間戳記,應對組合和對應採用穩定排序, 只寫入輸出的相對檔案路徑,無絕對路徑。未遵循這項規則,將會 導致非預期的建構行為 (Bazel 不會重新建構您認為會預期的 Genrule) 也會降低快取效能
- 針對輸出內容、工具和來源,廣泛使用
$(location)
。由於 針對不同設定區隔輸出檔案,genrules 不能依賴硬式編碼 和/或絕對路徑 - 請編寫一個通用的 Starlark 巨集,以在 。如果 Genrule 是很複雜的,請考慮在指令碼或 星際大戰規則。這有助於改善可讀性和可測試性。
- 確認結束程式碼可正確指出 Genrule 成功或失敗。
- 請勿將資訊訊息寫入 stdout 或 stderr。雖然對偵錯很有幫助 變得雜訊;成功的 Genrule 應為靜止狀態另一方面,失敗的 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 不會複製目錄/符號連結 但不包含 genrules 及其目錄的依附元件檢查作業。
- 在其他規則中參照 genrule 時,可以使用 Genrule 標籤或
個別輸出檔案的標籤有時候其中一種方法易讀易懂,有時候就是
other:在使用規則的
srcs
中依名稱參照輸出可避免 無意中接收到 Genrule 的其他輸出內容 會產生許多輸出內容
範例
這個範例會產生 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
|
String;預設值為 $(location)
和「廠牌」設定變數替代。
cmd_bash 、cmd_ps 和 cmd_bat 的備用方案。
(如果所有元素都不適用)。
如果指令列的長度超出平台限制 (在 Linux/macOS 為 64K,在 Windows 上為 8K),
那麼 Genrule 會將指令寫入指令碼,並執行該指令碼來解決問題這個
適用於所有 cmd 屬性 ( |
cmd_bash
|
String;預設值為 這個屬性的優先順序高於 |
cmd_bat
|
String;預設值為 此屬性的優先順序高於
|
cmd_ps
|
String;預設值為 此屬性的優先順序高於
為了讓 Powershell 易於使用,並減少出錯的可能性,我們執行了以下程式碼 指令來設定環境,然後在 genrule 中執行 Powershell 指令。
|
executable
|
布林值;不可設定;預設為
將此標記設為 True 表示輸出是可執行的檔案,且可以使用
不支援為產生的執行檔宣告資料依附元件。 |
local
|
布林值;預設值為
如果設為 True,這個選項會強制這個
這等同於提供「local」做為標記 ( |
message
|
String;預設值為
在執行這個建構步驟時,系統會顯示的進度訊息。根據預設,
訊息為「產生 output」有時您也會提供
也就是更具體的請使用這個屬性,不要使用 |
output_licenses
|
授權類型;預設值為 common attributes
」
|
output_to_bindir
|
布林值;不可設定;預設為
如果設為 True,這個選項會讓輸出檔案寫入 |
tools
|
標籤清單;預設為
建構系統會確保在執行 genrule 指令之前先建構這些必要條件。
是使用 exec
設定,因為這些工具會在建構作業中執行。節點上的
個別
凡是由 |
starlark_doc_extract
查看規則來源starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)
starlark_doc_extract()
會擷取規則、函式 (包括
巨集)、規格和提供者,在特定 .bzl
或
.scl
檔案。這項規則的輸出內容是 ModuleInfo
二進位 proto,符合定義的
英吋
stardoc_output.proto
在 Bazel 來源樹狀結構中。
隱含輸出目標
name.binaryproto
(預設輸出):AModuleInfo
二進位檔 proto。name.textproto
(僅在明確要求時建構):文字name.binaryproto
的 proto 版本。
警告:這項規則的輸出格式不保證是固定的。主要用於以下用途: Stardoc 內部使用。
引數
屬性 | |
---|---|
name |
名稱;必選 此目標的專屬名稱。 |
deps
|
標籤清單;預設為 load() 為基礎的 Starlark 檔案的目標清單
src 。這些目標應在正常使用之下
bzl_library 敬上
但 starlark_doc_extract 規則不會強制執行此政策
在 DefaultInfo 中提供 Starlark 檔案的任何目標。
請注意,包裝的 Starlark 檔案必須是來源樹狀結構中的檔案。Bazel 無法
|
src
|
標籤;必選 要擷取文件的 Starlark 檔案。請注意,這必須是原始碼樹狀結構中的檔案。Bazel 無法 |
render_main_repo_name
|
布林值;預設值為 //foo:bar.bzl 會以下列形式發出:
@main_repo_name//foo:bar.bzl )。
主要存放區要使用的名稱是從 產生以下項目的說明文件時,應將這項屬性設為 |
symbol_names
|
字串清單;預設值為 只有在符合下列條件時,
|
test_suite
查看規則來源test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)
test_suite
用於定義一組「實用」的測試人類可以使用。這個
可讓您為專案定義一組測試,例如「您必須在入住前執行的測試」、「我們的
的壓力測試」或「所有小型測試」bazel test
指令會遵循這個順序
針對叫用 bazel test //some/test:suite
這類的叫用,Bazel 會先
列舉 //some/test:suite
目標間接納入的所有測試目標 (我們
將此目標命名為「test_suite 擴充」,然後 Bazel 就會建構並測試這些目標。
範例
測試套件,用於執行目前套件中的所有小型測試。
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
|
字串清單;不可設定;預設為 開頭為「-」的標記字元都會視為排除標記。 前面的「-」字元不屬於代碼的一部分,因此套件代碼 的「-小」符合測試的「小」大小所有其他代碼都會納入考量 正確標記。 (選用) 如要讓正面標記更加明確,也可在開頭加上 「+」字元,系統不會將其視為代碼文字的一部分進行評估。這項服務 只是讓正面和負面區別更容易閱讀 只測試符合「所有」正數標記,且「無」負面標記的測試規則 將納入測試套件。請注意,這不代表錯誤檢查 並略過已篩除測試的依附元件。略過的依附元件 測試仍必須合法 (例如不受瀏覽權限限制封鎖)。
請注意,系統會將測試的
如果您需要 |
tests
|
測試套件清單和任何語言的測試目標。
此處接受任何
如果 |