.bzl stil kılavuzu

. Sorun bildirin Kaynağı göster Gece · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Bu sayfada Starlark için temel stil yönergeleri ele alınmaktadır. Ayrıca, makrolar ve kurallar hakkında bilgi edinin.

Starlark, Yazılımın nasıl oluşturulduğunu tanımlayan bir dildir ve bu nedenle programlama ve yapılandırma dili.

BUILD dosyaları ve makroları yazmak ve kuralları oluşturmak için Starlark'ı kullanacaksınız. Makrolar ve kurallar, temelde meta dillerdir. BUILD dosyalarının nasıl yazıldığını tanımlarlar. BUILD dosya basit ve kendini tekrarlayacak şekilde tasarlanmıştır.

Tüm yazılımlar yazılı olarak daha sık okunur. Bu, özellikle de Starlark, mühendisler bu sistemlerin bağımlılıklarını anlamak için BUILD dosyalarını ve derlemelerinin ayrıntılarına inceleyebilirsiniz. Bu ölçüm genellikle geçerken ve aceleye getirmek veya başka bir görevi tamamlamaya paralel olarak sunmaktır. Bunun sonucunda, Basitlik ve okunabilirlik çok önemlidir; böylece kullanıcılar, ayrıştırıp BUILD dosyaları hızlı bir şekilde kavrayabilir.

Bir kullanıcı BUILD dosyasını açtığında Google Ads'deki hedeflerin listesini hemen öğrenmek ister. emin olmaktır. veya o C++ kitaplığının kaynak listesini inceleyin; veya bir öğeyi kaldırın bağımlılığının altını çizeriz. Her soyutlama katmanı eklediğinizde, kullanıcının bu görevleri yapmasını zorlaştırır.

BUILD dosya da birçok farklı araç tarafından analiz edilir ve güncellenir. Araçlar soyutlama kullanıyorsa BUILD dosyanızı düzenleyebilirsiniz. BUILD saklanıyor daha iyi araçlar elde etmenizi sağlar. Kod tabanı büyüdükçe BUILD dosyasında değişiklik yapma sıklığı gittikçe artıyor: kitaplığı güncelleyebilir veya temizlik yapabilirsiniz.

Genel tavsiye

Buildifier'ı kullanma son derece önemlidir.
Test yönergelerini uygulayın.

Stil

Python stili

Şüpheye düştüğünüzde Mümkün olduğunda PEP 8 stil kılavuzu. Özellikle, girintilendirme için iki yerine dört boşluk kullanın: Python kuralı.

Başlangıç Starlark, Python değildir Python stilinin bazı yönleri geçerli değildir. Örneğin PEP 8, Singletonlarla karşılaştırmalar, şurada bir operatör olmayan is ile yapılabilir: Starlark.

Belge dizesi

docstrings kullanarak doküman dosyaları ve işlevleri. Her .bzl dosyasının üst kısmında bir docstring ve her herkese açık için bir doküman dizesi kullanın işlevini kullanın.

Kuralları ve unsurları belgeleyin

Kuralları ve nitelikleri, özellikleri, sağlayıcılar ve alanları, doc bağımsız değişkeni kullanılarak belgelenmelidir.

Adlandırma kuralı

Değişkenler ve işlev adları, küçük harfle yazılan kelimelerde alt çizgi ([a-z][a-z0-9_]*), örneğin cc_library.
Üst düzey gizli değerler bir alt çizgiyle başlar. Bazel, özel değerler diğer dosyalardan kullanılamaz. Yerel değişkenler alt çizgi ön ekini kullanmalıdır.

Satır uzunluğu

Etiketler uzun olabileceğinden, BUILD dosyalarında olduğu gibi kesin bir satır uzunluğu sınırı yoktur. Mümkün olduğunda her satırda en fazla 79 karakter kullanmaya çalışın (Python'ın stil kılavuzu, PEP 8). Bu kural katı bir şekilde uygulanmamalıdır: Düzenleyiciler 80'den fazla sütun görüntülemelidir, Otomatik değişiklikler çoğu zaman daha uzun satırlara yol açar ve ancak önceden okunabilen satırları bölerek zaman geçiriyorlar.

Anahtar kelime bağımsız değişkenleri

Anahtar kelime bağımsız değişkenlerinde, eşittir işareti çevresindeki boşluklar tercih edilir:

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

Boole değerleri

Boole değerleri için 1 ve 0 yerine True ve False değerlerini tercih et (ör. bir kuralda boole özelliği kullanılırken).

Hata ayıklama için yalnızca yazdırmayı kullan

Üretim kodunda print() işlevini kullanmayın; yalnızca hata ayıklama işlemi gerçekleştirip .bzl dosyanızın doğrudan ve dolaylı tüm kullanıcılarına spam gönderir. İlgili içeriği oluşturmak için kullanılan Tek istisna, devre dışı bırakılırsa print() kullanan bir kod gönderebilmenizdir. varsayılan olarak ayarlanır ve yalnızca kaynak düzenlenerek etkinleştirilebilir (örneğin, print() kullanımları, DEBUG için sabit kodlu olduğu durumlarda if DEBUG: tarafından korunur False. Bu ifadelerin projeyi haklı çıkaracak kadar faydalı olup olmadığına dikkat edin daha iyi anlamalarını sağlayabilirsiniz.

Makrolar

Makro, yükleme sırasında bir veya daha fazla kural üreten bir fonksiyondur aşamasındayız. Genel olarak, mümkün olduğunda makrolar yerine kuralları kullanın. Derleme kullanıcıya ait grafik, deneme süresi boyunca Bazel'in derleme: makrolar, Bazel herhangi bir yapı grafiği analizi yapmadan önce genişletilir.

Bu nedenle bir şeyler ters gittiğinde kullanıcı, makronuzun uygulanmasıyla ilgili daha fazla bilgi edinebilirsiniz. Ayrıca, hedeflerde gösterilen hedefler nedeniyle bazel query sonuçlarının yorumlanması zor olabilir. makro genişlemeden gelir. Son olarak, bazı unsurlar makroların farkında değildir. bağlı olarak da (IDE'ler ve diğerleri) başarısız olabilir.

Makrolar için güvenli bir kullanım, özel amaçlanan ek hedefler tanımlamak içindir doğrudan Bazel CLI'da veya BUILD dosyalarında referans verildiğinde: Bu durumda yalnızca son kullanıcılarının bunlar hakkında bilgi sahibi olması gerekir ve zaman zaman makrolar tarafından bunların kullanımından uzaklaşmaz.

Oluşturulan hedefleri tanımlayan makrolar için (makronun uygulama ayrıntıları) KSA'da atıfta bulunulmayan veya hedeflere bağlı olmayan örneklenmemişse) aşağıdaki en iyi uygulamaları izleyin:

Bir makro, name bağımsız değişkeni almalı ve bu adla bir hedef tanımlamalıdır. Bu hedef, makronun ana hedefi haline gelir.
Oluşturulan hedefler (bir makro tarafından tanımlanan diğer tüm hedefler) için şunları yapmalıdır:
- Adlarının başında <name> veya _<name> bulunmalıdır. Örneğin, name = '%s_bar' % (name)
- Görünürlüğü kısıtlı (//visibility:private) ve
- Joker karakterli hedeflerde genişletmeyi önlemek için bir manual etiketi bulundurun (:all, ..., :* vb.)
name yalnızca makrosu ile başlar, başka hiçbir şey için değil. Örneğin, makronun kendisi tarafından oluşturulmayan bir bağımlılık veya giriş dosyası.
Makroda oluşturulan tüm hedefler, olacaktır.
Makrodaki parametre adlarının tutarlı olmasını sağlayın. Bir parametre özelliğini ana hedefe özellik değeri olarak eklemek için, hedefin adını aynı tutun. Bir makro parametresi, deps, özelliği kullandığınız şekilde adlandırın (aşağıya bakın).
Bir makro çağırırken yalnızca anahtar kelime bağımsız değişkenlerini kullanın. Bu, ve okunabilirliği büyük ölçüde iyileştirir.

Mühendisler genellikle ilgili kuralların Starlark API'si kullanıldığında kullanım durumu için yetersiz kalması durumunda (kuralın yerel kodda Bazel veya Starlark'ta tanımlanır. Yeni bir web tasarımcısı kuralının yazarına, istediğiniz işlemleri gerçekleştirmek için API'yi hedefler.

Genel kural olarak, kurallara ne kadar çok makro benzese de o kadar iyidir.

Ayrıca makrolar konusuna bakın.

Kurallar

Kurallar, yönler ve özelliklerde küçük harfli adlar kullanılmalıdır ("yılan destek kaydı").
Kural adları, bağımlılıkları açısından (veya yaprak kuralları açısından kullanıcı) tarafından sağlanır. Bu her zaman bir dosya son eki olmayabilir. Örneğin, Python uzantıları olarak kullanılması amaçlanan C++ yapıları oluşturur py_extension Çoğu dilde tipik kurallar şunlardır:
- *_library - bir derleme birimi veya "modül".
- *_binary: Yürütülebilir dosya veya dağıtım birimi oluşturan bir hedef.
- *_test - bir test hedefi. Buna birden fazla test dahil olabilir. Tümünü bekle *_test hedefindeki testlerin aynı temanın varyasyonları olmasını tek bir kitaplığı test etme.
- *_import: Önceden derlenmiş bir yapıyı kapsayan bir hedef. Örneğin: .jar veya derleme sırasında kullanılan bir .dll.
Özellikler için tutarlı adlar ve türler kullanın. Bazıları genellikle özellikleri şunları içerir:
- srcs: label_list, dosyalara izin veriliyor: kaynak dosyalar, genellikle gerçek kişilerdir.
- deps: label_list, genellikle dosyalara izin vermez: derleme ve bildirmeyi konuştuk.
- data: label_list, dosyalara izin verir: test verileri gibi veri dosyaları.
- runtime_deps: label_list: Gerekli olmayan çalışma zamanı bağımlılıkları derler.
Belirgin olmayan davranışa sahip özellikler (örneğin, dize şablonları) özel ikamelerle veya belirli ifadelerle çağrılan araçlarla gereksinimleri yerine getirmek için) doc anahtar kelime bağımsız değişkenini kullanarak özelliğinin bildirimi (attr.label_list() veya benzeri).
Kural uygulama işlevleri neredeyse her zaman gizli işlevler olmalıdır (başta alt çizgi ile belirtilir). Ortak bir stil, myrule için uygulama fonksiyonu (_myrule_impl adı).
Kurallarınız arasında bilgi aktarmak için iyi tanımlanmış provider arayüzününde Bildirim ve belge sağlayıcı alanları.
Kuralınızı tasarlarken genişletilebilirliği göz önünde bulundurun. Başka kuralların da kuralınızla etkileşimde bulunmak, sağlayıcılarınıza erişmek ve işlemlerdir.
Kurallarınızdaki performans yönergelerini uygulayın.