Men-deploy Aturan

Halaman ini ditujukan untuk penulis aturan yang berencana menyediakan aturan mereka untuk orang lain.

Sebaiknya mulai kumpulan 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 agar distribusi kumpulan aturan Anda menjadi mudah.

Aturan hosting dan penamaan

Aturan baru harus masuk ke repositori GitHub-nya sendiri di organisasi Anda. Mulai diskusi di GitHub jika Anda merasa aturan Anda termasuk dalam organisasi bazelbuild.

Nama repositori untuk aturan Bazel distandardisasi dengan format berikut: $ORGANIZATION/rules_$NAME. Lihat contoh di GitHub. Untuk konsistensi, Anda harus mengikuti format yang sama saat memublikasikan aturan Bazel.

Pastikan untuk menggunakan deskripsi repositori GitHub dan judul README.md yang deskriptif, contoh:

• Nama repositori: bazelbuild/rules_go
• Deskripsi repositori: Go rules for Bazel
• Tag repositori: golang, bazel
• README.md header: 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 agar pengguna dapat dengan cepat memahami aturan baru.

Misalnya, saat menulis aturan baru untuk bahasa mockascript (fiktif), 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 memberi nama repositori <org>_rules_<lang> (seperti build_stack_rules_proto). Mulai diskusi di GitHub jika Anda merasa aturan Anda harus mengikuti konvensi untuk aturan di organisasi bazelbuild.

Di bagian berikut, asumsikan repositori termasuk dalam organisasi bazelbuild.

module(name = "rules_mockascript")

README

Di tingkat atas, harus ada README yang berisi deskripsi singkat tentang kumpulan aturan Anda, dan API yang diharapkan pengguna.

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 agar direktori menjadi paket). Untuk rules_mockascript, artinya akan ada direktori bernama mockascript, dan file BUILD serta file defs.bzl di dalamnya:

/
  mockascript/
    BUILD
    defs.bzl

Batasan

Jika aturan Anda menentukan toolchain aturan, Anda mungkin perlu menentukan constraint_setting kustom dan/atau constraint_values. Tempatkan aturan 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 melihat batasan yang sudah ada, serta pertimbangkan untuk memberikan kontribusi batasan Anda di sana jika batasan tersebut tidak bergantung pada bahasa. Berhati-hatilah saat memperkenalkan batasan kustom, semua pengguna aturan Anda akan menggunakannya untuk melakukan logika khusus platform di file BUILD mereka (misalnya, menggunakan pilihan). Dengan batasan kustom, Anda menentukan bahasa yang akan digunakan seluruh ekosistem Bazel.

Library runfiles

Jika aturan Anda menyediakan library standar untuk mengakses runfiles, aturan tersebut harus dalam bentuk target library yang terletak di //<LANG>/runfiles (singkatan dari //<LANG>/runfiles:runfiles). Target pengguna yang perlu mengakses dependensi data mereka 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 juga dapat mendaftarkan toolchain, yang juga dapat Anda tentukan dalam file MODULE.bazel.

Perhatikan bahwa untuk menyelesaikan 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 untuk mendaftarkan toolchain, Anda perlu melakukan komputasi yang kompleks di repositori, pertimbangkan untuk membagi repositori dengan toolchain target dari repositori dengan <LANG>_toolchain target. Yang pertama akan selalu diambil, dan yang kedua hanya akan diambil jika pengguna benar-benar perlu membuat kode <LANG>.

Cuplikan rilis

Dalam pengumuman rilis, berikan cuplikan yang dapat disalin dan ditempel oleh pengguna ke dalam file MODULE.bazel mereka. Cuplikan ini secara umum akan terlihat sebagai berikut:

bazel_dep(name = "rules_<LANG>", version = "<VERSION>")

Pengujian

Harus ada pengujian yang memverifikasi bahwa aturan berfungsi seperti yang diharapkan. Pengujian ini dapat berada di lokasi standar untuk bahasa yang digunakan aturan atau direktori tests/ di tingkat atas.

Contoh (opsional)

Pengguna akan merasa terbantu jika ada direktori examples/ yang menunjukkan beberapa cara dasar penggunaan aturan.

CI/CD

Banyak kumpulan aturan menggunakan GitHub Actions. Lihat konfigurasi yang digunakan di 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 commit main, dan release.yaml berjalan setiap kali Anda mengirim tag ke repositori. Lihat komentar di repo rules-template 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 cara memberi komentar pada aturan Anda sehingga dokumentasi dapat dibuat secara otomatis.

Folder docs/ rules-template menunjukkan cara sederhana untuk memastikan konten Markdown di folder docs/ selalu 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. Kepemilikan aturan individual menjadi lebih jelas, sehingga mengurangi beban developer Bazel. Bagi pengguna kami, pemisahan ini memudahkan mereka untuk mengubah, mengupgrade, mendowngrade, dan mengganti aturan. Memberikan kontribusi pada aturan bisa lebih ringan daripada memberikan kontribusi 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 di file MODULE.bazel mereka.

Kami dulu memiliki semua aturan di repositori Bazel (di bagian //tools/build_rules atau //tools/build_defs). Kami masih memiliki beberapa aturan di sana, tetapi kami sedang berupaya memindahkan aturan yang tersisa.