Halaman ini mengasumsikan bahwa Anda sudah memahami Bazel dan memberikan panduan serta saran untuk menyusun project guna memanfaatkan fitur Bazel sepenuhnya.
Tujuan keseluruhannya adalah:
- Menggunakan dependensi terperinci untuk memungkinkan paralelisme dan inkrementalitas.
- Untuk menjaga agar dependensi tetap terenkapsulasi dengan baik.
- Untuk membuat kode yang 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 disebutkan di halaman utama lint, "Hadiah khusus akan diberikan kepada orang pertama untuk menghasilkan program sungguhan yang tidak menghasilkan error dengan pemeriksaan ketat". Namun, menggabungkan sebanyak mungkin prinsip ini akan membuat project lebih mudah dibaca, tidak terlalu rentan terhadap error, dan lebih cepat di-build.
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 di-build dalam kondisi tertentu (seperti,memerlukan flag build tertentu, tidak dibangun di platform tertentu, memerlukan perjanjian lisensi) harus diberi tag sespesifik mungkin (misalnya, "requires-osx"). Pemberian tag ini memungkinkan target difilter pada tingkat yang lebih mendetail daripada tag "manual" dan memungkinkan seseorang memeriksa file BUILD untuk memahami apa yang dimaksud dengan batasan target.
Dependensi pihak ketiga
Anda dapat menyatakan dependensi pihak ketiga:
- Deklarasikan properti tersebut sebagai repositori jarak jauh dalam file
WORKSPACE. - Atau, tempatkan di direktori bernama
third_party/pada direktori workspace Anda.
Bergantung pada biner
Semuanya harus dibuat dari sumber jika memungkinkan. Secara umum, hal ini berarti
bahwa, daripada bergantung pada some-library.so library, Anda akan membuat
file BUILD dan mem-build some-library.so dari sumbernya, lalu bergantung pada target
tersebut.
Selalu mem-build dari sumber akan 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 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 membuat library lebih mudah diupdate (hanya satu
target yang perlu diupdate). Library ini juga lebih tahan terhadap masalah dependensi diamond: jika satu library bergantung pada guava-19.0 dan satu lagi bergantung pada guava-20.0, Anda mungkin akan memiliki 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 berikut:
try-import %workspace%/user.bazelrc
(atau nama file lainnya) di workspace/.bazelrc dan tambahkan user.bazelrc ke .gitignore.
Paket
Setiap direktori yang berisi file yang dapat di-build harus berupa paket. Jika file BUILD
merujuk ke file di subdirektori (seperti, srcs = ["a/b/C.java"]), itu
pertanda bahwa 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 peningkatan jumlah
dependensi terbalik harus diupdate.