Trang này dành cho những người viết quy tắc mà họ dự định cung cấp quy tắc với những người khác.
Bạn nên bắt đầu một bộ quy tắc mới từ kho lưu trữ mẫu: https://github.com/bazel-contrib/rules-template Mẫu đó tuân theo các đề xuất bên dưới và bao gồm việc tạo tài liệu API và thiết lập quy trình CI/CD để việc phân phối bộ quy tắc trở nên đơn giản.
Quy tắc lưu trữ và đặt tên
Các quy tắc mới sẽ nằm trong kho lưu trữ GitHub riêng trong tổ chức của bạn. Bắt đầu một luồng trên GitHub nếu bạn cảm thấy các quy tắc của mình đã có sẵn trong bazelbuild tổ chức.
Tên kho lưu trữ cho các quy tắc Bazel được chuẩn hoá theo định dạng sau:
$ORGANIZATION/rules_$NAME.
Xem ví dụ trên GitHub.
Để đảm bảo tính nhất quán, bạn nên sử dụng cùng một định dạng này khi xuất bản các quy tắc Bazel.
Hãy nhớ sử dụng phần mô tả mang tính mô tả về kho lưu trữ GitHub và README.md
tiêu đề, ví dụ:
- Tên kho lưu trữ:
bazelbuild/rules_go - Nội dung mô tả về kho lưu trữ: Quy tắc Go cho Bazel
- Thẻ kho lưu trữ:
golang,bazel - Tiêu đề
README.md: Quy tắc áp dụng cho Bazel (lưu ý đường liên kết đến https://bazel.build để hướng dẫn những người dùng chưa quen thuộc với Bazel vào đúng nơi)
Bạn có thể nhóm các quy tắc theo ngôn ngữ (chẳng hạn như Scala), nền tảng thời gian chạy (chẳng hạn như Android) hoặc khung (chẳng hạn như Spring).
Nội dung trong kho lưu trữ
Mỗi kho lưu trữ quy tắc phải có một bố cục nhất định để người dùng có thể nhanh chóng hiểu các quy tắc mới.
Ví dụ: khi viết các quy tắc mới cho (hãy tin tưởng)
mockascript, thì kho lưu trữ quy tắc sẽ có cấu trúc như sau:
/
LICENSE
README
WORKSPACE
mockascript/
constraints/
BUILD
runfiles/
BUILD
runfiles.mocs
BUILD
defs.bzl
tests/
BUILD
some_test.sh
another_test.py
examples/
BUILD
bin.mocs
lib.mocs
test.mocs
KHÔNG GIAN LÀM VIỆC
Trong WORKSPACE của dự án, bạn nên xác định tên mà người dùng sẽ sử dụng
để tham khảo các quy tắc của bạn. Nếu quy tắc của bạn thuộc về
bazelbuild, bạn phải sử dụng
rules_<lang> (chẳng hạn như rules_mockascript). Nếu không, bạn nên đặt tên
kho lưu trữ <org>_rules_<lang> (chẳng hạn như build_stack_rules_proto). Năn nỉ
bắt đầu một luồng trên GitHub
nếu bạn cảm thấy các quy tắc của mình nên tuân theo quy ước cho các quy tắc trong
tổ chức bazelbuild.
Trong các phần sau, giả sử kho lưu trữ thuộc về bazelbuild.
workspace(name = "rules_mockascript")
README
Ở cấp cao nhất, phải có một README chứa (ít nhất) nội dung
người dùng cần sao chép và dán vào tệp WORKSPACE để sử dụng quy tắc của bạn.
Nhìn chung, đây sẽ là một http_archive trỏ đến bản phát hành GitHub của bạn và
lệnh gọi macro tải xuống/định cấu hình bất kỳ công cụ nào mà quy tắc của bạn cần. Ví dụ:
cho gói Go
quy tắc này,
sẽ có dạng như sau:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_go",
urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()
Nếu quy tắc của bạn phụ thuộc vào quy tắc của một kho lưu trữ khác, hãy chỉ định quy tắc đó trong
tài liệu về các quy tắc (ví dụ: xem
Quy tắc Skydoc
phụ thuộc vào quy tắc Sass) và cung cấp WORKSPACE
sẽ tải tất cả phần phụ thuộc xuống (xem rules_go ở trên).
Quy tắc
Thông thường, kho lưu trữ của bạn sẽ cung cấp nhiều quy tắc. Tạo một
thư mục được đặt tên theo ngôn ngữ và cung cấp một điểm truy cập – tệp defs.bzl
xuất tất cả quy tắc (cũng bao gồm tệp BUILD để thư mục là một gói).
Đối với rules_mockascript, điều đó nghĩa là sẽ có một thư mục có tên
mockascript, một tệp BUILD và một tệp defs.bzl bên trong:
/
mockascript/
BUILD
defs.bzl
Giới hạn
Nếu quy tắc của bạn xác định
chuỗi công cụ
có thể bạn cần phải xác định các constraint_setting tuỳ chỉnh và/hoặc
constraint_value giây. Đặt các mục này vào gói //<LANG>/constraints. Thông tin
cấu trúc thư mục sẽ có dạng như sau:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Vui lòng đọc
github.com/bazelbuild/platforms
để biết các phương pháp hay nhất cũng như xem những hạn chế hiện có, và
hãy cân nhắc đóng góp các ràng buộc của bạn vào đó nếu các quy tắc này độc lập về ngôn ngữ.
Hãy lưu ý đến việc giới thiệu các quy tắc ràng buộc tuỳ chỉnh, tất cả người dùng các quy tắc của bạn sẽ
sử dụng chúng để thực hiện logic dành riêng cho nền tảng trong các tệp BUILD (ví dụ:
bằng cách sử dụng chọn).
Với các điều kiện ràng buộc tuỳ chỉnh, bạn xác định ngôn ngữ mà toàn bộ hệ sinh thái Bazel
sẽ nói.
Thư viện Runfiles
Nếu quy tắc của bạn cung cấp thư viện chuẩn để truy cập vào các tệp runfile, thì quy tắc đó phải là
dưới dạng mục tiêu thư viện đặt tại //<LANG>/runfiles (viết tắt
/ //<LANG>/runfiles:runfiles). Các mục tiêu người dùng cần truy cập vào dữ liệu của họ
các phần phụ thuộc thường sẽ thêm mục tiêu này vào thuộc tính deps của chúng.
Quy tắc kho lưu trữ
Phần phụ thuộc
Các quy tắc của bạn có thể có các phần phụ thuộc bên ngoài. Để thực hiện theo quy tắc của bạn
đơn giản hơn, hãy cung cấp macro WORKSPACE để khai báo các phần phụ thuộc trên
các phần phụ thuộc bên ngoài đó. Không khai báo các phần phụ thuộc của chương trình kiểm thử ở đó, mà chỉ khai báo
các phần phụ thuộc mà quy tắc đòi hỏi phải có để hoạt động. Đặt các phần phụ thuộc phát triển vào
Tệp WORKSPACE.
Tạo một tệp có tên <LANG>/repositories.bzl và cung cấp một điểm truy cập duy nhất
có tên rules_<LANG>_dependencies. Thư mục của chúng tôi sẽ có dạng như sau:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
Đăng ký chuỗi công cụ
Các quy tắc của bạn cũng có thể đăng ký chuỗi công cụ. Vui lòng cung cấp một WORKSPACE riêng
macro đăng ký các chuỗi công cụ này. Bằng cách này, người dùng có thể quyết định bỏ qua
macro trước đó và kiểm soát các phần phụ thuộc theo cách thủ công, trong khi vẫn được phép
đăng ký chuỗi công cụ.
Do đó, hãy thêm macro WORKSPACE có tên rules_<LANG>_toolchains vào
<LANG>/repositories.bzl.
Lưu ý rằng để phân giải chuỗi công cụ trong giai đoạn phân tích, Bazel cần:
phân tích tất cả mục tiêu toolchain đã được đăng ký. Bazel sẽ không cần
phân tích tất cả các mục tiêu được tham chiếu bởi thuộc tính toolchain.toolchain. Nếu theo thứ tự
để đăng ký chuỗi công cụ, bạn cần thực hiện các phép tính phức tạp trong
kho lưu trữ, hãy cân nhắc việc chia tách kho lưu trữ với các mục tiêu toolchain khỏi
kho lưu trữ có mục tiêu <LANG>_toolchain. Cũ sẽ luôn được tìm nạp và
mã thứ hai sẽ chỉ được tìm nạp khi người dùng thực sự cần tạo mã <LANG>.
Đoạn mã của bản phát hành
Trong thông báo về bản phát hành, hãy cung cấp một đoạn mã mà người dùng có thể sao chép và dán
vào tệp WORKSPACE. Đoạn mã này nhìn chung sẽ có dạng như sau:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_<LANG>",
urls = ["<url_to_the_release.zip"],
sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()
Thử nghiệm
Cần có các bài kiểm thử xác minh rằng các quy tắc đang hoạt động như mong đợi. Chiến dịch này
có thể ở vị trí chuẩn cho ngôn ngữ áp dụng quy tắc hoặc
Thư mục tests/ ở cấp cao nhất.
Ví dụ (không bắt buộc)
Sẽ hữu ích cho người dùng khi có một thư mục examples/ hiển thị cho người dùng một vài
cách cơ bản để sử dụng quy tắc.
CI/CD (Đo lường khả năng tiếp cận khách hàng)
Nhiều bộ quy tắc sử dụng GitHub Actions. Xem cấu hình dùng trong kho lưu trữ rules-template, được đơn giản hoá bằng cách sử dụng "quy trình công việc có thể sử dụng lại" được lưu trữ trong bazel-contrib
org. ci.yaml chạy kiểm thử trên từng comit PR và main, còn release.yaml sẽ chạy bất cứ khi nào bạn đẩy một thẻ vào kho lưu trữ.
Xem nhận xét trong kho lưu trữ mẫu quy tắc để biết thêm thông tin.
Nếu kho lưu trữ của bạn thuộc tổ chức Bazelbuild, bạn có thể yêu cầu thêm nó lên ci.bazel.build.
Tài liệu
Hãy xem tài liệu về Stardoc để biết hướng dẫn về cách nhận xét quy tắc của bạn để có thể tạo tài liệu tự động.
Tài liệu/ thư mục mẫu quy tắc
cho thấy một cách đơn giản để đảm bảo nội dung Markdown trong thư mục docs/ luôn là mới nhất
vì các tệp Starlark đã được cập nhật.
Câu hỏi thường gặp
Tại sao chúng ta không thể thêm quy tắc của mình vào kho lưu trữ Bazel chính trên GitHub?
Chúng tôi muốn tách biệt các quy tắc trong bản phát hành Bazel nhiều nhất có thể. Nội dung rõ ràng hơn sở hữu các quy tắc riêng lẻ, giúp giảm tải cho các nhà phát triển Bazel. Đối với người dùng, việc phân tách giúp việc sửa đổi, nâng cấp, hạ cấp và thay thế các quy tắc trở nên dễ dàng hơn. Việc đóng góp cho các quy tắc có thể nhẹ nhàng hơn việc đóng góp cho Bazel – tùy thuộc vào quy tắc, bao gồm cả quyền gửi đầy đủ vào Kho lưu trữ GitHub. Việc gửi quyền truy cập vào chính Bazel sẽ phức tạp hơn của chúng tôi.
Nhược điểm là quá trình cài đặt một lần phức tạp hơn đối với người dùng:
họ phải sao chép và dán một quy tắc vào tệp WORKSPACE, như được minh hoạ trong
Mục README.md ở trên.
Chúng tôi từng có tất cả các quy tắc trong kho lưu trữ Bazel (trong
//tools/build_rules hoặc //tools/build_defs). Chúng tôi vẫn có một vài quy tắc
ở đó, nhưng chúng tôi đang cố gắng loại bỏ các quy tắc còn lại.