Trang này dành cho những người viết quy tắc đang có kế hoạch cung cấp quy tắc của họ cho người khác.
Bạn nên bắt đầu một nhóm 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, bao gồm cả việc tạo tài liệu API và thiết lập quy trình CI/CD để dễ dàng phân phối nhóm quy tắc của bạn.
Quy tắc về việc lưu trữ và đặt tên
Các quy tắc mới phải nằm trong kho lưu trữ GitHub riêng trong tổ chức của bạn. Bắt đầu một chuỗi thảo luận trên GitHub nếu bạn cảm thấy các quy tắc của mình thuộc về tổ chức bazelbuild.
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 các ví dụ trên GitHub.
Để đảm bảo tính nhất quán, bạn nên tuân theo cùng một định dạng này khi xuất bản các quy tắc Bazel.
Nhớ sử dụng nội dung mô tả kho lưu trữ GitHub và README.mdtiêu đề mô tả, ví dụ:
- Tên kho lưu trữ:
bazelbuild/rules_go - Nội dung mô tả kho lưu trữ: Các quy tắc Go cho Bazel
- Thẻ kho lưu trữ:
golang,bazel - Tiêu đề
README.md: Các quy tắc Go cho Bazel (lưu ý đường liên kết đến https://bazel.build sẽ hướng dẫn những người dùng chưa quen với Bazel đến đú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 quy tắc đều phải có một bố cục nhất định để người dùng có thể nhanh chóng hiểu được các quy tắc mới.
Ví dụ: khi viết các quy tắc mới cho ngôn ngữ mockascript (tưởng tượng), kho quy tắc sẽ có cấu trúc như sau:
/
LICENSE
README
MODULE.bazel
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
MODULE.bazel
Trong MODULE.bazel của dự án, bạn nên xác định tên mà người dùng sẽ dùng để tham chiếu các quy tắc của bạn. Nếu các quy tắc của bạn thuộc tổ chức 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 cho kho lưu trữ của mình là <org>_rules_<lang> (chẳng hạn như build_stack_rules_proto). Vui lòng bắt đầu một chuỗi thảo luận trên GitHub nếu bạn cảm thấy các quy tắc của mình phải 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 tổ chức bazelbuild.
module(name = "rules_mockascript")
README
Ở cấp cao nhất, phải có một README chứa nội dung mô tả ngắn gọn về bộ quy tắc của bạn và những gì người dùng API mong đợi.
Quy tắc
Kho lưu trữ của bạn thường sẽ cung cấp nhiều quy tắc. Tạo một thư mục có 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ả cá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 đó có nghĩa là sẽ có một thư mục tên là 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 các quy tắc toolchain, thì có thể bạn sẽ cần xác định các constraint_setting và/hoặc constraint_value tuỳ chỉnh. Đặt các tệp này vào một gói //<LANG>/constraints. Cấu trúc thư mục của bạn 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, xem những hạn chế hiện có và cân nhắc đóng góp các hạn chế của bạn ở đó nếu chúng không phụ thuộc vào ngôn ngữ.
Hãy lưu ý đến việc giới thiệu các điều kiện ràng buộc tuỳ chỉnh, tất cả người dùng quy tắc của bạn sẽ sử dụng các điều kiện ràng buộc đó để thực hiện logic dành riêng cho nền tảng trong tệp BUILD (ví dụ: sử dụng selects).
Với các điều kiện ràng buộc tuỳ chỉnh, bạn sẽ xác định một ngôn ngữ mà toàn bộ hệ sinh thái Bazel sẽ sử dụng.
Thư viện Runfiles
Nếu quy tắc của bạn cung cấp một thư viện chuẩn để truy cập vào các tệp chạy, thì quy tắc đó phải ở dạng mục tiêu thư viện nằm tại //<LANG>/runfiles (viết tắt của //<LANG>/runfiles:runfiles). Các mục tiêu người dùng cần truy cập vào các phần phụ thuộc dữ liệu của họ thường sẽ thêm mục tiêu này vào thuộc tính deps.
Quy tắc kho lưu trữ
Phần phụ thuộc
Các quy tắc của bạn có thể có phần phụ thuộc bên ngoài mà bạn cần chỉ định trong tệp MODULE.bazel.
Đă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ụ mà bạn cũng có thể chỉ định trong tệp MODULE.bazel.
Xin lưu ý rằng để giải quyết các chuỗi công cụ trong giai đoạn phân tích, Bazel cần phân tích tất cả các mục tiêu toolchain đã đăng ký. Bazel sẽ không cần phân tích tất cả các mục tiêu mà thuộc tính toolchain.toolchain tham chiếu. Nếu để đăng ký chuỗi công cụ, bạn cần thực hiện phép tính phức tạp trong kho lưu trữ, hãy cân nhắc việc chia kho lưu trữ có các mục tiêu toolchain với kho lưu trữ có các mục tiêu <LANG>_toolchain. Mục đầu tiên sẽ luôn được tìm nạp và mục 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 trích về bản phát hành
Trong thông báo 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 MODULE.bazel của họ. Đoạn mã này thường sẽ có dạng như sau:
bazel_dep(name = "rules_<LANG>", version = "<VERSION>")
Thử nghiệm
Bạn nên có các bài kiểm thử để xác minh rằng các quy tắc đang hoạt động như dự kiến. Thư mục này có thể nằm ở vị trí tiêu chuẩn cho ngôn ngữ mà các quy tắc áp dụng hoặc thư mục tests/ ở cấp cao nhất.
Ví dụ (không bắt buộc)
Người dùng sẽ thấy hữu ích khi có một thư mục examples/ cho biết một số cách cơ bản mà người dùng có thể sử dụng các quy tắc.
CI/CD
Nhiều bộ quy tắc sử dụng GitHub Actions. Hãy xem cấu hình được dùng trong kho lưu trữ rules-template. Cấu hình này được đơn giản hoá bằng cách sử dụng "quy trình có thể sử dụng lại" được lưu trữ trong bazel-contrib.org. ci.yaml chạy kiểm thử trên mỗi PR và main comit, còn release.yaml chạy bất cứ khi nào bạn đẩy một thẻ vào kho lưu trữ.
Hãy xem phần nhận xét trong kho lưu trữ rules-template để 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 kho lưu trữ đó vào ci.bazel.build.
Tài liệu
Hãy xem tài liệu Stardoc để biết hướng dẫn về cách nhận xét các quy tắc để tài liệu có thể được tạo tự động.
Thư mục rules-template docs/ cho thấy một cách đơn giản để đảm bảo nội dung Markdown trong thư mục docs/ luôn được cập nhật khi 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 GitHub chính?
Chúng tôi muốn tách các quy tắc khỏi bản phát hành Bazel càng nhiều càng tốt. Rõ ràng hơn về việc ai sở hữu các quy tắc riêng lẻ, giảm tải cho nhà phát triển Bazel. Đối với người dùng, việc tách rời giúp họ dễ dàng sửa đổi, nâng cấp, hạ cấp và thay thế các quy tắc. Việc đóng góp cho các quy tắc có thể nhẹ hơn so với việc đóng góp cho Bazel – tuỳ thuộc vào các quy tắc – bao gồm cả quyền gửi đầy đủ cho kho lưu trữ GitHub tương ứng. Việc có được quyền gửi đến chính Bazel là một quy trình phức tạp hơn nhiều.
Nhược điểm là quy trình cài đặt một lần phức tạp hơn đối với người dùng của chúng tôi: họ phải thêm một phần phụ thuộc vào bộ quy tắc của bạn trong tệp MODULE.bazel.
Trước đây, chúng tôi 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 số quy tắc ở đó, nhưng chúng tôi đang nỗ lực di chuyển các quy tắc còn lại ra ngoài.