Bagian ini mendefinisikan berbagai istilah dan konsep yang umum untuk banyak fungsi atau aturan build.
Daftar Isi
- Tokenisasi Bourne shell
- Ekspansi Label
- Atribut umum yang ditentukan oleh sebagian besar aturan pembuatan
- Atribut umum untuk semua aturan pembuatan
- Atribut umum untuk semua aturan pengujian (*_test)
- Atribut umum untuk semua aturan biner (*_binary)
- Atribut yang dapat dikonfigurasi
- Target output implisit
Tokenisasi Bourne shell
Atribut string tertentu dari beberapa aturan dibagi menjadi beberapa kata sesuai dengan aturan tokenisasi Bourne shell: spasi yang tidak diapit tanda petik membatasi kata-kata terpisah, dan karakter tanda petik tunggal dan ganda serta garis miring terbalik digunakan untuk mencegah tokenisasi.
Atribut yang tunduk pada tokenisasi ini secara eksplisit ditunjukkan sebagai atribut yang tunduk pada tokenisasi dalam definisinya dalam dokumen ini.
Atribut yang tunduk pada ekspansi 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 satu variabel string diperluas menjadi daftar kata opsi khusus konfigurasi.
Perluasan label
Beberapa atribut string dari beberapa aturan tunduk pada perluasan label: jika string tersebut berisi label yang valid sebagai sub-string, seperti //mypkg:target
, dan label tersebut adalah prasyarat yang dinyatakan dari aturan saat ini, label tersebut akan diperluas menjadi nama jalur file yang diwakili oleh target
//mypkg:target
.
Contoh atribut mencakup genrule.cmd
dan
cc_binary.linkopts
. Detailnya dapat sangat bervariasi dalam setiap kasus, terkait masalah seperti: apakah label relatif diperluas; cara menangani label yang diperluas ke beberapa file, 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; defaultnya adalah File yang diperlukan oleh aturan ini saat runtime. Dapat mencantumkan target file atau aturan. Umumnya memungkinkan semua target.
Output dan file yang dapat dijalankan default target dalam atribut
Aturan baru harus menentukan atribut |
deps |
Daftar label; defaultnya adalah
Dependensi untuk target ini. Umumnya hanya akan 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 arti target bergantung pada target lain menggunakan
Sebagian besar, dependensi |
licenses |
Daftar string; tidak dapat dikonfigurasi;
defaultnya 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 lagi digunakan oleh Bazel. Jangan gunakan ini. |
srcs |
Daftar label; defaultnya adalah
File yang diproses atau disertakan oleh aturan ini. Biasanya 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 |
---|---|
aspect_hints |
Daftar label; defaultnya adalah Daftar label arbitrer yang diekspos ke aspek (khususnya - aspek yang dipanggil oleh dependensi terbalik aturan ini), tetapi tidak diekspos ke implementasi aturan ini sendiri. Lihat dokumentasi untuk mengetahui detail tentang efek yang akan ditimbulkan oleh petunjuk aspek tertentu untuk set aturan khusus bahasa. Anda dapat menganggap petunjuk aspek sebagai alternatif yang lebih kaya untuk tag:
sementara tag hanya menyampaikan status boolean (tag ada atau tidak ada dalam
daftar Dalam praktiknya, petunjuk aspek digunakan untuk interoperabilitas antara set aturan khusus bahasa yang berbeda. Misalnya, bayangkan Anda memiliki target Untuk contoh konkret, lihat
Praktik terbaik:
|
compatible_with |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah Daftar lingkungan yang dapat dibangun untuk 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 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, hal ini digunakan untuk memberi tahu pengguna bahwa target sudah tidak berlaku, 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 orang dapat dengan mudah mengetahui perubahan apa yang diperlukan untuk menghindari pesan tersebut. Jika ada target baru yang dapat digunakan sebagai pengganti langsung, sebaiknya migrasikan saja semua pengguna target lama.
Atribut ini tidak memengaruhi cara pembuatan, tetapi dapat memengaruhi output diagnostik alat build. Alat build mengeluarkan
peringatan saat aturan dengan atribut Dependensi dalam paket dikecualikan dari peringatan ini, sehingga, misalnya, membangun pengujian aturan yang tidak digunakan lagi tidak akan memunculkan 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. |
exec_compatible_with |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah
Daftar
|
exec_group_compatible_with |
Kamus string ke daftar label;
nonconfigurable; default adalah
Kamus nama grup exec ke daftar
|
exec_properties |
Kamus string; defaultnya adalah Kamus string yang akan ditambahkan ke Jika kunci ada di properti tingkat platform dan target, nilai akan diambil dari target. Kunci dapat diawali dengan nama grup eksekusi yang diikuti dengan |
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 |
package_metadata |
Daftar label;
nonconfigurable; default adalah
Daftar label yang merupakan metadata terkait target ini. Biasanya, label adalah aturan sederhana yang menampilkan penyedia nilai konstanta. Aturan dan aspek dapat menggunakan label ini untuk melakukan beberapa analisis tambahan pada grafik build.
Kasus penggunaan kanonis adalah
rules_license.
Untuk kasus penggunaan tersebut, |
restricted_to |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah Daftar lingkungan yang dapat dibangun untuk target ini, bukan lingkungan yang didukung secara default.
Ini adalah bagian dari sistem batasan Bazel. Lihat
|
tags |
Daftar string; tidak dapat dikonfigurasi;
defaultnya adalah
Tag dapat digunakan pada 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 memberi anotasi pada 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 menjalankan pengujian jika menemukan kata kunci berikut di atribut
|
target_compatible_with |
Daftar label; defaultnya adalah
Daftar
Target yang bergantung secara transitif pada target yang tidak kompatibel juga dianggap tidak kompatibel. File ini juga dilewati untuk pembuatan dan pengujian. Daftar kosong (yang merupakan default) menandakan 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 melewati target yang tidak kompatibel. |
testonly |
Boolean; tidak dapat dikonfigurasi; defaultnya adalah
Jika
Dengan kata lain, aturan yang bukan
Pengujian (aturan Atribut ini dimaksudkan untuk menunjukkan bahwa target tidak boleh terkandung dalam biner yang dirilis ke produksi. Karena testonly diterapkan pada waktu build, bukan waktu proses, dan menyebar secara viral melalui hierarki dependensi, testonly harus diterapkan dengan bijak. Misalnya, stub dan tiruan yang berguna untuk pengujian unit juga dapat berguna untuk pengujian integrasi yang melibatkan biner yang sama yang akan dirilis ke produksi, dan oleh karena itu, mungkin tidak boleh ditandai sebagai testonly. Sebaliknya, aturan yang bahkan berbahaya untuk ditautkan, mungkin karena aturan tersebut secara tanpa syarat menggantikan perilaku normal, harus ditandai sebagai testonly. |
toolchains |
Daftar label;
tidak dapat dikonfigurasi; defaultnya adalah
Kumpulan target yang Buat variabelnya diizinkan untuk diakses oleh target ini. Target ini adalah instance aturan yang menyediakan
Perhatikan bahwa hal ini berbeda dengan konsep
penyelesaian toolchain
yang digunakan oleh penerapan aturan untuk konfigurasi yang bergantung pada platform. Anda tidak dapat menggunakan atribut ini untuk menentukan |
visibility |
Daftar label; tidak dapat dikonfigurasi; default bervariasi
Atribut
Untuk target yang dideklarasikan langsung dalam file BUILD atau dalam makro lama yang dipanggil dari file BUILD, nilai defaultnya adalah |
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 substitusi
$(location) dan
"Buat variabel", serta
tokenisasi Bourne shell; defaultnya adalah Argumen command line yang diteruskan Bazel ke target saat dijalankan dengan
Argumen ini diteruskan sebelum nilai |
||||||||||||||||||||
env |
Kamus string; nilai tunduk pada
penggantian $(location) dan
"Buat variabel"; defaultnya adalah
Menentukan variabel lingkungan tambahan yang akan ditetapkan saat 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 "bobot" target pengujian: berapa banyak waktu/resource yang diperlukan untuk menjalankan pengujian. Pengujian unit dianggap "kecil", pengujian integrasi "sedang", dan pengujian end-to-end "besar" atau "sangat besar". Bazel menggunakan ukuran untuk menentukan waktu tunggu default, yang dapat diganti menggunakan atribut
Ukuran pengujian sesuai dengan waktu tunggu default dan penggunaan resource lokal puncak yang diasumsikan sebagai berikut:
Variabel lingkungan
|
||||||||||||||||||||
timeout |
String Berapa lama pengujian diperkirakan akan berjalan sebelum ditampilkan.
Meskipun atribut ukuran pengujian mengontrol estimasi resource, waktu tunggu pengujian dapat ditetapkan secara terpisah. Jika tidak ditentukan secara eksplisit, waktu tunggu
didasarkan pada ukuran pengujian. Waktu tunggu
pengujian dapat diganti dengan tanda
Untuk waktu selain di atas, waktu tunggu pengujian dapat diganti dengan
flag bazel
Variabel lingkungan
|
||||||||||||||||||||
flaky |
Boolean; non-dapat dikonfigurasi;
defaultnya adalah Menandai pengujian sebagai tidak stabil. Jika ditetapkan, menjalankan pengujian hingga tiga kali, menandainya sebagai gagal hanya jika gagal setiap kali. Secara default, atribut ini ditetapkan ke False dan pengujian dieksekusi hanya satu kali. Perhatikan bahwa penggunaan atribut ini umumnya tidak disarankan - pengujian harus lulus dengan andal saat pernyataannya ditegakkan. |
||||||||||||||||||||
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 disetel, nilai ini akan menggantikan semua heuristik 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 sejak awal. Lihat juga: Jika sharding pengujian diaktifkan, variabel lingkungan Sharding mengharuskan test runner mendukung protokol sharding pengujian. Jika tidak, kemungkinan besar semua pengujian akan dijalankan di setiap shard, yang bukan yang Anda inginkan. Lihat Test Sharding di Test Encyclopedia untuk mengetahui detail tentang sharding. |
||||||||||||||||||||
local |
Boolean; non-dapat dikonfigurasi;
defaultnya adalah Memaksa pengujian dijalankan secara lokal, tanpa sandbox. Menetapkan ini ke True sama dengan memberikan "local" sebagai tag
( |
Atribut 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
"Buat variabel", dan
tokenisasi shell Bourne;
tidak dapat dikonfigurasi;
defaultnya adalah
Argumen command line yang akan diteruskan Bazel ke target saat dijalankan
baik 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
"Buat variabel"; defaultnya adalah Menentukan variabel lingkungan tambahan yang akan disetel saat target
dieksekusi 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 tidak digunakan lagi dan tidak lagi digunakan oleh Bazel. Jangan gunakan ini. |
Atribut yang dapat dikonfigurasi
Sebagian besar atribut 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 hilir yang meminta target. Hal ini dapat digunakan, misalnya, untuk menyesuaikan target beberapa platform atau mode kompilasi.
Contoh berikut mendeklarasikan berbagai sumber untuk berbagai arsitektur
target. Menjalankan bazel build :multiplatform_lib --cpu x86
akan mem-build target menggunakan x86_impl.cc
, sementara mengganti
--cpu arm
akan menyebabkan target 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 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 yang dapat dikonfigurasi target. 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 menyelesaikan
select()
.
Lihat Atribut Build yang Dapat Dikonfigurasi untuk mengetahui ringkasan mendetail.
Target output implisit
Output implisit di C++ tidak digunakan lagi. Sebaiknya jangan menggunakannya dalam bahasa lain jika memungkinkan. Kami belum memiliki jalur penghentian penggunaan tetapi pada akhirnya jalur tersebut 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 khusus untuk aturan.
Misalnya, saat Anda secara eksplisit mendeklarasikan aturan
java_binary(name='foo', ...)
, 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 utama dari grafik target global. Seperti target lainnya, target ini dibuat sesuai permintaan,
baik saat ditentukan dalam perintah build tingkat teratas, atau saat
menjadi prasyarat yang diperlukan untuk target build lainnya. File tersebut 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). Berikut 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 (yaitu "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 dirujuk dari dalam file BUILD atau dari command line.
Dengan cara ini, alat build dapat menyembunyikan detail penerapan tertentu tentang
cara kerjanya. Hal ini dijelaskan lebih lengkap dalam
Referensi Konsep BUILD.