Label

Label adalah ID untuk target. Label standar dalam bentuk kanoniknya yang lengkap terlihat seperti:

@@myrepo//my/app/main:app_binary

Bagian pertama label adalah nama repositori, @@myrepo. Sintaksis @ ganda menandakan bahwa ini adalah nama repo kanonis, yang unik dalam ruang kerja. Label dengan nama repo kanonis secara jelas mengidentifikasi target, apa pun konteksnya.

Sering kali nama repo kanonis adalah string yang tidak jelas dan terlihat seperti @@rules_java++toolchains+local_jdk. Yang lebih sering terlihat adalah label dengan nama repo yang tampak, yang terlihat seperti:

@myrepo//my/app/main:app_binary

Satu-satunya perbedaan adalah nama repo yang diawali dengan satu @, bukan dua. Hal ini merujuk pada repo dengan nama myrepo, yang dapat berbeda berdasarkan konteks label ini muncul.

Dalam kasus umum bahwa label merujuk ke repositori yang sama dari tempat label tersebut digunakan, bagian nama repo dapat dihilangkan. Jadi, di dalam @@myrepo, label pertama biasanya ditulis sebagai

//my/app/main:app_binary

Bagian kedua label adalah nama paket yang tidak memenuhi syarat my/app/main, jalur ke paket relatif terhadap root repositori. Bersama-sama, nama repositori dan nama paket yang tidak memenuhi syarat membentuk nama paket yang sepenuhnya memenuhi syarat @@myrepo//my/app/main. Jika label merujuk ke paket yang sama dengan yang digunakan, nama paket (dan secara opsional, titik dua) dapat dihilangkan. Jadi, di dalam @@myrepo//my/app/main, label ini dapat ditulis dengan salah satu cara berikut:

app_binary
:app_binary

Penghilangan titik dua untuk file dan mempertahankan titik dua untuk aturan adalah masalah konvensi, tetapi tidak signifikan.

Bagian label setelah titik dua, app_binary adalah nama target yang tidak memenuhi syarat. Jika cocok dengan komponen terakhir jalur paket, maka komponen tersebut, 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 relatif terhadap root paket (direktori yang berisi file BUILD). Jadi, file ini berada di subdirektori my/app/main/testdata 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, string tersebut berarti //my/app:app dan @@some_repo//my/app:app. Namun, saat Bazel mengharapkan paket (misalnya dalam spesifikasi package_group), Bazel akan mereferensikan paket yang berisi label tersebut.

Kesalahan umum dalam file BUILD adalah menggunakan //my/app untuk merujuk ke paket, atau ke semua target dalam paket--hal ini tidak dapat dilakukan. 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 paket dianjurkan dalam spesifikasi package_group atau dalam file .bzl, karena secara jelas mengomunikasikan bahwa nama paket bersifat absolut dan berakar di direktori tingkat teratas 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 pohon sumber berisi paket my/app dan paket my/app/testdata (setiap direktori ini memiliki file BUILD sendiri), paket terakhir berisi file bernama testdepot.zip. Berikut dua cara (satu salah, satu benar) untuk merujuk ke file ini dalam //my/app:BUILD:

Salah — testdata adalah paket yang berbeda, jadi Anda tidak dapat menggunakan jalur relatif

testdata/testdepot.zip

Benar — merujuk ke testdata dengan jalur lengkapnya

//my/app/testdata:testdepot.zip

Label yang diawali dengan @@// adalah referensi ke repositori utama, yang akan tetap berfungsi meskipun dari repositori eksternal. Oleh karena itu, @@//a/b/c berbeda dengan //a/b/c saat dirujuk dari repositori eksternal. Yang pertama merujuk kembali ke repositori utama, sedangkan yang kedua mencari //a/b/c di repositori eksternal itu sendiri. Hal ini terutama 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 Anda dapat merujuk ke target, lihat pola target.

Spesifikasi leksikal label

Sintaksis label tidak menganjurkan penggunaan karakter meta yang memiliki arti khusus bagi shell. Hal ini membantu menghindari masalah kutipan yang tidak disengaja, dan mempermudah pembuatan alat dan skrip yang memanipulasi label, seperti Bazel Query Language.

Detail yang tepat dari nama target yang diizinkan tercantum 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 jalur namanya relatif terhadap direktori yang berisi file BUILD.

Nama target harus sepenuhnya terdiri dari karakter yang diambil dari set a–z, A–Z, 0–9, dan simbol tanda baca !%-@^_"#$&'()*-+,;<=>?[]{|}~/..

Nama file harus berupa nama jalur relatif dalam bentuk normal, yang berarti nama file tidak boleh diawali atau diakhiri dengan garis miring (misalnya, /foo dan foo/ tidak diizinkan) atau berisi beberapa garis miring berurutan sebagai pemisah jalur (misalnya, foo//bar). Demikian pula, referensi tingkat atas (..) dan referensi direktori saat ini (./) tidak diizinkan.

Salah — Jangan gunakan .. untuk merujuk ke file dalam paket lain

Benar — Gunakan //package-name:filename

Meskipun umum menggunakan / dalam nama target file, hindari penggunaan / dalam nama aturan. Terutama saat bentuk singkat label digunakan, hal ini dapat membingungkan pembaca. Label //foo/bar/wiz selalu merupakan singkatan untuk //foo/bar/wiz:wiz, meskipun tidak ada paket foo/bar/wiz tersebut; label ini tidak pernah merujuk ke //foo:bar/wiz, meskipun target tersebut ada.

Namun, ada beberapa situasi saat penggunaan garis miring lebih mudah, atau bahkan terkadang diperlukan. Misalnya, nama aturan tertentu harus cocok dengan file sumber utamanya, yang mungkin berada di subdirektori paket.

Nama paket — //package-name:target-name

Nama paket adalah nama direktori yang berisi file BUILD-nya, relatif terhadap direktori tingkat teratas dari repositori yang berisi. Contoh: my/app.

Pada tingkat teknis, Bazel menerapkan hal berikut:

• Karakter yang diizinkan dalam nama paket adalah huruf kecil a hingga z, huruf besar A hingga Z, angka 0 hingga 9, karakter ! \"#$%&'()*+,-.;<=>?@[]^_`{|} (ya, ada karakter spasi di sana!), dan tentu saja garis miring / (karena merupakan pemisah direktori).
• Nama paket tidak boleh diawali atau diakhiri dengan karakter garis miring /.
• Nama paket tidak boleh berisi substring //. Hal ini tidak masuk akal---apa jalur direktori yang sesuai?
• Nama paket tidak boleh berisi substring /./ atau /../ atau /.../, dll. Penegakan ini dilakukan untuk menghindari kebingungan saat menerjemahkan antara nama paket logis dan nama direktori fisik, mengingat makna semantik karakter titik dalam string jalur.

Pada tingkat praktis:

• Untuk bahasa dengan struktur direktori yang signifikan bagi sistem modulnya (misalnya, Java), Anda harus memilih nama direktori yang merupakan ID yang valid dalam bahasa tersebut. Misalnya, jangan memulai dengan angka di depan dan hindari karakter khusus, terutama garis bawah dan tanda hubung.
• Meskipun Bazel mendukung target dalam paket root ruang kerja (misalnya, //:foo), sebaiknya biarkan paket tersebut kosong agar semua paket yang bermakna memiliki nama deskriptif.

Aturan

Aturan menentukan hubungan antara input dan output, serta langkah-langkah untuk membuat output. Aturan dapat berupa salah satu dari berbagai jenis (terkadang disebut kelas aturan), yang menghasilkan file yang dapat dieksekusi dan library yang dikompilasi, file yang dapat dieksekusi untuk pengujian, dan output lain yang didukung seperti yang dijelaskan dalam Ensiklopedia Build.

File BUILD mendeklarasikan target dengan memanggil aturan.

Pada contoh di bawah, kita melihat deklarasi target my_app 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 setiap atribut adalah fungsi dari jenis aturan; lihat Build Encyclopedia untuk mengetahui daftar aturan dan atribut yang sesuai. Setiap atribut memiliki nama dan jenis. Beberapa jenis umum yang dapat dimiliki atribut adalah bilangan bulat, label, list of labels, string, list of string, label output, list of label output. Tidak semua atribut harus ditentukan dalam setiap aturan. Dengan demikian, atribut membentuk kamus dari kunci (nama) ke nilai yang diketik opsional.

Atribut srcs yang ada di banyak aturan memiliki jenis "daftar label"; 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 arbitrer, dan yang lebih menarik adalah nama file yang dihasilkan oleh aturan, dan hal ini berlaku untuk genrules. Untuk mengetahui informasi selengkapnya, lihat Aturan Umum: genrule.

Dalam kasus lain, nama tersebut penting: untuk aturan *_binary dan *_test, misalnya, nama aturan menentukan nama yang dapat dieksekusi yang dihasilkan oleh build.

Directed acyclic graph di atas target ini disebut grafik target atau grafik dependensi build, dan merupakan domain tempat alat Kueri Bazel beroperasi.