Semua target termasuk dalam satu paket. Nama target disebut label. Setiap label mengidentifikasi target secara unik. Label standar dalam bentuk kanonis terlihat seperti ini:
@myrepo//my/app/main:app_binary
Bagian pertama label adalah nama repositori, @myrepo//
.
Pada kasus umum, label merujuk ke repositori yang sama dengan yang digunakannya, ID repositori dapat disingkat menjadi //
.
Jadi, dalam @myrepo
, label ini biasanya ditulis sebagai
//my/app/main:app_binary
Bagian kedua dari label adalah nama paket
my/app/main
yang tidak memenuhi syarat, jalur ke paket
yang terkait dengan root repositori. Secara bersamaan, nama repositori dan
nama paket yang tidak memenuhi syarat membentuk nama paket
@myrepo//my/app/main
yang sepenuhnya memenuhi syarat. Jika label mengacu pada paket
yang sama dengan yang digunakan padanya, nama paket (dan secara opsional, titik dua)
dapat dihilangkan. Jadi, dalam @myrepo//my/app/main
,
label ini dapat ditulis dengan salah satu cara berikut:
app_binary
:app_binary
Ini adalah masalah konvensi bahwa titik dua dihilangkan untuk file, tetapi dipertahankan untuk aturan, tetapi tidak signifikan.
Bagian dari label setelah titik dua, app_binary
adalah nama target yang tidak memenuhi syarat. Jika cocok dengan komponen terakhir dari jalur paket, komponen dan
titik dua dapat dihilangkan. Jadi, kedua label ini setara:
//my/app/lib
//my/app/lib:lib
Nama target file dalam subdirektori paket adalah jalur file
yang relatif terhadap root paket (direktori yang berisi file BUILD
). Jadi,
file ini berada di subdirektori my/app/main/testdata
dari repositori:
//my/app/main:testdata/input.txt
String seperti //my/app
dan @some_repo//my/app
memiliki dua arti bergantung pada
konteks penggunaannya: saat Bazel mengharapkan label, masing-masing berarti
//my/app:app
dan @some_repo//my/app:app
. Namun, saat Bazel mengharapkan paket (misalnya dalam spesifikasi package_group
), Bazel mereferensikan paket yang berisi label tersebut.
Kesalahan umum di file BUILD
adalah penggunaan //my/app
untuk merujuk ke paket, atau
untuk semua target dalam paket--tidak demikian. Ingat, ini
setara dengan //my/app:app
, sehingga memberi nama target app
dalam paket my/app
repositori saat ini.
Namun, penggunaan //my/app
untuk merujuk ke sebuah paket disarankan dalam
spesifikasi file package_group
atau .bzl
, karena paket tersebut dengan jelas
menyatakan bahwa nama paket bersifat absolut dan di-root di direktori tingkat
atas ruang kerja.
Label relatif tidak dapat digunakan untuk merujuk ke target dalam paket lain; ID
repositori dan nama paket harus selalu ditentukan dalam kasus ini.
Misalnya, jika hierarki sumber berisi paket my/app
dan
paket my/app/testdata
(masing-masing dari dua direktori ini memiliki file
BUILD
sendiri), paket yang terakhir berisi file bernama testdepot.zip
. Berikut adalah dua cara (satu salah, satu benar) untuk merujuk file ini dalam //my/app:BUILD
:
Salah — testdata
adalah paket yang berbeda, sehingga Anda tidak dapat menggunakan jalur relatif
testdata/testdepot.zip
Benar — lihat testdata
beserta jalur lengkapnya
//my/app/testdata:testdepot.zip
Label yang dimulai dengan @//
adalah referensi ke repositori utama, yang masih akan berfungsi bahkan dari repositori eksternal.
Oleh karena itu, @//a/b/c
berbeda dengan
//a/b/c
jika dirujuk dari repositori eksternal.
Versi yang pertama merujuk kembali ke repositori utama, sedangkan yang kedua
mencari //a/b/c
di repositori eksternal itu sendiri.
Hal ini sangat relevan saat menulis aturan di repositori utama yang merujuk ke target di repositori utama, dan akan digunakan dari repositori eksternal.
Untuk mengetahui informasi tentang berbagai cara merujuk ke target, lihat pola target.
Spesifikasi label leksikal
Sintaksis label mencegah penggunaan karakter meta yang memiliki arti khusus pada shell. Ini membantu menghindari masalah kutipan yang tidak disengaja, dan mempermudah pembuatan alat dan skrip yang memanipulasi label, seperti Bazel Query Language.
Detail terperinci tentang nama target yang diizinkan ada di bawah.
Nama target — package-name:target-name
target-name
adalah nama target dalam paket. Nama aturan adalah nilai atribut name
dalam deklarasi aturan dalam file BUILD
; nama file adalah nama jalurnya yang relatif terhadap direktori yang berisi file BUILD
.
Nama target harus seluruhnya terdiri dari karakter yang digambar dari kumpulan a
–z
,
A
–Z
, 0
–9
, dan simbol tanda baca !%-@^_"#$&'()*-+,;<=>?[]{|}~/.
.
Nama file harus berupa nama jalur relatif dalam bentuk normal, yang berarti mereka tidak boleh
diawali atau diakhiri dengan garis miring (misalnya, /foo
dan foo/
dilarang) atau berisi beberapa garis miring berturut-turut sebagai pemisah jalur
(misalnya, foo//bar
). Demikian pula, referensi tingkat atas (..
) dan
referensi direktori saat ini (./
) dilarang.
Salah — Jangan gunakan `..` untuk merujuk ke file dalam paket lain
Benar — Gunakan `//package-name:filename`
Meskipun penggunaan /
atas nama target file adalah hal yang umum, hindari penggunaan /
dalam nama aturan. Terutama ketika format label singkat digunakan, mungkin membingungkan pembaca. Label //foo/bar/wiz
selalu merupakan singkatan
untuk //foo/bar/wiz:wiz
, meskipun tidak ada paket foo/bar/wiz
tersebut; label
tidak pernah merujuk ke //foo:bar/wiz
, meskipun target tersebut ada.
Namun, ada beberapa situasi yang membuat penggunaan garis miring menjadi lebih mudah, atau terkadang bahkan diperlukan. Misalnya, nama aturan tertentu harus cocok dengan file sumber utamanya, yang mungkin berada dalam subdirektori paket.
Nama paket — //package-name:target-name
Nama paket adalah nama direktori yang berisi file BUILD
-nya,
relatif terhadap direktori level teratas dari repositori yang memuatnya.
Misalnya: my/app
.
Nama paket harus seluruhnya terdiri dari karakter yang digambar dari kumpulan
A
-Z
, a
–z
, 0
–9
, '/
', '-
', '.
', '@
', dan '_
', serta tidak boleh
diawali dengan garis miring.
Untuk bahasa dengan struktur direktori yang signifikan bagi sistem modulnya (misalnya, Java), penting untuk memilih nama direktori yang merupakan ID yang valid dalam bahasa tersebut.
Meskipun Bazel mendukung target dalam paket root ruang kerja (misalnya,
//:foo
), sebaiknya biarkan paket tersebut kosong sehingga semua paket yang bermakna
memiliki nama deskriptif.
Nama paket tidak boleh berisi substring //
, atau diakhiri dengan garis miring.
Aturan
Aturan menetapkan hubungan antara input dan output, serta langkah-langkah untuk mem-build output. Aturan dapat berupa salah satu dari banyak jenis (terkadang disebut class aturan), yang menghasilkan file yang dapat dieksekusi dan library yang dikompilasi, menguji file yang dapat dieksekusi, dan output lain yang didukung seperti yang dijelaskan dalam Membuat Ensiklopedia.
File BUILD
mendeklarasikan target dengan memanggil aturan.
Pada contoh di bawah, kita melihat deklarasi my_app
target menggunakan aturan cc_binary
.
cc_binary(
name = "my_app",
srcs = ["my_app.cc"],
deps = [
"//absl/base",
"//absl/strings",
],
)
Setiap pemanggilan aturan memiliki atribut name
(yang harus berupa
nama target yang valid), yang mendeklarasikan target dalam paket
file BUILD
.
Setiap aturan memiliki serangkaian atribut; atribut yang berlaku untuk aturan tertentu, serta signifikansi dan semantik untuk setiap atribut merupakan fungsi dari jenis aturan tersebut; lihat Build Encyclopedia untuk mengetahui daftar aturan dan atributnya yang sesuai. Setiap atribut memiliki nama dan jenis. Beberapa jenis umum yang dapat dimiliki atribut adalah bilangan bulat, label, daftar label, string, daftar string, label output, daftar label output. Tidak semua atribut perlu ditentukan di setiap aturan. Dengan demikian, atribut membentuk kamus dari kunci (nama) ke nilai opsional yang diketik.
Atribut srcs
yang ada dalam banyak aturan memiliki jenis "list of labels"; nilainya, jika ada, adalah daftar label, yang masing-masing merupakan nama target yang menjadi input untuk aturan ini.
Dalam beberapa kasus, nama jenis aturan agak acak dan lebih menarik adalah nama file yang dihasilkan oleh aturan, dan hal ini berlaku pada aturan umum. Untuk mengetahui informasi selengkapnya, lihat Aturan Umum: genrule.
Dalam kasus lain, namanya signifikan: untuk aturan *_binary
dan *_test
, misalnya, nama aturan menentukan nama file yang dapat dieksekusi yang dihasilkan oleh build.
Grafik asiklik terarah ini di atas target disebut grafik target atau grafik dependensi build, dan merupakan domain tempat alat Kueri Bazel beroperasi.
Target | MEMBANGUN file |