Halaman ini mengasumsikan bahwa Anda sudah memahami Bazel dan memberikan panduan serta saran tentang cara menyusun project untuk memanfaatkan fitur Bazel sepenuhnya.
Tujuan keseluruhannya adalah:
- Menggunakan dependensi terperinci untuk memungkinkan paralelisme dan inkrementalitas.
- Menjaga dependensi tetap terenkapsulasi dengan baik.
- Membuat kode terstruktur dengan baik dan dapat diuji.
- Membuat konfigurasi build yang mudah dipahami dan dikelola.
Panduan ini bukan persyaratan: hanya beberapa project yang dapat mematuhi semuanya. Seperti yang dikatakan halaman manual 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, tidak 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 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 ditandai sespesifik mungkin (misalnya, "requires-osx"). Penandaan ini memungkinkan target difilter pada tingkat yang lebih terperinci daripada tag "manual" dan memungkinkan seseorang yang memeriksa file BUILD memahami batasan target.
Dependensi pihak ketiga
Anda dapat mendeklarasikan dependensi pihak ketiga:
- Mendeklarasikannya sebagai repositori jarak jauh dalam file
MODULE.bazel. - Atau menempatkannya di direktori bernama
third_party/di bawah direktori ruang kerja Anda.
Bergantung pada biner
Semua hal harus dibuat dari sumber jika memungkinkan. Umumnya, ini berarti bahwa, alih-alih bergantung pada library some-library.so, Anda akan membuat file BUILD dan membuat some-library.so dari sumbernya, lalu bergantung pada target tersebut.
Selalu membuat 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 sumber.
Pembuatan Versi
Sebaiknya buat semua kode dari head jika memungkinkan. Jika versi harus
digunakan, hindari menyertakan versi dalam nama target (misalnya, //guava,
bukan //guava-20.0). Penamaan ini memudahkan library 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 bergantung pada guava-20.0, Anda dapat menggunakan 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 (lihat format bazelrc).
Jika Anda ingin mendukung opsi per pengguna untuk project yang tidak ingin Anda check in ke kontrol sumber, sertakan baris:
try-import %workspace%/user.bazelrc
(atau nama file lainnya) di workspace/.bazelrc
dan tambahkan user.bazelrc ke .gitignore.
bazelrc-preset.bzl open source
menghasilkan file bazelrc kustom yang cocok dengan versi Bazel Anda dan menyediakan preset flag yang direkomendasikan.
Paket
Setiap direktori yang berisi file yang dapat dibuat harus berupa paket. Jika file BUILD
merujuk ke file di subdirektori (seperti, srcs = ["a/b/C.java"]), hal ini menandakan bahwa file BUILD harus ditambahkan ke subdirektori tersebut. Semakin lama struktur ini ada, semakin besar kemungkinan dependensi melingkar akan dibuat secara tidak sengaja, cakupan target akan merayap, dan semakin banyak dependensi terbalik yang harus diupdate.