Praktik Terbaik

Laporkan masalah Lihat sumber

Halaman ini mengasumsikan bahwa Anda sudah memahami Bazel dan memberikan panduan serta saran untuk menyusun project agar dapat memanfaatkan fitur Bazel sepenuhnya.

Sasaran keseluruhannya adalah:

  • Menggunakan dependensi yang lebih mendetail untuk memungkinkan paralelisme dan inkrementalitas.
  • Agar dependensi tetap dienkapsulasi dengan baik.
  • Agar 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 semuanya. Seperti yang disebutkan di halaman manual untuk lint, "Reward khusus akan diberikan kepada orang pertama yang menghasilkan program sebenarnya yang tidak menghasilkan error dengan pemeriksaan yang ketat". Namun, memasukkan sebanyak mungkin prinsip ini harus membuat project lebih mudah dibaca, tidak terlalu 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 cabangnya yang stabil. Target yang diperlukan,tetapi tidak dibuat dalam keadaan tertentu (seperti memerlukan flag build tertentu, tidak mem-build di platform tertentu, memerlukan perjanjian lisensi) harus diberi tag sespesifik mungkin (misalnya, "requires-osx"). Pemberian tag ini memungkinkan target difilter pada tingkat 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 item tersebut sebagai repositori jarak jauh di file WORKSPACE.
  • Atau tempatkan keduanya di direktori bernama third_party/ di bawah direktori ruang kerja Anda.

Bergantung pada biner

Semuanya harus dibuat dari sumber jika memungkinkan. Ini berarti, bukannya bergantung pada library some-library.so, Anda sebaiknya 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 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 sumbernya.

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 diperbarui (hanya satu target yang perlu diupdate). Metode ini juga lebih tahan terhadap masalah dependensi intan: jika satu library bergantung pada guava-19.0 dan satu library bergantung pada guava-20.0, Anda 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 Anda yang tidak ingin Anda kontrol 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 buildable harus berupa paket. Jika file BUILD merujuk pada file di subdirektori (seperti, srcs = ["a/b/C.java"]), file tersebut adalah tanda bahwa file BUILD harus ditambahkan ke subdirektori tersebut. Semakin lama struktur ini ada, semakin besar dependensi sirkular yang akan dibuat secara tidak sengaja, cakupan target akan menurun, dan semakin banyak dependensi terbalik yang harus diperbarui.