Halaman ini mengasumsikan bahwa Anda sudah memahami Bazel dan memberikan panduan serta saran untuk menyusun project agar dapat memanfaatkan fitur Bazel sepenuhnya.
Sasaran keseluruhannya adalah:
- Menggunakan dependensi yang lebih mendetail untuk memungkinkan paralelisme dan inkrementalitas.
- Agar dependensi tetap dienkapsulasi dengan baik.
- Agar kode terstruktur dengan baik dan dapat diuji.
- Untuk membuat konfigurasi build yang mudah dipahami dan dikelola.
Panduan ini bukan persyaratan: hanya sedikit project yang dapat mematuhi semuanya. Seperti yang disebutkan di halaman manual untuk lint, "Reward khusus akan diberikan kepada orang pertama yang menghasilkan program sebenarnya yang tidak menghasilkan error dengan pemeriksaan yang ketat". Namun, memasukkan sebanyak mungkin prinsip ini harus membuat project lebih mudah dibaca, tidak terlalu rentan error, dan lebih cepat dibuat.
Halaman ini menggunakan tingkat persyaratan yang dijelaskan dalam RFC ini.
Menjalankan build dan pengujian
Project harus selalu dapat menjalankan bazel build //...
dan
bazel test //...
dengan sukses di cabangnya yang stabil. Target yang diperlukan,tetapi tidak dibuat dalam keadaan tertentu (seperti memerlukan flag build tertentu, tidak mem-build di platform tertentu, memerlukan perjanjian lisensi) harus diberi tag sespesifik mungkin (misalnya, "requires-osx
"). Pemberian tag ini memungkinkan target difilter pada tingkat yang lebih terperinci daripada tag "manual" dan memungkinkan seseorang memeriksa file BUILD
untuk memahami batasan target.
Dependensi pihak ketiga
Anda dapat mendeklarasikan dependensi pihak ketiga:
- Deklarasikan item tersebut sebagai repositori jarak jauh di file
WORKSPACE
. - Atau tempatkan keduanya di direktori bernama
third_party/
di bawah direktori ruang kerja Anda.
Bergantung pada biner
Semuanya harus dibuat dari sumber jika memungkinkan. Ini berarti, bukannya bergantung pada library some-library.so
, Anda sebaiknya membuat file BUILD
dan mem-build some-library.so
dari sumbernya, lalu bergantung pada target tersebut.
Selalu mem-build dari sumber memastikan bahwa build tidak menggunakan library yang dibuat dengan flag yang tidak kompatibel atau arsitektur yang berbeda. Ada juga beberapa fitur seperti cakupan, analisis statis, atau analisis dinamis yang hanya berfungsi pada sumbernya.
Pembuatan versi
Memilih membuat semua kode dari head jika memungkinkan. Saat versi harus
digunakan, hindari menyertakan versi dalam nama target (misalnya, //guava
,
bukan //guava-20.0
). Penamaan ini membuat library lebih mudah diperbarui (hanya satu
target yang perlu diupdate). Metode ini juga lebih tahan terhadap masalah dependensi
intan: jika satu library bergantung pada guava-19.0
dan satu library bergantung pada guava-20.0
,
Anda akan mendapatkan library yang mencoba bergantung pada dua versi berbeda.
Jika Anda membuat alias yang menyesatkan untuk mengarahkan kedua target ke satu library guava
,
file BUILD
akan menyesatkan.
Menggunakan file .bazelrc
Untuk opsi khusus project, gunakan file konfigurasi workspace/.bazelrc
Anda (lihat format Bazelrc).
Jika ingin mendukung opsi per pengguna untuk project Anda yang tidak ingin Anda kontrol ke kontrol sumber, sertakan baris:
try-import %workspace%/user.bazelrc
(atau nama file lainnya) di workspace/.bazelrc
dan tambahkan user.bazelrc
ke .gitignore
Anda.
Paket
Setiap direktori yang berisi file buildable harus berupa paket. Jika file BUILD
merujuk pada file di subdirektori (seperti, srcs = ["a/b/C.java"]
),
file tersebut adalah tanda bahwa file BUILD
harus ditambahkan ke subdirektori tersebut. Semakin lama struktur ini ada, semakin besar dependensi sirkular yang akan dibuat secara tidak sengaja, cakupan target akan menurun, dan semakin banyak dependensi terbalik yang harus diperbarui.