Halaman ini ditujukan untuk penulis aturan yang berencana menyediakan aturan mereka kepada orang lain.
Sebaiknya mulai aturan baru dari repositori template: https://github.com/bazel-contrib/rules-template Template tersebut mengikuti rekomendasi di bawah, dan menyertakan pembuatan dokumentasi API serta menyiapkan pipeline CI/CD untuk memudahkan distribusi aturan Anda.
Aturan hosting dan penamaan
Aturan baru harus masuk ke repositori GitHub-nya sendiri di organisasi Anda. Mulai rangkaian pesan di GitHub jika Anda merasa aturan Anda termasuk dalam organisasi bazelbuild.
Nama repositori untuk aturan Bazel distandarisasi dalam format berikut:
$ORGANIZATION/rules_$NAME
.
Lihat contoh di GitHub.
Untuk konsistensi, Anda harus mengikuti format yang sama ini saat memublikasikan aturan Bazel.
Pastikan untuk menggunakan deskripsi repositori GitHub yang deskriptif dan judul README.md
, contohnya:
- Nama repositori:
bazelbuild/rules_go
- Deskripsi repositori: Aturan Go untuk Bazel
- Tag repositori:
golang
,bazel
- Header
README.md
: Aturan Go untuk Bazel (perhatikan link ke https://bazel.build yang akan memandu pengguna yang tidak terbiasa dengan Bazel ke tempat yang tepat)
Aturan dapat dikelompokkan berdasarkan bahasa (seperti Scala), platform runtime (seperti Android), atau framework (seperti Spring).
Konten repositori
Setiap repositori aturan harus memiliki tata letak tertentu sehingga pengguna dapat dengan cepat memahami aturan baru.
Misalnya, saat menulis aturan baru untuk bahasa mockascript
(buat-percaya), repositori aturan akan memiliki struktur berikut:
/
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
Di MODULE.bazel
project, Anda harus menentukan nama yang akan digunakan pengguna untuk mereferensikan aturan Anda. Jika aturan Anda termasuk dalam organisasi bazelbuild, Anda harus menggunakan rules_<lang>
(seperti rules_mockascript
). Jika tidak, Anda harus menamai repositori Anda <org>_rules_<lang>
(seperti build_stack_rules_proto
). Mulai thread di GitHub jika Anda merasa aturan Anda harus mengikuti konvensi untuk aturan di organisasi bazelbuild.
Di bagian berikut, asumsikan repositori adalah milik organisasi bazelbuild.
module(name = "rules_mockascript")
README
Di tingkat teratas, harus ada README
yang berisi deskripsi singkat tentang kumpulan aturan Anda, dan yang diharapkan pengguna API.
Aturan
Sering kali akan ada beberapa aturan yang disediakan oleh repositori Anda. Buat direktori yang diberi nama berdasarkan bahasa dan berikan titik entri - file defs.bzl
yang mengekspor semua aturan (sertakan juga file BUILD
sehingga direktorinya adalah paket).
Untuk rules_mockascript
, artinya akan ada direktori bernama
mockascript
, serta file BUILD
dan file defs.bzl
di dalamnya:
/
mockascript/
BUILD
defs.bzl
Batasan
Jika aturan Anda menentukan
aturan toolchain,
mungkin Anda perlu menentukan constraint_setting
dan/atau
constraint_value
kustom. Masukkan ini ke dalam paket //<LANG>/constraints
. Struktur direktori Anda akan terlihat seperti ini:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Baca
github.com/bazelbuild/platforms
untuk mengetahui praktik terbaik, dan melihat batasan yang sudah ada, serta
pertimbangkan untuk berkontribusi pada batasan Anda di sana jika tidak bergantung pada bahasa.
Perhatikan batasan kustom yang diperkenalkan, semua pengguna aturan Anda akan menggunakannya untuk menjalankan logika khusus platform dalam file BUILD
mereka (misalnya, menggunakan select).
Dengan batasan kustom, Anda menentukan bahasa yang akan digunakan seluruh ekosistem Bazel.
Library runfile
Jika aturan Anda menyediakan library standar untuk mengakses runfile, library tersebut harus
berupa target library yang terletak di //<LANG>/runfiles
(singkatan
dari //<LANG>/runfiles:runfiles
). Target pengguna yang perlu mengakses dependensi
datanya biasanya akan menambahkan target ini ke atribut deps
mereka.
Aturan repositori
Dependensi
Aturan Anda mungkin memiliki dependensi eksternal, yang harus Anda tentukan dalam file MODULE.bazel.
Mendaftarkan toolchain
Aturan Anda mungkin juga mendaftarkan toolchain, yang juga dapat Anda tentukan dalam file MODULE.bazel.
Perhatikan bahwa untuk me-resolve toolchain dalam fase analisis, Bazel perlu
menganalisis semua target toolchain
yang terdaftar. Bazel tidak perlu
menganalisis semua target yang dirujuk oleh atribut toolchain.toolchain
. Jika untuk
mendaftarkan toolchain, Anda perlu melakukan komputasi kompleks di
repositori, sebaiknya bagi repositori dengan target toolchain
dari
repositori dengan target <LANG>_toolchain
. Yang pertama akan selalu diambil, dan
yang kedua hanya akan diambil saat pengguna benar-benar perlu mem-build kode <LANG>
.
Rilis cuplikan
Dalam pengumuman rilis, berikan cuplikan yang dapat disalin-tempel oleh pengguna
ke dalam file MODULE.bazel
mereka. Cuplikan ini secara umum akan terlihat seperti berikut:
bazel_dep(name = "rules_<LANG>", version = "<VERSION>")
Pengujian
Harus ada pengujian yang memverifikasi bahwa aturan berfungsi seperti yang diharapkan. Aturan ini
dapat berada di lokasi standar untuk bahasa yang menjadi tujuan aturan atau
direktori tests/
di tingkat teratas.
Contoh (opsional)
Pengguna akan merasa terbantu dengan adanya direktori examples/
yang menunjukkan beberapa
cara dasar penggunaan aturan.
CI/CD
Banyak kumpulan aturan yang menggunakan GitHub Actions. Lihat konfigurasi yang digunakan dalam repositori rules-template, yang disederhanakan menggunakan "alur kerja yang dapat digunakan kembali" yang dihosting dalam org bazel-contrib. ci.yaml
menjalankan pengujian pada setiap PR dan comit main
, dan release.yaml
berjalan setiap kali Anda mendorong tag ke repositori.
Lihat komentar di repo template aturan untuk mengetahui informasi selengkapnya.
Jika repositori Anda berada dalam organisasi bazelbuild, Anda dapat meminta untuk menambahkannya ke ci.bazel.build.
Dokumentasi
Baca dokumentasi Stardoc untuk mengetahui petunjuk mengenai cara memberi komentar pada aturan Anda agar dokumentasi dapat dibuat secara otomatis.
Folder docs/ rules-template
menunjukkan cara sederhana untuk memastikan konten Markdown di folder docs/
selalu yang terbaru
saat file Starlark diperbarui.
FAQ
Mengapa kita tidak dapat menambahkan aturan ke repositori GitHub Bazel utama?
Kami ingin memisahkan aturan dari rilis Bazel sebanyak mungkin. Lebih jelas siapa yang memiliki setiap aturan, sehingga mengurangi beban pada developer Bazel. Bagi pengguna kami, pemisahan akan memudahkan untuk mengubah, mengupgrade, mendowngrade, dan mengganti aturan. Berkontribusi pada aturan dapat lebih ringan daripada berkontribusi pada Bazel - bergantung pada aturan -, termasuk akses pengiriman penuh ke repositori GitHub yang sesuai. Mendapatkan akses pengiriman ke Bazel itu sendiri adalah proses yang jauh lebih rumit.
Kelemahannya adalah proses penginstalan satu kali yang lebih rumit bagi pengguna kami:
mereka harus menambahkan dependensi pada kumpulan aturan Anda dalam file MODULE.bazel
mereka.
Kami dulu memiliki semua aturan di repositori Bazel (di
//tools/build_rules
atau //tools/build_defs
). Kami masih memiliki beberapa aturan
di sana, tetapi kami sedang berupaya memindahkan aturan yang tersisa.