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

Panduan gaya .bzl

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

Halaman ini mencakup panduan gaya dasar untuk Starlark dan juga mencakup informasi tentang makro dan aturan.

Starlark adalah bahasa yang menentukan cara software dibuat, dan karenanya merupakan pemrograman serta bahasa konfigurasi.

Anda akan menggunakan Starlark untuk menulis file BUILD, makro, dan aturan build. Makro dan aturan pada dasarnya adalah bahasa meta - keduanya menentukan cara file BUILD ditulis. File BUILD dimaksudkan agar sederhana dan berulang.

Semua software lebih sering dibaca daripada ditulis. Hal ini sangat berlaku untuk Starlark, karena engineer membaca file BUILD untuk memahami dependensi target dan detail build mereka. Bacaan ini sering kali terjadi secara mendadak, terburu-buru, atau bersamaan dengan menyelesaikan tugas lain. Akibatnya, kemudahan dan keterbacaan sangat penting agar pengguna dapat mengurai dan memahami file BUILD dengan cepat.

Saat membuka file BUILD, pengguna ingin mengetahui daftar target dalam file dengan cepat; atau meninjau daftar sumber library C++ tersebut; atau menghapus dependensi dari biner Java tersebut. Setiap kali menambahkan lapisan abstraksi, Anda akan mempersulit pengguna untuk melakukan tugas tersebut.

File BUILD juga dianalisis dan diperbarui oleh berbagai alat. Alat mungkin tidak dapat mengedit file BUILD jika menggunakan abstraksi. Dengan menyederhanakan file BUILD, Anda akan mendapatkan alat yang lebih baik. Seiring dengan berkembangnya code base, ini menjadi semakin sering melakukan perubahan di banyak file BUILD untuk memperbarui library atau melakukan pembersihan.

Saran umum

Gaya

Gaya Python

Jika ragu, ikuti panduan gaya PEP 8 jika memungkinkan. Secara khusus, gunakan empat alih-alih dua spasi untuk indentasi untuk mengikuti konvensi Python.

Karena Starlark bukan Python, beberapa aspek gaya Python tidak berlaku. Misalnya, PEP 8 menyarankan bahwa perbandingan dengan singleton dilakukan dengan is, yang bukan operator di Starlark.

String Dokumen

Mendokumentasikan file dan fungsi menggunakan docstrings. Gunakan docstring di bagian atas setiap file .bzl, dan docstring untuk setiap fungsi publik.

Aturan dan aspek dokumen

Aturan dan aspek, beserta atributnya, serta penyedia dan kolomnya, harus didokumentasikan menggunakan argumen doc.

Konvensi penamaan

  • Variabel dan nama fungsi menggunakan huruf kecil dengan kata-kata yang dipisahkan oleh garis bawah ([a-z][a-z0-9_]*), seperti cc_library.
  • Nilai pribadi tingkat teratas dimulai dengan satu garis bawah. Bazel menerapkan bahwa nilai pribadi tidak dapat digunakan dari file lain. Variabel lokal tidak boleh menggunakan prefiks garis bawah.

Panjang baris

Seperti pada file BUILD, tidak ada batas panjang baris yang ketat karena label dapat panjang. Jika memungkinkan, coba gunakan maksimal 79 karakter per baris (dengan mengikuti panduan gaya Python, PEP 8). Panduan ini tidak boleh diterapkan secara ketat: editor harus menampilkan lebih dari 80 kolom, perubahan otomatis akan sering menampilkan baris yang lebih panjang, dan manusia tidak boleh menghabiskan waktu untuk memisahkan baris yang sudah dapat dibaca.

Argumen kata kunci

Dalam argumen kata kunci, spasi di sekitar tanda sama dengan lebih disukai:

def fct(name, srcs):
    filtered_srcs = my_filter(source = srcs)
    native.cc_library(
        name = name,
        srcs = filtered_srcs,
        testonly = True,
    )

Nilai boolean

Lebih memilih nilai True dan False (bukan 1 dan 0) untuk nilai boolean (seperti saat menggunakan atribut boolean dalam aturan).

Jangan gunakan fungsi print() dalam kode produksi karena fungsi ini hanya dimaksudkan untuk proses debug, dan akan mengirim spam kepada semua pengguna langsung dan tidak langsung dari file .bzl Anda. Satu-satunya pengecualian adalah Anda dapat mengirimkan kode yang menggunakan print() jika dinonaktifkan secara default dan hanya dapat diaktifkan dengan mengedit sumber -- misalnya, jika semua penggunaan print() dilindungi oleh if DEBUG: di mana DEBUG di-hardcode ke False. Perhatikan apakah pernyataan ini cukup berguna untuk membenarkan dampaknya terhadap keterbacaan.

Makro

Makro adalah fungsi yang membuat instance satu atau beberapa aturan selama fase pemuatan. Secara umum, gunakan aturan jika memungkinkan, bukan makro. Grafik build yang dilihat oleh pengguna tidak sama dengan yang digunakan oleh Bazel selama build - makro diperluas sebelum Bazel melakukan analisis grafik build.

Karena itu, saat terjadi masalah, pengguna perlu memahami implementasi makro Anda untuk memecahkan masalah build. Selain itu, hasil bazel query mungkin sulit ditafsirkan karena target yang ditampilkan dalam hasil berasal dari perluasan makro. Terakhir, aspek tidak mengetahui makro, sehingga alat yang bergantung pada aspek (IDE dan lainnya) mungkin gagal.

Penggunaan makro yang aman adalah untuk menentukan target tambahan yang dirujuk secara langsung di Bazel CLI atau dalam file BUILD: Dalam hal ini, hanya pengguna akhir dari target tersebut yang perlu diketahui, dan setiap masalah build yang diperkenalkan oleh makro tidak pernah jauh dari penggunaannya.

Untuk makro yang menentukan target yang dihasilkan (detail penerapan makro yang tidak seharusnya dirujuk di CLI atau bergantung pada target yang tidak dipakai oleh makro tersebut), ikuti praktik terbaik berikut:

  • Makro harus mengambil argumen name dan menentukan target dengan nama tersebut. Target tersebut menjadi target utama makro tersebut.
  • Target yang dihasilkan, yaitu semua target lain yang ditentukan oleh makro, harus:
    • Memiliki nama yang diawali dengan <name> atau _<name>. Misalnya, menggunakan name = '%s_bar' % (name).
    • Memiliki visibilitas terbatas (//visibility:private), dan
    • Memiliki tag manual untuk menghindari perluasan target karakter pengganti (:all, ..., :*, dll.).
  • name hanya boleh digunakan untuk memperoleh nama target yang ditentukan oleh makro, dan bukan untuk hal lainnya. Misalnya, jangan gunakan nama untuk memperoleh dependensi atau file input yang tidak dihasilkan oleh makro itu sendiri.
  • Semua target yang dibuat di makro harus digabungkan dengan beberapa cara ke target utama.
  • Pertahankan nama parameter dalam makro agar konsisten. Jika parameter diteruskan sebagai nilai atribut ke target utama, pastikan namanya tetap sama. Jika parameter makro memiliki tujuan yang sama seperti atribut aturan umum, seperti deps, beri nama yang sama seperti atribut (lihat di bawah).
  • Saat memanggil makro, gunakan hanya argumen kata kunci. Hal ini konsisten dengan aturan, dan sangat meningkatkan keterbacaan.

Teknisi sering menulis makro saat Starlark API dari aturan yang relevan tidak memadai untuk kasus penggunaan khusus mereka, terlepas dari apakah aturan ditentukan dalam Bazel dalam kode native atau di Starlark. Jika Anda mengalami masalah ini, tanyakan kepada penulis aturan apakah mereka dapat memperluas API untuk mencapai sasaran Anda.

Sebagai pedoman umum, semakin banyak makro yang menyerupai aturan, semakin baik.

Lihat juga makro.

Aturan

  • Aturan, aspek, dan atributnya harus menggunakan nama huruf kecil ("kapitalisasi ular").
  • Nama aturan adalah kata benda yang mendeskripsikan jenis artefak utama yang dihasilkan oleh aturan, dari sudut pandang dependensinya (atau untuk aturan perincian, pengguna). Akhiran file belum tentu. Misalnya, aturan yang menghasilkan artefak C++ yang dimaksudkan untuk digunakan sebagai ekstensi Python dapat disebut py_extension. Untuk sebagian besar bahasa, aturan standar mencakup:
    • *_library - unit kompilasi atau "modul".
    • *_binary - target yang menghasilkan unit deployment atau deployment.
    • *_test - target pengujian. Pengujian ini dapat mencakup beberapa pengujian. Perkirakan semua pengujian dalam target *_test memiliki variasi pada tema yang sama, misalnya, menguji satu library.
    • *_import: target yang mengenkapsulasi artefak yang telah dikompilasi sebelumnya, seperti .jar, atau .dll yang digunakan selama kompilasi.
  • Gunakan nama dan jenis yang konsisten untuk atribut. Beberapa atribut yang berlaku umum mencakup:
    • srcs: label_list, yang mengizinkan file: file sumber, biasanya ditulis oleh manusia.
    • deps: label_list, biasanya tidak mengizinkan file: dependensi kompilasi.
    • data: label_list, yang mengizinkan file: file data, seperti data pengujian, dll.
    • runtime_deps: label_list: dependensi runtime yang tidak diperlukan untuk kompilasi.
  • Untuk atribut yang memiliki perilaku yang tidak jelas (misalnya, template string dengan substitusi khusus, atau alat yang dipanggil dengan persyaratan tertentu), berikan dokumentasi menggunakan argumen kata kunci doc ke deklarasi atribut (attr.label_list() atau serupa).
  • Fungsi penerapan aturan hampir selalu berupa fungsi pribadi (diberi nama dengan garis bawah di awal). Gaya yang umum adalah memberikan fungsi implementasi untuk myrule nama _myrule_impl.
  • Meneruskan informasi di antara aturan Anda menggunakan antarmuka provider yang didefinisikan dengan baik. Deklarasikan dan kolom penyedia dokumen.
  • Rancang aturan Anda dengan mempertimbangkan faktor perluasan. Pertimbangkan bahwa aturan lain mungkin ingin berinteraksi dengan aturan Anda, mengakses penyedia, dan menggunakan kembali tindakan yang Anda buat.
  • Ikuti panduan performa di aturan Anda.