規則教學課程

7.3 · 7.2 · 7.1 · 7.0 · 6.5

Starlark 是類似 Python 的設定語言，最初是為了在 Bazel 中使用而開發，後來其他工具也採用了這項語言。Bazel 的 BUILD 和 .bzl 檔案是以 Starlark 的方言編寫，這正是「建構語言」的正確名稱，但通常會簡稱為「Starlark」，尤其是在強調某項功能是以建構語言表示，而非 Bazel 的內建或「原生」部分時。Bazel 會透過許多與建構相關的函式 (例如 glob、genrule、java_binary 等) 擴充核心語言。

詳情請參閱 Bazel 和 Starlark 說明文件，並參閱 Rules SIG 範本做為新規則集的起點。

空白規則

如要建立第一個規則，請建立 foo.bzl 檔案：

def _foo_binary_impl(ctx):
    pass

foo_binary = rule(
    implementation = _foo_binary_impl,
)

呼叫 rule 函式時，您必須定義回呼函式。邏輯會放在這個位置，但您可以先將函式留空。ctx 引數會提供目標的相關資訊。

您可以載入規則，並從 BUILD 檔案使用該規則。

在同一個目錄中建立 BUILD 檔案：

load(":foo.bzl", "foo_binary")

foo_binary(name = "bin")

現在可以建構目標：

$ bazel build bin
INFO: Analyzed target //:bin (2 packages loaded, 17 targets configured).
INFO: Found 1 target...
Target //:bin up-to-date (nothing to build)

雖然規則沒有任何作用，但其行為與其他規則相同：它有強制名稱，且支援 visibility、testonly 和 tags 等常見屬性。

評估模型

在進一步研究之前，請先瞭解程式碼的評估方式。

使用一些列印陳述式更新 foo.bzl：

def _foo_binary_impl(ctx):
    print("analyzing", ctx.label)

foo_binary = rule(
    implementation = _foo_binary_impl,
)

print("bzl file evaluation")

並構思：

load(":foo.bzl", "foo_binary")

print("BUILD file")
foo_binary(name = "bin1")
foo_binary(name = "bin2")

ctx.label 對應於要分析的目標標籤。ctx 物件具有許多實用的欄位和方法，您可以在 API 參考資料中找到完整清單。

查詢程式碼：

$ bazel query :all
DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation
DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file
//:bin2
//:bin1

請注意以下幾點：

  • 系統會先列印「bzl 檔案評估」。在評估 BUILD 檔案之前，Bazel 會評估其載入的所有檔案。如果有多個 BUILD 檔案正在載入 foo.bzl，您只會看到一次「bzl 檔案評估」事件，因為 Bazel 會快取評估結果。
  • 系統不會呼叫回呼函式 _foo_binary_impl。Bazel 查詢會載入 BUILD 檔案，但不會分析目標。

如要分析目標，請使用 cquery (「已設定查詢」) 或 build 指令：

$ bazel build :all
DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation
DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file
DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin1
DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin2
INFO: Analyzed 2 targets (0 packages loaded, 0 targets configured).
INFO: Found 2 targets...

如您所見，_foo_binary_impl 現在會呼叫兩次，每個目標各一次。

有些讀者會注意到，雖然在呼叫 bazel query 後，foo.bzl 的評估結果會快取，但「bzl 檔案評估」會再次列印。Bazel 不會重新評估程式碼，只會重播列印事件。無論快取狀態為何，您都會取得相同的輸出內容。

建立檔案

如要讓規則更實用，請更新規則以產生檔案。首先，請宣告檔案並為其命名。在本例中，請建立與目標相同名稱的檔案：

ctx.actions.declare_file(ctx.label.name)

如果現在執行 bazel build :all，您會收到錯誤訊息：

The following files have no generating action:
bin2

每次宣告檔案時，您都必須建立動作，告訴 Bazel 如何產生檔案。使用 ctx.actions.write 建立含有指定內容的檔案。

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello\n",
    )

代碼有效，但不會執行任何動作：

$ bazel build bin1
Target //:bin1 up-to-date (nothing to build)

ctx.actions.write 函式註冊了動作，可教導 Bazel 如何產生檔案。但 Bazel 只會在實際要求時才會建立檔案。因此，最後要做的事就是告訴 Bazel，該檔案是規則的輸出內容，而不是規則實作中使用的暫存檔案。

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello!\n",
    )
    return [DefaultInfo(files = depset([out]))]

稍後我們會介紹 DefaultInfo 和 depset 函式。目前，我們假設最後一行是選擇規則輸出內容的方式。

接著執行 Bazel：

$ bazel build bin1
INFO: Found 1 target...
Target //:bin1 up-to-date:
  bazel-bin/bin1

$ cat bazel-bin/bin1
Hello!

您已成功產生檔案！

屬性

如要讓規則更實用，請使用 attr 模組新增屬性，並更新規則定義。

新增名為 username 的字串屬性：

foo_binary = rule(
    implementation = _foo_binary_impl,
    attrs = {
        "username": attr.string(),
    },
)

接著，請在 BUILD 檔案中設定：

foo_binary(
    name = "bin",
    username = "Alice",
)

如要存取回呼函式中的值，請使用 ctx.attr.username。例如：

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello {}!\n".format(ctx.attr.username),
    )
    return [DefaultInfo(files = depset([out]))]

請注意，您可以將屬性設為必填，或設定預設值。請參閱 attr.string 的說明文件。您也可以使用其他類型的屬性，例如布林值或整數清單。

依附元件

依附屬性 (例如 attr.label 和 attr.label_list) 會宣告依附屬性，從擁有依附屬性的目標，連結至標籤出現在依附屬性值中的目標。這類屬性是目標圖表的基礎。

在 BUILD 檔案中，目標標籤會顯示為字串物件，例如 //pkg:name。在實作函式中，目標會以 Target 物件形式提供存取權。例如，使用 Target.files 查看目標傳回的檔案。

多個檔案

根據預設，只有由規則建立的目標才會顯示為依附元件 (例如 foo_library() 目標)。如果您希望屬性接受輸入檔案 (例如儲存庫中的來源檔案) 做為目標，可以使用 allow_files 並指定接受的副檔名清單 (或使用 True 允許任何副檔名)：

"srcs": attr.label_list(allow_files = [".java"]),

您可以使用 ctx.files.<attribute name> 存取檔案清單。例如，您可以透過以下方式存取 srcs 屬性中的檔案清單：

ctx.files.srcs

單一檔案

如果只需要一個檔案，請使用 allow_single_file：

"src": attr.label(allow_single_file = [".java"])

接著，您可以在 ctx.file.<attribute name> 下存取這個檔案：

ctx.file.src

使用範本建立檔案

您可以建立規則，根據範本產生 .cc 檔案。此外，您也可以使用 ctx.actions.write 輸出規則實作函式中建構的字串，但這有兩個問題。首先，隨著範本變得更大，將記憶體放在獨立的檔案中，並避免在分析階段建構大型字串，會更有效率。其次，使用獨立檔案會讓使用者更為方便。請改用 ctx.actions.expand_template，這個函式會在範本檔案中執行替換作業。

建立 template 屬性，宣告範本檔案的依附元件：

def _hello_world_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name + ".cc")
    ctx.actions.expand_template(
        output = out,
        template = ctx.file.template,
        substitutions = {"{NAME}": ctx.attr.username},
    )
    return [DefaultInfo(files = depset([out]))]

hello_world = rule(
    implementation = _hello_world_impl,
    attrs = {
        "username": attr.string(default = "unknown person"),
        "template": attr.label(
            allow_single_file = [".cc.tpl"],
            mandatory = True,
        ),
    },
)

使用者可以使用以下規則：

hello_world(
    name = "hello",
    username = "Alice",
    template = "file.cc.tpl",
)

cc_binary(
    name = "hello_bin",
    srcs = [":hello"],
)

如果您不想向使用者公開範本並一律使用相同的範本，則可設定預設值並將屬性設為不公開：

    "_template": attr.label(
        allow_single_file = True,
        default = "file.cc.tpl",
    ),

以底線開頭的屬性為私有屬性，無法在 BUILD 檔案中設定。範本現在是「隱含依附元件」：每個 hello_world 目標都有這個檔案的依附元件。請記得更新 BUILD 檔案並使用 exports_files，讓其他套件能夠查看這個檔案：

exports_files(["file.cc.tpl"])

再升級