BUILD file

Bagian sebelumnya menjelaskan paket, target, dan label, serta grafik dependensi build secara abstrak. Bagian ini menjelaskan sintaksis konkret yang digunakan untuk menentukan paket.

Secara definisi, setiap paket berisi file BUILD, yang merupakan program singkat.

File BUILD dievaluasi menggunakan bahasa imperatif, Starlark.

Fungsi ini ditafsirkan sebagai daftar pernyataan berurutan.

Secara umum, urutan memang penting: misalnya, variabel harus ditentukan sebelum digunakan. Namun, sebagian besar file BUILD hanya terdiri dari deklarasi aturan build, dan urutan relatif pernyataan ini tidak penting; yang penting adalah aturan mana yang dideklarasikan, dan dengan nilai apa, pada saat evaluasi paket selesai.

Saat fungsi aturan build, seperti cc_library, dijalankan, fungsi tersebut akan membuat target baru dalam grafik. Target ini nantinya dapat dirujuk menggunakan label.

Dalam file BUILD sederhana, deklarasi aturan dapat diurutkan ulang secara bebas tanpa mengubah perilaku.

Untuk mendorong pemisahan yang bersih 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 melakukan I/O arbitrer. Invarian ini membuat interpretasi file BUILD hermetis — hanya bergantung pada kumpulan input yang diketahui, yang penting untuk memastikan bahwa build dapat direproduksi. Untuk mengetahui detail selengkapnya, lihat Hermetisitas.

Karena file BUILD perlu diperbarui setiap kali dependensi kode yang mendasarinya berubah, file tersebut biasanya dikelola oleh beberapa orang dalam tim. Penulis file BUILD harus memberikan komentar secara bebas untuk mendokumentasikan peran setiap target build, baik ditujukan 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. Ini dapat digunakan untuk memuat aturan, fungsi, atau konstanta baru (misalnya, string atau daftar). Beberapa simbol dapat diimpor dengan menggunakan argumen tambahan ke panggilan ke load. Argumen harus berupa literal string (tanpa variabel) dan pernyataan load harus muncul di tingkat atas — tidak boleh ada dalam isi fungsi.

Argumen pertama load adalah label yang mengidentifikasi file .bzl. Jika merupakan label relatif, label akan di-resolve sehubungan 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 sepenuhnya sah (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 yang dapat memuat file .bzl.

Jenis aturan build

Sebagian besar aturan build berasal dari grup, yang dikelompokkan berdasarkan bahasa. Misalnya, cc_binary, cc_library, dan cc_test adalah aturan build untuk 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 saja dapat membuat aturan baru.

• Aturan *_binary mem-build program yang dapat dieksekusi dalam bahasa tertentu. Setelah 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, atau aturan apa pun dalam penutupan dependensi transitifnya; kumpulan file ini dikumpulkan bersama di satu tempat untuk memudahkan deployment ke produksi.

• Aturan *_test adalah spesialisasi dari aturan *_binary, yang digunakan untuk pengujian otomatis. Pengujian hanyalah program yang menampilkan nol jika berhasil.

  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.) Kegagalan untuk mematuhi aturan akan menyebabkan pengujian gagal saat dijalankan di 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.

Encoding file

File BUILD dan .bzl harus dienkode dalam UTF-8, dengan ASCII sebagai subset yang valid. Urutan byte arbitrer saat ini diizinkan, tetapi mungkin berhenti didukung pada masa mendatang.