Tips

Laporkan masalah Lihat sumber Per malam · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Laman ini mengasumsikan Anda sudah mengenal Bazel dan memberikan pedoman serta saran tentang menyusun proyek Anda untuk memanfaatkan sepenuhnya fitur Bazel.

Tujuan keseluruhan adalah:

  • Untuk menggunakan dependensi terperinci guna memungkinkan paralelisme dan inkrementalitas.
  • Untuk menjaga dependensi agar tetap dienkapsulasi dengan baik.
  • Untuk membuat kode terstruktur dengan baik dan dapat diuji.
  • Untuk membuat konfigurasi build yang mudah dipahami dan dikelola.

Pedoman ini bukanlah persyaratan: hanya sedikit proyek yang dapat mematuhi semuanya. Seperti yang dikatakan oleh halaman utama untuk lint, “Hadiah spesial akan diberikan kepada orang pertama yang menghasilkan program nyata yang tidak menghasilkan kesalahan dengan pemeriksaan ketat." Namun, menggabungkan sebanyak mungkin prinsip-prinsip ini harus membuat proyek lebih mudah dibaca, tidak rentan terhadap kesalahan, dan lebih cepat dibangun.

Halaman ini menggunakan tingkat persyaratan yang dijelaskan di RFC ini.

Menjalankan build dan pengujian

Sebuah project harus selalu dapat menjalankan bazel build //... dan bazel test //... berhasil di cabang stabilnya. Target yang diperlukan tetapi tidak membangun dalam keadaan tertentu (seperti,memerlukan build khusus flag, jangan dibuat di platform tertentu, membutuhkan perjanjian lisensi) harus diberi tag sespesifik mungkin (misalnya, "requires-osx"). Ini memungkinkan penargetan untuk difilter di tingkat yang lebih terperinci daripada "manual" dan memungkinkan seseorang memeriksa file BUILD untuk memahami apa batasan target.

Dependensi pihak ketiga

Anda dapat mendeklarasikan dependensi pihak ketiga:

  • Deklarasikan sebagai repositori jarak jauh dalam file WORKSPACE.
  • Atau, letakkan dalam direktori bernama third_party/ di bawah direktori ruang kerja Anda.

Bergantung pada biner

Segala sesuatu harus dibuat dari sumber jika memungkinkan. Umumnya hal ini berarti sehingga, alih-alih bergantung pada library some-library.so, Anda akan membuat BUILD dan buat some-library.so dari sumbernya, lalu bergantung pada resource tersebut target.

Selalu membangun dari sumber memastikan bahwa build tidak menggunakan library yang dibangun dengan penanda yang tidak kompatibel atau arsitektur yang berbeda. Ada juga beberapa fitur seperti cakupan, analisis statis, atau analisis dinamis yang hanya bekerja pada sumber.

Pembuatan Versi

Memilih membuat semua kode dari head jika memungkinkan. Kapan 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 perlu diperbarui). Desain ini juga lebih tahan terhadap dependensi berlian masalah: jika satu library bergantung pada guava-19.0 dan library lain bergantung pada guava-20.0, Anda mungkin menemui sebuah {i>library<i} 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 tersebut menyesatkan.

Menggunakan file .bazelrc

Untuk opsi khusus proyek, gunakan file konfigurasi yang workspace/.bazelrc (lihat format bazelrc).

Jika ingin mendukung opsi per pengguna untuk project Anda, yang tidak yang ingin Anda periksa 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 yang dapat dibangun harus berupa paket. Jika BUILD merujuk ke file di subdirektori (misalnya, srcs = ["a/b/C.java"]). tanda bahwa file BUILD harus ditambahkan ke subdirektori tersebut. Semakin lama struktur ini ada, semakin besar kemungkinan dependensi sirkular akan tidak sengaja dibuat, ruang lingkup target akan merayap, dan meningkatnya jumlah dependensi terbalik harus diperbarui.