巨集

本頁將介紹巨集使用基本概念，並涵蓋常見用途。偵錯和慣例

巨集是從 BUILD 檔案呼叫的函式，可用來建立規則例項。巨集主要用於封裝和重複使用現有規則的程式碼和其他巨集結尾載入階段，巨集已不存在而 Bazel 只會看到具體的例項化規則組合。

用量

巨集的常見用途是重複使用規則。

例如，BUILD 檔案中的 genrule 會使用 //:generator，其中含有硬式編碼的 some_arg 引數：

genrule(
    name = "file",
    outs = ["file.txt"],
    cmd = "$(location //:generator) some_arg > $@",
    tools = ["//:generator"],
)

如要產生更多使用不同引數的檔案，建議您將這段程式碼擷取至巨集函式假設巨集 file_generator 包含 name 和 arg 參數將 genrule 替換為下列內容：

load("//path:generator.bzl", "file_generator")

file_generator(
    name = "file",
    arg = "some_arg",
)

file_generator(
    name = "file-two",
    arg = "some_arg_two",
)

file_generator(
    name = "file-three",
    arg = "some_arg_three",
)

您可以從這裡的 .bzl 檔案載入 file_generator 符號。 //path 套件中。將巨集函式定義放在獨立的 .bzl 檔案，讓 BUILD 檔案保持清理及宣告式「.bzl」可以從工作區中的任何套件載入。

最後，在 path/generator.bzl 中，將巨集的定義寫入封裝原始 genrule 定義並參數化：

def file_generator(name, arg, visibility=None):
  native.genrule(
    name = name,
    outs = [name + ".txt"],
    cmd = "$(location //:generator) %s > $@" % arg,
    tools = ["//:generator"],
    visibility = visibility,
  )

您也可以使用巨集將規則鏈結在一起。這個範例顯示鏈結 genrules，其中 Genrule 使用前一個 Genrule 的輸出內容做為輸入內容：

def chained_genrules(name, visibility=None):
  native.genrule(
    name = name + "-one",
    outs = [name + ".one"],
    cmd = "$(location :tool-one) $@",
    tools = [":tool-one"],
    visibility = ["//visibility:private"],
  )

  native.genrule(
    name = name + "-two",
    srcs = [name + ".one"],
    outs = [name + ".two"],
    cmd = "$(location :tool-two) $< $@",
    tools = [":tool-two"],
    visibility = visibility,
  )

這個範例只會將瀏覽權限值指派給第二個 Genrule。這樣一來，巨集作者可以隱藏中繼規則的輸出內容工作區內其他目標。

展開巨集

如要調查巨集的用途，請使用 query 指令，並加上 --output=build，即可查看展開的表單：

$ bazel query --output=build :file
# /absolute/path/test/ext.bzl:42:3
genrule(
  name = "file",
  tools = ["//:generator"],
  outs = ["//test:file.txt"],
  cmd = "$(location //:generator) some_arg > $@",
)

將原生規則例項化

原生規則 (不需要 load() 陳述式的規則) 可以是從 native 模組例項化：

def my_macro(name, visibility=None):
  native.cc_library(
    name = name,
    srcs = ["main.cc"],
    visibility = visibility,
  )

如果您需要知道套件名稱 (例如，BUILD 檔案巨集)，請使用 native.package_name() 函式。請注意，native 只能用於 .bzl 檔案，無法用於 BUILD 檔案。

巨集中的標籤解析度

由於巨集是在載入階段接受評估，系統會解讀在巨集中發生的標籤字串，例如 "//foo:bar" 相對於使用巨集的 BUILD 檔案在其中定義的 .bzl 檔案。這種行為通常不適合以便用於其他存放區中的巨集隸屬於已發布的 Starlark 規則集。

如要取得與 Starlark 規則相同的行為，請使用 Label 建構函式：

# @my_ruleset//rules:defs.bzl
def my_cc_wrapper(name, deps = [], **kwargs):
  native.cc_library(
    name = name,
    deps = deps + select({
      # Due to the use of Label, this label is resolved within @my_ruleset,
      # regardless of its site of use.
      Label("//config:needs_foo"): [
        # Due to the use of Label, this label will resolve to the correct target
        # even if the canonical name of @dep_of_my_ruleset should be different
        # in the main repo, such as due to repo mappings.
        Label("@dep_of_my_ruleset//tools:foo"),
      ],
      "//conditions:default": [],
    }),
    **kwargs,
  )

偵錯

bazel query --output=build //my/path:all 會向你說明 BUILD 檔案的方式外觀所有巨集、glob、迴圈已展開。已知限制：select 運算式目前未顯示在輸出內容中。
您可以根據 generator_function (哪個函式) 篩選輸出內容產生的規則) 或 generator_name (巨集的名稱屬性)： bash $ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'
如要找出 foo 規則在 BUILD 檔案中的確切產生位置，您必須可以試試以下技巧在 BUILD 頂端附近插入這一行檔案：cc_library(name = "foo")。執行 Bazel。如遇此情況，由於名稱衝突，系統建立「foo」規則，會顯示或完整的堆疊追蹤
您也可以使用 print 進行偵錯。顯示在載入階段，將訊息顯示為 DEBUG 記錄行。例外情況請移除 print 呼叫，或是在 debugging 參數在提交程式碼給False 開始訓練

錯誤

如要擲回錯誤，請使用 fail 函式。向使用者清楚說明發生錯誤的原因，以及如何修正 BUILD 檔案。無法擷取錯誤。

def my_macro(name, deps, visibility=None):
  if len(deps) < 2:
    fail("Expected at least two values in deps")
  # ...

慣例

所有未以底線開頭的公開函式，例項化規則必須具備 name 引數。這個引數不應選填 (不指定預設值)。
公開函式應在 Python 後面使用 docstring 慣例。
在 BUILD 檔案中，巨集的 name 引數必須是關鍵字引數 (並非位置引數)。
巨集產生的規則的 name 屬性應包含名稱做為前置字串舉例來說，macro(name = "foo") 可以產生 cc_library foo 和 genrule foo_gen。
在大多數情況下，選用參數應有預設值 None。 None 可以直接傳遞至原生規則，其視為與輸入的值。因此您不需要更換搭配 0、False 或 [] 使用。相反地因為預設值可能很複雜，也可能發生在讓應用程式從可以最快做出回應的位置回應使用者要求此外，還有一個明確設定為其預設值的參數看起來與存取時從未設定 (或設為 None) 的值不同查詢語言或建構系統內部資訊
巨集應有選用的 visibility 引數。