一般規則

規則

• 別名
• config_setting
• filegroup
• genquery
• genrule
• test_suite

別名

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

alias 規則會建立另一個可參照的規則名稱。

別名僅適用於「一般」目標。請特別注意，package_group 和 test_suite 不能以別名顯示。

別名規則有自己的瀏覽權限宣告。在所有其他方面，其行為類似它所參照的規則 (例如，忽略別名的測試項目，改用參照規則的僅供測試性)，但有一些細微例外情況：

• 如果在指令列上提及別名，則不會執行測試。如要定義執行參照測試的別名，請在其 tests 屬性中使用具有單一目標的 test_suite 規則。
• 定義環境群組時，不支援 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",
      ]
  )
  

Notes

• 如果多個 config_setting 符合目前的設定狀態，請參閱 select 一節。
• 對於支援簡寫形式的標記 (例如，--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 都必須設定至少一個組合。

引數

            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 建立測試資料目錄：

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, 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 的輸出，以便強制執行確定性輸出。

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

範例

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

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

引數

產生規則

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 指令產生一個或多個檔案。

Gen 規則 是一般的建構規則，沒有該工作沒有具體規則時可用。 例如，您可以執行 Bash 單行模式。不過，如果您需要編譯 C++ 檔案，請繼續使用現有的 cc_* 規則，因為所有繁重的作業都已為您完成。

請注意，genrule 需要殼層來解讀指令引數。 此外，您可以輕鬆參照 PATH 上的任意程式，但這會導致指令本身不具標準，而且可能無法重現。如果只需要執行單一工具，請考慮改用 run_binary。

請勿使用 genrule 執行測試。測試和測試結果有特殊分配，包括快取政策和環境變數。一般來說，必須在建構完成後和目標架構上執行，而在建構和執行架構 (在兩者中) 可能會執行 genrule。如果您需要一般用途測試規則，請使用 sh_test。

跨平台程式碼的考量要素

請參閱使用者手冊，進一步瞭解跨平台程式碼編譯。

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

建構系統會使用執行設定來說明執行建構作業的機器，以及透過目標設定來說明執行建構作業的機器。這項功能可以設定個別檔案，並將對應的檔案分隔成不同的目錄，以免發生衝突。

針對 gen 規則，建構系統會確保依附元件的建構正確：如有必要，系統會針對目標設定建構 srcs，為exec 設定建構 tools，並將輸出視為目標設定。同時還會提供 「Make」變數，Gengen 指令可傳遞至對應的工具。

實際上，genrule 並未定義 deps 屬性：其他內建規則會在規則之間傳遞語言相關的中繼資訊，自動判斷如何處理相依規則，但這項自動化作業無法進行這項自動化作業。Gen 規則 僅用於檔案和執行檔案層級。

特殊情況

執行編譯編譯：在某些情況下，建構必須執行 gen 規則，才能在輸出期間執行輸出。舉例來說，如果 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) 來輸出、工具及來源。由於不同的設定會輸出輸出檔案，因此 genrule 無法依賴硬式編碼和/或絕對路徑。
• 請撰寫常見的 Starlark 巨集，以便在多個位置使用相同或非常相似的基因。如果 genrule 相當複雜，請考慮以指令碼或 Starlark 規則實作。如此可提升可讀性和測試能力。
• 確認結束代碼已正確表示 產生規則的成敗，
• 請勿將資訊訊息寫入 stdout 或 stderr。雖然偵錯功能很有用，但很容易造成雜訊；成功的 Ge 規則應該是靜音。另一方面，失敗的 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 不會複製由 genrule 建立的目錄/符號連結結構，而且會檢查目錄的依附元件檢查作業沒有問題。
• 在其他規則中參照 genrule 時，您可以使用 genrule 的標籤或個別輸出檔案的標籤。有時其中一種方法比較容易理解，有時另一種方法：在使用規則的 srcs 中參照名稱時，會避免無意擷取其他規則的輸出，但如果生成規則產生許多輸出，這可能會很慢。

範例

這個範例會產生 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) > $@",
)

引數

測試套件

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 擴充」)，然後 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"],
)

引數