Pendaftaran BazelCon 2024 sudah dibuka!

Halaman ini diterjemahkan oleh Cloud Translation API.

Men-deploy Aturan

Laporkan masalah Lihat sumber Per Malam · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Halaman ini ditujukan untuk penulis aturan yang berencana menyediakan aturan mereka kepada 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 mencakup pembuatan dokumentasi API dan menyiapkan pipeline CI/CD agar mudah untuk mendistribusikan kumpulan aturan Anda.

Aturan hosting dan penamaan

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

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 README.md judul, contoh:

Nama repositori: bazelbuild/rules_go
Deskripsi repositori: Aturan Go untuk Bazel
Tag repositori: golang, bazel
Header README.md: Aturan Go untuk Bazel (perhatikan tautan 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 sehingga pengguna dapat dengan cepat memahami aturan baru.

Misalnya, saat menulis aturan baru untuk (buat-percaya) 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

Dalam WORKSPACE project, Anda harus menentukan nama yang akan digunakan pengguna sebagai referensi pada aturan Anda. Jika aturan Anda termasuk dalam bazelbuild, Anda harus menggunakan rules_<lang> (seperti rules_mockascript). Jika tidak, Anda harus menamai repositori <org>_rules_<lang> (seperti build_stack_rules_proto). Memohon mulai rangkaian pesan di GitHub jika merasa aturan Anda harus mengikuti konvensi untuk aturan dalam bazelbuild.

Di bagian berikut, asumsikan bahwa repositori adalah milik bazelbuild.

workspace(name = "rules_mockascript")

README

Di tingkat atas, harus ada README yang berisi (setidaknya) apa pengguna harus menyalin dan menempel ke file WORKSPACE mereka untuk menggunakan aturan Anda. Secara umum, ini adalah http_archive yang mengarah ke rilis GitHub Anda dan panggilan makro yang mendownload/mengonfigurasi alat yang dibutuhkan aturan Anda. Misalnya, untuk model Go aturan, hal ini 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 dokumentasi aturan (misalnya, lihat Aturan Skydoc, yang bergantung pada aturan Sass), dan menyediakan WORKSPACE makro 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 mengekspor semua aturan (sertakan juga file BUILD sehingga direktorinya adalah sebuah paket). Untuk rules_mockascript, itu berarti akan ada direktori bernama mockascript, dan file BUILD serta file defs.bzl di dalamnya:

/
  mockascript/
    BUILD
    defs.bzl

Batasan

Jika aturan Anda menetapkan toolchain, Anda mungkin perlu menentukan constraint_setting kustom, dan/atau constraint_value dtk. Masukkan ini ke dalam paket //<LANG>/constraints. Nama struktur direktori akan terlihat seperti ini:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

Harap dibaca github.com/bazelbuild/platforms untuk praktik terbaik, dan untuk melihat batasan apa yang sudah ada, dan pertimbangkan untuk berkontribusi dalam batasan tersebut jika tidak tergantung bahasa. Jangan lupa untuk memasukkan batasan khusus, semua pengguna aturan Anda akan menggunakannya untuk menjalankan logika khusus platform di file BUILD mereka (misalnya, menggunakan pilihan). Dengan batasan khusus, Anda menentukan bahasa yang akan digunakan oleh seluruh ekosistem Bazel akan berbicara.

Library Runfiles

Jika aturan Anda menyediakan pustaka standar untuk mengakses {i>runfile<i}, aturan itu harus dalam bentuk target library yang terletak di //<LANG>/runfiles (singkatan dari //<LANG>/runfiles:runfiles). Target pengguna yang perlu mengakses data mereka dependensi biasanya akan menambahkan target ini ke atribut deps miliknya.

Aturan repositori

Dependensi

Aturan Anda mungkin memiliki dependensi eksternal. Untuk membuat bergantung pada aturan Anda lebih sederhana, berikan makro WORKSPACE yang akan mendeklarasikan dependensi pada dependensi-dependensi eksternal tersebut. Jangan mendeklarasikan dependensi pengujian yang ada di sana, hanya dependensi yang dibutuhkan aturan agar dapat berfungsi. Masukkan dependensi pengembangan ke dalam File WORKSPACE.

Buat file bernama <LANG>/repositories.bzl dan berikan satu titik entri makro 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. Cantumkan WORKSPACE yang terpisah makro yang mendaftarkan toolchain ini. Dengan cara ini, pengguna dapat memutuskan untuk menghilangkan dependensi makro dan kontrol sebelumnya secara manual, sementara masih diizinkan untuk mendaftarkan toolchain.

Oleh karena itu, tambahkan makro WORKSPACE bernama rules_<LANG>_toolchains ke dalam File <LANG>/repositories.bzl.

Perhatikan bahwa untuk menyelesaikan toolchain dalam fase analisis, Bazel perlu analisis semua target toolchain yang terdaftar. Bazel tidak perlu analisis semua target yang dirujuk oleh atribut toolchain.toolchain. Jika secara berurutan untuk mendaftarkan toolchain, Anda perlu melakukan komputasi kompleks dalam repositori, pertimbangkan untuk memisahkan repositori dengan target toolchain dari repositori dengan target <LANG>_toolchain. Data 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 ditempelkan oleh pengguna Anda ke dalam file WORKSPACE. 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 dapat berada di lokasi standar untuk bahasa target aturan atau Direktori tests/ di tingkat teratas.

Contoh (opsional)

Hal ini berguna bagi pengguna untuk memiliki direktori examples/ yang menampilkan beberapa cara-cara dasar di mana aturan tersebut dapat digunakan.

CI/CD

Banyak kumpulan aturan menggunakan Tindakan GitHub. Lihat konfigurasi yang digunakan di repositori rules-template, yang disederhanakan menggunakan "alur kerja yang dapat digunakan kembali" dalam {i>bazel-contrib<i} org. 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 di bawah organisasi bazelbuild, Anda bisa meminta untuk menambahkan ke ci.bazel.build.

Dokumentasi

Lihat dokumentasi Stardoc untuk petunjuk tentang cara memberikan 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 yang memiliki aturan individual, mengurangi beban pengembang Bazel. Bagi pengguna kami, pemisahan memudahkan Anda mengubah, mengupgrade, mendowngrade, dan mengganti aturan. Berkontribusi pada aturan bisa jadi lebih ringan dibandingkan berkontribusi pada Bazel - bergantung pada aturan -, termasuk akses kirim penuh ke repositori GitHub ASL. Mendapatkan akses kirim ke Bazel sendiri jauh lebih rumit {i>checkout<i}.

Kelemahannya adalah proses penginstalan satu kali yang lebih rumit bagi pengguna kami: mereka harus menyalin dan menempel aturan ke file WORKSPACE, seperti yang ditunjukkan pada README.md bagian di atas.

Dulu kami memiliki semua aturan di repositori Bazel (di bawah //tools/build_rules atau //tools/build_defs). Kita masih punya beberapa aturan di sana, tetapi kami sedang berupaya memindahkan aturan yang tersisa.