一般規則

規則

• 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)

與預期的設定狀態相符 (以建構標記或平台限制表示)，以便觸發可設定的屬性。如需一般功能簡介，請參閱「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 與目前設定狀態相符時會發生什麼事，請參閱「選取」。
• 對於支援簡寫形式的旗標 (例如 --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(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",
    ],
)

引數

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() 會執行 Blaze 查詢語言 中指定的查詢，並將結果轉儲至檔案。

為了維持建構作業的一致性，查詢只能造訪 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。

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

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

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

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

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

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

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

特殊情況

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

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

Genrule 環境

genrule 指令由 Bash 殼層執行，設為在指令或管道故障時執行失敗，使用 set -e -o pipefail。

建構工具會在經過淨化的程序環境中執行 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 用於定義一組測試，這些測試對使用者來說「實用」。這可讓專案定義一組測試，例如「您必須在簽入前執行的測試」、「專案的壓力測試」或「所有小型測試」。blaze test 指令會遵循這種組織方式：對於 blaze test //some/test:suite 這類叫用，Blaze 會先列舉 //some/test:suite 目標間接包含的所有測試目標 (我們稱之為「test_suite expansion」)，然後 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"],
)

引數