規則
別名
查看規則來源alias(name, actual, aspect_hints, compatible_with, deprecation, features, package_metadata, restricted_to, tags, target_compatible_with, testonly, visibility)
alias 規則會建立規則可參照的另一個名稱。
別名僅適用於「一般」目標。特別是 package_group 和 test_suite 無法別名化。
在大型存放區中，重新命名目標需要變更大量檔案，這時別名就派得上用場。您也可以使用別名規則儲存 select 函式呼叫，以便將該邏輯用於多個目標。
別名規則有自己的可見性宣告。在所有其他方面，這個別名規則的行為都與參照的規則相同 (例如，系統會忽略別名上的 testonly ，並改用參照規則的 testonly 屬性)，但有幾個例外狀況：
-
如果指令列中提及測試的別名，系統就不會執行測試。如要定義執行參照測試的別名，請使用
test_suite規則，並在tests屬性中加入單一目標。 -
定義環境群組時，系統不支援
environment規則的別名。--target_environment指令列選項也不支援這些功能。
範例
filegroup(
name = "data",
srcs = ["data.txt"],
)
alias(
name = "other",
actual = ":data",
)
引數
| 屬性 | |
|---|---|
name |
名稱：必填 這個目標的專屬名稱。 |
actual
|
標籤 (必填) 別名參照的目標。不一定要是規則，也可以是輸入檔案。 |
config_setting
查看規則來源config_setting(name, aspect_hints, constraint_values, define_values, deprecation, features, flag_values, licenses, package_metadata, tags, testonly, values, visibility)
符合預期的設定狀態 (以建構標記或平台限制表示)，目的是觸發可設定的屬性。如要瞭解如何使用這項規則，請參閱「select」；如要瞭解一般功能的總覽，請參閱「 可設定的屬性」。
範例
以下會比對任何設定 --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",
]
)
config_setting 與頂層指令列標記不符，仍可能與某些建構目標相符。
附註
- 如要瞭解多個
config_setting符合目前設定狀態時會發生什麼情況，請參閱選取。 - 對於支援簡寫形式的旗標 (例如
--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
|
字典：字串 -> 字串；nonconfigurable；預設值為 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
|
字典：label -> 字串；nonconfigurable；預設為 values 相同，但適用於
使用者定義的建構旗標。這是不同的屬性，因為使用者定義的旗標會參照標籤，而內建旗標則會參照任意字串。 |
values
|
字典：字串 -> 字串；nonconfigurable；預設值為 這項規則會繼承已設定目標的設定，並在 為方便起見，設定值會指定為建構標記 (不含前置 如果未在指令列中明確設定旗標，系統會使用預設值。
如果字典中出現重複的鍵，系統只會使用最後一個例項。
如果金鑰參照的標記可在指令列上設定多次 (例如
|
filegroup
查看規則來源filegroup(name, srcs, data, aspect_hints, compatible_with, deprecation, features, licenses, output_group, package_metadata, 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
|
字串；預設值為 「輸出群組」是目標的輸出構件類別，在該規則的實作中指定。 |
genquery
查看規則來源genquery(name, deps, data, aspect_hints, compatible_with, compressed_output, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, expression, features, licenses, opts, package_metadata, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)
genquery() 會執行以 Bazel 查詢語言指定的查詢，並將結果傾印至檔案。
為確保建構作業一致，查詢只能存取 scope 屬性中指定目標的遞移閉包。如果 strict 未指定或為 true (如果 strict 為 false，系統只會略過範圍外的目標並發出警告)，違反這項規則的查詢會在執行期間失敗。如要確保不會發生這種情況，最簡單的方法是在範圍中提及與查詢運算式相同的標籤。
此處允許的查詢與指令列查詢的唯一差異在於，此處不允許包含萬用字元目標規格 (例如 //pkg:* 或 //pkg:all) 的查詢。原因有二：第一，genquery 必須指定範圍，以免查詢的遞移閉包外部目標影響輸出內容；第二，BUILD 檔案不支援萬用字元依附元件 (例如不允許 deps=["//a/..."])。
為確保輸出內容具有確定性，genquery 的輸出內容會依字典順序排序，但 --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
|
字串；必填 要執行的查詢。與指令列和 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, aspect_hints, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, package_metadata, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)
genrule 會使用使用者定義的 Bash 指令產生一或多個檔案。
Genrule 是通用建構規則，如果沒有特定規則可執行工作，您可以使用這項規則。
舉例來說，您可以執行 Bash 單行指令。但如果您需要編譯 C++ 檔案，請沿用現有的 cc_* 規則，因為所有繁重的工作都已為您完成。
請注意，genrule 需要殼層來解讀指令引數。 您也可以輕鬆參照 PATH 中提供的任意程式，但這會使指令成為非密封式，且可能無法重現。如果只需要執行單一工具，建議改用 run_binary。
與其他動作一樣，genrule 建立的動作不應對工作目錄做出任何假設；Bazel 保證的是，宣告的輸入內容會位於 $(location) 為標籤傳回的路徑。舉例來說，如果動作是在沙箱或遠端執行，沙箱或遠端執行的實作方式會決定工作目錄。如果直接執行 (使用 standalone 策略)，工作目錄會是執行根目錄，也就是 bazel info execution_root 的結果。
請勿使用 genrule 執行測試。測試和測試結果有特別豁免規定，包括快取政策和環境變數。一般來說，測試需要在建構完成後，於目標架構上執行，而 genrule 則是在建構期間於 exec 架構上執行 (兩者可能不同)。如需一般用途的測試規則，請使用 sh_test。
跨平台編譯注意事項
如要進一步瞭解交叉編譯，請參閱使用手冊。
雖然 genrule 會在建構期間執行，但其輸出內容通常會在建構後用於部署或測試。以編譯微控制器的 C 程式碼為例：編譯器會接受 C 來源檔案，並產生可在微控制器上執行的程式碼。產生的程式碼顯然無法在用於建構的 CPU 上執行，但 C 編譯器 (如果是從來源編譯) 本身必須執行。
建構系統會使用執行設定來描述建構作業執行的機器，並使用目標設定來描述建構作業輸出內容執行的機器。這個工具提供選項來設定上述各項，並將對應的檔案分別放入不同目錄，以免發生衝突。
對於 genrule，建構系統會確保依附元件建構正確：
srcs (如有必要) 會針對 target 設定建構，
tools 會針對 exec 設定建構，且輸出內容會視為 target 設定。此外，它還提供「Make」變數，genrule 指令可將這些變數傳遞至對應工具。
genrule 刻意未定義 deps 屬性：其他內建規則會使用在規則之間傳遞的語言相關中繼資訊，自動判斷如何處理依附規則，但 genrule 無法達到這種自動化程度。Genrule 僅適用於檔案和 Runfile 層級。
特殊情況
執行檔編譯：在某些情況下，建構系統需要執行 genrule，以便在建構期間執行輸出內容。舉例來說，如果 genrule 建構了某個自訂編譯器，而該編譯器隨後會由另一個 genrule 使用，則第一個 genrule 必須為執行設定產生輸出內容，因為編譯器會在另一個 genrule 中執行。在這種情況下，建構系統會自動執行正確的操作：針對執行設定建構第一個 genrule 的 srcs 和 outs，而不是目標設定。詳情請參閱使用手冊。
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)，包括輸出內容、工具和來源。由於不同設定的輸出檔案會分開，genrule 無法依賴硬式編碼和/或絕對路徑。 - 如果多個位置使用相同或非常相似的 genrule，請編寫通用的 Starlark 巨集。如果 genrule 很複雜，建議您在指令碼中或以 Starlark 規則實作。這有助於提高可讀性和可測試性。
- 請務必確認結束代碼是否正確指出 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 不會複製 genrule 建立的目錄/符號連結結構，且目錄的依附元件檢查不健全。
- 在其他規則中參照 genrule 時，您可以使用 genrule 的標籤或個別輸出檔案的標籤。有時其中一種方法較容易閱讀，有時則不然：在取用規則的
srcs中依名稱參照輸出內容，可避免無意間擷取 genrule 的其他輸出內容，但如果 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
|
字串；預設值為 $(location)
和「Make」變數替代規則。
cmd_bash、cmd_ps 和 cmd_bat 都不適用，系統會改用這個值。
如果指令列長度超過平台限制 (Linux/macOS 為 64K，Windows 為 8K)，genrule 會將指令寫入指令碼，並執行該指令碼來解決問題。這項規定適用於所有 cmd 屬性 ( |
cmd_bash
|
字串；預設值為 這個屬性的優先順序高於 |
cmd_bat
|
字串；預設值為 這個屬性的優先順序高於
|
cmd_ps
|
字串；預設值為 這項屬性的優先順序高於
為方便使用 Powershell 並減少錯誤，我們會在 genrule 中執行 Powershell 指令前，先執行下列指令來設定環境。
|
executable
|
布林值；無法設定；預設值為
將此旗標設為 True 表示輸出內容為可執行檔，可使用 系統不支援為產生的可執行檔宣告資料依附元件。 |
local
|
布林值；預設值為
如果設為 True，這個選項會強制使用「本機」策略執行這個
這相當於提供「local」做為標記 ( |
message
|
字串；預設值為
執行這個建構步驟時，系統會列印進度訊息。根據預設，訊息為「正在生成輸出內容」(或同樣平淡的內容)，但您可以提供更具體的訊息。請在 |
output_licenses
|
字串清單；預設值為 common attributes
|
output_to_bindir
|
布林值；無法設定；預設值為
如果設為 True，這個選項會將輸出檔案寫入 |
toolchains
|
允許這項 genrule 存取「建立變數」的目標集，或這項 genrule 將存取的
透過 |
tools
|
標籤清單；預設值為
建構系統會確保在執行 genrule 指令前建構這些必要條件；這些必要條件是使用 exec
設定建構，因為這些工具會做為建構的一部分執行。您可以使用
凡是由 |
starlark_doc_extract
查看規則來源starlark_doc_extract(name, deps, src, data, allow_unused_doc_comments, aspect_hints, compatible_with, deprecation, exec_compatible_with, exec_group_compatible_with, exec_properties, features, licenses, package_metadata, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)
starlark_doc_extract() 會擷取特定 .bzl 或 .scl 檔案中定義或重新匯出的規則、函式 (包括巨集)、構面和供應商的文件。這項規則的輸出內容是 ModuleInfo 二進位 proto，如 Bazel 來源樹狀結構中的 stardoc_output.proto 所定義。
隱含輸出目標
name.binaryproto(預設輸出)：AModuleInfo二進位 proto。name.textproto(僅在明確要求時建構)：name.binaryproto的文字原型版本。
引數
| 屬性 | |
|---|---|
name |
名稱：必填 這個目標的專屬名稱。 |
deps
|
標籤清單；預設值為 load()-ed 進行
src。在正常使用情況下，這些目標應為 bzl_library 目標，但 starlark_doc_extract 規則不會強制執行這項操作，且會接受在 DefaultInfo 中提供 Starlark 檔案的任何目標。
請注意，包裝的 Starlark 檔案必須是來源樹狀結構中的檔案；Bazel 無法 |
src
|
標籤 (必填) 要從中擷取文件內容的 Starlark 檔案。請注意，這必須是來源樹狀結構中的檔案；Bazel 無法生成檔案。
|
allow_unused_doc_comments
|
布林值；預設值為 #: 開頭的註解)，或附加至變數的註解，但變數值的說明文件應以其他方式提供 (例如函式的 docstring，或規則的 rule(doc = ...))。
|
render_main_repo_name
|
布林值；預設值為 //foo:bar.bzl 會發出為 @main_repo_name//foo:bar.bzl) 呈現主要存放區中的標籤。主要存放區使用的名稱取自主要存放區 如要為僅供同一存放區使用的 Starlark 檔案產生說明文件，這個屬性應設為 |
symbol_names
|
字串清單；預設值為
|
test_suite
查看規則來源test_suite(name, aspect_hints, compatible_with, deprecation, features, licenses, package_metadata, restricted_to, tags, target_compatible_with, testonly, tests, visibility)
test_suite 定義一組對人類「有用」的測試。這樣專案就能定義測試集，例如「您必須在簽入前執行的測試」、「我們專案的壓力測試」或「所有小型測試」。bazel test 指令會遵守這類組織結構：對於 bazel test //some/test:suite 等叫用，Bazel 會先列舉 //some/test:suite 目標以遞移方式納入的所有測試目標 (我們稱之為「test_suite 擴充」)，然後建構及測試這些目標。
範例
測試套件，用於執行目前套件中的所有小型測試。
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」套件標記會與測試的「small」大小相符。所有其他標記都視為正向標記。 如要更明確地指出正面標記，標記開頭也可以加上「+」字元，系統不會將其視為標記文字的一部分。這只是為了方便讀取正負面差異。 測試套件只會納入符合所有正向標記，以及任何負向標記的測試規則。請注意，這不代表系統會略過已篩除測試的依附元件錯誤檢查；略過測試的依附元件仍須合法 (例如未受可見度限制封鎖)。
在涉及萬用字元目標模式的呼叫中，
請注意，為進行篩選，測試的
如果需要包含互斥標記的測試 (例如所有小型和中型測試) 的 |
tests
|
任何語言的測試套件和測試目標清單。
這裡接受任何
如果 |