Bagian ini mendefinisikan berbagai istilah dan konsep yang umum untuk banyak fungsi atau aturan build.
Daftar Isi
- Tokenisasi Bourne 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-kata yang terpisah, serta karakter tanda kutip tunggal dan ganda serta garis miring terbalik digunakan untuk mencegah tokenisasi.
Atribut yang tunduk pada tokenisasi ini ditunjukkan secara eksplisit sebagaimana dimaksud 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, substitusi ini memungkinkan variabel string tunggal diperluas ke daftar kata opsi khusus konfigurasi.
Perluasan label
Beberapa atribut string dari beberapa aturan dapat tunduk pada 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 tersebut akan diperluas ke
nama jalur file yang direpresentasikan oleh
target
//mypkg:target.
Atribut contoh mencakup genrule.cmd dan
cc_binary.linkopts. Detailnya dapat sangat berbeda dalam setiap kasus, terkait masalah seperti: apakah label relatif diperluas; bagaimana label yang diperluas ke beberapa file diperlakukan, dll. Lihat dokumentasi atribut aturan untuk informasi spesifik.
Atribut umum yang ditentukan oleh sebagian besar aturan build
Bagian ini menjelaskan atribut yang ditentukan oleh banyak aturan build, tetapi tidak semuanya.
| Atribut | Deskripsi |
|---|---|
data |
Daftar label; defaultnya adalah File yang diperlukan oleh aturan ini saat runtime. Dapat mencantumkan target file atau aturan. Umumnya mengizinkan semua target.
Output dan runfile default target dalam atribut
Aturan baru harus menentukan atribut |
deps |
Daftar label; defaultnya adalah
Dependensi untuk target ini. Umumnya hanya boleh mencantumkan target aturan. (Meskipun beberapa aturan mengizinkan file untuk dicantumkan secara langsung di Aturan khusus bahasa umumnya membatasi target yang tercantum hanya untuk target yang memiliki penyedia tertentu.
Semantik yang tepat tentang maksudnya bagi target untuk bergantung pada aturan lain menggunakan
Biasanya, dependensi |
licenses |
Daftar string; nonconfigurable;
defaultnya adalah Daftar string jenis lisensi yang akan digunakan untuk target khusus ini. Ini adalah bagian dari API pemberian lisensi yang sudah tidak digunakan lagi dan tidak lagi digunakan Bazel. Jangan gunakan ini. |
srcs |
Daftar label; defaultnya adalah
File yang diproses atau disertakan oleh aturan ini. Umumnya mencantumkan file secara langsung, tetapi
dapat mencantumkan target aturan (seperti Aturan khusus bahasa sering kali mengharuskan file yang tercantum memiliki ekstensi file tertentu. |
Atribut yang umum untuk semua aturan build
Bagian ini menjelaskan atribut yang ditambahkan secara implisit ke semua aturan build.
| Atribut | Deskripsi |
|---|---|
compatible_with |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah Selain lingkungan yang didukung default, daftar lingkungan yang dapat dibuat target ini juga dapat dibuat. 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 |
String; tidak dapat dikonfigurasi; defaultnya adalah Pesan peringatan penjelasan yang terkait dengan target ini. Biasanya, parameter ini digunakan untuk memberi tahu pengguna bahwa target sudah tidak berlaku, atau telah digantikan oleh aturan lain, bersifat pribadi untuk suatu paket, atau mungkin dianggap berbahaya karena alasan tertentu. Sebaiknya sertakan beberapa referensi (seperti halaman web, nomor bug, atau contoh CL migrasi) sehingga kita dapat dengan mudah mengetahui perubahan apa yang diperlukan untuk menghindari pesan tersebut. Jika ada target baru yang dapat digunakan sebagai penurunan pengganti, sebaiknya migrasikan semua pengguna target lama.
Atribut ini tidak berpengaruh pada cara build, tetapi
dapat memengaruhi output diagnostik alat build. Alat build mengeluarkan
peringatan saat aturan dengan atribut Dependensi intra-paket dikecualikan dari peringatan ini, sehingga misalnya, pembuatan pengujian aturan yang tidak digunakan lagi tidak akan menampilkan peringatan. Jika target yang tidak digunakan lagi bergantung pada target lain yang tidak digunakan lagi, tidak ada pesan peringatan yang akan dikeluarkan. Setelah pengguna berhenti menggunakannya, target dapat dihapus. |
distribs |
Daftar string; nonconfigurable;
defaultnya adalah Daftar string metode distribusi yang akan digunakan untuk target khusus ini. Ini adalah bagian dari API pemberian lisensi yang sudah tidak digunakan lagi dan tidak lagi digunakan Bazel. Jangan gunakan ini. |
exec_compatible_with |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah
Daftar
|
exec_properties |
Kamus string; defaultnya adalah Kamus string yang akan ditambahkan ke Jika kunci ada di properti level target dan platform, nilai akan diambil dari target. |
features |
Daftar string fitur; defaultnya adalah Fitur adalah tag string yang dapat diaktifkan atau dinonaktifkan pada target. Arti fitur bergantung pada aturan itu sendiri. Atribut |
restricted_to |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah Daftar lingkungan yang dapat di-build untuk target ini, bukan lingkungan yang didukung default.
Ini adalah bagian dari sistem pembatas Bazel. Untuk
detailnya, lihat
|
tags |
Daftar string; nonconfigurable;
defaultnya adalah
Tag dapat digunakan di aturan apa pun. Tag pada pengujian dan aturan
Bazel mengubah perilaku kode sandbox-nya jika menemukan kata kunci berikut dalam atribut
Tag pada pengujian umumnya digunakan untuk menganotasi peran pengujian dalam proses debug dan rilis Anda. Biasanya, tag paling berguna untuk pengujian C++ dan Python, yang tidak memiliki kemampuan anotasi runtime. Penggunaan tag dan elemen ukuran memberikan fleksibilitas dalam menyusun rangkaian pengujian berdasarkan kebijakan check in codebase.
Bazel mengubah perilaku pengujian yang berjalan jika menemukan kata kunci berikut dalam atribut
|
target_compatible_with |
Daftar label; defaultnya adalah
Daftar
Target yang secara transitif bergantung pada target yang tidak kompatibel dengan sendirinya dianggap tidak kompatibel. Pengujian ini juga dilewati untuk proses build 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 memiliki pengaruh. Misalnya, menentukan
Lihat halaman Platform untuk mengetahui informasi selengkapnya tentang pengabaian target yang tidak kompatibel. |
testonly |
Boolean; nonconfigurable; defaultnya adalah
Jika
Demikian pula, aturan yang bukan
Pengujian (aturan Atribut ini dimaksudkan untuk menunjukkan bahwa target tidak boleh dimuat dalam biner yang dirilis ke produksi. Karena hanya pengujian diterapkan pada waktu build, bukan waktu proses, dan disebarkan secara viral melalui hierarki dependensi, penerapan ini harus diterapkan secara bijak. Misalnya, stub dan palsu yang berguna untuk pengujian unit mungkin juga berguna untuk pengujian integrasi yang melibatkan biner yang sama yang akan dirilis ke produksi, dan oleh karena itu mungkin tidak boleh ditandai sebagai pengujian saja. Sebaliknya, aturan yang berbahaya untuk dihubungkan, mungkin karena aturan tersebut tanpa syarat mengganti perilaku normal, pasti harus ditandai sebagai uji coba saja. |
toolchains |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah
Kumpulan target yang setelan Buat variabel-nya diizinkan untuk diakses oleh target ini. Target ini adalah instance aturan yang menyediakan
Perhatikan bahwa ini berbeda dengan konsep resolusi toolchain yang digunakan oleh implementasi aturan untuk konfigurasi yang bergantung pada platform. Anda tidak dapat menggunakan atribut ini untuk menentukan |
visibility |
Daftar label;
nonconfigurable;
default-nya adalah
Atribut |
Atribut yang umum untuk semua aturan pengujian (*_test)
Bagian ini menjelaskan atribut yang bersifat umum untuk semua aturan pengujian.
| Atribut | Deskripsi | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Daftar string; tunduk pada substitusi
$(location) dan
"Make variabel", serta
tokenisasi shell Bourne; default-nya adalah Argumen command line yang diteruskan Bazel ke target saat
dieksekusi dengan
Argumen ini diteruskan sebelum nilai |
||||||||||||||||||||
env |
Kamus string; nilai tunduk kepada substitusi
$(lokasi) dan
"Buat variabel"; defaultnya adalah
Menentukan variabel lingkungan tambahan yang akan ditetapkan kapan pengujian dijalankan oleh
Atribut ini hanya berlaku untuk aturan native, seperti |
||||||||||||||||||||
env_inherit |
Daftar string; defaultnya adalah Menentukan variabel lingkungan tambahan yang akan diwarisi dari
lingkungan eksternal saat pengujian dijalankan oleh
Atribut ini hanya berlaku untuk aturan native, seperti |
||||||||||||||||||||
size |
String Menentukan "ketebalan" target pengujian: berapa banyak waktu/resource yang perlu dijalankan. Pengujian unit dianggap "kecil", pengujian integrasi "sedang", dan pengujian menyeluruh "besar" atau "besar". Bazel menggunakan ukuran untuk menentukan waktu tunggu default, yang dapat diganti menggunakan
atribut Ukuran pengujian sesuai dengan waktu tunggu default berikut dan asumsi penggunaan resource lokal puncak:
Variabel lingkungan |
||||||||||||||||||||
timeout |
String Perkiraan lama pengujian diperkirakan akan berjalan sebelum ditampilkan kembali.
Meskipun atribut ukuran pengujian mengontrol estimasi resource, waktu tunggu
pengujian dapat ditetapkan secara terpisah. Jika tidak ditentukan secara eksplisit, waktu tunggu akan didasarkan pada ukuran pengujian. Waktu tunggu
pengujian dapat diganti dengan flag
Untuk waktu selain yang disebutkan di atas, waktu tunggu pengujian dapat diganti dengan
flag bazel Variabel lingkungan |
||||||||||||||||||||
flaky |
Boolean; nonconfigurable;
defaultnya adalah Menandai pengujian sebagai tidak stabil. Jika disetel, pengujian akan dijalankan hingga tiga kali, dan menandainya sebagai gagal hanya jika gagal setiap kali dilakukan. Secara default, atribut ini ditetapkan ke Salah (False) dan pengujian hanya dijalankan satu kali. Perhatikan bahwa penggunaan atribut ini umumnya tidak disarankan - pengujian harus dapat diandalkan jika pernyataannya dipertahankan. |
||||||||||||||||||||
shard_count |
Bilangan bulat non-negatif kurang dari atau sama dengan 50; defaultnya adalah Menentukan jumlah shard paralel yang akan digunakan untuk menjalankan pengujian. Jika ditetapkan, nilai ini akan menggantikan heuristik apa pun yang digunakan untuk menentukan jumlah
sharding paralel yang digunakan untuk menjalankan pengujian. Perlu diperhatikan bahwa untuk beberapa aturan pengujian, parameter ini mungkin diperlukan untuk mengaktifkan sharding sejak awal. Lihat juga: Jika sharding pengujian diaktifkan, variabel lingkungan Sharding memerlukan runner pengujian untuk mendukung protokol sharding pengujian. Jika tidak, kemungkinan besar sistem akan menjalankan setiap pengujian di setiap shard, yang tidak Anda inginkan. Lihat Menguji Sharding di Ensiklopedia Pengujian untuk mengetahui detail tentang sharding. |
||||||||||||||||||||
local |
Boolean; nonconfigurable;
defaultnya adalah Memaksa pengujian untuk dijalankan secara lokal, tanpa sandbox. Menetapkan ini ke Benar (True) sama dengan menyediakan "local" sebagai tag
( |
Atribut yang umum untuk semua aturan biner (*_binary)
Bagian ini menjelaskan atribut yang bersifat umum untuk semua aturan biner.
| Atribut | Deskripsi |
|---|---|
args |
Daftar string; tunduk pada substitusi
$(location) dan
"Make variabel", serta
tokenisasi shell Bourne;
nonconfigurable;
default-nya adalah
Argumen command line yang akan diteruskan Bazel ke target saat dijalankan
oleh perintah
CATATAN: Argumen tidak diteruskan saat Anda menjalankan target
di luar Bazel (misalnya, dengan menjalankan biner secara manual di
|
env |
Kamus string; nilai tunduk pada substitusi
$(location) dan
"Make variabel"; defaultnya adalah Menentukan variabel lingkungan tambahan yang akan ditetapkan kapan 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 |
Daftar string; defaultnya adalah Lisensi file output yang dihasilkan oleh biner ini. Ini adalah bagian dari API pemberian lisensi yang sudah tidak digunakan lagi dan tidak lagi digunakan Bazel. Jangan gunakan ini. |
Atribut yang dapat dikonfigurasi
Sebagian besar atribut dapat "dapat dikonfigurasi", yang berarti nilainya dapat berubah saat target dibuat dengan cara yang berbeda. Secara khusus, atribut yang dapat dikonfigurasi dapat bervariasi berdasarkan tanda yang diteruskan ke command line Bazel, atau dependensi downstream apa yang meminta target. Ini dapat digunakan, misalnya, untuk menyesuaikan target untuk berbagai platform atau mode kompilasi.
Contoh berikut mendeklarasikan sumber yang berbeda untuk arsitektur
target yang berbeda. Menjalankan bazel build :multiplatform_lib --cpu x86 akan membangun 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 berbagai nilai alternatif untuk atribut yang dapat dikonfigurasi berdasarkan
kriteria config_setting
atau constraint_value
yang dipenuhi oleh konfigurasi target.
Bazel mengevaluasi atribut yang dapat dikonfigurasi setelah memproses makro dan sebelum memproses aturan (secara teknis, di antara
fase pemuatan dan analisis).
Pemrosesan apa pun sebelum evaluasi select() tidak akan mengetahui cabang mana yang dipilih select(). Makro, misalnya, tidak dapat mengubah perilakunya berdasarkan cabang yang dipilih, dan bazel query hanya dapat membuat perkiraan konservatif tentang dependensi target yang dapat dikonfigurasi. Lihat
FAQ ini
untuk mengetahui informasi selengkapnya tentang penggunaan select() dengan aturan dan makro.
Atribut bertanda nonconfigurable dalam dokumentasinya tidak dapat menggunakan fitur ini. Biasanya atribut tidak dapat dikonfigurasi karena Bazel
secara internal perlu mengetahui nilainya agar dapat menentukan cara me-resolve
select().
Lihat Atribut Build yang Dapat Dikonfigurasi untuk mengetahui ringkasan mendetail.
Target output implisit
Output implisit dalam C++ tidak digunakan lagi. Harap jangan menggunakannya dalam bahasa lain jika memungkinkan. Kami belum memiliki jalur penghentian penggunaan, tetapi jalur tersebut juga pada akhirnya tidak akan digunakan lagi.
Saat menentukan aturan build dalam file BUILD, Anda secara eksplisit mendeklarasikan target aturan baru yang bernama dalam sebuah paket. Berbagai fungsi aturan build juga secara implisit juga memerlukan satu atau beberapa target file output, yang konten dan maknanya spesifik per aturan.
Misalnya, jika secara eksplisit mendeklarasikan aturan
java_binary(name='foo', ...), Anda juga
secara implisit mendeklarasikan file output
yang menargetkan 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 di-build on demand,
baik ketika ditentukan dalam perintah bawaan tingkat atas maupun saat
merupakan prasyarat yang diperlukan untuk target build lainnya. Parameter 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 aturan semacam itu.
Perbedaan penting antara kedua namespace yang digunakan oleh sistem build: label mengidentifikasi target, yang dapat berupa aturan atau file, dan target file dapat dibagi menjadi target file sumber (atau input) dan target file turunan (atau output). Berikut adalah beberapa hal yang dapat Anda sebutkan dalam file BUILD,
membangun dari command line, atau memeriksanya menggunakan bazel query;
ini adalah namespace target. Setiap target file sesuai dengan satu file aktual pada disk ("namespace sistem file"); setiap target aturan dapat berkaitan dengan nol, satu, atau beberapa file aktual 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 dapat menyembunyikan detail implementasi tertentu tentang
cara kerjanya. Hal ini dijelaskan lebih lengkap dalam Referensi Konsep BUILD.