Halaman ini ditujukan untuk penulis aturan yang berencana menyediakan aturan mereka bagi orang lain.
Sebaiknya mulai kumpulan aturan baru dari repositori template: https://github.com/bazel-contrib/rules-template Template tersebut mengikuti rekomendasi di bawah, serta menyertakan pembuatan dokumentasi API dan menyiapkan pipeline CI/CD agar distribusi kumpulan aturan Anda mudah dilakukan.
Aturan hosting dan penamaan
Aturan baru akan masuk ke repositori GitHub-nya sendiri di bagian organisasi Anda. Mulai thread di GitHub jika Anda merasa aturan Anda termasuk dalam organisasi bazelbuild.
Nama repositori untuk aturan Bazel distandardisasi menggunakan format berikut:
$ORGANIZATION/rules_$NAME
.
Lihat contoh di GitHub.
Agar konsisten, Anda harus mengikuti format yang sama ini saat memublikasikan aturan Bazel.
Pastikan untuk menggunakan deskripsi repositori GitHub yang deskriptif dan judul README.md
, misalnya:
- 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 menggunakan 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 agar pengguna dapat dengan cepat memahami aturan baru.
Misalnya, saat menulis aturan baru untuk bahasa mockascript
(buat keyakinan), repositori aturan akan memiliki struktur berikut:
/
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
RUANG KERJA
Dalam WORKSPACE
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 memberi nama repositori <org>_rules_<lang>
(seperti build_stack_rules_proto
). Mulai thread di GitHub jika merasa aturan Anda harus mengikuti konvensi untuk aturan dalam organisasi bazelbuild.
Di bagian berikut, anggap repositori adalah milik organisasi bazelbuild.
workspace(name = "rules_mockascript")
README
Di tingkat atas, harus ada README
yang berisi (setidaknya) hal yang perlu disalin dan ditempel oleh pengguna ke file WORKSPACE
mereka untuk menggunakan aturan Anda.
Secara umum, ini akan berupa http_archive
yang mengarah ke rilis GitHub Anda dan
panggilan makro yang mendownload/mengonfigurasi alat apa pun yang diperlukan aturan Anda. Misalnya,
untuk aturan
Go, terlihat
seperti ini:
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()
Jika aturan Anda bergantung pada aturan repositori lain, tentukan dalam dokumentasi aturan (misalnya, lihat aturan Skydoc, yang bergantung pada aturan Sass), dan berikan makro WORKSPACE
yang akan mendownload semua dependensi (lihat rules_go
di atas).
Aturan
Sering kali 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 direktori tersebut berupa 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, ada kemungkinan Anda harus 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 di sana jika tidak bergantung pada bahasa.
Berhati-hatilah memperkenalkan batasan khusus, semua pengguna aturan Anda akan menggunakannya untuk melakukan logika khusus platform dalam file BUILD
mereka (misalnya, menggunakan pilihan).
Dengan batasan kustom, Anda menentukan bahasa yang akan digunakan oleh seluruh
ekosistem Bazel.
Library Runfiles
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
-nya.
Aturan repositori
Dependensi
Aturan Anda mungkin memiliki dependensi eksternal. Untuk lebih menyederhanakan dependensi pada aturan Anda, berikan makro WORKSPACE
yang akan mendeklarasikan dependensi pada
dependensi eksternal tersebut. Jangan mendeklarasikan dependensi pengujian di sana, hanya dependensi yang diperlukan aturan agar dapat berfungsi. Masukkan dependensi pengembangan ke dalam
file WORKSPACE
.
Buat file bernama <LANG>/repositories.bzl
dan berikan satu makro titik entri
bernama rules_<LANG>_dependencies
. Direktori kami akan terlihat seperti berikut:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
Mendaftarkan toolchain
Aturan Anda mungkin juga mendaftarkan toolchain. Harap sediakan makro WORKSPACE
terpisah yang mendaftarkan toolchain ini. Dengan cara ini, pengguna dapat memutuskan untuk menghapus
makro sebelumnya dan mengontrol dependensi secara manual, sambil tetap diizinkan untuk
mendaftarkan toolchain.
Oleh karena itu, tambahkan makro WORKSPACE
bernama rules_<LANG>_toolchains
ke dalam
file <LANG>/repositories.bzl
.
Perlu diketahui bahwa untuk menyelesaikan 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, pertimbangkan untuk membagi repositori dengan target toolchain
dari
repositori dengan target <LANG>_toolchain
. Versi sebelumnya akan selalu diambil, dan versi yang kedua hanya akan diambil saat pengguna benar-benar perlu membuat kode <LANG>
.
Cuplikan rilis
Dalam pengumuman rilis, berikan cuplikan yang dapat disalin dan ditempel oleh pengguna
ke file WORKSPACE
mereka. Cuplikan ini secara umum akan terlihat seperti berikut:
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()
Pengujian
Harus ada pengujian yang memverifikasi bahwa aturan berfungsi seperti yang diharapkan. Lokasi ini dapat berada di lokasi standar untuk bahasa yang digunakan aturannya atau direktori tests/
di level teratas.
Contoh (opsional)
Sebaiknya pengguna memiliki direktori examples/
yang menunjukkan beberapa
cara dasar penggunaan aturan.
CI/CD
Banyak kumpulan aturan menggunakan GitHub Actions. Lihat konfigurasi yang digunakan dalam repo rules-template, yang disederhanakan menggunakan "alur kerja yang dapat digunakan kembali" yang dihosting di organisasi bazel-contrib. ci.yaml
menjalankan pengujian pada setiap PR dan comit main
, dan release.yaml
berjalan setiap kali Anda mengirim tag ke repositori.
Lihat komentar dalam repositori template aturan untuk mengetahui informasi selengkapnya.
Jika repositori Anda berada di organisasi bazelbuild, Anda dapat meminta untuk menambahkannya ke ci.bazel.build.
Dokumentasi
Lihat dokumentasi Stardoc untuk mengetahui petunjuk tentang cara memberi komentar pada aturan agar dokumentasi dapat dibuat secara otomatis.
rules-template docs/ folder
menunjukkan cara sederhana untuk memastikan konten Markdown dalam folder docs/
selalu terbaru
saat file Starlark diperbarui.
FAQ
Mengapa kita tidak dapat menambahkan aturan ke repositori GitHub Bazel utama?
Kita ingin memisahkan aturan dari rilis Bazel sebanyak mungkin. Semakin jelas siapa yang memiliki aturan individual, sehingga mengurangi beban pada developer Bazel. Bagi pengguna, decoupling memudahkan untuk mengubah, mengupgrade, mendowngrade, dan mengganti aturan. Berkontribusi pada aturan bisa jadi lebih ringan daripada berkontribusi pada Bazel - bergantung pada aturan -, termasuk akses kirim penuh ke repositori GitHub yang sesuai. Mendapatkan akses pengiriman ke Bazel sendiri merupakan proses yang jauh lebih rumit.
Kelemahannya adalah proses penginstalan satu kali yang lebih rumit bagi pengguna:
mereka harus menyalin dan menempelkan aturan ke dalam file WORKSPACE
, seperti yang ditunjukkan pada
bagian README.md
di atas.
Dulu kami 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.