Halaman ini mengasumsikan bahwa Anda sudah mengenal Bazel dan memberikan panduan serta saran untuk menyusun project agar dapat memanfaatkan fitur Bazel secara maksimal.
Tujuan keseluruhan adalah:
- Untuk menggunakan dependensi terperinci guna memungkinkan paralelisme dan inkrementalitas.
- Untuk menjaga dependensi agar tetap dienkapsulasi dengan baik.
- Untuk membuat kode terstruktur dengan baik dan dapat diuji.
- Untuk membuat konfigurasi build yang mudah dipahami dan dikelola.
Panduan ini bukanlah persyaratan: hanya sedikit project yang dapat mematuhi semuanya. Seperti yang dikatakan oleh halaman utama untuk lint, "Reward spesial akan diberikan kepada orang pertama yang menghasilkan program sungguhan yang tidak menghasilkan error dengan pemeriksaan ketat". Namun, menggabungkan sebanyak mungkin prinsip-prinsip ini akan membuat project lebih mudah dibaca, tidak rentan error, dan lebih cepat dibangun.
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 cabang stabilnya. Target yang diperlukan, tetapi tidak dibuat dalam keadaan tertentu (seperti, memerlukan flag build tertentu, tidak dibuat di platform tertentu, memerlukan perjanjian lisensi) harus diberi tag sespesifik mungkin (misalnya, "requires-osx"). Pemberian tag ini memungkinkan target difilter pada level 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 sebagai repositori jarak jauh dalam file
WORKSPACE. - Atau, letakkan dalam direktori bernama
third_party/di bawah direktori ruang kerja Anda.
Bergantung pada biner
Segala sesuatu harus dibuat dari sumber jika memungkinkan. Secara umum, hal ini berarti
bahwa, alih-alih bergantung pada some-library.so library, Anda akan membuat
file BUILD dan mem-build some-library.so dari sumbernya, kemudian bergantung pada
target tersebut.
Selalu membangun dari sumber akan memastikan bahwa build tidak menggunakan library yang di-build dengan flag yang tidak kompatibel atau arsitektur yang berbeda. Ada juga beberapa fitur seperti cakupan, analisis statis, atau analisis dinamis yang hanya berfungsi pada sumber.
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 memudahkan library untuk diupdate (hanya satu
target yang perlu diperbarui). Metode ini juga lebih tahan terhadap masalah dependensi diamond: jika satu library bergantung pada guava-19.0 dan yang lain bergantung pada guava-20.0, Anda mungkin 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 yang tidak ingin Anda periksa 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 yang dapat dibangun harus berupa paket. Jika file BUILD
merujuk ke file di subdirektori (seperti, srcs = ["a/b/C.java"]), itu
tandanya file BUILD harus ditambahkan ke subdirektori tersebut. Makin lama
struktur ini ada, makin besar kemungkinan dependensi sirkular
dibuat secara tidak sengaja, cakupan target akan merayap, dan makin banyak
dependensi terbalik yang harus diperbarui.