Halaman ini membahas panduan gaya dasar untuk Starlark dan juga mencakup informasi tentang makro dan aturan.
Starlark adalah bahasa yang menentukan cara software dibuat, dan dengan demikian merupakan bahasa pemrograman dan bahasa konfigurasi.
Anda akan menggunakan Starlark untuk menulis file BUILD
, makro, dan aturan build. Makro dan
aturan pada dasarnya adalah meta-bahasa - keduanya menentukan cara file BUILD
ditulis.
File BUILD
harus sederhana dan berulang.
Semua software lebih sering dibaca daripada yang ditulis. Hal ini terutama berlaku bagi
Starlark, karena engineer membaca file BUILD
untuk memahami dependensi
target dan detail build mereka. Pembacaan ini akan sering terjadi secara kelulusan,
dengan terburu-buru, atau secara paralel untuk menyelesaikan beberapa tugas lainnya. Oleh karena itu,
kemudahan dan keterbacaan sangat penting agar pengguna dapat mengurai dan
memahami file BUILD
dengan cepat.
Saat pengguna membuka file BUILD
, mereka dengan cepat ingin mengetahui daftar target dalam
file; 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 ini.
File BUILD
juga dianalisis dan diperbarui oleh berbagai alat. Alat mungkin
tidak dapat mengedit file BUILD
jika menggunakan abstraksi. Dengan file BUILD
yang sederhana, Anda akan mendapatkan alat yang lebih baik. Saat makin berkembang, code base
akan semakin sering melakukan perubahan di banyak file BUILD
untuk
memperbarui 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 daripada dua spasi untuk indentasi untuk mengikuti konvensi Python.
Karena
Starlark is not 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
Dokumentasikan file dan fungsi menggunakan docstrings.
Gunakan docstring di bagian atas setiap file .bzl
dan docstring untuk setiap fungsi publik.
Aspek 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 yang dipisahkan oleh garis bawah (
[a-z][a-z0-9_]*
), seperticc_library
. - Nilai pribadi tingkat atas dimulai dengan satu garis bawah. Bazel menerapkan 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 batasan panjang baris yang ketat karena label boleh panjang.
Jika memungkinkan, coba gunakan paling banyak 79 karakter per baris (mengikuti panduan gaya Python, PEP 8). Panduan ini
tidak boleh diterapkan secara ketat: editor harus menampilkan lebih dari 80 kolom,
perubahan otomatis sering kali menyertakan baris yang lebih panjang, dan pengguna 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
Memilih nilai True
dan False
(bukan 1
dan 0
) untuk nilai boolean (seperti saat menggunakan atribut boolean dalam aturan).
Gunakan cetak hanya untuk proses debug
Jangan gunakan fungsi print()
dalam kode produksi karena fungsi tersebut hanya ditujukan untuk proses debug dan akan mengirimkan 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 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, ketika terjadi masalah, pengguna perlu memahami implementasi makro 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 mengenali makro, sehingga alat yang bergantung pada aspek (IDE dan lainnya) mungkin akan gagal.
Penggunaan makro yang aman adalah untuk menentukan target tambahan yang akan direferensikan secara langsung di Bazel CLI atau dalam file BUILD: Dalam hal ini, hanya pengguna akhir dari target tersebut yang perlu diketahui, dan masalah build yang diperkenalkan oleh makro tidak pernah jauh dari penggunaannya.
Untuk makro yang menentukan target yang dihasilkan (detail penerapan makro yang tidak boleh dirujuk di CLI atau bergantung pada target yang tidak dibuat 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 target karakter pengganti (:all
,...
,:*
, dll.).
- Namanya diawali dengan
name
hanya boleh digunakan untuk mendapatkan nama target yang ditentukan oleh makro, dan bukan untuk yang lain. Misalnya, jangan gunakan nama untuk memperoleh dependensi atau file input yang tidak dihasilkan oleh makro itu sendiri.- Semua target yang dibuat dalam makro harus digabungkan dengan cara tertentu ke target utama.
- Pertahankan nama parameter dalam makro yang konsisten. Jika parameter diteruskan
sebagai nilai atribut ke target utama, pastikan namanya tetap sama. Jika parameter makro
memiliki tujuan yang sama dengan atribut aturan umum, seperti
deps
, beri nama yang Anda gunakan untuk atribut tersebut (lihat di bawah). - Saat memanggil makro, hanya gunakan argumen kata kunci. Hal ini konsisten dengan aturan, dan sangat meningkatkan keterbacaan.
Engineer sering kali menulis makro saat Starlark API dari aturan yang relevan tidak memadai untuk kasus penggunaan khusus mereka, terlepas dari apakah aturan tersebut ditentukan dalam Bazel dalam kode native atau di Starlark. Jika Anda mengalami masalah ini, tanyakan kepada pembuat aturan apakah mereka dapat memperluas API untuk mencapai sasaran Anda.
Sebagai aturan praktis, semakin banyak makro yang menyerupai aturan, semakin baik.
Lihat juga makro.
Aturan
- Aturan, aspek, dan atributnya harus menggunakan huruf kecil ("huruf ular").
- Nama aturan adalah kata benda yang mendeskripsikan jenis artefak utama yang dihasilkan oleh
aturan, dari sudut pandang dependensinya (atau untuk pengguna, aturan daun). Akhiran ini belum tentu akhiran file. Misalnya, aturan yang
menghasilkan artefak C++ yang akan digunakan sebagai ekstensi Python mungkin disebut
py_extension
. Untuk sebagian besar bahasa, aturan standar meliputi:*_library
- unit kompilasi atau "modul".*_binary
- target yang menghasilkan file yang dapat dieksekusi atau unit deployment.*_test
- target pengujian. Hal ini dapat mencakup beberapa pengujian. Anggap 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 meliputi:
srcs
:label_list
, mengizinkan file: file sumber, biasanya dibuat oleh manusia.deps
:label_list
, biasanya tidak mengizinkan file: dependensi kompilasi.data
:label_list
, yang memungkinkan 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 serupa). - Fungsi penerapan aturan seharusnya hampir selalu berupa fungsi pribadi (diberi nama dengan garis bawah di awal). Gaya yang umum adalah memberi
fungsi implementasi untuk
myrule
nama_myrule_impl
. - Teruskan informasi di antara aturan Anda menggunakan antarmuka provider yang didefinisikan dengan baik. Kolom deklarasi dan penyedia dokumen.
- Rancang aturan Anda dengan ekstensibilitas. Pertimbangkan bahwa aturan lain mungkin ingin berinteraksi dengan aturan Anda, mengakses penyedia Anda, dan menggunakan kembali tindakan yang Anda buat.
- Ikuti panduan performa dalam aturan Anda.