Halaman ini ditujukan untuk penulis aturan yang berencana menyediakan aturan mereka kepada orang lain.
Aturan hosting dan penamaan
Aturan baru harus masuk ke repositori GitHub mereka sendiri di organisasi Anda. Hubungi milis bazel-dev jika 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 menurut bahasa (seperti Scala) atau platform (seperti Android).
Konten repositori
Setiap repositori aturan harus memiliki tata letak tertentu agar pengguna dapat memahami aturan baru dengan cepat.
Misalnya, saat menulis aturan baru untuk bahasa
mockascript (fiktif), 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
Di 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). Hubungi
milis bazel-dev
jika Anda merasa aturan Anda harus mengikuti konvensi untuk aturan di
organisasi bazelbuild.
Di bagian berikut, asumsikan repositori adalah milik organisasi bazelbuild.
workspace(name = "rules_mockascript")
README
Di tingkat teratas, harus ada README yang berisi (setidaknya) hal-hal yang
harus disalin-tempel oleh pengguna ke dalam 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, 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 berdasarkan bahasa dan berikan titik entri - file defs.bzl
yang mengekspor semua aturan (sertakan juga file BUILD sehingga direktori 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 untuk mengetahui batasan yang sudah ada, serta
pertimbangkan untuk berkontribusi pada batasan Anda di sana jika batasan tersebut 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. Untuk mempermudah 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 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 kita akan terlihat seperti berikut:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
Mendaftarkan toolchain
Aturan Anda juga dapat 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
file <LANG>/repositories.bzl.
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, pertimbangkan untuk membagi 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>.
Cuplikan rilis
Dalam pengumuman rilis, sediakan cuplikan yang dapat disalin dan ditempel 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 bekerja seperti yang diharapkan. Kolom ini
dapat berada di lokasi standar untuk bahasa yang digunakan aturan atau
direktori tests/ di tingkat atas.
Contoh (opsional)
Pengguna sebaiknya memiliki direktori examples/ yang menunjukkan beberapa cara dasar penggunaan aturan kepada pengguna.
Pengujian
Siapkan Travis seperti yang dijelaskan dalam dokumen
memulai. Kemudian, 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 di bawah organisasi bazelbuild, Anda dapat meminta untuk menambahkannya ke ci.bazel.build.
Dokumentasi
Lihat dokumentasi Stardoc untuk mengetahui petunjuk cara memberi komentar pada aturan Anda sehingga dokumentasi dapat dibuat secara otomatis.
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 menyalin dan menempel aturan ke file WORKSPACE, seperti yang ditunjukkan di
bagian README.md di atas.
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.