Panduan gaya .bzl

Laporkan masalah Lihat sumber Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

Starlark adalah bahasa yang menentukan cara software dibuat, dan oleh karena itu, bahasa ini adalah bahasa pemrograman dan konfigurasi.

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

Semua software 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 terjadi secara sepintas, terburu-buru, atau secara paralel dengan menyelesaikan tugas lain. Oleh karena itu, kesederhanaan dan keterbacaan sangat penting agar pengguna dapat mengurai dan memahami file BUILD dengan cepat.

Saat pengguna membuka file BUILD, mereka ingin mengetahui dengan cepat daftar target dalam file tersebut; atau meninjau daftar sumber library C++ tersebut; atau menghapus dependensi dari biner Java tersebut. Setiap kali Anda menambahkan lapisan abstraksi, Anda membuat pengguna lebih sulit 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 Anda tetap sederhana akan memungkinkan Anda mendapatkan alat yang lebih baik. Seiring bertambahnya basis kode, perubahan di banyak file BUILD menjadi semakin sering dilakukan untuk memperbarui library atau melakukan pembersihan.

Saran umum

Gaya

Gaya Python

Jika ragu, ikuti panduan gaya PEP 8 jika memungkinkan. Khususnya, gunakan empat, bukan dua spasi untuk indentasi guna mengikuti konvensi 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.

Docstring

Mendokumentasikan file dan fungsi menggunakan docstring. 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

  • Nama variabel dan 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 memastikan bahwa nilai pribadi tidak dapat digunakan dari file lain. Variabel lokal tidak boleh menggunakan awalan garis bawah.

Panjang baris

Seperti pada file BUILD, tidak ada batas panjang baris yang ketat karena label bisa panjang. Jika memungkinkan, coba gunakan maksimal 79 karakter per baris (mengikuti panduan gaya Python, PEP 8). Pedoman ini tidak boleh diterapkan secara ketat: editor harus menampilkan lebih dari 80 kolom, perubahan otomatis akan sering kali menghasilkan 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 baik gunakan nilai True dan False (daripada 1 dan 0) untuk nilai boolean (seperti saat menggunakan atribut boolean dalam aturan).

Jangan gunakan fungsi print() dalam kode produksi; fungsi ini hanya ditujukan untuk proses debug, dan akan membanjiri semua pengguna langsung dan tidak langsung dari file .bzl Anda. Satu-satunya pengecualian adalah Anda dapat mengirimkan kode yang menggunakan print() jika kode tersebut dinonaktifkan secara default dan hanya dapat diaktifkan dengan mengedit sumber -- misalnya, jika semua penggunaan print() dilindungi oleh if DEBUG: dengan DEBUG dikodekan secara permanen 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, jika terjadi kesalahan, pengguna harus memahami penerapan makro Anda untuk memecahkan masalah build. Selain itu, hasil bazel query dapat 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 dimaksudkan untuk dirujuk secara langsung di Bazel CLI atau dalam file BUILD: Dalam hal ini, hanya pengguna akhir target tersebut yang perlu mengetahuinya, dan masalah build apa pun yang disebabkan oleh makro tidak akan 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 di-instansiasi 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 dibuat, 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 dalam target karakter pengganti (:all, ..., :*, dll.).
  • name hanya boleh digunakan untuk mendapatkan nama target yang ditentukan oleh makro, dan tidak untuk hal lain. Misalnya, jangan gunakan nama untuk mendapatkan 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.
  • Secara konvensional, name harus menjadi argumen pertama saat menentukan makro.
  • Pertahankan nama parameter dalam makro agar tetap konsisten. Jika parameter diteruskan sebagai nilai atribut ke target utama, pertahankan nama yang sama. Jika parameter 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 sangat meningkatkan keterbacaan.

Engineer sering menulis makro saat Starlark API dari aturan yang relevan tidak cukup untuk kasus penggunaan spesifik mereka, terlepas dari apakah aturan tersebut ditentukan dalam Bazel dalam kode native, atau dalam Starlark. Jika Anda menghadapi masalah ini, tanyakan kepada penulis aturan apakah mereka dapat memperluas API untuk mencapai tujuan Anda.

Sebagai aturan praktis, semakin mirip makro dengan aturan, semakin baik.

Lihat juga makro.

Aturan

  • Aturan, aspek, dan atributnya harus menggunakan nama lower_case ("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). Ini belum tentu merupakan sufiks file. Misalnya, aturan yang menghasilkan artefak C++ yang dimaksudkan untuk digunakan sebagai ekstensi Python dapat disebut py_extension. Untuk sebagian besar bahasa, aturan umum 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. Semua pengujian dalam target *_test diharapkan menjadi variasi pada tema yang sama, misalnya, menguji satu pustaka.
    • *_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 memungkinkan 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 apa pun dengan perilaku yang tidak jelas (misalnya, template string dengan penggantian 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 depannya). Gaya umum adalah memberikan fungsi penerapan untuk myrule nama _myrule_impl.
  • Teruskan informasi antar-aturan menggunakan antarmuka penyedia yang ditentukan dengan baik. Mendeklarasikan dan mendokumentasikan 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 panduan performa dalam aturan Anda.