Starlark là một ngôn ngữ cấu hình giống Python, ban đầu được phát triển để sử dụng trong Bazel và sau đó được các công cụ khác sử dụng. Các tệp BUILD
và .bzl
của Bazel được viết bằng một phương ngữ của Starlark, gọi đúng là "Ngôn ngữ bản dựng", mặc dù thường được gọi đơn giản là "Starlark", đặc biệt là khi nhấn mạnh rằng một tính năng được thể hiện bằng Ngôn ngữ bản dựng chứ không phải là một phần tích hợp sẵn hoặc "bản địa" của Bazel. Bazel tăng cường ngôn ngữ cốt lõi bằng nhiều hàm liên quan đến bản dựng, chẳng hạn như glob
, genrule
, java_binary
, v.v.
Hãy xem tài liệu về Bazel và Starlark để biết thêm thông tin chi tiết, đồng thời dùng mẫu SIG của quy tắc để bắt đầu tạo tập hợp quy tắc mới.
Quy tắc trống
Để tạo quy tắc đầu tiên, hãy tạo tệp foo.bzl
:
def _foo_binary_impl(ctx):
pass
foo_binary = rule(
implementation = _foo_binary_impl,
)
Khi gọi hàm rule
, bạn phải xác định một hàm gọi lại. Logic sẽ ở đó, nhưng bạn có thể để trống hàm này vào lúc này. Đối số ctx
cung cấp thông tin về mục tiêu.
Bạn có thể tải và sử dụng quy tắc từ tệp BUILD
.
Tạo tệp BUILD
trong cùng thư mục:
load(":foo.bzl", "foo_binary")
foo_binary(name = "bin")
Bây giờ, bạn có thể tạo mục tiêu:
$ 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)
Mặc dù không làm gì cả, nhưng quy tắc này vẫn hoạt động như các quy tắc khác: có tên bắt buộc, hỗ trợ các thuộc tính phổ biến như visibility
, testonly
và tags
.
Mô hình đánh giá
Trước khi đi sâu hơn, bạn cần hiểu cách mã được đánh giá.
Cập nhật foo.bzl
bằng một số câu lệnh in:
def _foo_binary_impl(ctx):
print("analyzing", ctx.label)
foo_binary = rule(
implementation = _foo_binary_impl,
)
print("bzl file evaluation")
và BUILD:
load(":foo.bzl", "foo_binary")
print("BUILD file")
foo_binary(name = "bin1")
foo_binary(name = "bin2")
ctx.label
tương ứng với nhãn của mục tiêu đang được phân tích. Đối tượng ctx
có nhiều trường và phương thức hữu ích; bạn có thể tìm thấy danh sách đầy đủ trong tài liệu tham khảo API.
Truy vấn mã:
$ 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
Lưu ý:
- "bzl file evaluation" (đánh giá tệp bzl) được in trước tiên. Trước khi đánh giá tệp
BUILD
, Baazel sẽ đánh giá tất cả các tệp đã tải. Nếu nhiều tệpBUILD
đang tải foo.bzl, bạn sẽ chỉ thấy một lần xuất hiện "đánh giá tệp bzl" vì Bazel lưu kết quả đánh giá vào bộ nhớ đệm. - Hàm callback
_foo_binary_impl
không được gọi. Truy vấn Bazel tải các tệpBUILD
nhưng không phân tích các mục tiêu.
Để phân tích các mục tiêu, hãy sử dụng cquery
("truy vấn đã định cấu hình") hoặc lệnh 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...
Như bạn có thể thấy, _foo_binary_impl
hiện được gọi hai lần – một lần cho mỗi mục tiêu.
Một số độc giả sẽ nhận thấy thông tin "đánh giá tệp bzl" được in lại, mặc dù kết quả đánh giá foo.bzl được lưu vào bộ nhớ đệm sau lệnh gọi đến bazel query
. Bazel không đánh giá lại mã mà chỉ phát lại các sự kiện in. Bất kể trạng thái bộ nhớ đệm, bạn vẫn nhận được kết quả như nhau.
Tạo tệp
Để quy tắc của bạn hữu ích hơn, hãy cập nhật quy tắc đó để tạo tệp. Trước tiên, hãy khai báo và đặt tên cho tệp. Trong ví dụ này, hãy tạo một tệp có cùng tên với mục tiêu:
ctx.actions.declare_file(ctx.label.name)
Nếu chạy bazel build :all
ngay bây giờ, bạn sẽ thấy một thông báo lỗi:
The following files have no generating action:
bin2
Bất cứ khi nào khai báo một tệp, bạn phải cho Bazel biết cách tạo tệp đó bằng cách tạo một thao tác. Dùng ctx.actions.write
để tạo tệp có nội dung đã cho.
def _foo_binary_impl(ctx):
out = ctx.actions.declare_file(ctx.label.name)
ctx.actions.write(
output = out,
content = "Hello\n",
)
Mã này hợp lệ, nhưng sẽ không có tác dụng gì:
$ bazel build bin1
Target //:bin1 up-to-date (nothing to build)
Hàm ctx.actions.write
đã đăng ký một thao tác, hướng dẫn cho Bazel cách tạo tệp. Tuy nhiên, Bazel sẽ không tạo tệp cho đến khi tệp này thực sự được yêu cầu. Vì vậy, điều cuối cùng cần làm là cho Bazel biết rằng tệp này là kết quả của quy tắc, chứ không phải là tệp tạm thời được dùng trong quá trình triển khai quy tắc.
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]))]
Hãy xem các hàm DefaultInfo
và depset
sau. Hiện tại, giả sử dòng cuối cùng là cách chọn đầu ra của một quy tắc.
Bây giờ, hãy chạy Bazel:
$ bazel build bin1
INFO: Found 1 target...
Target //:bin1 up-to-date:
bazel-bin/bin1
$ cat bazel-bin/bin1
Hello!
Bạn đã tạo thành công một tệp!
Thuộc tính
Để quy tắc trở nên hữu ích hơn, hãy thêm các thuộc tính mới bằng cách sử dụng mô-đun attr
và cập nhật định nghĩa quy tắc.
Thêm một thuộc tính chuỗi có tên username
:
foo_binary = rule(
implementation = _foo_binary_impl,
attrs = {
"username": attr.string(),
},
)
Tiếp theo, hãy đặt giá trị này trong tệp BUILD
:
foo_binary(
name = "bin",
username = "Alice",
)
Để truy cập giá trị trong hàm callback, hãy sử dụng ctx.attr.username
. Ví dụ:
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]))]
Xin lưu ý rằng bạn có thể đặt thuộc tính này là bắt buộc hoặc đặt giá trị mặc định. Xem tài liệu về attr.string
.
Bạn cũng có thể sử dụng các loại thuộc tính khác, chẳng hạn như boolean hoặc danh sách số nguyên.
Phần phụ thuộc
Các thuộc tính phần phụ thuộc, chẳng hạn như attr.label
và attr.label_list
, khai báo phần phụ thuộc từ mục tiêu sở hữu thuộc tính đến mục tiêu có nhãn xuất hiện trong giá trị của thuộc tính. Loại thuộc tính này tạo thành cơ sở của biểu đồ mục tiêu.
Trong tệp BUILD
, nhãn mục tiêu xuất hiện dưới dạng một đối tượng chuỗi, chẳng hạn như //pkg:name
. Trong hàm triển khai, bạn có thể truy cập mục tiêu dưới dạng đối tượng Target
. Ví dụ: xem các tệp mà mục tiêu trả về bằng cách sử dụng Target.files
.
Nhiều tệp
Theo mặc định, chỉ các mục tiêu do quy tắc tạo ra mới có thể xuất hiện ở dạng phần phụ thuộc (chẳng hạn như mục tiêu foo_library()
). Nếu muốn thuộc tính chấp nhận các mục tiêu là tệp đầu vào (chẳng hạn như tệp nguồn trong kho lưu trữ), bạn có thể thực hiện bằng allow_files
và chỉ định danh sách đuôi tệp được chấp nhận (hoặc True
để cho phép đuôi tệp bất kỳ):
"srcs": attr.label_list(allow_files = [".java"]),
Bạn có thể truy cập vào danh sách tệp bằng ctx.files.<attribute name>
. Ví dụ: bạn có thể truy cập danh sách các tệp trong thuộc tính srcs
thông qua
ctx.files.srcs
Tệp đơn
Nếu bạn chỉ cần một tệp, hãy sử dụng allow_single_file
:
"src": attr.label(allow_single_file = [".java"])
Sau đó, bạn có thể truy cập vào tệp này trong ctx.file.<attribute name>
:
ctx.file.src
Tạo tệp bằng mẫu
Bạn có thể tạo một quy tắc tạo tệp .cc dựa trên mẫu. Ngoài ra, bạn có thể sử dụng ctx.actions.write
để xuất một chuỗi được tạo trong hàm triển khai quy tắc, nhưng cách này có hai vấn đề. Trước tiên, khi mẫu lớn hơn, bạn nên đặt mẫu vào một tệp riêng biệt để tiết kiệm bộ nhớ và tránh tạo các chuỗi lớn trong giai đoạn phân tích. Thứ hai, việc sử dụng một tệp riêng sẽ thuận tiện hơn cho người dùng. Thay vào đó, hãy sử dụng ctx.actions.expand_template
để thực hiện các thay thế trên tệp mẫu.
Tạo thuộc tính template
để khai báo phần phụ thuộc trên tệp mẫu:
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,
),
},
)
Người dùng có thể sử dụng quy tắc như sau:
hello_world(
name = "hello",
username = "Alice",
template = "file.cc.tpl",
)
cc_binary(
name = "hello_bin",
srcs = [":hello"],
)
Nếu không muốn hiển thị mẫu cho người dùng cuối và luôn sử dụng cùng một mẫu, bạn có thể đặt giá trị mặc định và đặt thuộc tính ở chế độ riêng tư:
"_template": attr.label(
allow_single_file = True,
default = "file.cc.tpl",
),
Các thuộc tính bắt đầu bằng dấu gạch dưới là thuộc tính riêng tư và không thể được đặt trong tệp BUILD
. Mẫu hiện là một phần phụ thuộc ngầm ẩn: Mọi mục tiêu hello_world
đều có một phần phụ thuộc trên tệp này. Đừng quên hiển thị tệp này cho các gói khác bằng cách cập nhật tệp BUILD
và sử dụng exports_files
:
exports_files(["file.cc.tpl"])
Tìm hiểu thêm
- Hãy xem tài liệu tham khảo về các quy tắc.
- Làm quen với depsets.
- Hãy xem kho lưu trữ ví dụ, trong đó có thêm các ví dụ về quy tắc.