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 {i>shell Bourne<i}: spasi tanpa tanda kutip membatasi kata terpisah, dan tanda petik tunggal karakter tanda kutip ganda dan garis miring terbalik digunakan untuk mencegah tokenisasi.
Atribut yang tunduk pada tokenisasi ini secara eksplisit dinyatakan seperti itu dalam definisinya dalam dokumen ini.
Atribut yang tunduk pada "Merek" ekspansi variabel dan {i>shell Bourne<i}
tokenisasi biasanya digunakan untuk
meneruskan opsi arbitrer ke
compiler dan alat lainnya. Contoh dari atribut tersebut adalah
cc_library.copts dan java_library.javacopts.
Bersama-sama, substitusi ini memungkinkan
variabel string tunggal untuk diperluas ke daftar khusus konfigurasi
kata opsi.
Perluasan label
Beberapa atribut string dari sangat sedikit aturan tunduk pada label
perluasan: jika {i>string<i} tersebut
berisi label yang valid sebagai
substring, seperti //mypkg:target, dan label tersebut adalah
yang dinyatakan sebagai prasyarat dari aturan saat ini, hal itu diperluas ke dalam
nama jalur dari file yang direpresentasikan oleh
target
//mypkg:target.
Atribut contoh mencakup genrule.cmd dan
cc_binary.linkopts. Detailnya bisa sangat bervariasi dalam
setiap kasus, terhadap masalah seperti: apakah label relatif
diperluas; bagaimana label yang
diperluas ke beberapa file
diperlakukan, dll. Baca dokumentasi atribut aturan untuk
secara spesifik.
Atribut umum yang ditentukan oleh sebagian besar aturan build
Bagian ini menjelaskan atribut yang ditentukan oleh banyak aturan build, tetapi tidak semua.
| Atribut | Deskripsi |
|---|---|
data |
Daftar label; default adalah File yang diperlukan oleh aturan ini saat runtime. Dapat mencantumkan target file atau aturan. Umumnya memungkinkan semua target.
Output dan runfile default target dalam atribut
Aturan baru harus menentukan atribut |
deps |
Daftar label; default adalah
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 tepat tentang maksud target untuk bergantung pada yang lain menggunakan
Paling sering, dependensi |
licenses |
Daftar {i>string<i}; tidak dapat dikonfigurasi;
default 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. Larangan gunakan ini. |
srcs |
Daftar label; default adalah
File yang diproses atau disertakan oleh aturan ini. Biasanya mencantumkan file secara langsung, tetapi
dapat mencantumkan target aturan (seperti Aturan spesifik bahasa sering kali mengharuskan file yang tercantum memiliki ekstensi file. |
Atribut yang umum untuk semua aturan build
Bagian ini menjelaskan atribut yang secara implisit ditambahkan ke semua build aturan.
| Atribut | Deskripsi |
|---|---|
compatible_with |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah Daftar lingkungan yang dapat dibuat target ini, selain yang didukung secara default. Ini adalah bagian dari sistem pembatas Bazel, yang memungkinkan pengguna mendeklarasikan target dapat dan tidak dapat saling bergantung. Misalnya, yang dapat di-deploy secara eksternal biner tidak boleh bergantung pada {i>library <i}dengan kode rahasia perusahaan. Lihat ConstraintSemantics untuk mengetahui detailnya. |
deprecation |
String; tidak dapat dikonfigurasi; default adalah Pesan peringatan penjelasan yang terkait dengan target ini. Biasanya, 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. Ada baiknya untuk menyertakan beberapa referensi (seperti laman web, nomor {i>bug<i} atau contoh CL migrasi) jadi orang dapat dengan mudah mengetahui perubahan apa yang diperlukan untuk menghindari pesan tersebut. Jika ada target baru yang dapat digunakan sebagai penurunan penggantian, itu adalah ide yang bagus untuk memigrasikan semua pengguna dari target lama.
Atribut ini tidak berpengaruh pada cara objek dibuat, tetapi
dapat memengaruhi output diagnostik alat build. Alat build mengeluarkan
peringatan saat aturan dengan atribut Dependensi intra-paket dikecualikan dari peringatan ini, sehingga, misalnya, membangun pengujian aturan yang sudah tidak digunakan lagi mendapatkan peringatan. Jika target yang tidak digunakan lagi bergantung pada target lain yang tidak digunakan lagi, tidak ada peringatan pesan diterbitkan. Setelah pengguna berhenti menggunakannya, target dapat dihapus. |
distribs |
Daftar {i>string<i}; tidak dapat dikonfigurasi;
default 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. Larangan gunakan ini. |
exec_compatible_with |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah
Daftar
|
exec_properties |
Kamus {i>string<i}; default-nya 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; default adalah Fitur adalah tag string yang dapat diaktifkan atau dinonaktifkan pada target. Tujuan arti fitur tergantung pada aturan itu sendiri. Atribut |
restricted_to |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah Daftar lingkungan yang dapat di-build untuk target ini, bukan yang didukung secara default.
Ini adalah bagian dari sistem pembatas Bazel. Lihat
|
tags |
Daftar {i>string<i}; tidak dapat dikonfigurasi;
default adalah
Tag dapat digunakan di aturan apa pun. Tag pada pengujian dan
Aturan
Bazel memodifikasi perilaku kode {i>sandbox<i}-nya jika menemukan hal berikut
kata kunci dalam atribut
Tag pada pengujian umumnya digunakan untuk menganotasi peran pengujian di proses debug dan perilisan. Biasanya, tag paling berguna untuk C++ dan Python yang tidak memiliki kemampuan anotasi runtime. Penggunaan {i>tag<i} dan ukuran memberikan fleksibilitas dalam menyusun rangkaian pengujian berdasarkan codebase {i>check-in<i}.
Bazel memodifikasi perilaku uji coba jika menemukan kata kunci berikut pada
Atribut
|
target_compatible_with |
Daftar label; default adalah
Daftar
Target yang secara transitif bergantung pada target yang tidak kompatibel adalah target itu sendiri dianggap tidak kompatibel. Pengujian ini juga dilewati untuk proses build dan pengujian. Daftar kosong (yang merupakan default) menandakan bahwa target kompatibel dengan semua platform.
Semua aturan selain Aturan Workspace mendukung fitur ini
.
Untuk beberapa aturan, atribut ini tidak memiliki pengaruh. Misalnya, menentukan
Lihat Platform untuk informasi selengkapnya tentang pengabaian target yang tidak kompatibel. |
testonly |
Boolean; tidak dapat dikonfigurasi; default adalah
Jika
Setara dengan itu, aturan yang bukan
Pengujian ( Atribut ini dimaksudkan untuk menunjukkan bahwa target tidak boleh yang terkandung dalam biner yang dirilis ke produksi. Karena testonly diterapkan pada waktu build, bukan runtime, dan menyebar secara viral melalui pohon dependensi, maka harus diterapkan secara bijaksana. Sebagai contoh, stub dan palsu berguna untuk pengujian unit juga mungkin berguna untuk pengujian integrasi yang melibatkan biner yang sama yang akan dirilis ke produksi, dan oleh karena itu mungkin tidak ditandai sebagai {i>testonly<i}. Sebaliknya, aturan yang berbahaya untuk ditautkan, mungkin karena mereka tanpa syarat mengabaikan perilaku normal, maka harus ditandai sebagai {i>testonly<i}. |
toolchains |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah
Kumpulan target yang Jadikan variabel sebagai target ini
yang diizinkan untuk diakses. Target ini merupakan contoh dari 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 ini
untuk menentukan |
visibility |
Daftar label;
tidak dapat dikonfigurasi;
defaultnya 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 {i>string<i}; tunduk kepada
$(location) dan
Penggantian "Buat variabel", dan
Tokenisasi shell Bourne; default-nya adalah Argumen command line yang diteruskan Bazel ke target saat
dieksekusi dengan
Argumen ini diteruskan sebelum nilai |
||||||||||||||||||||
env |
Kamus {i>string<i}; nilai tersebut tunduk kepada
$(location) dan
Penggantian "Buat variabel"; defaultnya adalah
Menentukan variabel lingkungan tambahan yang akan ditetapkan kapan pengujian dijalankan
Atribut ini hanya berlaku untuk aturan native, seperti |
||||||||||||||||||||
env_inherit |
Daftar {i>string<i}; default-nya 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
"sangat besar". Bazel menggunakan ukuran untuk menentukan waktu tunggu {i>default<i}, yang dapat diganti menggunakan
Atribut Ukuran uji sesuai dengan waktu tunggu default berikut dan asumsi resource lokal puncak penggunaan:
Variabel lingkungan |
||||||||||||||||||||
timeout |
String Perkiraan lama pengujian diperkirakan akan berjalan sebelum ditampilkan kembali.
Atribut ukuran pengujian mengontrol estimasi resource, sedangkan
waktu tunggu dapat disetel secara terpisah. Jika tidak ditentukan secara eksplisit,
waktu tunggu didasarkan pada ukuran pengujian. Tes
waktu tunggu dapat diganti dengan tanda
Untuk waktu selain yang disebutkan di atas, waktu tunggu pengujian dapat diganti dengan
Bendera bazel Variabel lingkungan |
||||||||||||||||||||
flaky |
Boolean; tidak dapat dikonfigurasi;
default adalah Menandai pengujian sebagai tidak stabil. Jika disetel, pengujian akan dijalankan hingga tiga kali, dan menandainya sebagai gagal hanya jika gagal setiap kali. Secara default, atribut ini disetel ke Salah (False) dan pengujian ditetapkan hanya dijalankan sekali. Perhatikan bahwa penggunaan atribut ini umumnya tidak disarankan - pengujian harus berhasil secara andal jika pernyataannya ditegakkan. |
||||||||||||||||||||
shard_count |
Bilangan bulat non-negatif yang lebih kecil atau sama dengan 50; default-nya 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
shard paralel yang akan digunakan untuk menjalankan pengujian. Perhatikan bahwa untuk beberapa pengujian,
aturan, 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 ia akan menjalankan setiap pengujian di setiap shard, yang tidak sesuai dengan keinginan Anda. Lihat Menguji Sharding di Test Encyclopedia untuk mengetahui detail tentang sharding. |
||||||||||||||||||||
local |
Boolean; tidak dapat dikonfigurasi;
default adalah Memaksa pengujian untuk dijalankan secara lokal, tanpa sandbox. Menetapkan ini ke True sama dengan memberikan "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 {i>string<i}; tunduk kepada
$(location) dan
Penggantian "Buat variabel", dan
Tokenisasi shell Bourne;
tidak dapat dikonfigurasi;
default-nya adalah
Argumen command line yang akan diteruskan Bazel ke target saat dieksekusi
baik dengan perintah
CATATAN: Argumen tidak diteruskan saat Anda menjalankan target
di luar Bazel (misalnya, dengan
menjalankan biner secara manual di
|
env |
Kamus {i>string<i}; nilai tersebut tunduk kepada
$(location) dan
Penggantian "Buat variabel"; defaultnya adalah Menentukan variabel lingkungan tambahan yang akan ditetapkan saat 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 {i>string<i}; default-nya 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. Larangan gunakan ini. |
Atribut yang dapat dikonfigurasi
Sebagian besar atribut dapat "dikonfigurasi", artinya nilainya dapat berubah saat target dibangun dengan cara yang berbeda. Secara khusus, atribut yang dapat dikonfigurasi dapat bervariasi berdasarkan penanda yang diteruskan ke baris perintah Bazel, atau apa dependensi downstream meminta target. Ini dapat digunakan, untuk instance, untuk menyesuaikan target untuk beberapa platform atau mode kompilasi.
Contoh berikut mendeklarasikan berbagai sumber untuk berbagai target
terkait arsitektur. Menjalankan bazel build :multiplatform_lib --cpu x86
akan membuat target menggunakan x86_impl.cc, sekaligus mengganti
Sebagai gantinya, --cpu arm akan membuatnya 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
di mana config_setting
atau constraint_value
yang dipenuhi oleh konfigurasi target.
Bazel mengevaluasi atribut yang dapat dikonfigurasi setelah memproses makro dan sebelum
aturan pemrosesan (secara teknis, di antara
pemuatan dan analisis).
Setiap pemrosesan sebelum evaluasi select() tidak mengetahui
yang dipilih oleh select(). Makro, misalnya, tidak dapat berubah
perilakunya berdasarkan cabang yang dipilih, dan bazel query dapat
hanya membuat perkiraan konservatif tentang dependensi yang dapat dikonfigurasi milik target. Lihat
FAQ ini
untuk informasi selengkapnya tentang penggunaan select() dengan aturan dan makro.
Atribut yang ditandai nonconfigurable dalam dokumentasinya tidak dapat
menggunakan fitur ini. Biasanya atribut tidak dapat dikonfigurasi karena Bazel
secara internal perlu mengetahui nilainya
sebelum dapat menentukan cara menyelesaikan
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 pada akhirnya fitur tersebut juga tidak akan digunakan lagi.
Saat mendefinisikan aturan build dalam file BUILD, Anda secara eksplisit
mendeklarasikan target aturan baru yang bernama dalam sebuah paket. Banyak aturan build
fungsi juga secara implisit memerlukan satu atau beberapa file output
target, yang konten dan maknanya spesifik per aturan.
Misalnya, ketika Anda secara eksplisit mendeklarasikan sebuah
java_binary(name='foo', ...), Anda juga
secara implisit mendeklarasikan file output
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
target grafik. Sama seperti target lainnya, target dibuat sesuai permintaan,
baik ketika ditentukan dalam perintah
{i>build<i} tingkat atas, atau ketika
adalah prasyarat yang diperlukan untuk target build lainnya. Dapat berupa
yang direferensikan sebagai dependensi dalam file BUILD,
output alat analisis seperti bazel query.
Untuk setiap jenis aturan build, dokumentasi aturan berisi sebuah elemen bagian khusus yang merinci nama dan isi dari output yang dicakup oleh deklarasi aturan semacam itu.
Perbedaan yang penting namun
agak mirip antara
dua 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 file turunan (atau output)
target. Berikut adalah hal-hal yang dapat Anda
sebutkan di file BUILD,
membangun dari command line, atau memeriksa menggunakan bazel query;
ini adalah namespace target. Setiap target file sesuai
ke satu file sebenarnya di disk ("namespace sistem file"); setiap aturan
target mungkin sesuai dengan nol, satu atau beberapa file aktual pada {i>disk<i}.
Mungkin ada file di disk yang tidak memiliki target yang sesuai; untuk
contoh, file objek .o yang dihasilkan selama kompilasi C++
tidak dapat dirujuk dari dalam file BUILD atau dari baris perintah.
Dengan cara ini, alat pembangunan dapat
menyembunyikan detail implementasi tertentu dari
bagaimana ia melakukan tugasnya. Hal ini dijelaskan lebih lengkap dalam
Referensi Konsep BUILD.