Pendaftaran dan CFP BazelCon 2024 sudah dibuka sekarang
Untuk dokumentasi rilis stabil, gunakan drop-down "Dokumen berversi". Tampilan default mencerminkan versi terbaru di HEAD.

Halaman ini diterjemahkan oleh Cloud Translation API.

Men-deploy Aturan

7/0.9/2.5. Lihat sumber Nightly {/3/}

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 ini, dan menyertakan pembuatan dokumentasi API serta menyiapkan pipeline CI/CD agar mendistribusikan kumpulan aturan Anda menjadi mudah.

Aturan hosting dan penamaan

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

Nama repositori untuk aturan Bazel distandarisasi 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 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 belum 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
  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 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, anggap repositori tersebut milik organisasi bazelbuild.

workspace(name = "rules_mockascript")

README

Di tingkat atas, harus ada README yang berisi (setidaknya) hal yang diperlukan pengguna untuk menyalin dan menempel 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, tampilannya akan 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 hal tersebut dalam dokumentasi aturan (misalnya, lihat aturan Skydoc, yang bergantung pada aturan Sass), dan sediakan 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 dinamai menurut bahasa dan berikan titik entri - file defs.bzl yang mengekspor semua aturan (sertakan juga file BUILD sehingga direktori tersebut 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 menetapkan aturan toolchain, Anda mungkin 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 untuk mengetahui batasan yang sudah ada, serta pertimbangkan untuk berkontribusi pada batasan Anda di sana jika batasan tersebut tidak bergantung pada bahasa. Perhatikan saat memasukkan batasan kustom. Semua pengguna aturan Anda akan menggunakannya untuk menjalankan logika khusus platform dalam file BUILD mereka (misalnya, menggunakan pilihan). Dengan batasan khusus, 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 mereka.

Aturan repositori

Dependensi

Aturan Anda mungkin memiliki dependensi eksternal. Agar lebih sederhana 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 makro titik entri tunggal 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 menghilangkan 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.

Perlu diperhatikan 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. yang sebelumnya akan selalu diambil, dan yang kedua hanya akan diambil saat pengguna benar-benar perlu membuat 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. Ini bisa berada di lokasi standar untuk bahasa yang menjadi target aturan atau direktori tests/ di tingkat atas.

Contoh (opsional)

Pengguna sebaiknya memiliki direktori examples/ yang menunjukkan beberapa cara dasar penggunaan aturan kepada pengguna.

CI/CD

Banyak kumpulan aturan menggunakan Tindakan GitHub. Lihat konfigurasi yang digunakan dalam repositori aturan-template, yang disederhanakan menggunakan "alur kerja yang dapat digunakan kembali" yang dihosting dalam org bazel-contrib. ci.yaml menjalankan pengujian pada setiap PR dan main comit, dan release.yaml berjalan setiap kali Anda mengirim tag ke repositori. Lihat komentar di repositori 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/ dokumen template aturan 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. Lebih jelas siapa yang memiliki aturan individual, sehingga mengurangi beban developer Bazel. Bagi pengguna kami, pemisahan akan mempermudah aturan untuk memodifikasi, mengupgrade, mendowngrade, dan mengganti. Berkontribusi pada aturan bisa jadi lebih ringan daripada berkontribusi pada Bazel - bergantung pada aturan -, termasuk akses pengiriman penuh ke repositori GitHub yang sesuai. Mendapatkan akses kirim ke Bazel sendiri merupakan 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.

Sebelumnya, kami 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.