Bagian ini menentukan berbagai istilah dan konsep yang umum untuk banyak fungsi atau aturan build.
Daftar Isi
- Tokenisasi shell Bourne
- Ekspansi 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 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, penggantian ini memungkinkan
variabel string tunggal diperluas menjadi daftar kata opsi
khusus konfigurasi.
Perluasan label
Beberapa atribut string dari sangat sedikit aturan tunduk pada perluasan label: jika string tersebut berisi label yang valid sebagai substring, seperti //mypkg:target, dan label tersebut adalah prasyarat yang dideklarasikan dari aturan saat ini, string tersebut akan diperluas menjadi jalur file yang diwakili oleh target
//mypkg:target.
Contoh atribut meliputi genrule.cmd dan
cc_binary.linkopts. Detailnya dapat bervariasi secara signifikan dalam
setiap kasus, terkait masalah seperti: apakah label relatif
diperluas; cara label yang diperluas ke beberapa file
diperlakukan, dll. Lihat dokumentasi atribut aturan untuk
mengetahui detailnya.
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; default-nya adalah File yang diperlukan oleh aturan ini saat runtime. Dapat mencantumkan target file atau aturan. Umumnya memungkinkan target apa pun.
Output default dan runfile target dalam atribut
Aturan baru harus menentukan atribut |
deps |
Daftar label; default-nya 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 untuk target dengan penyedia tertentu.
Semantik yang tepat tentang arti target yang bergantung pada target lain menggunakan
Sering kali, dependensi |
licenses |
Daftar string; tidak dapat dikonfigurasi;
default adalah Daftar string jenis lisensi yang akan digunakan untuk target tertentu ini. Ini adalah bagian dari API pemberian lisensi yang tidak digunakan lagi dan tidak digunakan lagi oleh Bazel. Jangan gunakan ini. |
srcs |
Daftar label; default-nya 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 mewajibkan file yang tercantum memiliki ekstensi file tertentu. |
Atribut yang umum untuk semua aturan build
Bagian ini menjelaskan atribut yang secara implisit ditambahkan ke semua aturan build.
| Atribut | Deskripsi |
|---|---|
compatible_with |
Daftar label;
tidak dapat dikonfigurasi; default-nya adalah Daftar lingkungan yang dapat digunakan untuk mem-build target ini, selain lingkungan yang didukung secara default. Ini adalah bagian dari sistem batasan Bazel, yang memungkinkan pengguna mendeklarasikan target mana yang dapat dan tidak dapat bergantung satu sama lain. 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; default-nya adalah Pesan peringatan penjelasan yang terkait dengan target ini. Biasanya, ini digunakan untuk memberi tahu pengguna bahwa target sudah tidak digunakan lagi, atau telah diganti 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) sehingga seseorang dapat dengan mudah mengetahui perubahan yang diperlukan untuk menghindari pesan tersebut. Jika ada target baru yang dapat digunakan sebagai penggantian langsung, 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, mem-build pengujian aturan yang tidak digunakan lagi tidak akan mengalami peringatan. Jika target yang tidak digunakan lagi bergantung pada target lain yang tidak digunakan lagi, tidak ada pesan peringatan yang dikeluarkan. Setelah orang berhenti menggunakannya, target dapat dihapus. |
distribs |
Daftar string; tidak dapat dikonfigurasi;
default adalah Daftar string metode distribusi yang akan digunakan untuk target tertentu ini. Ini adalah bagian dari API pemberian lisensi yang tidak digunakan lagi dan tidak digunakan lagi oleh Bazel. Jangan gunakan ini. |
exec_compatible_with |
Daftar label;
tidak dapat dikonfigurasi; default-nya adalah
Daftar
|
exec_properties |
Kamus string; default-nya adalah Kamus string yang akan ditambahkan ke Jika kunci ada di properti tingkat platform dan target, nilai akan diambil dari target. |
features |
Daftar string fitur; default-nya adalah Fitur adalah tag string yang dapat diaktifkan atau dinonaktifkan di target. Makna fitur bergantung pada aturan itu sendiri. Atribut |
restricted_to |
Daftar label;
tidak dapat dikonfigurasi; default-nya adalah Daftar lingkungan yang dapat digunakan untuk mem-build target ini, bukan lingkungan yang didukung secara default.
Ini adalah bagian dari sistem batasan Bazel. Lihat
|
tags |
Daftar string; tidak dapat dikonfigurasi;
default adalah
Tag dapat digunakan pada aturan apa pun. Tag pada aturan pengujian dan
Bazel mengubah perilaku kode sandbox-nya jika menemukan kata kunci
berikut dalam atribut
Tag pada pengujian biasanya 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 di
atribut
|
target_compatible_with |
Daftar label; default-nya adalah
Daftar
Target yang secara transitif bergantung pada target yang tidak kompatibel juga dianggap tidak kompatibel. Pengujian ini 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 lewati target yang tidak kompatibel. |
testonly |
Boolean; tidak dapat dikonfigurasi; defaultnya adalah
Jika
Demikian pula, aturan yang bukan
Pengujian (aturan Atribut ini dimaksudkan untuk menunjukkan bahwa target tidak boleh berisi dalam biner yang dirilis ke produksi. Karena testonly diterapkan pada waktu build, bukan waktu run, dan disebarkan secara viral melalui hierarki dependensi, testonly harus diterapkan dengan cermat. Misalnya, stub dan palsu yang berguna untuk pengujian unit juga dapat berguna untuk pengujian integrasi yang melibatkan biner yang sama yang akan dirilis ke produksi, dan karenanya mungkin tidak boleh ditandai sebagai testonly. Sebaliknya, aturan yang bahkan berbahaya untuk ditautkan, mungkin karena aturan tersebut secara tidak bersyarat mengganti perilaku normal, harus ditandai sebagai testonly. |
toolchains |
Daftar label;
tidak dapat dikonfigurasi; default-nya adalah
Kumpulan target yang Variabel Make-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;
tidak dapat dikonfigurasi;
defaultnya adalah
Atribut |
Atribut yang umum untuk semua aturan pengujian (*_test)
Bagian ini menjelaskan atribut yang umum untuk semua aturan pengujian.
| Atribut | Deskripsi | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Daftar string; tunduk pada penggantian $(location) dan "Make variable", 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 pada penggantian
$(location) dan
"Make variable"; default-nya adalah
Menentukan variabel lingkungan tambahan yang akan ditetapkan saat pengujian dijalankan oleh
Atribut ini hanya berlaku untuk aturan native, seperti |
||||||||||||||||||||
env_inherit |
Daftar string; 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 "beban" target pengujian: berapa banyak waktu/resource yang diperlukan untuk dijalankan. Pengujian unit dianggap "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 |
String Berapa lama pengujian diperkirakan akan berjalan sebelum kembali.
Meskipun atribut ukuran pengujian mengontrol estimasi resource, waktu tunggu
pengujian dapat ditetapkan secara independen. Jika tidak ditentukan secara eksplisit, waktu tunggu 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; tidak dapat dikonfigurasi;
defaultnya adalah Menandai pengujian sebagai tidak stabil. Jika ditetapkan, akan mengeksekusi pengujian hingga tiga kali, menandainya sebagai gagal hanya jika gagal setiap kali. Secara default, atribut ini ditetapkan ke Salah dan pengujian hanya dieksekusi satu kali. Perhatikan bahwa penggunaan atribut ini umumnya tidak dianjurkan - pengujian harus lulus dengan andal saat pernyataannya ditegakkan. |
||||||||||||||||||||
shard_count |
Bilangan bulat non-negatif yang kurang dari atau sama dengan 50; default-nya adalah Menentukan jumlah shard paralel yang akan digunakan untuk menjalankan pengujian. Jika ditetapkan, nilai ini akan mengganti heuristik apa pun yang digunakan untuk menentukan jumlah
shard paralel yang akan digunakan untuk menjalankan pengujian. Perhatikan bahwa untuk beberapa aturan
pengujian, parameter ini mungkin diperlukan untuk mengaktifkan sharding
terlebih dahulu. Lihat juga: Jika sharding pengujian diaktifkan, variabel lingkungan Sharding mengharuskan runner pengujian untuk mendukung protokol sharding pengujian. Jika tidak, kemungkinan besar setiap pengujian akan dijalankan di setiap shard, yang bukan yang Anda inginkan. Lihat Menguji Sharding di Ensiklopedia Pengujian untuk mengetahui detail tentang sharding. |
||||||||||||||||||||
local |
Boolean; tidak dapat dikonfigurasi;
defaultnya adalah Memaksa pengujian 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 umum untuk semua aturan biner.
| Atribut | Deskripsi |
|---|---|
args |
Daftar string; tunduk pada penggantian
$(location) dan
"Make variable", serta
tokenisasi shell Bourne;
tidak dapat dikonfigurasi;
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 mengeksekusi biner secara manual di
|
env |
Kamus string; nilai tunduk pada penggantian
$(location) dan
"Make variable"; default-nya 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 mengeksekusi biner secara manual di
|
output_licenses |
Daftar string; default-nya adalah Lisensi file output yang dihasilkan biner ini. Ini adalah bagian dari API pemberian lisensi yang tidak digunakan lagi dan tidak digunakan lagi oleh Bazel. Jangan gunakan ini. |
Atribut yang dapat dikonfigurasi
Sebagian besar atribut bersifat "dapat dikonfigurasi", yang berarti 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 untuk arsitektur target
yang berbeda. Menjalankan bazel build :multiplatform_lib --cpu x86
akan mem-build target menggunakan x86_impl.cc, sedangkan penggantian
--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 konfigurasi target.
Bazel mengevaluasi atribut yang dapat dikonfigurasi setelah memproses makro dan sebelum
memproses aturan (secara teknis, antara
fase pemuatan dan analisis).
Setiap pemrosesan sebelum evaluasi select() tidak mengetahui cabang mana yang dipilih select(). Misalnya, makro 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 tidak dapat dikonfigurasi karena Bazel
secara internal perlu mengetahui nilainya sebelum dapat menentukan cara me-resolve
select().
Lihat Atribut Build yang Dapat Dikonfigurasi untuk ringkasan mendetail.
Target output implisit
Output implisit di C++ tidak digunakan lagi. Sebisa mungkin, jangan gunakan bahasa lain. Kami belum memiliki jalur penghentian penggunaan, tetapi pada akhirnya juga akan dihentikan penggunaannya.
Saat menentukan aturan build dalam file BUILD, Anda secara eksplisit
mendeklarasikan target aturan baru yang diberi nama dalam paket. Banyak fungsi aturan
build juga secara implisit memerlukan satu atau beberapa target file
output, yang konten dan artinya bersifat khusus 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 ini dibuat berdasarkan permintaan,
baik saat ditentukan dalam perintah build tingkat teratas, maupun saat
merupakan prasyarat yang diperlukan untuk target build lainnya. Fungsi 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 konten output implisit yang diperlukan oleh deklarasi jenis aturan tersebut.
Perbedaan penting tetapi agak halus 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 target file turunan (atau output). Ini adalah hal-hal yang dapat Anda sebutkan dalam file BUILD,
build dari command line, atau periksa menggunakan bazel query;
ini adalah namespace target. Setiap target file sesuai
dengan satu file sebenarnya di disk ("namespace sistem file"); setiap target
aturan dapat sesuai dengan nol, satu, atau beberapa file sebenarnya di disk.
Mungkin ada file di 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 alat tersebut melakukan tugasnya. Hal ini dijelaskan lebih lengkap dalam
Referensi Konsep BUILD.