規則
別名
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias 規則會建立另一個規則可參照的名稱。
別名僅適用於「一般」目標。請特別注意，package_group 和 test_suite 不能建立別名。
別名規則有專屬的瀏覽權限宣告。在所有其他情況下，其行為方式與所參照的規則相同 (例如，系統會忽略「只在別名上」進行測試，而是改用參照規則的測試專用性)，但有一些小例外：
-
如果指令列中有提及別名，系統就不會執行測試。如要定義執行參照測試的別名，請使用
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)
比對預期的設定狀態 (如建構旗標或平台限制)，以便觸發可設定的屬性。請參閱「選取」一節，瞭解如何使用這項規則；如需一般功能的概覽，請參閱「 選取項目」一節。
範例
以下程式碼會比對在指令列中明確或透過 .bazelrc 檔案設定 --compilation_mode=opt 或 -c opt 的任何建構作業：
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 與頂層指令列旗標不符，仍可能與某些建構目標相符。附註
- 請參閱 select 相關說明，瞭解當多個
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
|
config_setting 而指定的最小 constraint_values 組合。(此處不考慮執行平台)。平台忽略的任何額外限制值都會遭到忽略。詳情請參閱「
可設定的建構屬性」一文。
如果兩個 |
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 篩選 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
|
|
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(
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
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 指令產生一或多個檔案。
Genrules 是通用的建構規則，可供在工作沒有特定規則時使用。例如，您可以執行 Bash 單行程式碼。不過，如果需要編譯 C++ 檔案，請繼續使用現有的 cc_* 規則，因為系統已為您完成所有繁重作業。
請勿使用 genrule 執行測試。測試和測試結果都有特殊的配量，包括快取政策和環境變數。一般來說，測試作業必須在建構完成後並位於目標架構後執行，而 Genrules 會在建構期間和主機架構上執行 (兩者可能不同)。如果您需要一般用途測試規則，請使用 sh_test。
跨編譯的注意事項
如要進一步瞭解跨平台編譯，請參閱使用手冊。
當 Genrules 在建構期間執行時，其輸出內容通常會在建構後使用，以進行部署或測試。以對微控制器編譯 C 程式碼為例：編譯器接受 C 來源檔案，並產生在微控制器上執行的程式碼。而產生的程式碼顯然無法在用於建構程式碼的 CPU 上執行，但 C 編譯器 (如果從來源編譯時) 必須自行執行。
建構系統會使用主機設定描述建構作業執行的機器，而目標設定則用來說明應在哪些機器上執行建構作業的輸出內容。您可以分別設定各個項目，並將對應的檔案隔離成不同的目錄，以免發生衝突。
對於 Genrules，建構系統會確保正確建構依附元件：視需要為目標設定建構 srcs、專為主機設定建構 tools，並將輸出內容視為用於 target 設定。這個程式庫也提供
「Make」變數，讓 Genrule 指令傳遞到對應的工具。
genrule 並未定義任何 deps 屬性，其他內建規則會使用在規則之間傳遞的語言相關中繼資訊，自動判斷如何處理相依規則，但 Genrules 無法提供這種自動化程度的自動化功能。Genrules 只在檔案和執行檔案層級運作。
特殊情況
主機主機編譯：在某些情況下，建構系統必須執行 Genrules，才能在建構期間執行輸出。舉例來說，如果 Genrule 建構一些自訂編譯器，之後另一個 Genrule 會使用該編譯器，第一個編譯器必須產生主機設定的輸出內容，因為編譯器會在另一個 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)。由於系統會區隔不同設定的輸出檔案，因此 Genrules 不能依賴硬式編碼和/或絕對路徑。 - 撰寫常見的 Starlark 巨集，以防多個位置使用相同或非常類似的 genrules。如果 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 不會複製 genrules 建立的目錄/符號連結結構，而且不會同步處理目錄的依附元件檢查。
- 在其他規則中參照 Genrule 時，您可以使用 Genrule 的標籤，或是個別輸出檔案的標籤。有時其中一種方式比較容易閱讀，但另一種方法則是：在使用所用規則的
srcs中依名稱參照輸出內容，可避免意外取得 genRule 的其他輸出內容，但當 Genrule 產生許多輸出內容時，可能就會感到繁瑣。
範例
本範例會產生 foo.h。指令未接受任何輸入內容，因此沒有來源。在指令執行的「二進位」是 Perl 指令碼，這是與 Genrule 使用的相同套件。
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 屬性相同，不過系統會針對規則的執行平台 (而非主機設定) 設定這些依附元件。這表示 exec_tools 中的依附元件不受與 tools 依附元件相同的限制。具體來說，他們不需要在自己的遞移依附元件中使用主機設定。詳情請參閱 tools。
Blaze 團隊正在遷移所有使用 |
executable
|
將此標記設為 True 即代表輸出是可執行的檔案，且可透過 不支援為產生的執行檔宣告資料依附元件。 |
local
|
如果設為 True，這個選項會強制使用「本機」策略執行這個
這相當於提供「local」標記 ( |
message
|
執行此建構步驟時，系統會列印的進度訊息。根據預設，訊息為「產生 output」(或同樣有 bland)，但您可以提供更具體的訊息。請在 |
output_licenses
|
common attributes
|
output_to_bindir
|
如果設為 True，這個選項會導致輸出檔案寫入 |
tools
|
建構系統會確保在執行 genrule 指令之前建構這些先決條件；使用「host」設定進行建構，因為這些工具會在建構作業期間執行。您可以使用
任何由 |
test_suite
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_suiteExpansion」)，接著 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
|
無論語言為何，此處接受任何
如果 |