Men-deploy Aturan

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Halaman ini ditujukan bagi penulis aturan yang berencana membuat aturan mereka tersedia bagi orang lain.

Aturan hosting dan penamaan

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

Nama repositori untuk aturan Bazel distandardisasi 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 dan judul repositori GitHub yang deskriptif, contoh:README.md

  • 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 mengenal Bazel ke tempat yang tepat)

Aturan dapat dikelompokkan berdasarkan bahasa (seperti Scala) atau platform (seperti Android).

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
  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

WORKSPACE

Di WORKSPACE project, Anda harus menentukan nama yang akan digunakan pengguna untuk merujuk ke 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 bahwa repositori tersebut adalah milik organisasi bazelbuild.

workspace(name = "rules_mockascript")

README

Di tingkat teratas, harus ada README yang berisi (setidaknya) apa yang perlu disalin dan ditempel pengguna ke dalam file WORKSPACE mereka untuk menggunakan aturan Anda. Secara umum, 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, ini terlihat seperti:

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 dinamai 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, serta file BUILD dan file defs.bzl di dalamnya:

/
  mockascript/
    BUILD
    defs.bzl

Batasan

Jika aturan Anda menentukan aturan toolchain, Anda mungkin 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 melihat batasan yang sudah ada, serta pertimbangkan untuk menyumbangkan 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 dalam file BUILD mereka (misalnya, menggunakan selects). Dengan batasan kustom, Anda menentukan bahasa yang akan digunakan oleh seluruh ekosistem Bazel.

Library runfile

Jika aturan Anda menyediakan library standar untuk mengakses runfile, aturan tersebut harus berupa 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. Untuk mempermudah penggunaan aturan Anda, berikan makro WORKSPACE yang akan mendeklarasikan dependensi pada dependensi eksternal tersebut. Jangan deklarasikan dependensi pengujian di sana, hanya dependensi yang diperlukan aturan agar dapat 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. Berikan 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 dalam file <LANG>/repositories.bzl.

Perhatikan 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 yang kompleks di repositori, sebaiknya pisahkan repositori dengan target toolchain dari repositori dengan target <LANG>_toolchain. Former akan selalu diambil, dan latter hanya akan diambil saat pengguna benar-benar perlu membuat kode <LANG>.

Cuplikan rilis

Dalam pengumuman rilis, berikan cuplikan yang dapat disalin dan ditempelkan pengguna ke dalam file WORKSPACE mereka. Cuplikan ini secara umum akan terlihat sebagai 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 berfungsi seperti yang diharapkan. File ini dapat berada di lokasi standar untuk bahasa yang digunakan dalam aturan atau di direktori tests/ di tingkat teratas.

Contoh (opsional)

Pengguna akan merasa terbantu dengan adanya direktori examples/ yang menunjukkan beberapa cara dasar penggunaan aturan.

Pengujian

Siapkan Travis seperti yang dijelaskan dalam dokumen memulai penggunaannya. 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 agar 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 memudahkan aturan untuk diubah, diupgrade, didowngrade, dan diganti. 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.

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

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