BazelCon 2022 akan hadir pada 16-17 November ke New York dan online.
Daftar sekarang.

File BUILD

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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.

Keduanya ditafsirkan sebagai daftar pernyataan berurutan.

Secara umum, urutan bersifat 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; semua hal yang penting adalah aturan mana yang dideklarasikan, dan beserta nilainya, saat evaluasi paket waktu selesai.

Saat fungsi aturan build, seperti cc_library, dijalankan, target baru dalam grafik akan dibuat. 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 jelas antara kode dan data, file BUILD tidak boleh berisi definisi fungsi, pernyataan for atau pernyataan if (tetapi pemahaman daftar dan ekspresi if diizinkan) Domain . Fungsi dapat dideklarasikan dalam file .bzl. Selain itu, argumen *args dan **kwargs tidak diizinkan dalam file BUILD; sebagai gantinya cantumkan semua argumen secara eksplisit.

Sangat penting, program di Starlark tidak dapat menjalankan I/O arbitrer. Invarian ini membuat interpretasi file BUILD menjadi hermetic, bergantung hanya pada set input yang diketahui, yang penting untuk memastikan bahwa build dapat direproduksi. Untuk detail selengkapnya, lihat Hermeticity.

File BUILD seharusnya hanya ditulis menggunakan karakter ASCII, meskipun secara teknis dapat ditafsirkan menggunakan himpunan karakter Latin-1.

Karena file BUILD perlu diupdate setiap kali dependensi kode dasar berubah, file tersebut biasanya dikelola oleh beberapa orang dalam tim. Penulis file BUILD harus memberikan komentar secara liberal untuk mendokumentasikan peran setiap target build, baik ditujukan untuk penggunaan publik atau 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 menggunakan argumen tambahan untuk panggilan ke load. Argumen harus berupa literal string (tanpa variabel) dan pernyataan load harus muncul di tingkat atas, dan tidak boleh berada dalam isi fungsi.

Argumen pertama load adalah label yang mengidentifikasi file .bzl. Jika merupakan label relatif, ini harus diselesaikan sehubungan dengan paket (bukan direktori) yang berisi file bzl saat ini. Label relatif dalam pernyataan load harus menggunakan : di awal.

load juga mendukung alias, karena itu, Anda dapat menetapkan nama 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 sangatlah legal (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 akan diekspor dan tidak dapat dimuat dari file lain. Visibilitas belum memengaruhi pemuatan (belum): Anda tidak perlu menggunakan exports_files untuk membuat file .bzl terlihat.

Jenis aturan build

Sebagian besar aturan build terdiri dari keluarga, 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 Build Encyclopedia, tetapi siapa saja dapat membuat aturan baru.

  • Aturan *_binary membuat program yang dapat dieksekusi dalam bahasa tertentu. Setelah build, file executable akan berada di hierarki output biner alat build pada nama yang sesuai untuk label aturan, sehingga //my:program akan muncul pada (misalnya) $(BINDIR)/my/program.

    Dalam beberapa bahasa, aturan tersebut juga membuat direktori runfiles yang berisi semua file yang disebutkan dalam atribut data milik aturan tersebut, atau aturan apa pun dalam lampiran transitif dependensinya; kumpulan file ini dikumpulkan di satu tempat untuk kemudahan deployment ke produksi.

  • Aturan *_test adalah spesialisasi aturan *_binary yang digunakan untuk pengujian otomatis. Pengujian adalah program yang tidak mengembalikan keberhasilan.

    Seperti biner, pengujian juga memiliki hierarki runfiles, dan file di bawahnya adalah satu-satunya file yang dapat dibuka secara sah pada 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 sama dengan menggunakan variabel lingkungan secara langsung.) Jika aturan tidak diamati, pengujian akan gagal saat dijalankan pada host pengujian jarak jauh.

  • Aturan *_library menentukan modul yang dikompilasi secara terpisah dalam bahasa pemrograman yang diberikan. Library dapat bergantung pada library lain, serta biner dan pengujian dapat bergantung pada library, dengan perilaku kompilasi terpisah yang diharapkan.

Label Dependensi