BUILD file

Laporkan masalah Lihat sumber Per Malam · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Bagian sebelumnya menjelaskan paket, target dan label, serta membangun grafik dependensi secara abstrak. Bagian ini menjelaskan {i>syntax<i} konkret digunakan untuk menentukan paket.

Menurut definisi, setiap paket berisi file BUILD, yang merupakan program ini. BUILD file dievaluasi menggunakan bahasa imperatif, Starlark.

Mereka ditafsirkan sebagai daftar pernyataan yang berurutan.

Secara umum, urutan itu penting: variabel harus didefinisikan terlebih dahulu digunakan, misalnya. Akan tetapi, sebagian besar file BUILD hanya terdiri dari deklarasi membangun aturan, dan urutan relatif pernyataan ini tidak penting; semua yang penting adalah aturan mana yang dideklarasikan, dan dengan nilai apa, evaluasi paket waktu selesai.

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

Dalam file BUILD sederhana, deklarasi aturan dapat diatur ulang secara bebas tanpa mengubah perilakunya.

Untuk mendorong pemisahan yang jelas antara kode dan data, file BUILD tidak dapat berisi definisi fungsi, pernyataan for, atau pernyataan if (tetapi cantumkan pemahaman dan ekspresi if diizinkan). Fungsi dapat dideklarasikan di .bzl file saja. Selain itu, argumen *args dan **kwargs tidak diizinkan di BUILD file; sebagai gantinya mencantumkan semua argumen secara eksplisit.

Yang terpenting, program di Starlark tidak dapat menjalankan I/O arbitrer. Invarian ini membuat interpretasi file BUILD bersifat hermetik — hanya bergantung pada yang penting untuk memastikan bahwa build dapat direproduksi. Untuk mengetahui detail selengkapnya, lihat Hermeticity.

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

Karena file BUILD perlu diupdate setiap kali dependensi perubahan kode yang mendasarinya, mereka biasanya dikelola oleh banyak orang di tim. BUILD penulis file harus memberikan komentar secara bebas untuk mendokumentasikan peran setiap target build, apakah itu dimaksudkan 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 suatu ekstensi.

load("//foo/bar:file.bzl", "some_library")

Kode ini memuat file foo/bar/file.bzl dan menambahkan simbol some_library terhadap lingkungan. Ini 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 (tidak ada variabel) dan pernyataan load harus muncul di tingkat teratas — keduanya tidak boleh dalam isi fungsi.

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

load juga mendukung alias. Oleh karena itu, 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 biasa. Hal berikut contoh 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 muat untuk membatasi yang dapat memuat file .bzl.

Jenis aturan build

Sebagian besar aturan build berasal dari kelompok, yang dikelompokkan menurut di bahasa target. Misalnya, cc_binary, cc_library dan cc_test adalah aturan build untuk biner C++, library, dan pengujian. Bahasa lain menggunakan metode skema penamaan baru, dengan awalan yang berbeda, seperti java_* untuk Java. Beberapa fungsi ini didokumentasikan dalam Buat Ensiklopedia, tetapi Anda dapat melakukannya bagi siapa saja untuk membuat aturan baru.

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

    Di beberapa bahasa, aturan seperti itu juga membuat direktori runfiles berisi semua file yang disebutkan dalam data yang termasuk dalam aturan, atau aturan apa pun dalam penutupan ketergantungan; kumpulan file ini dikumpulkan dalam satu tempat untuk memudahkan deployment ke produksi.

  • Aturan *_test adalah spesialisasi dari aturan *_binary, yang digunakan untuk aturan otomatis pengujian. 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 oleh tes 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 utilitas untuk yang mengakses nilai $TEST_SRCDIR, tetapi semuanya setara dengan menggunakan variabel lingkungan secara langsung.) Ketidakpatuhan terhadap aturan akan menyebabkan pengujian gagal saat dijalankan pada {i>host<i} pengujian jarak jauh.

  • Aturan *_library menentukan modul yang dikompilasi secara terpisah dalam yang berpusat pada data (data-centric). {i>Library<i} dapat bergantung pada {i>library<i} lain, biner, dan pengujian dapat bergantung pada library, dengan fungsi perilaku kompilasi terpisah.

Label Dependensi