Panduan gaya .bzl

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

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

Starlark adalah bahasa yang menentukan bagaimana perangkat lunak dibangun, dan karena itu merupakan pemrograman dan bahasa konfigurasi.

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

Semua perangkat lunak lebih sering dibaca daripada yang ditulisnya. Hal ini terutama berlaku untuk Starlark, saat para engineer membaca file BUILD untuk memahami dependensi target dan detail build mereka. Pembacaan ini akan sering terjadi secara sepintas, terburu-buru, atau secara paralel menyelesaikan beberapa tugas lain. Oleh karena itu, kesederhanaan dan keterbacaan sangat penting sehingga pengguna dapat mengurai dan memahami file BUILD dengan cepat.

Saat pengguna membuka file BUILD, mereka ingin segera mengetahui daftar target di file; atau meninjau daftar sumber dari {i>library<i} C++ tersebut; atau menghapus dependensi dari biner Java tersebut. Setiap kali menambahkan lapisan abstraksi, Anda mempersulit pengguna untuk melakukan tugas-tugas ini.

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

Penting: Jangan buat variabel atau makro hanya untuk menghindari beberapa pengulangan dalam file BUILD. File BUILD Anda harus mudah dibaca oleh {i>developer<i} dan {i>tool<i}. Tujuan Prinsip DRY tidak benar-benar berlaku di sini.

Saran umum

• Menggunakan Buildifier sebagai pemformat dan linter.
• Ikuti panduan pengujian.

Gaya

Gaya Python

Jika ragu, ikuti Panduan gaya PEP 8 jika memungkinkan. Secara khusus, gunakan empat, bukan dua spasi, untuk indentasi guna mengikuti Konvensi Python.

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

{i>Docstring<i}

File dan fungsi dokumen menggunakan docstring. Gunakan docstring di bagian atas setiap file .bzl, dan docstring untuk setiap publik .

Mendokumentasikan aturan dan aspek

Aturan dan aspek, beserta atributnya, serta penyedia dan kolom, 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 memaksa bahwa nilai pribadi tidak dapat digunakan dari file lain. Variabel lokal tidak boleh gunakan awalan garis bawah.

Panjang baris

Seperti dalam file BUILD, tidak ada batas panjang baris yang ketat karena label dapat panjang. Jika memungkinkan, cobalah untuk menggunakan paling banyak 79 karakter per baris (mengikuti metode panduan gaya, PEP 8). Panduan ini tidak boleh diterapkan secara ketat: editor harus menampilkan lebih dari 80 kolom, perubahan otomatis akan menimbulkan garis yang lebih panjang, dan manusia seharusnya tidak menghabiskan waktu memisahkan baris yang sudah bisa dibaca.

Argumen kata kunci

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

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 (daripada 1 dan 0) untuk nilai boolean (misalnya saat menggunakan atribut boolean dalam aturan).

Menggunakan versi cetak hanya untuk proses debug

Jangan gunakan fungsi print() dalam kode produksi; aplikasi ini hanya ditujukan untuk proses debug, dan akan mengirim spam ke semua pengguna langsung dan tidak langsung file .bzl Anda. Tujuan satu-satunya pengecualian adalah Anda boleh mengirimkan kode yang menggunakan print() jika dinonaktifkan jika tidak diubah dan hanya dapat diaktifkan dengan mengedit sumber -- misalnya, jika semua penggunaan print() dilindungi oleh if DEBUG: saat DEBUG di-hardcode untuk False. Perhatikan apakah pernyataan-pernyataan ini cukup berguna untuk membenarkan dampaknya terhadap keterbacaan.

Makro

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

Karena itu, ketika terjadi kesalahan, 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. Akhirnya, aspek tidak mengetahui makro, jadi alat tergantung pada berbagai aspek (IDE dan lainnya) mungkin gagal.

Penggunaan yang aman untuk makro adalah untuk menentukan target tambahan yang dimaksudkan untuk yang direferensikan langsung di Bazel CLI atau file BUILD: Dalam hal ini, hanya pengguna akhir target tersebut perlu mengetahui tentang mereka, dan 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 tergantung pada target tidak dibuat instance-nya oleh makro tersebut), ikuti praktik terbaik berikut:

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

Insinyur sering menulis makro ketika API Starlark dari aturan yang relevan tidak memadai untuk kasus penggunaan spesifiknya, terlepas dari apakah aturan tersebut didefinisikan dalam Bazel dalam kode native, atau dalam Starlark. Jika Anda menghadapi masalah, tanyakan kepada pembuat aturan apakah mereka dapat memperluas API untuk menyelesaikan tujuan tersebut.

Sebagai aturan praktis, semakin banyak makro yang menyerupai aturan, semakin baik.

Lihat juga makro.

Aturan

• Aturan, aspek, dan atributnya harus menggunakan nama yang berhuruf kecil ("snake kasus").
• Nama aturan adalah kata benda yang menggambarkan jenis artefak utama yang dihasilkan oleh dari sudut pandang dependensinya (atau untuk aturan leaf, tertentu). Hal ini belum tentu berupa akhiran file. Misalnya, aturan yang menghasilkan artefak C++ yang dimaksudkan untuk digunakan sebagai ekstensi Python py_extension. Untuk sebagian besar bahasa, aturan umumnya mencakup:
  • *_library - unit kompilasi atau "modul".
  • *_binary - target yang menghasilkan unit deployment atau yang dapat dieksekusi.
  • *_test - target pengujian. Pengujian ini dapat mencakup beberapa pengujian. Tunggu semua pengujian di target *_test menjadi variasi dari tema yang sama, untuk contoh, menguji satu library.
  • *_import: target yang merangkum artefak yang telah dikompilasi sebelumnya, seperti .jar, atau .dll yang digunakan selama kompilasi.
• Gunakan nama dan jenis yang konsisten untuk atribut. Beberapa persyaratan umum atribut tersebut meliputi:
  • srcs: label_list, mengizinkan file: file sumber, biasanya ditulis manusia.
  • deps: label_list, biasanya tidak mengizinkan file: kompilasi dependensi.
  • data: label_list, mengizinkan file: file data, seperti data pengujian, dll.
  • runtime_deps: label_list: dependensi runtime yang tidak diperlukan untuk kompilasi.
• Untuk setiap atribut dengan perilaku yang tidak jelas (misalnya, template string dengan substitusi khusus, atau alat yang dipanggil dengan persyaratan), berikan dokumentasi menggunakan argumen kata kunci doc ke deklarasi atribut (attr.label_list() atau yang serupa).
• Fungsi penerapan aturan harus hampir selalu berupa fungsi pribadi (dinamai dengan garis bawah di awal). Gaya yang umum adalah memberikan fungsi implementasi untuk myrule bernama _myrule_impl.
• Meneruskan informasi di antara aturan Anda menggunakan provider. Deklarasikan dan dokumentasikan penyedia kolom.
• Rancang aturan Anda dengan mempertimbangkan ekstensibilitas. Pertimbangkan bahwa aturan lain mungkin ingin berinteraksi dengan aturan, mengakses penyedia, dan menggunakan kembali tindakan yang Anda buat.
• Ikuti panduan performa pada aturan Anda.