Label

Laporkan masalah Lihat sumber

Label adalah ID untuk target. Label umum dalam bentuk kanonis lengkapnya akan terlihat seperti ini:

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

Bagian pertama label adalah nama repositori, @@myrepo. Sintaksis@ ganda menandakan bahwa ini adalah nama repo kanonis, yang unik di dalam ruang kerja. Label dengan nama repo kanonis secara jelas mengidentifikasi target, terlepas dari konteks kemunculannya.

Sering kali nama repo kanonis adalah string aneh yang terlihat seperti @@rules_java~7.1.0~toolchains~local_jdk. Hal yang jauh lebih umum terlihat adalah label dengan nama repo apparent, yang terlihat seperti:

@myrepo//my/app/main:app_binary

Satu-satunya perbedaan adalah nama repo yang diawali dengan satu @, bukan dua. Ini mengacu pada repositori dengan nama jelas myrepo, yang dapat berbeda berdasarkan konteks tempat label ini muncul.

Dalam kasus umum, jika label merujuk ke repositori yang sama 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 ini adalah nama paket yang tidak memenuhi syarat my/app/main, yaitu jalur ke paket yang relatif terhadap root repositori. Bersama-sama, nama repositori dan nama paket yang tidak memenuhi syarat akan membentuk nama paket yang sepenuhnya memenuhi syarat @@myrepo//my/app/main. Jika label merujuk ke paket yang sama dengan yang digunakannya, nama paket (dan jika perlu, tanda titik dua) dapat dihilangkan. Jadi, di dalam @@myrepo//my/app/main, label ini dapat ditulis dengan salah satu cara berikut:

app_binary
:app_binary

Sudah menjadi kebiasaan bahwa titik dua dihilangkan untuk file, tetapi dipertahankan untuk aturan, tetapi tidak signifikan.

Bagian label setelah tanda titik dua, app_binary adalah nama target yang tidak memenuhi syarat. Jika cocok dengan komponen terakhir jalur paket, parameter ini, 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 terkait dengan 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 yang digunakan: saat Bazel mengharapkan label, artinya //my/app:app dan @@some_repo//my/app:app. Namun, saat Bazel mengharapkan paket (misalnya dalam spesifikasi package_group), Bazel akan merujuk ke paket yang berisi label tersebut.

Kesalahan umum dalam file BUILD adalah menggunakan //my/app untuk merujuk ke sebuah paket, atau ke semua target dalam sebuah paket--bukan demikian. Ingat, fungsi ini setara dengan //my/app:app sehingga nama target app dalam paket my/app repositori saat ini diberikan.

Namun, penggunaan //my/app untuk merujuk ke paket dianjurkan dalam spesifikasi package_group atau dalam file .bzl, karena dengan jelas mengomunikasikan 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 hal ini. Misalnya, jika hierarki sumber berisi paket my/app dan paket my/app/testdata (masing-masing dari kedua direktori ini memiliki file BUILD sendiri), paket yang 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, 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 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 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 untuk merujuk target, lihat pola target.

Spesifikasi leksikal dari suatu label

Sintaksis label tidak menyarankan penggunaan karakter meta yang memiliki arti khusus pada shell. Hal ini membantu menghindari masalah kutipan yang tidak disengaja, dan mempermudah pembuatan alat dan skrip yang memanipulasi label, seperti Bahasa Kueri Bazel.

Detail persis dari nama target yang diizinkan ada di bawah ini.

Nama target — package-name:target-name

target-name adalah nama target dalam paket. Nama aturan adalah nilai atribut name pada deklarasi aturan di file BUILD; nama file adalah nama jalurnya sesuai dengan direktori yang memuat file BUILD.

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

Nama file harus berupa nama jalur relatif dalam bentuk normal, yang berarti nama tersebut 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 menggunakan / dalam nama target file adalah hal yang umum, hindari penggunaan / dalam nama aturan. Penggunaan bentuk singkat dari label mungkin membingungkan pembaca. Label //foo/bar/wiz selalu merupakan singkatan untuk //foo/bar/wiz:wiz, meskipun tidak ada paket seperti itu foo/bar/wiz; label tidak pernah merujuk ke //foo:bar/wiz, meskipun target itu ada.

Namun, ada beberapa situasi di mana penggunaan garis miring terasa nyaman, 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, sesuai dengan direktori tingkat atas dari repositori yang memuatnya. Contoh: my/app.

Secara teknis, Bazel menerapkan hal berikut:

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

Secara praktis:

  • Untuk bahasa dengan struktur direktori yang signifikan bagi sistem modulnya (misalnya Java), pilih nama direktori yang merupakan ID yang valid dalam bahasa tersebut. Misalnya, jangan mulai dengan angka di depan dan hindari karakter khusus, terutama garis bawah dan tanda hubung.
  • Meskipun Bazel mendukung target di 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 banyak jenis yang berbeda (terkadang disebut class aturan), yang menghasilkan kompilasi file yang dapat dieksekusi dan library, pengujian yang dapat dieksekusi, dan output lain yang didukung seperti yang dijelaskan dalam Build Encyclopedia.

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 target name yang valid), yang mendeklarasikan target dalam paket file BUILD.

Setiap aturan memiliki kumpulan atribut; atribut yang berlaku untuk aturan tertentu, serta signifikansi dan semantik setiap atribut merupakan fungsi dari jenis aturan tersebut. Baca 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) hingga nilai opsional yang diketik.

Atribut srcs yang ada di banyak aturan memiliki jenis "daftar label"; nilainya, jika ada, berupa daftar label, masing-masing berupa nama target yang merupakan input untuk aturan ini.

Dalam beberapa kasus, nama jenis aturan agak arbitrer, dan yang lebih menarik adalah nama file yang dihasilkan oleh aturan tersebut, dan ini juga berlaku untuk genrules. Untuk mengetahui informasi lebih lanjut, lihat General Rules: genrule.

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

Grafik asiklik terarah pada target ini disebut grafik target atau grafik dependensi build, dan merupakan domain tempat alat Kueri Bazel beroperasi.

Target BANGUN file