Halaman ini membahas pedoman gaya dasar untuk Starlark dan juga menyertakan informasi tentang makro dan aturan.
Starlark adalah bahasa yang menentukan cara software dibuat, dan karenanya merupakan bahasa pemrograman dan konfigurasi.
Anda akan menggunakan Starlark untuk menulis file BUILD
, makro, dan aturan build. Makro dan
aturan pada dasarnya adalah bahasa meta yang menentukan cara penulisan file BUILD
.
File BUILD
dibuat sederhana dan berulang.
Semua perangkat lunak lebih sering dibaca daripada ditulis. Hal ini terutama berlaku untuk
Starlark, karena engineer membaca file BUILD
untuk memahami dependensi
target dan detail build mereka. Pembacaan ini sering kali dilakukan secara sepintas, terburu-buru, atau bersamaan dengan menyelesaikan beberapa tugas lain. Oleh karena itu,
kesederhanaan dan keterbacaan sangat penting agar pengguna dapat mengurai dan
memahami file BUILD
dengan cepat.
Saat membuka file BUILD
, pengguna akan segera ingin mengetahui daftar target dalam
file; atau meninjau daftar sumber library C++ tersebut; atau menghapus
dependensi dari biner Java tersebut. Setiap kali Anda menambahkan lapisan abstraksi, Anda
akan mempersulit pengguna untuk melakukan tugas ini.
File BUILD
juga dianalisis dan diperbarui oleh berbagai alat. Alat mungkin tidak
dapat mengedit file BUILD
jika menggunakan abstraksi. Menjaga agar file BUILD
tetap sederhana akan memungkinkan Anda mendapatkan alat yang lebih baik. Seiring berkembangnya code base, perubahan di banyak file BUILD
akan semakin sering dilakukan untuk
mengupdate library atau melakukan pembersihan.
Saran umum
- Gunakan 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 untuk mengikuti ketentuan Python.
Karena
Starlark bukan Python,
beberapa aspek gaya Python tidak berlaku. Misalnya, PEP 8 menyarankan agar
perbandingan dengan singleton dilakukan dengan is
, yang bukan merupakan operator di
Starlark.
Dokumen
Dokumentasikan file dan fungsi menggunakan docstring.
Gunakan docstring di bagian atas setiap file .bzl
, dan docstring untuk setiap fungsi publik.
Mendokumentasikan aturan dan aspek
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 dengan garis bawah (
[a-z][a-z0-9_]*
), seperticc_library
. - Nilai pribadi tingkat atas diawali dengan satu garis bawah. Bazel memberlakukan bahwa nilai pribadi tidak dapat digunakan dari file lain. Variabel lokal tidak boleh menggunakan awalan garis bawah.
Panjang baris
Seperti dalam 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). Pedoman ini
tidak boleh diberlakukan secara ketat: editor harus menampilkan lebih dari 80 kolom,
perubahan otomatis akan sering memunculkan 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 disarankan:
def fct(name, srcs):
filtered_srcs = my_filter(source = srcs)
native.cc_library(
name = name,
srcs = filtered_srcs,
testonly = True,
)
Nilai boolean
Memilih nilai True
dan False
(bukan 1
dan 0
) untuk nilai boolean (seperti saat menggunakan atribut boolean dalam aturan).
Hanya gunakan media cetak untuk proses debug
Jangan gunakan fungsi print()
dalam kode produksi; 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:
tempat 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.
Oleh karena itu, saat terjadi masalah, pengguna harus memahami
penerapan 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 akan gagal.
Penggunaan yang aman untuk makro adalah untuk menentukan target tambahan yang dimaksudkan untuk direferensikan langsung di Bazel CLI atau di file BUILD: Dalam hal ini, hanya pengguna akhir target tersebut yang perlu mengetahuinya, dan masalah build apa pun yang diperkenalkan oleh makro tidak pernah jauh dari penggunaannya.
Untuk makro yang menentukan target yang dihasilkan (detail implementasi makro yang tidak seharusnya dirujuk pada CLI atau bergantung pada target yang tidak dibuat instance-nya 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:
- Namanya diawali dengan
<name>
atau_<name>
. Misalnya, menggunakanname = '%s_bar' % (name)
. - Memiliki visibilitas terbatas (
//visibility:private
), dan - Memiliki tag
manual
untuk menghindari perluasan pada target karakter pengganti (:all
,...
,:*
, dll.).
- Namanya diawali dengan
name
hanya boleh digunakan untuk memperoleh nama target yang ditentukan oleh makro, dan bukan untuk hal lainnya. Misalnya, jangan gunakan nama untuk memperoleh file input atau dependensi yang tidak dihasilkan oleh makro itu sendiri.- Semua target yang dibuat dalam makro harus digabungkan dengan target utama.
- Pastikan nama parameter dalam makro konsisten. Jika parameter diteruskan
sebagai nilai atribut ke target utama, biarkan namanya tetap sama. Jika parameter makro
memiliki tujuan yang sama seperti atribut aturan umum, misalnya
deps
, beri nama seperti yang Anda lakukan untuk atribut tersebut (lihat di bawah). - Saat memanggil makro, gunakan hanya argumen kata kunci. Hal ini konsisten dengan aturan, dan sangat meningkatkan keterbacaan.
Engineer sering menulis makro saat Starlark API dari aturan yang relevan tidak memadai untuk kasus penggunaan spesifik mereka, terlepas dari apakah aturan tersebut 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.
Prinsipnya, semakin banyak makro yang menyerupai aturan, semakin baik.
Lihat juga makro.
Aturan
- Aturan, aspek, dan atributnya harus menggunakan nama huruf kecil ("snake case").
- Nama aturan adalah kata benda yang mendeskripsikan jenis artefak utama yang dihasilkan oleh
aturan, dari sudut pandang dependensinya (atau untuk aturan leaf, pengguna). Nilai ini belum tentu berupa akhiran file. Misalnya, aturan yang menghasilkan artefak C++ yang dimaksudkan untuk digunakan sebagai ekstensi Python mungkin disebut
py_extension
. Untuk sebagian besar bahasa, aturan umumnya meliputi:*_library
- unit kompilasi atau "modul".*_binary
- target yang menghasilkan unit deployment atau file yang dapat dieksekusi.*_test
- target pengujian. Ini dapat mencakup beberapa pengujian. Semua pengujian dalam target*_test
diperkirakan akan berupa 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 umumnya berlaku
meliputi:
srcs
:label_list
, yang mengizinkan file: file sumber, biasanya dibuat oleh manusia.deps
:label_list
, biasanya tidak mengizinkan file: dependensi kompilasi.data
:label_list
, mengizinkan file: file data, seperti data pengujian, dll.runtime_deps
:label_list
: dependensi runtime yang tidak diperlukan untuk kompilasi.
- Untuk atribut apa pun dengan 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 yang serupa). - Fungsi implementasi aturan harus hampir selalu berupa fungsi pribadi (diberi nama dengan garis bawah di depan). Gaya yang umum adalah memberikan
fungsi implementasi untuk
myrule
nama_myrule_impl
. - Teruskan informasi antara aturan Anda menggunakan antarmuka penyedia yang ditetapkan dengan baik. Deklarasikan dan dokumentasikan kolom penyedia.
- Rancang aturan Anda dengan mempertimbangkan ekstensibilitas. Pertimbangkan bahwa aturan lain mungkin ingin berinteraksi dengan aturan Anda, mengakses penyedia Anda, dan menggunakan kembali tindakan yang Anda buat.
- Ikuti pedoman performa dalam aturan Anda.