Menulis file konfigurasi bazelrc

Laporkan masalah Lihat sumber

Bazel menerima banyak opsi. Beberapa opsi sering bervariasi (misalnya, --subcommands) sementara opsi lainnya tetap sama di beberapa build (seperti --package_path). Untuk menghindari penentuan opsi yang tidak berubah ini untuk setiap build (dan perintah lainnya), Anda dapat menentukan opsi dalam file konfigurasi, yang disebut .bazelrc.

Di mana file .bazelrc?

Bazel mencari file konfigurasi opsional di lokasi berikut, sesuai urutan yang ditunjukkan di bawah. Opsi ini ditafsirkan dalam urutan ini, sehingga opsi dalam file berikutnya dapat mengganti nilai dari file sebelumnya jika konflik muncul. Semua opsi yang mengontrol file mana yang dimuat adalah opsi startup, yang berarti opsi tersebut harus terjadi setelah bazel dan sebelum perintah (build, test, dll.).

  1. File RC sistem, kecuali jika --nosystem_rc ada.

    Lokasi:

    • Di Linux/macOS/Unixes: /etc/bazel.bazelrc
    • Pada Windows: %ProgramData%\bazel.bazelrc

    Hal ini bukan error jika file ini tidak ada.

    Jika lokasi lain yang ditetapkan sistem diperlukan, Anda harus mem-build biner Bazel kustom, dengan mengganti nilai BAZEL_SYSTEM_BAZELRC_PATH di //src/main/cpp:option_processor. Lokasi yang ditentukan sistem dapat berisi referensi variabel lingkungan, seperti ${VAR_NAME} di Unix atau %VAR_NAME% di Windows.

  2. File RC ruang kerja, kecuali jika --noworkspace_rc ada.

    Jalur: .bazelrc di direktori ruang kerja Anda (di samping file WORKSPACE utama).

    Hal ini bukan error jika file ini tidak ada.

  3. File RC rumah, kecuali jika --nohome_rc ada.

    Lokasi:

    • Di Linux/macOS/Unixes: $HOME/.bazelrc
    • Di Windows: %USERPROFILE%\.bazelrc jika ada, atau %HOME%/.bazelrc

    Hal ini bukan error jika file ini tidak ada.

  4. File RC yang ditentukan pengguna, jika ditentukan dengan --bazelrc=file

    Flag ini bersifat opsional, tetapi juga dapat ditentukan beberapa kali.

    /dev/null menunjukkan bahwa semua --bazelrc selanjutnya akan diabaikan, yang berguna untuk menonaktifkan penelusuran file rc pengguna, seperti dalam build rilis.

    Contoh:

    --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
    
    • x.rc dan y.rc telah dibaca.
    • z.rc diabaikan karena /dev/null sebelumnya.

Selain file konfigurasi opsional ini, Bazel mencari file rc global. Untuk mengetahui detail selengkapnya, baca bagian bazel global.

Sintaksis dan semantik .bazelrc

Seperti semua file "rc" UNIX, file .bazelrc adalah file teks dengan tata bahasa berbasis baris. Baris kosong dan baris yang dimulai dengan # (komentar) akan diabaikan. Setiap baris berisi urutan kata, yang di-token sesuai dengan aturan yang sama dengan shell Bourne.

Impor

Baris yang dimulai dengan import atau try-import bersifat khusus: gunakan baris ini untuk memuat file "rc" lainnya. Untuk menentukan jalur yang relatif terhadap root Workspace, tulis import %workspace%/path/to/bazelrc.

Perbedaan antara import dan try-import adalah Bazel gagal jika file import tidak ada (atau tidak dapat dibaca), tetapi tidak demikian untuk file try-import.

Prioritas impor:

  • Opsi dalam file yang diimpor lebih diprioritaskan daripada opsi yang ditentukan sebelum pernyataan impor.
  • Opsi yang ditentukan setelah pernyataan impor lebih diprioritaskan daripada opsi dalam file yang diimpor.
  • Opsi dalam file yang diimpor kemudian akan diprioritaskan daripada file yang diimpor sebelumnya.

Opsi default

Sebagian besar baris Bazelrc menentukan nilai opsi default. Kata pertama di setiap baris menentukan kapan default berikut diterapkan:

  • startup: opsi startup, yang berjalan sebelum perintah, dan dijelaskan dalam bazel help startup_options.
  • common: opsi yang harus diterapkan ke semua perintah Bazel yang mendukungnya. Jika perintah tidak mendukung opsi yang ditentukan dengan cara ini, opsi tersebut akan diabaikan selama opsi tersebut valid untuk beberapa perintah Bazel lainnya. Perhatikan bahwa ini hanya berlaku untuk nama opsi: Jika perintah saat ini menerima opsi dengan nama yang ditentukan, tetapi tidak mendukung nilai yang ditentukan, perintah tersebut akan gagal.
  • always: opsi yang berlaku untuk semua perintah Bazel. Jika perintah tidak mendukung opsi yang ditentukan dengan cara ini, perintah akan gagal.
  • command: Perintah Bazel, seperti build atau query yang dikenai opsi. Opsi ini juga berlaku untuk semua perintah yang diwarisi dari perintah yang ditentukan. (Misalnya, test mewarisi dari build.)

Setiap baris ini dapat digunakan lebih dari sekali dan argumen yang mengikuti kata pertama digabungkan seakan-akan muncul dalam satu baris. (Pengguna CVS, alat lain dengan antarmuka command line "Swiss knife" akan menemukan sintaksis yang mirip dengan .cvsrc.) Misalnya, barisnya:

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

digabungkan sebagai:

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

sehingga tanda efektifnya adalah --verbose_failures dan --test_tmpdir=/tmp/bar.

Prioritas opsi:

  • Opsi di command line selalu lebih diutamakan daripada opsi di file rc. Misalnya, jika file rc bertuliskan build -c opt tetapi tanda command line-nya adalah -c dbg, flag command line akan diprioritaskan.
  • Dalam file rc, prioritas diatur oleh kekhususan: baris untuk perintah yang lebih spesifik lebih diutamakan daripada baris untuk perintah yang kurang spesifik.

    Kekhususan ditentukan oleh pewarisan. Beberapa perintah mewarisi opsi dari perintah lain, sehingga membuat perintah pewarisan lebih spesifik daripada perintah dasar. Misalnya, test mewarisi dari perintah build, sehingga semua flag bazel build valid untuk bazel test, dan semua baris build juga berlaku untuk bazel test kecuali jika ada baris test untuk opsi yang sama. Jika file rc menyebutkan:

    test -c dbg --test_env=PATH
    build -c opt --verbose_failures
    

    bazel build //foo akan menggunakan -c opt --verbose_failures, dan bazel test //foo akan menggunakan --verbose_failures -c dbg --test_env=PATH.

    Grafik pewarisan (kekhususan) adalah:

    • Setiap perintah diwarisi dari common
    • Perintah berikut mewarisi dari (dan lebih spesifik dari) build: test, run, clean, mobile-install, info, print_action, config, cquery, dan aquery
    • coverage mewarisi dari test
  • Dua baris yang menentukan opsi untuk perintah yang sama dengan kekhususan yang sama diuraikan sesuai urutan munculnya dalam file.

  • Karena aturan prioritas ini tidak cocok dengan urutan file, aturan ini membantu keterbacaan jika Anda mengikuti urutan prioritas dalam file rc: mulai dengan opsi common di bagian atas, dan akhiri dengan perintah paling spesifik di bagian bawah file. Dengan cara ini, urutan pembacaan opsi akan sama dengan urutan penerapannya, yang lebih intuitif.

Argumen yang ditentukan pada baris file rc dapat menyertakan argumen yang bukan merupakan opsi, seperti nama target build, dan sebagainya. Seperti opsi yang ditentukan dalam file yang sama, prioritasnya lebih rendah daripada saudara kandungnya pada command line, dan selalu ditambahkan ke daftar eksplisit argumen non-opsi.

--config

Selain menetapkan default opsi, file rc dapat digunakan untuk mengelompokkan opsi dan menyediakan singkatan untuk pengelompokan umum. Hal ini dilakukan dengan menambahkan akhiran :name ke perintah. Opsi ini diabaikan secara default, tetapi akan disertakan saat opsi --config=name ada, baik di command line maupun di file .bazelrc, secara rekursif, bahkan di dalam definisi konfigurasi lain. Opsi yang ditentukan oleh command:name hanya akan diperluas untuk perintah yang berlaku, dalam urutan prioritas yang dijelaskan di atas.

--config=foo diperluas ke opsi yang ditentukan dalam file rc "di tempat" sehingga opsi yang ditentukan untuk konfigurasi memiliki prioritas yang sama seperti opsi --config=foo.

Sintaksis ini tidak mencakup penggunaan startup untuk menetapkan opsi startup. Setelan startup:config-name --some_startup_option di .bazelrc akan diabaikan.

Contoh

Berikut adalah contoh file ~/.bazelrc:

# Bob's Bazel option defaults

startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going

# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600

File lain yang mengatur perilaku Bazel

.bazelignore

Anda dapat menentukan direktori dalam ruang kerja yang ingin diabaikan Bazel, seperti project terkait yang menggunakan sistem build lain. Tempatkan file bernama .bazelignore di root ruang kerja dan tambahkan direktori yang ingin diabaikan Bazel, satu per baris. Entri bersifat relatif terhadap root ruang kerja.

File bazelrc global

Bazel membaca file bazelrc opsional dalam urutan berikut:

  1. File rc sistem yang terletak di etc/bazel.bazelrc.
  2. File rc Workspace yang berlokasi di $workspace/tools/bazel.rc.
  3. File rc rumah yang berada di $HOME/.bazelrc

Setiap file bazel yang tercantum di sini memiliki flag yang sesuai dan dapat digunakan untuk menonaktifkannya (misalnya --nosystem_rc, --noworkspace_rc, --nohome_rc). Anda juga dapat membuat Bazel mengabaikan semua bazel dengan meneruskan opsi startup --ignore_all_rc_files.