Halaman ini mengasumsikan bahwa Anda sudah memahami Bazel dan memberikan pedoman serta saran tentang cara menyusun project untuk memanfaatkan sepenuhnya fitur Bazel.
Sasaran keseluruhannya adalah:
- Untuk menggunakan dependensi terperinci guna memungkinkan paralelisme dan inkrementalitas.
- Untuk menjaga dependensi tetap terenkapsulasi dengan baik.
- Untuk membuat 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 semua panduan ini. Seperti yang dinyatakan dalam halaman manual untuk lint, "Hadiah khusus akan diberikan kepada orang pertama yang membuat program nyata tanpa error dengan pemeriksaan ketat." Namun, menggabungkan sebanyak mungkin prinsip ini akan membuat project lebih mudah dibaca, lebih sedikit 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 berhasil 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 sejelas 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 memahami batasan target.
Dependensi pihak ketiga
Anda dapat mendeklarasikan dependensi pihak ketiga:
- Nyatakan sebagai repositori jarak jauh dalam file
MODULE.bazel. - Atau, letakkan di direktori bernama
third_party/di direktori ruang kerja Anda.
Bergantung pada biner
Sebisa mungkin, semuanya harus dibangun dari sumber. Biasanya, 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 membangun 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 di sumber.
Pembuatan Versi
Sebaiknya bangun 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 tangguh terhadap masalah dependensi berlian: jika satu library bergantung pada guava-19.0 dan satu library bergantung pada guava-20.0, Anda dapat berakhir dengan library yang mencoba bergantung pada dua versi yang berbeda.
Jika Anda membuat alias yang menyesatkan untuk mengarahkan kedua target ke satu library guava, maka file BUILD 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 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.
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"]), hal ini
menandakan 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 diupdate.