本頁面說明巨集的使用基礎，包括常見用途、偵錯和慣例。
巨集是從 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",
)
在這裡，您會從 //path 套件中的 .bzl 檔案載入 file_generator 符號。將巨集函式定義放在獨立的 .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,
)
您也可以使用巨集將規則串連在一起。這個範例顯示已連結的 genrule，其中 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 檔案，不能用於 WORKSPACE 或 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 workspace, 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)'如要找出
BUILD檔案中產生foo規則的位置，可以嘗試以下訣竅。在BUILD檔案頂端附近插入這行程式碼：cc_library(name = "foo")。執行 Bazel。建立規則foo時會發生例外狀況 (因名稱衝突)，並顯示完整堆疊追蹤。您也可以使用 print 進行偵錯。載入階段期間，系統會以
DEBUG記錄行顯示訊息。除非極少數情況，否則請移除print呼叫，或在預設為False的debugging參數下，將呼叫設為條件式，再將程式碼提交至儲存庫。
錯誤
如要擲回錯誤，請使用 fail 函式。
向使用者清楚說明發生錯誤的原因，以及如何修正 BUILD 檔案。
無法擷取錯誤。
def my_macro(name, deps, visibility=None):
if len(deps) < 2:
fail("Expected at least two values in deps")
# ...
慣例
所有會例項化規則的公開函式 (開頭不是底線的函式) 都必須有
name引數。這個引數不應為選用引數 (請勿提供預設值)。公開函式應使用遵循 Python 慣例的說明字串。
在
BUILD檔案中，巨集的name引數必須是關鍵字引數 (而非位置引數)。巨集產生的規則
name屬性應包含名稱引數做為前置字元。舉例來說，macro(name = "foo")可以產生cc_libraryfoo和 genrulefoo_gen。在大多數情況下，選用參數的預設值應為
None。None可以直接傳遞至原生規則，系統會將其視為您未傳遞任何引數。因此，您不必為此目的將其替換為0、False或[]。巨集應改為延遲至其建立的規則，因為這些規則的預設值可能很複雜，或會隨時間變更。此外，透過查詢語言或建構系統內部存取時，明確設為預設值的參數與從未設定 (或設為None) 的參數看起來不同。巨集應有選用的
visibility引數。