Bagian ini menentukan berbagai istilah dan konsep yang umum untuk banyak fungsi atau aturan build.
Daftar Isi
- Tokenisasi shell shell
- Perluasan Label
- Atribut umum yang ditentukan oleh sebagian besar aturan build
- Atribut yang umum untuk semua aturan build
- Atribut yang umum untuk semua aturan pengujian (*_test)
- Atribut yang umum untuk semua aturan biner (*_binary)
- Atribut yang dapat dikonfigurasi
- Target output implisit
Tokenisasi shell Bourne
Atribut string tertentu dari beberapa aturan dibagi menjadi beberapa kata sesuai dengan aturan tokenisasi shell Bourne: spasi tanpa tanda kutip membatasi kata terpisah, dan karakter tanda kutip tunggal dan ganda serta garis miring terbalik digunakan untuk mencegah tokenisasi.
Atribut yang tunduk pada tokenisasi ini secara eksplisit ditunjukkan seperti itu dalam definisinya dalam dokumen ini.
Atribut yang tunduk pada perluasan variabel "Make" dan tokenisasi shell Bourne biasanya digunakan untuk meneruskan opsi arbitrer ke compiler dan alat lainnya. Contoh atribut tersebut adalah
cc_library.copts
dan java_library.javacopts
.
Bersama-sama dengan substitusi ini,
variabel string tunggal dapat diperluas menjadi daftar kata-kata
opsi khusus konfigurasi.
Perluasan label
Beberapa atribut string dari beberapa aturan dapat mengalami perluasan label: jika string tersebut berisi label yang valid sebagai substring, seperti //mypkg:target
, dan label tersebut merupakan prasyarat yang dideklarasikan dari aturan saat ini, label akan diperluas menjadi nama jalur file yang diwakili oleh //mypkg:target
target.
Contoh atribut meliputi genrule.cmd
dan cc_binary.linkopts
. Detail setiap kasus dapat sangat berbeda, seperti: apakah label relatif diperluas; bagaimana label yang diperluas ke beberapa file diperlakukan, dll. Lihat dokumentasi atribut aturan untuk mengetahui detailnya.
Atribut umum yang didefinisikan oleh sebagian besar aturan build
Bagian ini menjelaskan atribut yang ditentukan oleh banyak aturan build, tetapi tidak semua.
Atribut | Deskripsi |
---|---|
data |
File yang diperlukan oleh aturan ini saat runtime. Dapat mencantumkan target file atau aturan. Umumnya memungkinkan semua target.
Output dan runfile target default di atribut
Aturan baru harus menentukan atribut |
deps |
Dependensi untuk target ini. Umumnya hanya boleh mencantumkan target aturan. (Meskipun beberapa aturan mengizinkan file dicantumkan langsung di Aturan khusus bahasa umumnya membatasi target yang tercantum pada target dengan penyedia tertentu.
Semantik yang persis dari arti target bergantung pada target lainnya yang menggunakan
Sering kali, dependensi |
licenses |
Daftar string jenis lisensi yang akan digunakan untuk target tertentu. Ini adalah bagian dari API pemberian lisensi yang tidak digunakan lagi yang tidak digunakan lagi oleh Bazel. Jangan gunakan ini. |
srcs |
File yang diproses atau disertakan oleh aturan ini. Umumnya, daftar file langsung tercantum, tetapi
mungkin mencantumkan target aturan (seperti Aturan spesifik per bahasa sering kali mengharuskan file yang tercantum memiliki ekstensi file tertentu. |
Atribut yang sama untuk semua aturan build
Bagian ini menjelaskan atribut yang ditambahkan secara implisit ke semua aturan build.
Atribut | Deskripsi |
---|---|
compatible_with |
Daftar lingkungan yang dapat dibuat untuk target ini, selain lingkungan yang didukung default. Ini adalah bagian dari sistem batasan Bazel, yang memungkinkan pengguna mendeklarasikan target mana yang dapat dan tidak dapat saling bergantung. Misalnya, biner yang dapat di-deploy secara eksternal tidak boleh bergantung pada library dengan kode rahasia perusahaan. Lihat ConstraintSemantics untuk mengetahui detailnya. |
deprecation |
Pesan peringatan penjelasan yang terkait dengan target ini. Peristiwa ini biasanya digunakan untuk memberi tahu pengguna bahwa target sudah tidak digunakan lagi, atau telah digantikan oleh aturan lain, bersifat pribadi untuk paket, atau mungkin dianggap berbahaya karena alasan tertentu. Sebaiknya sertakan beberapa referensi (seperti halaman web, nomor bug, atau contoh CL migrasi) agar Anda dapat dengan mudah mengetahui perubahan yang diperlukan untuk menghindari pesan. Jika ada target baru yang dapat digunakan sebagai pengganti pengganti, sebaiknya migrasikan semua pengguna target lama.
Atribut ini tidak memengaruhi cara pembuatan sesuatu, tetapi
dapat memengaruhi output diagnostik alat build. Alat build mengeluarkan peringatan saat aturan dengan atribut Dependensi intra-paket dikecualikan dari peringatan ini, sehingga misalnya, membuat pengujian aturan yang tidak digunakan lagi tidak menerima peringatan. Jika target yang tidak digunakan lagi bergantung pada target lain yang tidak digunakan lagi, tidak ada pesan peringatan yang dikeluarkan. Setelah pengguna berhenti menggunakannya, target dapat dihapus. |
distribs |
Daftar string metode distribusi yang akan digunakan untuk target khusus ini. Ini adalah bagian dari API pemberian lisensi yang tidak digunakan lagi yang tidak digunakan lagi oleh Bazel. Jangan gunakan ini. |
exec_compatible_with |
Daftar
|
exec_properties |
Kamus string yang akan ditambahkan ke Jika kunci ada di properti tingkat platform dan target, nilainya akan diambil dari target. |
features |
Fitur adalah tag string yang dapat diaktifkan atau dinonaktifkan pada target. Arti suatu fitur bergantung pada aturan itu sendiri. Atribut |
restricted_to |
Daftar lingkungan tempat target ini dapat dibuat, bukan lingkungan yang didukung default.
Ini adalah bagian dari sistem batasan Bazel. Lihat
|
tags |
Tag dapat digunakan pada aturan apa pun. Tag pada pengujian dan aturan
Bazel memodifikasi perilaku kode sandbox-nya jika menemukan kata kunci berikut dalam atribut
Tag pada saat pengujian umumnya digunakan untuk menganotasi peran pengujian dalam proses debug dan rilis. Biasanya, tag paling berguna untuk pengujian C++ dan Python, yang tidak memiliki kemampuan anotasi runtime. Penggunaan tag dan elemen ukuran memberikan fleksibilitas dalam menyatukan rangkaian pengujian berdasarkan kebijakan check-in codebase.
Bazel memodifikasi perilaku pengujian jika menemukan kata kunci berikut dalam atribut
|
target_compatible_with |
Daftar
Target yang secara transitif bergantung pada target yang tidak kompatibel akan dianggap tidak kompatibel. Keduanya juga dilewati untuk pembuatan dan pengujian. Daftar kosong (yang merupakan default) menunjukkan bahwa target kompatibel dengan semua platform.
Semua aturan selain Aturan Workspace mendukung atribut ini.
Untuk beberapa aturan, atribut ini tidak berpengaruh. Misalnya, menentukan
Lihat halaman Platform untuk mengetahui informasi selengkapnya tentang cara melewati target yang tidak kompatibel. |
testonly |
Jika True, hanya target pengujian saja (seperti pengujian) yang dapat bergantung pada target ini.
Secara setara, aturan yang bukan
Pengujian (aturan Atribut ini dimaksudkan bahwa target tidak boleh berisi biner yang dirilis ke produksi. Karena pengujian hanya diterapkan pada waktu build, bukan waktu proses, dan diterapkan secara merata melalui hierarki dependensi, kebijakan ini harus diterapkan dengan bijak. Misalnya, stub danPemalsuan yang berguna untuk pengujian unit juga dapat berguna untuk pengujian integrasi yang melibatkan biner yang sama yang akan dirilis ke produksi, dan karena itu mungkin tidak boleh ditandai hanya pengujian. Sebaliknya, aturan yang berbahaya untuk ditautkan, mungkin karena aturan tersebut menggantikan perilaku normal tanpa syarat, harus ditandai sebagai pengujian saja. |
toolchains |
Kumpulan target yang Membuat variabel yang diizinkan untuk diakses oleh target ini. Target ini adalah instance dari aturan yang menyediakan
Perhatikan bahwa ini berbeda dengan konsep
resolusi toolchain
yang digunakan oleh penerapan aturan untuk konfigurasi yang bergantung pada platform. Anda tidak dapat menggunakan atribut ini untuk menentukan |
visibility |
Atribut |
Atribut umum untuk semua aturan pengujian (*_test)
Bagian ini menjelaskan atribut yang berlaku umum untuk semua aturan pengujian.
Atribut | Deskripsi | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Argumen command line yang diteruskan Bazel ke target saat
dieksekusi dengan
Argumen ini diteruskan sebelum nilai |
||||||||||||||||||||
env |
Menentukan variabel lingkungan tambahan yang akan ditetapkan saat pengujian dijalankan oleh
Atribut ini hanya berlaku untuk aturan native, seperti |
||||||||||||||||||||
env_inherit |
Menentukan variabel lingkungan tambahan yang akan diwarisi dari lingkungan eksternal saat pengujian dijalankan oleh
Atribut ini hanya berlaku untuk aturan native, seperti |
||||||||||||||||||||
size |
Menentukan "kepadatan" target pengujian: berapa banyak waktu/resource yang diperlukan untuk dijalankan. Pengujian unit dianggap sebagai "kecil", pengujian integrasi "sedang", dan pengujian menyeluruh "besar" atau
"sangat besar". Bazel menggunakan ukuran untuk menentukan waktu tunggu default, yang dapat diganti menggunakan
atribut Ukuran pengujian sesuai dengan waktu tunggu default berikut dan penggunaan resource lokal puncak yang diasumsikan:
Variabel lingkungan |
||||||||||||||||||||
timeout |
Durasi pengujian diperkirakan sebelum berjalan kembali.
Meskipun atribut ukuran pengujian mengontrol estimasi resource, waktu tunggu pengujian dapat ditetapkan secara independen. Jika tidak ditentukan secara eksplisit, waktu tunggu akan didasarkan pada ukuran pengujian. Waktu tunggu pengujian dapat diganti dengan flag
Untuk waktu selain di atas, waktu tunggu pengujian dapat diganti dengan flag bazel Variabel lingkungan |
||||||||||||||||||||
flaky |
Tanda pengujian tidak stabil. Jika ditetapkan, jalankan pengujian hingga tiga kali dan tandai sebagai gagal hanya jika gagal setiap kali. Secara default, atribut ini ditetapkan ke Salah dan pengujian hanya dijalankan satu kali. Perhatikan bahwa penggunaan atribut ini umumnya tidak disarankan. Pengujian harus berhasil jika pernyataan tersebut ditegakkan. |
||||||||||||||||||||
shard_count |
Menentukan jumlah shard paralel yang akan digunakan untuk menjalankan pengujian. Nilai ini akan mengganti heuristik yang digunakan untuk menentukan jumlah shard paralel untuk menjalankan pengujian. Perlu diketahui bahwa untuk beberapa aturan pengujian, parameter ini mungkin diperlukan untuk mengaktifkan sharding di awal. Lihat juga Jika sharding pengujian diaktifkan, variabel lingkungan Sharding memerlukan runner pengujian untuk mendukung protokol sharding pengujian. Jika tidak, maka kemungkinan besar akan dijalankan di setiap pengujian dalam setiap shard, yang bukan ini yang Anda inginkan. Lihat Melakukan Sharding di Ensiklopedia Pengujian untuk mengetahui detail tentang sharding. |
||||||||||||||||||||
local |
Memaksa pengujian untuk dijalankan secara lokal, tanpa sandbox. Menyetelnya ke Benar (True) sama dengan menyediakan "lokal" sebagai tag ( |
Atribut umum untuk semua aturan biner (*_binary)
Bagian ini menjelaskan atribut yang berlaku umum untuk semua aturan biner.
Atribut | Deskripsi |
---|---|
args |
Argumen command line yang akan diteruskan oleh Bazel ke target saat dijalankan
oleh perintah
CATATAN: Argumen tidak akan diteruskan saat Anda menjalankan target
di luar Bazel (misalnya, dengan menjalankan biner secara manual di
|
env |
Menentukan variabel lingkungan tambahan yang akan ditetapkan ketika target dijalankan oleh
Atribut ini hanya berlaku untuk aturan native, seperti
CATATAN: Variabel lingkungan tidak ditetapkan saat Anda menjalankan target
di luar Bazel (misalnya, dengan menjalankan biner secara manual di
|
output_licenses |
Lisensi file output yang dihasilkan biner ini. Ini adalah bagian dari API pemberian lisensi yang tidak digunakan lagi yang tidak digunakan lagi oleh Bazel. Jangan gunakan ini. |
Atribut yang dapat dikonfigurasi
Sebagian besar atribut bersifat "dapat dikonfigurasi", artinya nilainya dapat berubah saat target dibuat dengan cara yang berbeda. Secara khusus, atribut yang dapat dikonfigurasi dapat bervariasi berdasarkan flag yang diteruskan ke command line Bazel, atau dependensi downstream yang meminta target. Hal ini dapat digunakan, misalnya, untuk menyesuaikan target untuk beberapa platform atau mode kompilasi.
Contoh berikut mendeklarasikan sumber yang berbeda-beda untuk arsitektur target
yang berbeda. Menjalankan bazel build :multiplatform_lib --cpu x86
akan membuat target menggunakan x86_impl.cc
, sedangkan mengganti
--cpu arm
akan menyebabkannya menggunakan arm_impl.cc
.
cc_library( name = "multiplatform_lib", srcs = select({ ":x86_mode": ["x86_impl.cc"], ":arm_mode": ["arm_impl.cc"] }) ) config_setting( name = "x86_mode", values = { "cpu": "x86" } ) config_setting( name = "arm_mode", values = { "cpu": "arm" } )
Fungsi select()
memilih di antara nilai alternatif yang berbeda untuk atribut yang dapat dikonfigurasi berdasarkan
kriteria config_setting
atau constraint_value
yang terpenuhi oleh konfigurasi target.
Bazel mengevaluasi atribut yang dapat dikonfigurasi setelah memproses makro dan sebelum memproses aturan (secara teknis, antara
fase pemuatan dan analisis).
Semua pemrosesan sebelum evaluasi select()
tidak mengetahui cabang mana yang dipilih oleh select()
. Makro, misalnya, tidak dapat mengubah
perilakunya berdasarkan cabang yang dipilih, dan bazel query
hanya
dapat membuat tebakan konservatif tentang dependensi target yang dapat dikonfigurasi. Lihat
FAQ ini
untuk mengetahui informasi selengkapnya tentang penggunaan select()
dengan aturan dan makro.
Atribut yang ditandai nonconfigurable
dalam dokumentasinya tidak dapat
menggunakan fitur ini. Biasanya atribut ini tidak dapat dikonfigurasi karena Bazel
secara internal perlu mengetahui nilainya sebelum dapat menentukan cara menyelesaikan
select()
.
Lihat Atribut Build yang Dapat Dikonfigurasi untuk ringkasan mendetail.
Target output implisit
Output implisit di C++ tidak digunakan lagi. Jangan menggunakannya dalam bahasa lain jika memungkinkan. Kami belum memiliki jalur penghentian penggunaan, tetapi pada akhirnya tidak akan digunakan lagi.
Saat menentukan aturan build dalam file BUILD, Anda secara eksplisit mendeklarasikan target aturan baru yang telah diberi nama dalam sebuah paket. Banyak fungsi aturan build juga secara implisit memerlukan satu atau beberapa target file output, yang kontennya dan artinya spesifik per aturan.
Misalnya, saat mendeklarasikan aturan
java_binary(name='foo', ...)
secara eksplisit, Anda juga
secara implisit mendeklarasikan target file
output foo_deploy.jar
sebagai anggota paket yang sama.
(Target khusus ini adalah arsip Java mandiri yang cocok untuk deployment.)
Target output implisit adalah anggota kelas satu dari grafik target global. Sama seperti target lainnya, target tersebut dibuat sesuai permintaan,
baik jika ditentukan dalam perintah build level atas, atau saat
merupakan prasyarat yang diperlukan untuk target build lainnya. Library ini dapat
direferensikan sebagai dependensi dalam file BUILD dan dapat diamati dalam
output alat analisis seperti bazel query
.
Untuk setiap jenis aturan build, dokumentasi aturan berisi bagian khusus yang menjelaskan nama dan isi output implisit yang diperlukan oleh deklarasi jenis aturan tersebut.
Perbedaan penting tetapi sedikit samar antara dua namespace yang digunakan oleh sistem build: label mengidentifikasi target, yang mungkin berupa aturan atau file, dan target file dapat dibagi menjadi target file sumber (atau input) dan target file turunan (atau output). Berikut adalah hal-hal yang dapat Anda sebutkan di file BUILD, mem-build dari command line, atau memeriksa menggunakan bazel query
. Ini adalah namespace target. Setiap target file merujuk
ke satu file yang sebenarnya di disk ("namespace sistem file"); setiap target
aturan dapat sesuai dengan nol, satu, atau beberapa file sebenarnya di disk.
Mungkin ada file pada disk yang tidak memiliki target yang sesuai; misalnya, file objek .o
yang dihasilkan selama kompilasi C++ tidak dapat direferensikan dari dalam file BUILD atau dari command line.
Dengan cara ini, alat build akan menyembunyikan detail implementasi tertentu tentang
cara kerjanya. Hal ini dijelaskan lebih lengkap dalam
Referensi Konsep BUILD.