BazelCon 2022 akan hadir pada 16-17 November ke New York dan online.
Daftar sekarang.

Men-deploy Aturan

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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

Aturan hosting dan penamaan

Aturan baru harus masuk ke repositori GitHub mereka sendiri di organisasi Anda. Hubungi milis bazel-dev jika Anda merasa aturan Anda termasuk dalam organisasi bazelbuild.

Nama repositori untuk aturan Bazel distandardisasi pada format berikut: $ORGANIZATION/rules_$NAME. Lihat contoh di GitHub. Agar konsisten, Anda harus mengikuti format ini saat memublikasikan aturan Bazel.

Pastikan Anda menggunakan deskripsi repositori GitHub yang deskriptif dan judul README.md, misalnya:

  • Nama repositori: bazelbuild/rules_go
  • Deskripsi repositori: Aturan Go untuk Bazel
  • Tag repositori: golang, bazel
  • Header README.md: Go rules for Bazel (catatan link ke https://bazel.build yang akan memandu pengguna yang tidak familier 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 sehingga pengguna bisa dengan cepat memahami aturan baru.

Misalnya, saat menulis aturan baru untuk bahasa mockascript (make-believe), 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 merujuk aturan Anda. Jika aturan Anda termasuk dalam organisasi bazelbuild, Anda harus menggunakan rules_<lang> (seperti rules_mockascript). Jika tidak, Anda harus menamai 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 tersebut milik organisasi bazelbuild.

workspace(name = "rules_mockascript")

README

Di tingkat teratas, harus ada README yang berisi (setidaknya) hal yang perlu disalin oleh pengguna ke dalam file WORKSPACE untuk menggunakan aturan Anda. Secara umum, hal ini akan menjadi 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 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 aturan 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 akan ada beberapa aturan yang disediakan oleh repositori Anda. Buat direktori yang diberi nama oleh bahasa dan berikan titik entri - file defs.bzl yang mengekspor semua aturan (juga menyertakan 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, Anda mungkin harus 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 praktik terbaik, dan untuk melihat batasan apa saja yang sudah ada, dan pertimbangkan untuk berkontribusi pada batasan Anda jika batasan tersebut tidak bergantung pada bahasa. Untuk menerapkan batasan khusus, semua pengguna aturan Anda akan menggunakannya untuk menjalankan logika khusus platform dalam file BUILD-nya (misalnya, menggunakan select). Dengan batasan khusus, Anda menentukan bahasa yang akan digunakan oleh keseluruhan 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 datanya biasanya akan menambahkan target ini ke atribut deps.

Aturan repositori

Dependensi

Aturan Anda mungkin memiliki dependensi eksternal. Untuk mempermudah, 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 agar 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 kami akan terlihat seperti berikut:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

Mendaftarkan toolchain

Aturan Anda juga dapat mendaftarkan toolchain. Berikan makro WORKSPACE terpisah yang mendaftarkan toolchain ini. Dengan cara ini, pengguna dapat memutuskan untuk menghilangkan dependensi makro dan 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.

Perlu diketahui 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 ingin mendaftarkan toolchain, Anda harus menjalankan 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, berikan cuplikan yang dapat disalin dan ditempel oleh 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 tersebut berfungsi seperti yang diharapkan. Ini dapat berada di lokasi standar untuk bahasa tempat aturan atau direktori tests/ di level atas.

Contoh (opsional)

Akan lebih bermanfaat jika pengguna memiliki direktori examples/ yang menampilkan beberapa cara dasar kepada pengguna untuk menggunakan aturan tersebut.

Pengujian

Siapkan Travis seperti yang dijelaskan dalam dokumen memulai mereka. 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 tentang 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 pemilik tiap aturan, sehingga mengurangi beban developer Bazel. Bagi pengguna kami, pemisahan memudahkan perubahan, upgrade, downgrade, dan penggantian aturan. Berkontribusi ke aturan dapat lebih ringan daripada berkontribusi ke Bazel - bergantung pada aturan -, termasuk akses kirim penuh ke repositori GitHub yang sesuai. Mendapatkan akses kirim ke Bazel sendiri adalah proses yang jauh lebih terlibat.

Kelemahannya adalah proses penginstalan satu kali yang lebih rumit bagi pengguna: mereka harus menyalin dan menempel aturan ke file WORKSPACE, seperti yang ditampilkan 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, tetapi kami berupaya untuk memindahkan aturan lainnya.