Bagian sebelumnya menjelaskan paket, target dan label, serta grafik dependensi build secara abstrak. Bagian ini menjelaskan sintaksis konkret yang digunakan untuk menentukan paket.
Menurut definisi, setiap paket berisi file BUILD
, yang merupakan program
singkat. File BUILD
dievaluasi menggunakan bahasa imperatif,
Starlark.
Mereka ditafsirkan sebagai daftar pernyataan yang berurutan.
Secara umum, urutan itu penting: misalnya, variabel harus ditentukan sebelum digunakan. Namun, sebagian besar file BUILD
hanya terdiri dari deklarasi
aturan build, dan urutan relatif pernyataan ini tidaklah penting; yang
penting adalah aturan mana yang dideklarasikan, dan dengan nilai apa, saat evaluasi paket selesai.
Saat fungsi aturan build, seperti cc_library
, dieksekusi, target baru akan dibuat dalam grafik. Target ini nantinya dapat dirujuk menggunakan label.
Dalam file BUILD
sederhana, deklarasi aturan dapat diatur ulang secara bebas tanpa
mengubah perilaku.
Untuk mendorong pemisahan yang jelas antara kode dan data, file BUILD
tidak boleh berisi definisi fungsi, pernyataan for
, atau pernyataan if
(tetapi pemahaman daftar dan ekspresi if
diizinkan). Sebagai gantinya, fungsi dapat dideklarasikan dalam
file .bzl
. Selain itu, argumen *args
dan **kwargs
tidak
diizinkan dalam file BUILD
. Sebagai gantinya, cantumkan semua argumen secara eksplisit.
Yang terpenting, program di Starlark tidak dapat menjalankan I/O arbitrer. Invarian ini
membuat interpretasi file BUILD
menjadi hermetik — hanya bergantung pada sekumpulan
input yang diketahui, yang penting untuk memastikan bahwa build dapat direproduksi.
Untuk mengetahui detail selengkapnya, lihat Hermetisitas.
File BUILD
harus ditulis hanya menggunakan karakter ASCII, meskipun
secara teknis file tersebut akan ditafsirkan menggunakan himpunan karakter Latin-1.
Karena BUILD
file perlu diperbarui setiap kali dependensi
perubahan kode yang mendasarinya, file tersebut biasanya dikelola oleh beberapa orang dalam
satu tim. Penulis file BUILD
harus memberikan komentar secara bebas untuk mendokumentasikan peran
setiap target build, baik dimaksudkan untuk penggunaan publik maupun tidak, dan untuk
mendokumentasikan peran paket itu sendiri.
Memuat ekstensi
Ekstensi Bazel adalah file yang berakhiran .bzl
. Gunakan pernyataan load
untuk mengimpor simbol dari ekstensi.
load("//foo/bar:file.bzl", "some_library")
Kode ini memuat file foo/bar/file.bzl
dan menambahkan simbol some_library
ke lingkungan. Dapat digunakan untuk memuat aturan, fungsi, atau konstanta baru (misalnya, string atau daftar). Beberapa simbol dapat diimpor menggunakan
argumen tambahan ke panggilan ke load
. Argumen harus berupa literal string (tanpa variabel) dan pernyataan load
harus muncul di tingkat teratas — tidak boleh berupa isi fungsi.
Argumen pertama load
adalah label yang mengidentifikasi
file .bzl
. Jika merupakan label relatif, masalah ini akan diselesaikan sesuai dengan
paket (bukan direktori) yang berisi file bzl
saat ini. Label relatif dalam
pernyataan load
harus menggunakan :
di awal.
load
juga mendukung alias, sehingga Anda dapat menetapkan nama yang berbeda ke
simbol yang diimpor.
load("//foo/bar:file.bzl", library_alias = "some_library")
Anda dapat menentukan beberapa alias dalam satu pernyataan load
. Selain itu, daftar argumen dapat berisi alias dan nama simbol reguler. Contoh
berikut ini sah secara hukum (harap perhatikan kapan harus menggunakan tanda kutip).
load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
Dalam file .bzl
, simbol yang dimulai dengan _
tidak diekspor dan tidak dapat
dimuat dari file lain.
Anda dapat menggunakan visibilitas pemuatan untuk membatasi
siapa saja yang dapat memuat file .bzl
.
Jenis aturan build
Sebagian besar aturan build berasal dari kelompok, yang dikelompokkan menurut bahasa. Misalnya, cc_binary
, cc_library
,
dan cc_test
adalah aturan build untuk masing-masing biner, library, dan pengujian C++. Bahasa lain menggunakan skema penamaan
yang sama, dengan awalan yang berbeda, seperti java_*
untuk
Java. Beberapa fungsi ini didokumentasikan dalam Ensiklopedia Build, tetapi siapa pun dapat membuat aturan baru.
Aturan
*_binary
mem-build program yang dapat dieksekusi dalam bahasa tertentu. Setelah di-build, file yang dapat dieksekusi akan berada di hierarki output biner alat build dengan nama yang sesuai untuk label aturan, sehingga//my:program
akan muncul di (misalnya)$(BINDIR)/my/program
.Dalam beberapa bahasa, aturan tersebut juga membuat direktori runfile yang berisi semua file yang disebutkan dalam atribut
data
yang termasuk dalam aturan tersebut, atau aturan apa pun dalam penutupan transitif dependensinya; kumpulan file ini dikumpulkan di satu tempat untuk memudahkan deployment ke produksi.Aturan
*_test
adalah spesialisasi dari aturan*_binary
, yang digunakan untuk pengujian otomatis. Tes hanyalah program yang menghasilkan nol untuk keberhasilan.Seperti biner, pengujian juga memiliki hierarki runfile, dan file di bawahnya adalah satu-satunya file yang dapat dibuka secara sah oleh pengujian saat runtime. Misalnya, program
cc_test(name='x', data=['//foo:bar'])
dapat membuka dan membaca$TEST_SRCDIR/workspace/foo/bar
selama eksekusi. (Setiap bahasa pemrograman memiliki fungsi utilitasnya sendiri untuk mengakses nilai$TEST_SRCDIR
, tetapi semuanya setara dengan menggunakan variabel lingkungan secara langsung.) Ketidakpatuhan terhadap aturan akan menyebabkan pengujian gagal saat dijalankan pada host pengujian jarak jauh.Aturan
*_library
menentukan modul yang dikompilasi secara terpisah dalam bahasa pemrograman tertentu. Library dapat bergantung pada library lain, dan biner serta pengujian dapat bergantung pada library, dengan perilaku kompilasi terpisah yang diharapkan.
Label | Dependensi |