本頁面將說明使用巨集的基本概念，並介紹常見的用途、偵錯和慣例。
巨集是從 BUILD 檔案呼叫的函式，可將規則例項化。巨集主要用於封裝現有規則和其他巨集的程式碼，並重複使用這些程式碼。
巨集有兩種類型：本頁所述的符號巨集和舊版巨集。建議您盡可能使用符號巨集，以便清楚顯示程式碼。
符號巨集提供類型引數 (字串轉換為標籤，相對於巨集呼叫的位置)，以及限制和指定建立目標的顯示設定的功能。這些類別的設計可接受延遲評估 (將在日後的 Bazel 版本中新增)。根據預設，Bazel 8 會提供符號巨集。本文件提到 macros 時，是指符號巨集。
您可以在 範例存放區中找到符號巨集的可執行範例。
用量
在 .bzl 檔案中定義巨集時，請呼叫 macro() 函式，並傳入兩個必要參數：attrs 和 implementation。
屬性
attrs 會接受屬性名稱至屬性類型的字典，代表巨集的引數。兩個常見的屬性 name 和 visibility 會隱含地新增至所有巨集，但不會包含在傳遞至 attrs 的字典中。
# macro/macro.bzl
my_macro = macro(
attrs = {
"deps": attr.label_list(mandatory = True, doc = "The dependencies passed to the inner cc_binary and cc_test targets"),
"create_test": attr.bool(default = False, configurable = False, doc = "If true, creates a test target"),
},
implementation = _my_macro_impl,
)
屬性類型宣告可接受 參數 mandatory、default 和 doc。大部分屬性類型也接受 configurable 參數，這項參數會決定屬性是否接受 select。如果屬性為 configurable，則會將非 select 值解析為無法設定的 select，"foo" 會變成 select({"//conditions:default": "foo"})。如要瞭解詳情，請參閱「選取」。
屬性繼承
巨集通常用於包裝規則 (或其他巨集)，而巨集作者通常會使用 **kwargs，將包裝符號的大部分屬性原封不動地轉送至巨集的主要目標 (或主要內部巨集)。
為支援此模式，巨集可以將規則或巨集符號傳遞至 macro() 的 inherit_attrs 引數，藉此繼承規則或其他巨集的屬性。(您也可以使用特殊字串 "common" 取代規則或巨集符號，以便繼承為所有 Starlark 建構規則定義的通用屬性)。只有公開屬性會繼承，而且巨集專屬 attrs 字典中的屬性會覆寫同名繼承屬性。您也可以使用 None 做為 attrs 字典中的值，移除繼承的屬性：
# macro/macro.bzl
my_macro = macro(
inherit_attrs = native.cc_library,
attrs = {
# override native.cc_library's `local_defines` attribute
local_defines = attr.string_list(default = ["FOO"]),
# do not inherit native.cc_library's `defines` attribute
defines = None,
},
...
)
無論原始屬性定義的預設值為何，非必要的繼承屬性預設值一律會覆寫為 None。如果您需要檢查或修改繼承的非必要屬性 (例如，如果您想在繼承的 tags 屬性中新增標記)，請務必在巨集的實作函式中處理 None 情況：
# macro/macro.bzl
_my_macro_implementation(name, visibility, tags, **kwargs):
# Append a tag; tags attr is an inherited non-mandatory attribute, and
# therefore is None unless explicitly set by the caller of our macro.
my_tags = (tags or []) + ["another_tag"]
native.cc_library(
...
tags = my_tags,
**kwargs,
)
...
實作
implementation 會接受包含巨集邏輯的函式。實作函式通常會透過呼叫一或多個規則來建立目標，且通常為私有 (名稱開頭為底線)。傳統上，這些函式會與巨集同名，但前置字串為 _，後置字串為 _impl。
與規則實作函式不同，規則實作函式會採用單一引數 (ctx)，其中包含屬性參照，而巨集實作函式會為每個引數接受參數。
# macro/macro.bzl
def _my_macro_impl(name, visibility, deps, create_test):
cc_library(
name = name + "_cc_lib",
deps = deps,
)
if create_test:
cc_test(
name = name + "_test",
srcs = ["my_test.cc"],
deps = deps,
)
如果巨集繼承屬性，其實作函式「必須」具有 **kwargs 剩餘關鍵字參數，可將其轉送至叫用繼承規則或子巨集的呼叫。(這有助於確保如果您繼承的規則或巨集新增了新屬性，巨集不會因此中斷)。
聲明
您可以透過在 BUILD 檔案中載入及呼叫巨集定義，宣告巨集。
# pkg/BUILD
my_macro(
name = "macro_instance",
deps = ["src.cc"] + select(
{
"//config_setting:special": ["special_source.cc"],
"//conditions:default": [],
},
),
create_tests = True,
)
這會建立 //pkg:macro_instance_cc_lib 和 //pkg:macro_instance_test 目標。
就像規則呼叫一樣，如果巨集呼叫中的屬性值設為 None，系統會將該屬性視為由巨集呼叫端省略。舉例來說，以下兩個巨集呼叫的作用相同：
# pkg/BUILD
my_macro(name = "abc", srcs = ["src.cc"], deps = None)
my_macro(name = "abc", srcs = ["src.cc"])
這項功能通常不適用於 BUILD 檔案，但在以程式輔助方式將巨集包裝在另一個巨集內時，這項功能就很實用。
詳細資料
建立目標的命名慣例
由符號巨集建立的任何目標或子巨集名稱，必須與巨集的 name 參數相符，或是前置 name，後接 _ (建議)、. 或 -。舉例來說，my_macro(name = "foo") 可能只會建立名為 foo 的檔案或目標，或是前置字串為 foo_、foo- 或 foo. 的檔案或目標，例如 foo_bar。
您可以宣告違反巨集命名慣例的目標或檔案，但無法建構，也無法用作依附元件。
與巨集例項位於相同套件中的非巨集檔案和目標，名稱應不與潛在的巨集目標名稱衝突，但系統不會強制執行這項排他性規定。我們正在實作延遲評估功能，以改善符號巨集的效能，因為在違反命名架構的套件中，符號巨集會受到影響。
限制
符號巨集與舊版巨集相比，有額外的限制。
符號巨集
- 必須使用
name引數和visibility引數 - 必須具備
implementation函式 - 可能不會傳回值
- 可能不會變更其引數
- 除非是特殊的
finalizer巨集，否則不得呼叫native.existing_rules() - 可能無法呼叫
native.package() - 可能不會呼叫
glob() - 可能無法呼叫
native.environment_group() - 必須建立名稱符合命名架構的目標
- 無法參照未宣告或未以引數傳入的輸入檔案 (詳情請參閱「可見度和巨集」)。
可見度和巨集
可見度系統可協助保護 (符號) 巨集和其呼叫端的實作詳細資料。
根據預設，在符號巨集中建立的目標會顯示在巨集本身中，但不一定會顯示在巨集的呼叫端。巨集可以透過轉送自身 visibility 屬性的值，將目標「匯出」為公開 API，如 some_rule(..., visibility = visibility) 所示。
巨集可見度的關鍵概念如下：
系統會根據宣告目標的巨集，而非呼叫巨集的套件，來檢查可見度。
- 換句話說，同一個套件中的目標並不會自動對其他目標可見。這可避免巨集的內部目標成為套件中其他巨集或頂層目標的依附元件。
規則和巨集的所有
visibility屬性都會自動納入呼叫規則或巨集的位置。- 因此，同一個巨集 (或
BUILD檔案，如果不在巨集中) 中宣告的其他目標，會無條件地向目標顯示。
- 因此，同一個巨集 (或
實際上，這表示當巨集宣告目標時，如果未設定其 visibility，目標預設為巨集內部。(套件的預設瀏覽權限不適用於巨集內)。匯出目標，表示目標對巨集的 visibility 屬性中指定的巨集呼叫端、巨集呼叫端本身的套件，以及巨集本身的程式碼可見。換個角度來看，巨集的瀏覽權限會決定除了巨集本身以外，誰可以查看巨集匯出的目標。
# tool/BUILD
...
some_rule(
name = "some_tool",
visibility = ["//macro:__pkg__"],
)
# macro/macro.bzl
def _impl(name, visibility):
cc_library(
name = name + "_helper",
...
# No visibility passed in. Same as passing `visibility = None` or
# `visibility = ["//visibility:private"]`. Visible to the //macro
# package only.
)
cc_binary(
name = name + "_exported",
deps = [
# Allowed because we're also in //macro. (Targets in any other
# instance of this macro, or any other macro in //macro, can see it
# too.)
name + "_helper",
# Allowed by some_tool's visibility, regardless of what BUILD file
# we're called from.
"//tool:some_tool",
],
...
visibility = visibility,
)
my_macro = macro(implementation = _impl, ...)
# pkg/BUILD
load("//macro:macro.bzl", "my_macro")
...
my_macro(
name = "foo",
...
)
some_rule(
...
deps = [
# Allowed, its visibility is ["//pkg:__pkg__", "//macro:__pkg__"].
":foo_exported",
# Disallowed, its visibility is ["//macro:__pkg__"] and
# we are not in //macro.
":foo_helper",
]
)
如果 my_macro 是使用 visibility = ["//other_pkg:__pkg__"] 呼叫，或是 //pkg 套件已將其 default_visibility 設為該值，則 //pkg:foo_exported 也可用於 //other_pkg/BUILD 或 //other_pkg:defs.bzl 中定義的巨集，但 //pkg:foo_helper 仍會受到保護。
巨集可以傳遞 visibility = ["//some_friend:__pkg__"] (針對內部目標) 或 visibility = visibility + ["//some_friend:__pkg__"] (針對匯出的目標)，宣告目標對友好套件可見。請注意，巨集宣告具有公開可見度 (visibility = ["//visibility:public"]) 的目標是反模式。這是因為即使呼叫端指定了更受限制的可見度，巨集也會讓目標無條件地向每個套件顯示。
所有可見度檢查都會以目前執行的內層符號巨集為準。不過，我們也提供可見度委派機制：如果巨集將標籤做為屬性值傳遞至內部巨集，內部巨集會根據外部巨集檢查標籤的任何用法。詳情請參閱「顯示設定」頁面。
請注意，舊版巨集對可見度系統完全透明，而且會以呼叫來源的 BUILD 檔案或符號巨集為位置運作。
選取
如果屬性為 configurable (預設)，且其值並非 None，則巨集實作函式會將屬性值視為包裝在簡單的 select 中。這樣一來，巨集作者就能更輕鬆地找出未預期屬性值可能為 select 的錯誤。
舉例來說，請參考以下巨集：
my_macro = macro(
attrs = {"deps": attr.label_list()}, # configurable unless specified otherwise
implementation = _my_macro_impl,
)
如果 my_macro 是使用 deps = ["//a"] 叫用，則會導致 _my_macro_impl 以其 deps 參數設為 select({"//conditions:default":
["//a"]}) 的狀態下叫用。如果這會導致實作函式失敗 (例如，因為程式碼嘗試將索引標示為 deps[0] 中的值，而 select 不允許這類操作)，巨集作者可以做出選擇：重新撰寫巨集，只使用與 select 相容的作業，或是將屬性標示為不可設定 (attr.label_list(configurable = False))。後者可確保使用者無法傳入 select 值。
規則目標會反向執行這項轉換作業，並將簡單的 select 儲存為無條件值；在上述範例中，如果 _my_macro_impl 宣告規則目標 my_rule(..., deps = deps)，則該規則目標的 deps 會儲存為 ["//a"]。這可確保 select 包裝不會導致在由巨集例項化的所有目標中儲存瑣碎的 select 值。
如果可設定屬性的值為 None，則不會包裝在 select 中。這可確保 my_attr == None 等測試仍能正常運作，且當屬性轉送至具有計算預設值的規則時，規則會正常運作 (也就是說，就如同完全未傳入屬性一樣)。屬性不一定會採用 None 值，但 attr.label() 類型和任何繼承的非必要屬性都可能會採用。
終結器
規則完成器是特殊的符號巨集，無論其在 BUILD 檔案中的字彙位置為何，都會在載入套件的最後階段評估，也就是在定義所有非完成器目標後。與一般符號式巨集不同，終結器可以呼叫 native.existing_rules()，其行為與舊版巨集略有不同：只會傳回一組非終結器規則目標。終結器可能會針對該集合的狀態提出斷言，或定義新的目標。
如要宣告終結器，請使用 finalizer = True 呼叫 macro()：
def _my_finalizer_impl(name, visibility, tags_filter):
for r in native.existing_rules().values():
for tag in r.get("tags", []):
if tag in tags_filter:
my_test(
name = name + "_" + r["name"] + "_finalizer_test",
deps = [r["name"]],
data = r["srcs"],
...
)
continue
my_finalizer = macro(
attrs = {"tags_filter": attr.string_list(configurable = False)},
implementation = _impl,
finalizer = True,
)
懶惰
重要事項：我們正在實作延遲巨集展開和評估功能。這項功能尚未推出。
目前，系統會在載入 BUILD 檔案後立即評估所有巨集，這可能會對套件中目標的效能造成負面影響，因為這些套件也包含耗用大量資源的無關巨集。日後，只有在建構作業需要非完成器符號巨集時，系統才會評估這些巨集。前置字串命名結構定義可協助 Bazel 判斷要針對要求的目標展開哪個巨集。
遷移作業疑難排解
以下列舉一些常見的遷移問題和解決方法。
- 舊版巨集呼叫
glob()
將 glob() 呼叫移至 BUILD 檔案 (或從 BUILD 檔案呼叫的舊版巨集)，然後使用標籤清單屬性將 glob() 值傳遞至符號巨集：
# BUILD file
my_macro(
...,
deps = glob(...),
)
- 舊版巨集的參數不是有效的 starlark
attr類型。
盡可能將邏輯移至巢狀符號式巨集，但請將頂層巨集設為舊版巨集。
- 舊版巨集會呼叫規則，建立違反命名結構定義的目標
沒關係，只要不要依賴「違規」目標即可。系統會悄悄略過命名檢查。