Halaman ini ditujukan bagi penulis aturan yang berencana membuat aturannya tersedia bagi orang lain.
Aturan penamaan dan hosting
Aturan baru harus dimasukkan ke dalam repositori GitHub mereka sendiri di bawah organisasi Anda. Mulai thread di GitHub jika merasa aturan Anda termasuk dalam organisasi bazelbuild.
Nama repositori untuk aturan Bazel distandarkan dalam 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 dan judul README.md
yang deskriptif, misalnya:
- Nama repositori:
bazelbuild/rules_go
- Deskripsi repositori: Aturan Go untuk Bazel
- Tag repositori:
golang
,bazel
- Header
README.md
: Buka aturan 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) atau platform (seperti Android).
Konten repositori
Setiap repositori aturan harus memiliki tata letak tertentu sehingga pengguna dapat memahami aturan baru dengan cepat.
Misalnya, saat menulis aturan baru untuk bahasa (pernyataan) mockascript
, 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
Pada 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>
Anda (seperti build_stack_rules_proto
). Mulai thread di GitHub jika Anda merasa aturan Anda harus mengikuti konvensi untuk aturan organisasi bazelbuild.
Di bagian berikut, asumsikan repositori milik organisasi bazelbuild.
workspace(name = "rules_mockascript")
README
Di tingkat teratas, harus ada README
yang berisi (setidaknya) hal yang diperlukan pengguna untuk menyalin dan menempel ke file WORKSPACE
mereka agar dapat menggunakan aturan Anda.
Secara umum, ini adalah http_archive
yang mengarah ke rilis GitHub dan
panggilan makro yang mendownload/mengonfigurasi alat apa pun yang diperlukan aturan Anda. Misalnya, untuk aturan Go, tampilannya 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 hal tersebut 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 menurut bahasa dan berikan titik entri - file defs.bzl
yang mengekspor semua aturan (juga sertakan file BUILD
sehingga direktori tersebut merupakan 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, Anda mungkin perlu menentukan constraint_setting
dan/atau constraint_value
kustom. Masukkan ke dalam paket //<LANG>/constraints
. Struktur direktori Anda akan terlihat seperti ini:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Harap baca
github.com/bazelbuild/platforms
untuk mengetahui praktik terbaik, dan untuk melihat batasan yang ada, serta
pertimbangkan kontribusi batasan Anda di sana jika bahasa tersebut tidak bergantung pada bahasa.
Berhati-hatilah dalam memperkenalkan batasan kustom, 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, aturan tersebut harus dalam bentuk 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
miliknya.
Aturan repositori
Dependensi
Aturan Anda mungkin memiliki dependensi eksternal. Agar lebih mudah bergantung 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 untuk 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. Berikan makro WORKSPACE
terpisah yang mendaftarkan toolchain ini. Dengan cara ini, pengguna dapat memutuskan untuk menghilangkan
makro dan dependensi kontrol sebelumnya secara manual, sambil tetap diizinkan untuk
mendaftarkan toolchain.
Oleh karena itu, tambahkan makro WORKSPACE
yang bernama rules_<LANG>_toolchains
ke dalam
file <LANG>/repositories.bzl
.
Perhatikan bahwa untuk mengatasi toolchain dalam fase analisis, Bazel perlu
menganalisis semua target toolchain
yang terdaftar. Bazel tidak perlu
menganalisis semua target yang direferensikan oleh atribut toolchain.toolchain
. Jika ingin mendaftarkan toolchain, Anda perlu melakukan komputasi yang kompleks di repositori, pertimbangkan untuk membagi repositori dengan target toolchain
dari repositori dengan target <LANG>_toolchain
. Data pertama akan selalu diambil, dan
yang terakhir hanya akan diambil saat pengguna benar-benar perlu membuat kode <LANG>
.
Cuplikan rilis
Dalam pengumuman rilis Anda, berikan cuplikan yang dapat disalin dan ditempelkan oleh pengguna ke dalam file WORKSPACE
mereka. Cuplikan ini secara umum akan terlihat sebagai 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. Hal ini bisa jadi berada di lokasi standar untuk bahasa yang digunakan aturan atau direktori tests/
di tingkat teratas.
Contoh (opsional)
Ada baiknya pengguna memiliki direktori examples/
yang menunjukkan kepada pengguna
beberapa cara dasar untuk menggunakan aturan.
Pengujian
Siapkan Travis seperti yang dijelaskan dalam dokumen memulai. Lalu tambahkan
file .travis.yml
ke repositori Anda dengan konten berikut:
dist: xenial # Ubuntu 16.04
# On trusty (or later) images, the Bazel apt repository can be used.
addons:
apt:
sources:
- sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
key_url: 'https://bazel.build/bazel-release.pub.gpg'
packages:
- bazel
script:
- bazel build //...
- bazel test //...
Jika repositori Anda berada dalam organisasi bazelbuild, Anda dapat meminta untuk menambahkannya ke ci.bazel.build.
Dokumentasi
Baca dokumentasi Stardoc untuk mengetahui petunjuk cara mengomentari aturan agar dokumentasi dapat dibuat secara otomatis.
FAQ
Mengapa kami tidak dapat menambahkan aturan ke repositori GitHub Bazel utama?
Kami ingin memisahkan aturan dari rilis Bazel sebanyak mungkin. Lebih jelas siapa yang memiliki aturan individual, sehingga mengurangi beban developer Bazel. Bagi pengguna kami, pemisahan memudahkan untuk mengubah, mengupgrade, mendowngrade, dan mengganti aturan. Berkontribusi ke aturan bisa jadi lebih ringan daripada berkontribusi pada Bazel - bergantung pada aturannya - 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: mereka harus menyalin dan menempelkan aturan ke dalam file WORKSPACE
, seperti yang ditunjukkan di bagian README.md
di atas.
Sebelumnya, kami memiliki semua aturan di repositori Bazel (pada //tools/build_rules
atau //tools/build_defs
). Kami masih memiliki beberapa aturan di sana, tetapi kami sedang berupaya untuk memindahkan aturan yang tersisa.