一般規則

規則

• alias
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• test_suite

別名

alias(name, actual, compatible_with, deprecation, features, 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",
)

引數

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",
      ]
  )
  

附註

• 如要瞭解多個 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 至少必須設定一個。

引數

            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",
                })
          

filegroup

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",
    ],
)

引數

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/..."])。

為了強制產生確定性的輸出內容，genquery 的輸出內容會依字典順序排序，但 --output=graph|minrank|maxrank 或 somepath 用於頂層函式時除外。

輸出檔案的名稱就是規則名稱。

範例

這個範例會將指定目標遞移關閉的標籤清單寫入檔案。

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

引數

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_* 規則，因為所有繁重的工作都已為您完成。

請注意，genrule 需要殼層來解讀指令引數。您也可以輕鬆參照 PATH 上提供的任意程式，但這會使指令無法密封，且可能無法重現。如果您只需要執行單一工具，建議改用 run_binary。

就像其他動作一樣，genrules 建立的動作不應假設任何關於工作目錄的資訊；所有 Bazel 都保證，宣告的輸入內容會在 $(location) 為其標籤傳回的路徑中提供。舉例來說，如果動作是在沙箱或遠端執行，則實際執行目錄或遠端執行作業將決定工作目錄。如果直接執行 (使用 standalone 策略)，工作目錄將是執行根目錄，也就是 bazel info execution_root 的結果。

請勿使用 genrule 執行測試。測試和測試結果有特殊豁免條款，包括快取政策和環境變數。一般來說，測試需要在建構完成後，且在目標架構上執行；而 genrules 則是在建構期間和執行架構上執行 (兩者可能不同)。如果您需要通用測試規則，請使用 sh_test。

跨平台程式碼編譯注意事項

如要進一步瞭解交叉編譯，請參閱使用手冊。

雖然 genrules 會在建構期間執行，但其輸出內容通常會在建構後用於部署或測試。以針對微控制器編譯 C 程式碼的範例：編譯器接受 C 來源檔案，並產生在微控制器上執行的程式碼。產生的程式碼顯然無法在用於建構的 CPU 上執行，但 C 編譯器 (如果是從原始碼編譯) 本身必須執行。

建構系統會使用執行設定來描述建構作業執行的機器，並使用目標設定來描述建構作業輸出內容應執行的機器。它提供設定這些項目的選項，並將對應的檔案分隔至不同的目錄，以免發生衝突。

針對 genrules，建構系統會確保適當建構依附元件：srcs 會根據 target 設定 (如有必要) 進行建構，tools 會根據 exec 設定進行建構，而輸出內容則視為 target 設定。並提供 「Make」變數，讓 Genrule 指令可以傳送至對應的工具。

genrule 刻意不定義 deps 屬性：其他內建規則會使用規則之間傳遞的語言相關元資料，自動判斷如何處理相關規則，但 genrule 無法達到這種程度的自動化。Genrules 僅在檔案和 runfiles 層級運作。

特殊情況

執行-執行編譯：在某些情況下，建構系統需要執行 genrules，以便在建構期間執行輸出內容。舉例來說，如果 genrule 建構某些自訂編譯器，而後者隨後會由另一個 genrule 使用，那麼第一個 genrule 就必須為執行設定產生輸出內容，因為編譯器會在另一個 genrule 中執行。在這種情況下，建構系統會自動執行正確的操作：為執行設定 (而非目標設定) 建構第一個 Genrule 的 srcs 和 outs。詳情請參閱使用手冊。

JDK 和 C++ 工具：如要使用 JDK 或 C++ 編譯器套件的工具，建構系統會提供一組可用的變數。詳情請參閱「"Make" 變數」一節。

Genrule 環境

使用 set -e -o pipefail 時，如果指令或管道失敗，則會執行 Bash 殼層，並在其中執行 genrule 指令。

建構工具會在經過淨化的程序環境中執行 Bash 指令，該環境只定義 PATH、PWD、TMPDIR 和其他幾個核心變數。為確保可重現建構作業，使用者 shell 環境中定義的大多數變數不會傳遞至 genrule 指令。不過，Bazel (而非 Blaze) 會傳遞使用者的 PATH 環境變數值。任何對 PATH 值所做的變更都會導致 Bazel 在下次建構時重新執行指令。

除非目前未強制執行這項指令，否則 Genrule 指令不得存取網路，只能連線至指令本身子項的程序。

建構系統會自動刪除任何現有的輸出檔案，但會在執行 genrule 之前建立任何必要的父系目錄。並在發生錯誤時移除所有輸出檔案。

一般建議

• 要確保 Genrule 執行的工具具有確定性與隱密性，不應將時間戳記寫入輸出內容，且應使用穩定的集合和地圖排序，並且只將相對檔案路徑寫入輸出內容，而非絕對路徑。違反這項規則可能會導致非預期的建構行為 (Bazel 不會重建您認為會重建的 genrule)，並降低快取效能。
• 請盡量使用 $(location) 來處理輸出內容、工具和來源。由於系統會區隔不同設定的輸出檔案，因此 Genrules 無法依賴硬式編碼和/或絕對路徑。
• 如果在多個位置使用相同或非常相似的 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 as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x)。
• 避免建立符號連結和目錄。Bazel 不會複製 genrules 建立的目錄/符號連結結構，且其對目錄的依附元件檢查不健全。
• 在其他規則中參照 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) > $@",
)

引數

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，如 Bazel 來源樹狀目錄中的 stardoc_output.proto 所定義。

隱含輸出目標

• name.binaryproto (預設輸出內容)：ModuleInfo 二進位 protobuf。
• name.textproto (僅在明確要求時建構)：name.binaryproto 的文字版 Protobuf。

警告：這項規則的輸出格式不保證穩定。主要用於 Stardoc 的內部人員。

引數

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 expansion」)，然後建構並測試這些目標。

範例

測試套件，用於執行目前套件中的所有小型測試。

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"],
)

引數