規則

回報問題 查看原始碼 夜間 7.4 ，直接在 Google Cloud 控制台實際操作。 7.3 7.2 7.1 7.0 6.5

規則可定義 Bazel 執行的一系列動作 會產生一組輸出內容，在 規則傳回的 providers 實作函式。舉例來說，C++ 二進位規則可能會：

1. 採用一組 .cpp 來源檔案 (輸入)。
2. 在來源檔案 (動作) 上執行 g++。
3. 傳回 DefaultInfo 供應器，並提供可在執行階段使用的執行檔輸出內容和其他檔案。
4. 傳回 CcInfo 供應器，其中包含從目標和依附元件收集到的 C++ 專屬資訊。

從 Bazel 的角度來看，g++ 和標準 C++ 程式庫也是此規則的輸入內容。規則編寫者除了必須考量使用者提供的規則輸入內容，還必須考量執行動作所需的所有工具和程式庫。

建立或修改任何規則前，請務必熟悉 Bazel 的建構階段。請務必瞭解 各階段 (載入、分析和執行) 的階段。這項工具也很實用 瞭解巨集來瞭解規則與 巨集。如要開始使用，請先參閱規則教學課程。然後參考這個頁面。

Bazel 本身就內建了一些規則。這些原生規則 (例如 cc_library 和 java_binary) 可為特定語言提供一些核心支援。定義自己的規則後，您就能為 Bazel 不支援的語言和工具新增類似的支援功能。

Bazel 提供可擴充性模型，可使用 Starlark 語言編寫規則。這些規則會以 .bzl 檔案編寫，可直接從 BUILD 檔案載入。

定義規則時，您可以決定規則支援哪些屬性，以及產生輸出內容的方式。

該規則的 implementation 函式會定義其在操作期間發生的確切行為， 分析階段。這個函式不會執行 以及外部指令而是會註冊即將使用的動作 並建構該規則的輸出內容 。

建立規則

在 .bzl 檔案中，使用 rule 函式定義新的規則，並將結果儲存在全域變數中。呼叫 rule 會指定 屬性和 實作函式：

example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        "deps": attr.label_list(),
        ...
    },
)

這會定義名為 example_library 的規則種類。

對 rule 的呼叫也必須指定規則是否要建立可執行輸出內容 (使用 executable=True)，或特別建立測試可執行內容 (使用 test=True)。如果是後者，規則就是測試規則，且規則名稱必須以 _test 結尾。

目標例項化

您可以在 BUILD 檔案中載入及呼叫規則：

load('//some/pkg:rules.bzl', 'example_library')

example_library(
    name = "example_target",
    deps = [":another_target"],
    ...
)

對建構規則的每個呼叫都不會傳回任何值，但會產生定義目標的副作用。這稱為「執行個體化」規則。這會為 新的目標和目標屬性的值。

您也可以從 Starlark 函式呼叫規則，並在 .bzl 檔案中載入。呼叫規則的 Starlark 函式稱為 Starlark 巨集。Starlark 巨集最終必須從 BUILD 檔案呼叫，且只能 會在載入階段呼叫，如果 BUILD 檔案會評估以將目標執行個體化。

屬性

屬性是規則引數。屬性可以提供特定值給 目標的實作，或參照 建立依附關係圖

如要定義規則專屬屬性 (例如 srcs 或 deps)，請將屬性名稱的對應項目從架構 (使用 attr 模組建立) 傳遞至 rule 的 attrs 參數。常見屬性，例如 所有規則會間接加入 name 和 visibility。系統會將其他屬性隱含地新增至可執行和測試規則。隱含新增至規則的屬性，無法納入傳遞至 attrs 的字典中。

依附元件屬性

處理來源程式的規則通常會定義下列屬性，以處理各種依附元件類型：

• srcs 會指定由目標動作處理的來源檔案。這通常 屬性結構定義會指定應使用哪些副檔名。 所處理的來源檔案針對含有標頭檔案的語言，規則通常會為目標及其使用者處理的標頭指定個別的 hdrs 屬性。
• deps 會指定目標的程式碼依附元件。屬性結構定義應指定這些依附元件必須提供哪些供應器。(對於 例如，cc_library 提供 CcInfo)。
• data 會指定要讓任何依賴目標的可執行檔在執行階段可用的檔案。這樣可以允許任意檔案 。

example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = [".example"]),
        "hdrs": attr.label_list(allow_files = [".header"]),
        "deps": attr.label_list(providers = [ExampleInfo]),
        "data": attr.label_list(allow_files = True),
        ...
    },
)

這些是依附元件屬性的範例。任何指定輸入標籤的屬性 (使用 attr.label_list、attr.label 或 attr.label_keyed_string_dict 定義的屬性)，會在定義目標時，在該屬性中列出目標和標籤 (或對應的 Label 物件) 之間的特定類型依附元件。這些標籤的存放區 (可能還有路徑) 會相對於定義的目標進行解析。

example_library(
    name = "my_target",
    deps = [":other_target"],
)

example_library(
    name = "other_target",
    ...
)

在這個範例中，other_target 是 my_target 的依附元件，因此 會先分析「other_target」。如果 目標依附元件圖

私人屬性和隱含依附元件

含有預設值的依附元件屬性會建立隱含依附元件。這是隱含的值，因為它是目標圖表的一部分，而使用者並未在 BUILD 檔案中指定該值。隱含依附性非常適合以硬式編碼的方式 規則與工具之間的關係 (建構時間依附元件，例如 編譯器)，因為使用者大部分的時間大多沒有指定 都會套用這個政策在規則的實作函式中，系統會將這 與其他依附元件相同

如何提供隱含依附元件，但不允許使用者 可以覆寫這個值，就可以為屬性命名，藉此將屬性設為 private 開頭為底線 (_)。私人屬性必須含有預設值 輕鬆分配獎金一般來說，只有在隱含依附元件時，才建議使用私人屬性。

example_library = rule(
    implementation = _example_library_impl,
    attrs = {
        ...
        "_compiler": attr.label(
            default = Label("//tools:example_compiler"),
            allow_single_file = True,
            executable = True,
            cfg = "exec",
        ),
    },
)

在這個範例中，每個 example_library 類型的目標都會對編譯器 //tools:example_compiler 有隱含的依附元件。這樣一來， example_library 的實作函式，可產生叫用 編譯器。開始時間 _compiler 是私有屬性，遵循 ctx.attr._compiler 一律會指向這項規則的所有目標中的 //tools:example_compiler 類型。或者，您也可以將屬性命名為 compiler，但不要加入 並保留預設值如此一來，使用者就能將 不同的編譯器，但不需要瞭解編譯器的 標籤。

隱含依附元件通常用於與規則實作位於相同存放區的工具。如果工具來自 執行平台或其他存放區 規則應透過工具鍊取得該工具。

輸出屬性

輸出屬性，例如 attr.output 和 attr.output_list，宣告輸出檔案 並產生目標這與依附元件屬性的差異有兩種：

• 用於定義輸出檔案目標，而非參照已定義的目標 如果其他位置需要使用資源 Compute Engine 有權終止工作
• 輸出檔案目標取決於已例項化的規則目標，而非相反。

一般而言，只有在規則需要建立輸出內容時，才會使用輸出屬性 。如果規則有一個輸出屬性，通常會命名為 out 或 outs。

輸出屬性是建立預先宣告的輸出內容的首選方式，可特別依附或在指令列中要求。

實作函式

每個規則都需要 implementation 函式。系統會執行 進行的分析階段，並將 載入階段產生的目標圖表 要執行的動作。因此 實作函式無法實際讀取或寫入檔案。

規則實作函式通常為私有 (名稱開頭為底線)。一般情況下，這些變數的名稱與規則相同，但後置字元 只在 _impl。

實作函式僅接受一個參數： 「規則內容」，通常命名為 ctx。這些方法會傳回供應商清單。

目標

在分析期間，依附元件會以 Target 物件表示。這些物件包含當 已執行目標的實作函式。

ctx.attr 有對應各個欄位名稱的欄位 依附元件屬性，包含 Target 物件，代表每個直接管道 透過該屬性取得依附元件對於 label_list 屬性，這是 Targets 的清單。對於 label 屬性，則是單一 Target 或 None。

目標的實作函式會傳回提供者物件清單：

return [ExampleInfo(headers = depset(...))]

您可以使用索引符號 ([]) 存取這些項目，並將提供者類型做為索引鍵。這些可以是 Starlark 中定義的自訂供應器，或是可做為 Starlark 全域變數使用的原生規則供應器。

舉例來說，如果規則透過 hdrs 屬性取得標頭檔案，並提供 再加上目標及其消費者的編譯動作 資料收集方式如下：

def _example_library_impl(ctx):
    ...
    transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs]

針對舊版樣式，其中 struct 是從目標的實作函式傳回，而非提供者物件清單：

return struct(example_info = struct(headers = depset(...)))

您可以從 Target 物件的對應欄位擷取提供者：

transitive_headers = [hdr.example_info.headers for hdr in ctx.attr.hdrs]

強烈建議不要採用這個樣式，規則應該設為 錯誤遷移。

檔案

檔案會以 File 物件表示。由於 Bazel 不會在分析階段執行檔案 I/O，因此這些物件無法用於直接讀取或寫入檔案內容。而是會轉向行動 函式 (請參閱 ctx.actions) 來建立 動作圖表

File 可以是來源檔案或產生的檔案。每個產生的檔案 必須是一項動作的輸出內容。來源檔案不得是任何動作的輸出內容。

每個依附元件屬性的對應欄位 ctx.files 包含所有預設輸出內容的清單 透過該屬性指定依附元件：

def _example_library_impl(ctx):
    ...
    headers = depset(ctx.files.hdrs, transitive=transitive_headers)
    srcs = ctx.files.srcs
    ...

ctx.file 包含一個 File 或 None： 規格設為 allow_single_file=True 的依附元件屬性。 ctx.executable 的運作方式與 ctx.file 相同，但只包含依附元件屬性的欄位，且規格已設定 executable=True。

宣告輸出

在分析階段中，規則的實作函式可以建立輸出內容。由於所有標籤都必須在載入階段中知悉，因此這些額外的輸出內容沒有標籤。您可以使用 ctx.actions.declare_file 和 ctx.actions.declare_directory 建立輸出項目的 File 物件。這通常 輸出內容的名稱取決於目標名稱 ctx.label.name:

def _example_library_impl(ctx):
  ...
  output_file = ctx.actions.declare_file(ctx.label.name + ".output")
  ...

針對預先宣告的輸出內容 (例如為輸出屬性建立的輸出內容)，您可以改為從 ctx.outputs 的對應欄位擷取 File 物件。

動作

動作說明如何從一組輸入內容產生一組輸出內容， 例如「run gcc on hello.c and get hello.o」。建立動作時，Bazel 不會立即執行指令。因為動作可能會依附於其他動作的輸出內容，因此會在依附元件圖中註冊該依附元件。例如在 C 中 就必須在編譯器之後呼叫連結器。

建立動作的通用函式會在 ctx.actions 中定義：

• ctx.actions.run，用於執行可執行檔。
• ctx.actions.run_shell，用於執行殼層 指令
• ctx.actions.write，將字串寫入檔案。
• ctx.actions.expand_template，到 從範本產生檔案

ctx.actions.args 可用於有效累積動作的引數。這能避免在 執行時間：

def _example_library_impl(ctx):
    ...

    transitive_headers = [dep[ExampleInfo].headers for dep in ctx.attr.deps]
    headers = depset(ctx.files.hdrs, transitive=transitive_headers)
    srcs = ctx.files.srcs
    inputs = depset(srcs, transitive=[headers])
    output_file = ctx.actions.declare_file(ctx.label.name + ".output")

    args = ctx.actions.args()
    args.add_joined("-h", headers, join_with=",")
    args.add_joined("-s", srcs, join_with=",")
    args.add("-o", output_file)

    ctx.actions.run(
        mnemonic = "ExampleCompile",
        executable = ctx.executable._compiler,
        arguments = [args],
        inputs = inputs,
        outputs = [output_file],
    )
    ...

動作會採用輸入檔案的清單或 depset，並產生 (非空白) 輸出檔案清單。在分析階段中，必須知道輸入和輸出檔案的組合。它可能會依屬性值而定，包括依附元件的提供者，但不能依執行結果而定。舉例來說，如果您的動作執行瞭解壓縮指令， ，並指定要加載哪些檔案 (在執行解壓縮前)。 在內部建立不同數量檔案的動作，可將這些檔案包裝在單一檔案中 (例如 ZIP、tar 或其他封存格式)。

動作必須列出所有輸入內容。列出未使用的輸入內容 但效率較低

動作必須建立其所有輸出內容。他們可以寫入其他檔案 系統不會將輸出結果中的所有資訊提供給消費者。所有宣告的輸出內容都必須由某些動作寫入。

動作與純功能相當：應只依附於 避免存取電腦資訊、使用者名稱、時鐘 或 I/O 裝置 (讀取輸入和寫入輸出除外)。這點很重要，因為系統會將輸出內容快取並重複使用。

Bazel 會解析依附元件，並決定要執行哪些動作。如果依附元件圖表中有循環，就會發生錯誤。建立中 動作並不保證會執行，取決於是否 建構需要輸出內容

提供者

提供者是規則向依附於該規則的其他規則公開的資訊。這項資料可包含輸出檔案、程式庫和要傳遞的參數 或者任何目標消費者應該知道的事項 介紹生成式 AI 模型

由於規則的實作函式只能讀取例項化目標的直接依附元件的提供者，因此規則需要將目標消費者需要知道的任何資訊從目標依附元件轉寄給消費者，通常是將這些資訊累積到 depset。

目標的提供者是由Provider 實作函式

舊實作函式也可以以舊版樣式編寫，在這種情況下，實作函式會傳回 struct，而非提供者物件的清單。我們強烈建議您不要使用這種樣式，並應將規則從這種樣式中移除。

預設輸出

目標的預設輸出是指在 會透過指令列要求建構目標。舉例來說 java_library 目標 //pkg:foo 的預設輸出為 foo.jar，因此， 都將由 bazel build //pkg:foo 指令建構

預設輸出項目由 DefaultInfo 的 files 參數指定：

def _example_library_impl(ctx):
    ...
    return [
        DefaultInfo(files = depset([output_file]), ...),
        ...
    ]

如果實作規則或 files 沒有傳回 DefaultInfo 未指定參數，DefaultInfo.files 會預設為所有值 預先宣告的輸出內容 (通常是透過 輸出產生的 屬性)。

執行動作的規則應該提供預設輸出內容，即使這些輸出內容 不必直接使用系統會刪除不在所要求輸出內容圖表中的動作。如果只有目標使用者會使用輸出內容， 系統不會在內建目標的情況下執行這些動作。這樣會使除錯作業更加困難，因為只重建失敗的目標不會重現失敗情形。

執行檔

執行檔案是目標在執行階段 (而非建構) 使用的一組檔案 時間)。在執行階段期間，Bazel 會建立目錄樹狀結構，其中包含指向執行檔案的符號連結。這會為二進位檔設定環境，讓二進位檔在執行階段存取執行檔案。

您可以在建立規則時手動新增執行檔。runfiles 物件可透過規則結構定義 ctx.runfiles 上的 runfiles 方法建立，並傳遞至 DefaultInfo 上的 runfiles 參數。可執行規則的可執行輸出內容會隱含新增至執行檔。

某些規則會指定屬性 (通常命名為 data，其輸出內容會新增至 指定目標runfiles.執行檔也應從 data 合併，以及從任何可能提供最終執行程式碼的屬性合併，通常是 srcs (可能包含與 data 相關聯的 filegroup 目標) 和 deps。

def _example_library_impl(ctx):
    ...
    runfiles = ctx.runfiles(files = ctx.files.data)
    transitive_runfiles = []
    for runfiles_attr in (
        ctx.attr.srcs,
        ctx.attr.hdrs,
        ctx.attr.deps,
        ctx.attr.data,
    ):
        for target in runfiles_attr:
            transitive_runfiles.append(target[DefaultInfo].default_runfiles)
    runfiles = runfiles.merge_all(transitive_runfiles)
    return [
        DefaultInfo(..., runfiles = runfiles),
        ...
    ]

自訂供應商

您可以使用 provider 定義供應商 用來表示規則相關資訊：

ExampleInfo = provider(
    "Info needed to compile/link Example code.",
    fields={
        "headers": "depset of header Files from transitive dependencies.",
        "files_to_link": "depset of Files from compilation.",
    })

這樣一來，規則實作函式就能建構並傳回供應器例項：

def _example_library_impl(ctx):
  ...
  return [
      ...
      ExampleInfo(
          headers = headers,
          files_to_link = depset(
              [output_file],
              transitive = [
                  dep[ExampleInfo].files_to_link for dep in ctx.attr.deps
              ],
          ),
      )
  ]

供應器的自訂初始化

您可以使用自訂前置處理和驗證邏輯，保護供應器的例項化作業。這能確保 提供者執行個體會遵循某些不變體，或為使用者提供更簡潔的 API 取得執行個體

方法是將 init 回呼傳遞至 provider 函式。如果提供這個回呼，provider() 的傳回類型會變更為兩個值的元組：提供者符號 (在未使用 init 時為一般傳回值) 和「原始建構函式」。

在此情況下，呼叫提供者符號，而不是直接傳回 新的例項，它會將引數一併轉送至 init 回呼。 回呼的傳回值必須是將欄位名稱 (字串) 對應至值的字典； 此物件可用於初始化新執行個體的欄位。請注意， 回呼可能具有任何簽章，且引數與簽章不符 系統會將錯誤回報為直接叫用回呼。

相較之下，原始建構函式會略過 init 回呼。

以下範例使用 init 預先處理並驗證其引數：

# //pkg:exampleinfo.bzl

_core_headers = [...]  # private constant representing standard library files

# It's possible to define an init accepting positional arguments, but
# keyword-only arguments are preferred.
def _exampleinfo_init(*, files_to_link, headers = None, allow_empty_files_to_link = False):
    if not files_to_link and not allow_empty_files_to_link:
        fail("files_to_link may not be empty")
    all_headers = depset(_core_headers, transitive = headers)
    return {'files_to_link': files_to_link, 'headers': all_headers}

ExampleInfo, _new_exampleinfo = provider(
    ...
    init = _exampleinfo_init)

export ExampleInfo

規則實作項目可能會依照下列方式將提供者例項化：

    ExampleInfo(
        files_to_link=my_files_to_link,  # may not be empty
        headers = my_headers,  # will automatically include the core headers
    )

您可以使用原始建構函式，定義不經過 init 邏輯的其他公開工廠函式。例如，在 exampleinfo.bzl 中 可以定義：

def make_barebones_exampleinfo(headers):
    """Returns an ExampleInfo with no files_to_link and only the specified headers."""
    return _new_exampleinfo(files_to_link = depset(), headers = all_headers)

一般來說，原始建構函式會繫結至名稱開頭為 因此使用者程式碼無法載入_new_exampleinfo 產生任意提供者執行個體

init 的另一個用途是防止使用者呼叫供應器。 符號，並強制要求他們改用工廠函式：

def _exampleinfo_init_banned(*args, **kwargs):
    fail("Do not call ExampleInfo(). Use make_exampleinfo() instead.")

ExampleInfo, _new_exampleinfo = provider(
    ...
    init = _exampleinfo_init_banned)

def make_exampleinfo(...):
    ...
    return _new_exampleinfo(...)

可執行的規則和測試規則

可執行的規則會定義可透過 bazel run 指令叫用的目標。 測試規則是一種特殊的可執行規則，其目標也可以透過 bazel test 指令叫用。可執行和測試規則的建立依據如下 設定對應的 executable 或 在對 rule 呼叫中呼叫 True 的 test 引數：

example_binary = rule(
   implementation = _example_binary_impl,
   executable = True,
   ...
)

example_test = rule(
   implementation = _example_binary_impl,
   test = True,
   ...
)

測試規則的名稱必須以 _test 結尾。(通常也要測試目標名稱 按照慣例在 _test 結尾，但這並非強制規定)。非測試規則不得 都有這個尾碼

這兩種規則必須產生一個可執行的輸出檔案 (不一定可以 run 或 test 指令叫用這些片段。如要告訴 Bazel 要使用哪個規則的輸出項目做為這個可執行檔，請將該項目做為傳回的 DefaultInfo 供應器的 executable 引數傳遞。該 executable 會新增至規則的預設輸出內容中 ( 但不必同時傳遞至 executable 和 files)。這個過程也隱含 新增到 runfiles 中：

def _example_binary_impl(ctx):
    executable = ctx.actions.declare_file(ctx.label.name)
    ...
    return [
        DefaultInfo(executable = executable, ...),
        ...
    ]

產生這個檔案的動作必須設定檔案的可執行位元。對於 ctx.actions.run 或 ctx.actions.run_shell 動作，這項操作應由該動作所叫用的基礎工具執行。針對 ctx.actions.write 動作，請傳遞 is_executable=True。

舊版行為：可執行的規則具有特殊的 ctx.outputs.executable 預先宣告輸出內容。如果您未使用 DefaultInfo 指定執行檔，系統會將這個檔案做為預設執行檔；否則，請勿使用這個檔案。這個輸出機制已淘汰，因為它不支援在分析期間自訂可執行檔案的名稱。

請參閱可執行規則和測試規則的範例。

可執行的規則和 測試規則 除了為 所有規則。預設值 隱性新增的屬性無法變更，但這可以 方法是在 Starlark 巨集中納入私人規則，將 預設：

def example_test(size="small", **kwargs):
  _example_test(size=size, **kwargs)

_example_test = rule(
 ...
)

執行檔案位置

使用 bazel run (或 test) 執行可執行目標時，runfiles 目錄的根目錄會位於可執行檔旁邊。路徑如下：

# Given launcher_path and runfile_file:
runfiles_root = launcher_path.path + ".runfiles"
workspace_name = ctx.workspace_name
runfile_path = runfile_file.short_path
execution_root_relative_path = "%s/%s/%s" % (
    runfiles_root, workspace_name, runfile_path)

runfiles 目錄下 File 的路徑會對應至 File.short_path。

由 bazel 直接執行的二進位檔會位於 runfiles 目錄的根目錄旁邊。不過，從執行檔呼叫的二進位檔無法做出相同假設。為緩解此問題，每個二進位檔都應提供一種方法： 使用環境或指令列，接受其執行檔案根目錄做為參數 引數/旗標這可讓二進位檔將正確的標準執行檔根目錄傳遞至所呼叫的二進位檔。如果未設定，二進位檔可以推測這是第一個呼叫的二進位檔，並尋找相鄰的 runfiles 目錄。

進階主題

要求輸出檔案

單一目標可以有多個輸出檔案。如果 bazel build 指令顯示為 因此系統會將指定該指令的目標輸出內容視為 提出要求。Bazel 只會建構這些要求的檔案，以及這些檔案直接或間接依附的檔案。(就動作圖而言，只有 Bazel 這會執行可做為 要求的檔案)。

除了預設輸出內容之外，任何預先宣告的輸出內容也可以 明確要求規則可以指定預先宣告的 透過輸出屬性執行輸出內容。在這種情況下，使用者在例項化規則時，會明確選擇輸出的標籤。為了達成 針對輸出屬性的 File 物件，請使用對應的 ctx.outputs 的屬性。規則可以 以隱含方式定義預先宣告的輸出內容，是以 加上目標名稱，但這項功能已淘汰。

除了預設輸出之外，還有「輸出群組」，這是集合 可能同時要求的輸出檔案這些資訊都可以透過 --output_groups。適用對象 舉例來說，如果目標 //pkg:mytarget 所屬的規則類型為 debug_files 輸出群組，執行 bazel build //pkg:mytarget --output_groups=debug_files 即可建立這些檔案。由於未預先宣告的輸出項目沒有標籤，因此您只能要求預設輸出項目或輸出群組顯示這些項目。

您可以使用 OutputGroupInfo 提供者。請注意，與許多內建供應器不同，OutputGroupInfo 可使用任意名稱的參數，定義具有該名稱的輸出群組：

def _example_library_impl(ctx):
    ...
    debug_file = ctx.actions.declare_file(name + ".pdb")
    ...
    return [
        DefaultInfo(files = depset([output_file]), ...),
        OutputGroupInfo(
            debug_files = depset([debug_file]),
            all_files = depset([output_file, debug_file]),
        ),
        ...
    ]

與大多數供應商不同的是，只要層面和套用該層面的規則目標未定義相同的輸出群組，OutputGroupInfo 就會由兩者同時傳回。在這種情況下，系統會合併產生的供應者。

請注意，OutputGroupInfo 通常不應用於表示特定排序 檔案和消費者的動作定義 規則專屬供應商。

設定

假設您要為不同架構建構 C++ 二進位檔。建構作業可能相當複雜，並涉及多個步驟。某些中繼二進位檔 (例如編譯器和程式碼產生器) 必須在執行平台上執行 (可能是主機或遠端執行程式)。某些二進位檔 (例如最終輸出內容) 必須針對目標架構建構。

因此，Bazel 採用「設定」的概念和轉場效果最上層的目標 (在指令列上要求的目標) 會在「target」設定中建構，而應在執行平台上執行的工具則會在「exec」設定中建構。規則可能會根據不同條件產生不同動作 設定，例如變更先前傳遞的 CPU 架構 提供給編譯器在某些情況下，不同設定可能需要相同的程式庫。發生這種情況時，系統會分析並可能多次建構該項目。

根據預設，Bazel 會使用與 也就是目標本身，也就是沒有轉場效果如果依附元件是用於建構目標所需的工具，則對應的屬性應指定轉換至執行設定的作業。這會導致工具及其 為執行平台建構的依附元件。

針對每個依附元件屬性，您可以使用 cfg 決定依附元件應在相同設定中建構，還是轉換為執行設定。如果依附元件屬性含有 executable=True 標記，則必須設定 cfg 。這可避免意外為錯誤設定建構工具。查看範例

一般來說， 也能使用相同的設定

在建構作業中執行的工具 (例如編譯器或程式碼產生器) 應針對執行設定進行建構。在這種情況下，請在屬性中指定 cfg="exec"。

否則，在執行階段使用的可執行檔 (例如測試的一部分) 應針對目標設定進行建構。在這種情況下，請在屬性中指定 cfg="target"。

cfg="target" 實際上並不會執行任何操作，它只是方便規則設計人員明確表達意圖的值。發生executable=False時， 這表示 cfg 為選用項目，只有在真正能提升可讀性時才設定此設定。

您也可以使用 cfg=my_transition： 使用者定義的轉場效果 讓規則作者能大幅彈性變更設定 缺點 放大建構圖表，使其較不易理解。

注意：過去 Bazel 並沒有執行平台的概念，而是將所有建構動作視為在主機上執行。Bazel 6.0 以下版本建立了專屬「主機」代表該物件 如果您在程式碼或舊版說明文件中看到「主機」的參照，就是指這個詞。建議您使用 Bazel 6.0 以上版本，避免這項額外的概念額外負擔。

設定片段

規則可存取 設定片段，例如 cpp、java和jvm。不過，您必須宣告所有必要片段，才能避免存取錯誤：

def _impl(ctx):
    # Using ctx.fragments.cpp leads to an error since it was not declared.
    x = ctx.fragments.java
    ...

my_rule = rule(
    implementation = _impl,
    fragments = ["java"],      # Required fragments of the target configuration
    host_fragments = ["java"], # Required fragments of the host configuration
    ...
)

Runfiles 符號連結

一般來說，執行檔案樹狀結構中檔案的相對路徑與 該檔案在來源樹狀結構或產生的輸出樹狀結構中的相對路徑。如果這些值因某些原因而需要不同，您可以指定 root_symlinks 或 symlinks 引數。root_symlinks 是指向 檔案，其中路徑與執行檔案目錄的根目錄相關。symlinks 字典相同，但路徑會隱含地加上主要工作區的名稱 (不是包含目前目標的存放區名稱)。

    ...
    runfiles = ctx.runfiles(
        root_symlinks = {"some/path/here.foo": ctx.file.some_data_file2}
        symlinks = {"some/path/here.bar": ctx.file.some_data_file3}
    )
    # Creates something like:
    # sometarget.runfiles/
    #     some/
    #         path/
    #             here.foo -> some_data_file2
    #     <workspace_name>/
    #         some/
    #             path/
    #                 here.bar -> some_data_file3

如果使用 symlinks 或 root_symlinks，請務必避免將兩個不同的檔案對應至 runfiles 樹狀結構中的相同路徑。這會導致建構作業失敗，並顯示描述衝突的錯誤。如要修正，請修改您的 用於移除衝突的 ctx.runfiles 引數。這項檢查將完成 使用規則的任何目標，以及符合這些規則的任何類型目標 目標。如果你的工具可能會常被用於這類用途，那就特別風險。 由其他工具提供符號連結名稱在工具的執行檔案中不可重複， 所有依附元件

程式碼涵蓋率

執行 coverage 指令時，建構作業可能需要為特定目標新增涵蓋率檢測工具。建構作業也會收集已檢測的來源檔案清單。子集 而這些目標取決於標記所控制的目標 --instrumentation_filter。 系統會排除測試目標，除非 --instrument_test_targets 。

如果規則實作會在建構期間新增涵蓋率檢測，就需要 因為這在實作函式中能反映這一點 ctx.coverage_instrumented 會在 涵蓋率模式，如應檢測目標的來源：

# Are this rule's sources instrumented?
if ctx.coverage_instrumented():
  # Do something to turn on coverage for this compile action

在涵蓋率模式中一律需要開啟的邏輯 (無論目標來源是否已具體檢測)，可視 ctx.configuration.coverage_enabled 而定。

如果規則在編譯前直接納入其依附元件的來源 (例如標頭檔案)，則如果依附元件的來源需要檢測，規則可能也需要開啟編譯時間檢測：

# Are this rule's sources or any of the sources for its direct dependencies
# in deps instrumented?
if (ctx.configuration.coverage_enabled and
    (ctx.coverage_instrumented() or
     any([ctx.coverage_instrumented(dep) for dep in ctx.attr.deps]))):
    # Do something to turn on coverage for this compile action

規則也應提供資訊，說明哪些屬性與 InstrumentedFilesInfo 供應商的涵蓋率相關，並使用 coverage_common.instrumented_files_info 建構。instrumented_files_info 的 dependency_attributes 參數應列出所有執行階段依附元件屬性，包括 deps 等程式碼依附元件，以及 data 等資料依附元件。如果可能要新增涵蓋率檢測工具，source_attributes 參數應列出規則的來源檔案屬性：

def _example_library_impl(ctx):
    ...
    return [
        ...
        coverage_common.instrumented_files_info(
            ctx,
            dependency_attributes = ["deps", "data"],
            # Omitted if coverage is not supported for this rule:
            source_attributes = ["srcs", "hdrs"],
        )
        ...
    ]

如果未傳回 InstrumentedFilesInfo，系統會為每個參數建立預設值 未設定的非工具依附元件屬性 屬性結構定義中的 cfg 變更為 "host" 或 "exec") dependency_attributes。(這並不是理想的行為，因為這會將屬性 類似 dependency_attributes 中的 srcs，而不是 source_attributes，但是 可避免對 Pod 中的所有規則 依附元件鏈結)。

驗證動作

有時您需要驗證建構作業的某些內容，而驗證作業所需的資訊只會出現在構件 (來源檔案或產生的檔案) 中。由於這項資訊位於構件中，規則無法在分析期間執行這項驗證作業，因為規則無法讀取檔案。相反地，動作必須在執行時進行這項驗證。時間 驗證失敗，動作就會失敗，因而建構失敗。

可能會執行的驗證包括靜態分析、Linter、依附元件和一致性檢查，以及樣式檢查。

驗證動作也可以將建構成果中不需要的部分動作移至個別動作，進而改善建構效能。舉例來說，如果單一動作會編譯和程式碼檢查， 程式碼分割為編譯動作和程式碼檢查動作 動作可作為驗證動作執行，並與其他動作並行執行。

這些「驗證動作」而且通常不會產生在其他地方使用的內容 物件中，因為他們只需要斷言輸入內容。不過，這會導致問題：如果驗證動作不會產生任何在建構中其他位置使用的內容，規則如何取得要執行的動作？以往，這個方法是將驗證動作輸出為空白 手動將該輸出內容新增至 動作：

這種做法雖然可行，因為 Bazel 一律會在編譯期間執行驗證動作 但這會產生重大缺點：

1. 驗證動作在版本的重要路徑中。因為 Bazel 認為執行編譯動作需要空白輸出，就會執行 驗證動作會先予以忽略，但編譯動作會忽略輸入內容。 這會降低平行作業數量，並減慢建構作業速度。

2. 如果建構中可能會執行其他動作，而非編譯動作，則驗證動作的空白輸出內容也必須加入這些動作 (例如 java_library 的來源 JAR 輸出內容)。這是 也會發生問題 ，之後就會意外遺漏空白驗證輸出內容。

解決這些問題的方法是使用驗證輸出群組。

驗證輸出群組

「驗證輸出群組」是一種輸出群組，用於保存驗證動作的未使用輸出內容，因此不必人為地將這些內容加入其他動作的輸入內容。

這個群組的特別之處在於，無論 --output_groups 標記的值為何，且無論目標的依附方式為何 (例如在指令列上、做為依附項目，或透過目標的隱含輸出)，系統一律會要求輸出內容。請注意，一般快取和成效增幅 仍然適用：如果驗證動作的輸入內容沒有變更，且 先前成功通過驗證，驗證動作就不會 此程序的第一步 是將程式碼簽入執行所有單元測試的存放區中

使用這個輸出群組時，驗證動作仍會輸出一些檔案。 即使空無一人也不例外這可能需要包裝一些通常不會 建立輸出內容，藉此建立檔案。

在下列三種情況下，目標的驗證動作無法執行：

• 目標依循工具
• 當目標依賴隱含依附元件時 (例如 以「_」開頭的屬性
• 如果在主機或 exec 設定中建立了目標。

假設這些目標都有各自的獨立建構和測試，可找出任何驗證失敗情形。

使用驗證輸出群組

驗證輸出群組的名稱為 _validation，使用方式與其他輸出群組相同：

def _rule_with_validation_impl(ctx):

  ctx.actions.write(ctx.outputs.main, "main output\n")

  ctx.actions.write(ctx.outputs.implicit, "implicit output\n")

  validation_output = ctx.actions.declare_file(ctx.attr.name + ".validation")
  ctx.actions.run(
      outputs = [validation_output],
      executable = ctx.executable._validation_tool,
      arguments = [validation_output.path])

  return [
    DefaultInfo(files = depset([ctx.outputs.main])),
    OutputGroupInfo(_validation = depset([validation_output])),
  ]


rule_with_validation = rule(
  implementation = _rule_with_validation_impl,
  outputs = {
    "main": "%{name}.main",
    "implicit": "%{name}.implicit",
  },
  attrs = {
    "_validation_tool": attr.label(
        default = Label("//validation_actions:validation_tool"),
        executable = True,
        cfg = "exec"),
  }
)

請注意，驗證輸出檔案不會新增至 DefaultInfo 或 其他動作輸入輸入內容這個規則種類目標的驗證動作 如果目標相依於標籤或目標的 隱含輸出內容直接或間接依附於。

驗證動作的輸出內容通常只會進入驗證輸出群組，而不會加入其他動作的輸入內容，因為這可能會抵銷並行處理的效益。請注意，Bazel 目前並未 執行任何特殊檢查因此，您應該 系統不會將驗證動作的輸出內容新增到 測試 Starlark 規則例如：

load("@bazel_skylib//lib:unittest.bzl", "analysistest")

def _validation_outputs_test_impl(ctx):
  env = analysistest.begin(ctx)

  actions = analysistest.target_actions(env)
  target = analysistest.target_under_test(env)
  validation_outputs = target.output_groups._validation.to_list()
  for action in actions:
    for validation_output in validation_outputs:
      if validation_output in action.inputs.to_list():
        analysistest.fail(env,
            "%s is a validation action output, but is an input to action %s" % (
                validation_output, action))

  return analysistest.end(env)

validation_outputs_test = analysistest.make(_validation_outputs_test_impl)

驗證動作旗標

執行驗證動作是由 --run_validations 指令列控管 旗標，預設為 true。

已淘汰的功能

已淘汰的預先宣告輸出內容

使用預先宣告的輸出內容有兩種已淘汰的方法：

• rule 的 outputs 參數會指定 輸出屬性名稱和用於產生內容的字串範本之間的對應關係 預先宣告的輸出標籤偏好使用未宣告的輸出內容，以及 明確地將輸出新增至 DefaultInfo.files。使用規則目標 使用標籤做為使用輸出 (而非預先宣告) 的規則輸入標籤 輸出內容的標籤

• 對於可執行規則，ctx.outputs.executable 是指預先宣告的可執行輸出內容，其名稱與規則目標相同。建議您明確宣告輸出內容，例如使用 ctx.actions.declare_file(ctx.label.name)，並確保產生可執行檔的指令會設定其權限，以便執行。明確將可執行輸出內容傳遞至 DefaultInfo 的 executable 參數。

應執行的檔案功能

ctx.runfiles 和 runfiles 類型具有一系列複雜的功能，其中有許多功能因傳統因素而保留。 請參考下列建議，降低複雜度：

• 避免使用 collect_data 和 collect_default 模式 ctx.runfiles。這些模式會間接收集 在特定硬式編碼依附元件邊緣中執行檔案，以令人混淆的方式執行。 請改用 ctx.runfiles 的 files 或 transitive_files 參數，或透過 runfiles = runfiles.merge(dep[DefaultInfo].default_runfiles) 合併依附元件的執行檔。

• 避免使用 data_runfiles 和 default_runfiles DefaultInfo 建構函式。請改為指定 DefaultInfo(runfiles = ...)。 為因應舊版需求，「預設」和「資料」執行檔之間的差異會保留。例如，有些規則會將預設輸出內容 data_runfiles，但不是 default_runfiles。規則應同時包含預設輸出內容，並從提供執行檔的屬性 (通常是 data) 合併 default_runfiles。請勿使用 data_runfiles。

• 從 DefaultInfo 擷取 runfiles 時 (通常僅適用於合併 會在目前規則及其依附元件之間傳輸檔案)，請使用 DefaultInfo.default_runfiles，不是 DefaultInfo.data_runfiles。

從舊版供應商遷移

以往 Bazel 供應商是 Target 物件上的簡單欄位。這些欄位是使用點運算子存取，並將欄位放入規則實作函式傳回的結構體中而建立。

這類樣式已淘汰，不應在新的程式碼中使用；請參閱下方資訊，瞭解如何進行遷移。新的供應商機制會避免名稱 的衝突。也支援隱藏資料，方法是要求任何程式碼存取 以提供者符號進行擷取。

目前仍可繼續支援舊版供應商。規則可同時傳回 舊版和新型供應商的供應器如下：

def _old_rule_impl(ctx):
  ...
  legacy_data = struct(x="foo", ...)
  modern_data = MyInfo(y="bar", ...)
  # When any legacy providers are returned, the top-level returned value is a
  # struct.
  return struct(
      # One key = value entry for each legacy provider.
      legacy_info = legacy_data,
      ...
      # Additional modern providers:
      providers = [modern_data, ...])

如果 dep 是此規則例項的結果 Target 物件， 其內容可用 dep.legacy_info.x 和 dep[MyInfo].y。

除了 providers 以外，傳回的結構也可以是其他 某些欄位具有特殊意義 (因此不會建立對應的舊版 供應商)：

• files、runfiles、data_runfiles、default_runfiles 和 executable 對應於 DefaultInfo。您無法同時指定任何這些欄位和傳回 DefaultInfo 提供者。

• 欄位 output_groups 會採用結構體值，並對應至 OutputGroupInfo。

在規則的 provides 宣告中，以及依附元件屬性的 providers 宣告中，舊版供應器會以字串形式傳入，而新版供應器則會以 *Info 符號傳入。請務必從字串改為符號 執行遷移適用於較複雜或大型規則集，且難以更新 將所有規則統一排序，因此如果在測試時依循此順序 步驟：

1. 使用上述語法修改產生舊版供應者的規則，以便同時產生舊版和新版供應者。對於宣告 會傳回舊版供應商，請更新該宣告，以同時包含 舊版和新型供應商的服務。

2. 修改使用舊版供應器的規則，改為使用新版供應器。如有任何屬性宣告需要舊版供應商 更新這些元件，改為需要現代供應商。您也可以 在步驟 1 和步驟 1 之間交互作用，讓消費者接受/要求 供應商：使用 hasattr(target, 'foo')，或是使用 FooInfo in target 的新供應商。

3. 從所有規則中完全移除舊版供應器。