規則

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

規則定義 Bazel 在輸入內容上執行的一系列動作，以產生一組輸出內容，這些輸出內容會在規則的實作函式傳回的供應器中參照。舉例來說，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，宣告輸出檔案 並產生目標這與依附元件屬性有兩個不同之處：

  • 這些屬性會定義輸出檔案目標，而非參照其他位置定義的目標。
  • 輸出檔案目標取決於已例項化的規則目標，而非相反。

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

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

實作函式

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

規則導入函式通常屬於私人性質 (以 底線)。一般情況下，這些變數的名稱與規則相同，但後置字元 只在 _impl。

實作函式只會採用一個參數：規則情境，通常命名為 ctx。他們會傳回 供應商。

目標

在分析時，依附元件會顯示為 Target 如需儲存大量結構化物件 建議使用 Cloud Bigtable這些物件包含執行目標實作函式時產生的 供應器。

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。

宣告輸出

在分析階段，規則的實作函式可建立輸出內容。 由於所有標籤都必須在載入階段中知悉，因此這些額外的輸出內容沒有標籤。輸出的 File 物件可使用 ctx.actions.declare_file和 ctx.actions.declare_directory。這通常 輸出內容的名稱取決於目標名稱 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.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]), ...),
        ...
    ]

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

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

Runfiles

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

您可以在建立規則時手動新增執行檔。runfiles 物件可透過規則結構定義 ctx.runfiles 上的 runfiles 方法建立，並傳遞至 DefaultInfo 上的 runfiles 參數。系統呼叫 系統會間接將執行檔規則新增至執行檔案。

部分規則會指定屬性，通常會命名為 data，其輸出內容會加入至目標的執行檔。執行檔也應從 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 指令叫用。您可以透過在對 rule 的呼叫中，將各自的 executable 或 test 引數設為 True，建立可執行和測試規則：

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

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

測試規則的名稱必須以 _test 結尾。(依慣例，測試目標名稱通常會以 _test 結尾，但這並非必要)。非測試規則不得使用這個後置字串。

這兩種規則必須產生一個可執行的輸出檔案 (不一定可以 run 或 test 指令叫用這些片段。說明 要將哪個規則輸出做為這個執行檔使用，並將該輸出內容做為 傳回的 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 也可以由 aspect 以及要套用該切面的規則目標，例如 前提是這些輸出群組沒有定義相同的輸出群組在這種情況下，系統會合併產生的供應者。

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

設定

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

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

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

對於每個依附元件屬性，您可以使用 cfg 判斷是否依附關係 應以相同的設定建構，或是轉換至 exec 設定。 如果依附元件屬性含有旗標 executable=True，則必須明確設定 cfg。這是為了避免不小心建立錯誤的工具 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定 查看示例

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

在建構作業中執行的工具 (例如編譯器或程式碼產生器) 應針對執行設定進行建構。在本例中，請將 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
    ...
)

通常，執行檔案樹狀目錄中檔案的相對路徑，會與來源樹狀目錄或產生的輸出樹狀目錄中該檔案的相對路徑相同。如果這些值因某些原因而需要不同，您可以指定 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，請注意不要對應兩種 將檔案移到執行檔案樹狀結構的相同路徑上這會導致建構作業失敗，並顯示描述衝突的錯誤。如要修正，請修改您的 用於移除衝突的 ctx.runfiles 引數。這項檢查將完成 使用規則的任何目標，以及符合這些規則的任何類型目標 目標。如果工具可能會間接地由其他工具使用，這種做法就特別危險。在工具和所有相依項目的執行檔中，符號連結名稱必須是唯一的。

程式碼涵蓋率

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

如果規則實作在建構期間新增涵蓋率檢測功能，就必須在實作函式中考量這項因素。如果目標的來源應進行檢測，ctx.coverage_instrumented 會在涵蓋率模式中傳回 true：

# 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，系統會在 dependency_attributes 中使用每個非工具依附元件屬性 (未將 cfg 設為屬性結構定義中的 "host" 或 "exec") 建立預設 InstrumentedFilesInfo。(這並不是理想的行為，因為這會將屬性 類似 dependency_attributes 中的 srcs，而不是 source_attributes，但是 可避免對 Pod 中的所有規則 依附元件鏈結)。

驗證動作

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

靜態分析、程式碼檢查、 依附元件和一致性檢查，以及樣式檢查。

驗證動作也有助於移動零件，進而改善建構成效 將構件建構成獨立動作時不需要執行的動作。 舉例來說，如果執行編譯和 lint 的單一動作可分為編譯動作和 lint 動作，則 lint 動作可做為驗證動作執行，並與其他動作並行執行。

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

這麼做是可行的，因為 Bazel 會在編譯動作執行時一律執行驗證動作，但這有重大缺點：

  1. 驗證動作在版本的重要路徑中。由於 Bazel 認為空白輸出內容是執行編譯動作的必要條件，因此即使編譯動作會忽略輸入內容，它還是會先執行驗證動作。這會降低平行作業數量，並減慢建構作業速度。

  2. 如果建構中可能會執行其他動作，而非編譯動作，則驗證動作的空白輸出內容也必須加入這些動作 (例如 java_library 的來源 JAR 輸出內容)。如果您日後新增了可能會執行的動作 (而非編譯動作)，而空白的驗證輸出內容不小心遺漏，也會發生這個問題。

如要解決這類問題，請使用「驗證輸出群組」。

驗證輸出群組

「驗證輸出群組」是一個輸出群組，其用途是保留 未使用驗證動作的輸出內容，因此不必以人為方式 都會新增到其他動作的輸入來源中

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

使用這個輸出群組時，驗證動作仍會輸出一些檔案。 即使空無一人也不例外這可能需要包裝一些通常不會產生輸出的工具，以便建立檔案。

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

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

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

使用驗證輸出群組

「驗證輸出群組」的名稱是 _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。這些模式會間接收集 在特定硬式編碼依附元件邊緣中執行檔案，以令人混淆的方式執行。 請改為使用以下來源的 files 或 transitive_files 參數新增檔案： ctx.runfiles，或將依附元件從依附元件中合併 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 中，讓消費者接受/要求其中一個供應器，藉此與這項工作交錯執行：使用 hasattr(target, 'foo') 測試舊版供應器是否存在，或使用 FooInfo in target 測試新版供應器是否存在。

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