Halaman ini mengasumsikan bahwa Anda sudah memahami Bazel dan memberikan panduan serta saran tentang cara menyusun project untuk memanfaatkan fitur Bazel sepenuhnya.
Sasaran keseluruhannya adalah:
- Untuk menggunakan dependensi terperinci guna memungkinkan paralelisme dan inkrementalitas.
- Untuk menjaga dependensi tetap dienkapsulasi dengan baik.
- Untuk membuat kode yang terstruktur dengan baik dan dapat diuji.
- Untuk membuat konfigurasi build yang mudah dipahami dan dikelola.
Pedoman ini bukan persyaratan: hanya sedikit project yang dapat mematuhi semuanya. Seperti yang tertulis di halaman man untuk lint, "Hadiah khusus akan diberikan kepada orang pertama yang membuat program nyata yang tidak menghasilkan error dengan pemeriksaan ketat". Namun, menggabungkan sebanyak mungkin prinsip ini akan membuat project lebih mudah dibaca, lebih sedikit error, dan lebih cepat di-build.
Halaman ini menggunakan tingkat persyaratan yang dijelaskan dalam RFC ini.
Menjalankan build dan pengujian
Sebuah project harus selalu dapat menjalankan bazel build //... dan
bazel test //... dengan sukses di cabang stabilnya. Target yang diperlukan
tetapi tidak di-build dalam situasi tertentu (seperti,memerlukan flag build
tertentu, tidak di-build di platform tertentu, memerlukan perjanjian lisensi) harus
diberi tag sekhusus mungkin (misalnya, "requires-osx"). Pemberian tag
ini memungkinkan target difilter pada tingkat yang lebih terperinci daripada
tag "manual" dan memungkinkan seseorang yang 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, masukkan ke dalam direktori bernama
third_party/di direktori ruang kerja Anda.
Bergantung pada biner
Semuanya harus dibuat dari sumber jika memungkinkan. Secara umum, ini berarti
bahwa, alih-alih bergantung pada library some-library.so, Anda akan 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 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 di sumber.
Pembuatan Versi
Lebih memilih mem-build semua kode dari awal jika memungkinkan. Jika 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). Hal ini juga lebih tahan terhadap masalah dependensi berlian: jika satu library bergantung pada guava-19.0 dan satu lagi bergantung pada guava-20.0,
Anda mungkin akan mendapatkan library yang mencoba bergantung pada dua versi yang 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 Anda ingin mendukung opsi per pengguna untuk project yang tidak ingin Anda periksa ke dalam kontrol sumber, sertakan baris:
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 dalam subdirektori (seperti, srcs = ["a/b/C.java"]), ini
adalah tanda bahwa file BUILD harus ditambahkan ke subdirektori tersebut. Makin lama
struktur ini ada, makin besar kemungkinan dependensi melingkar akan
dibuat secara tidak sengaja, cakupan target akan meluas, dan makin banyak
dependensi terbalik yang harus diperbarui.