.bzl stil kılavuzu

Sorun bildirinopen_in_new Kaynağı gösteropen_in_new Gece · 7,4 , 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ı, makrolar ve derleme kuralları yazmak için Starlark'ı kullanırsı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ıldığından 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 okuma genellikle hızlıca, aceleyle veya başka bir görevi yerine getirirken yapılı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. Soyutlama kullanılıyorsa araçlar BUILD dosyanızı düzenleyemeyebilir. BUILD Dosyalarınızı basit tutmak, daha iyi araçlar kullanmanıza olanak tanır. Kod tabanı büyüdükçe, bir kitaplığı güncellemek veya temizlemek için birçok BUILD dosyasında değişiklik yapmanın sıklığı artar.

Genel tavsiye

• Düzenleyici ve yazım denetimi aracı olarak Buildifier'ı kullanın.
• Test yönergelerini uygulayın.

Stil

Python stili

Şüpheye düştüğünüzde mümkün olduğunda PEP 8 stil kılavuzuna uyun. Özellikle, Python kuralına uymak için girinti için iki yerine dört boşluk kullanın.

Başlangıç Starlark, Python değildir Python stilinin bazı yönleri geçerli değildir. Örneğin PEP 8, singletonlarla karşılaştırmalar, is ile yapılabilir. Bu, 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 özelliklerinin yanı sıra sağlayıcılar ve alanlarının tümü doc bağımsız değişkeni kullanılarak belgelenmelidir.

Adlandırma kuralı

• Değişkenler ve işlev adları, cc_library gibi alt çizgilerle ([a-z][a-z0-9_]*) ayrılmış kelimelerle küçük harflerle yazılır.
• Üst düzey özel değerler bir alt çizgiyle başlar. Bazel, özel değerler diğer dosyalardan kullanılamaz. Yerel değişkenler alt çizgi ön ekini kullanmamalıdır.

Satır uzunluğu

BUILD dosyalarında olduğu gibi, etiketler uzun olabileceğinden katı bir satır uzunluğu sınırı yoktur. Mümkün olduğunda satır başına en fazla 79 karakter kullanmaya çalışın (Python'un stil kılavuzu PEP 8'e uygun olarak). 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şaretinin etrafında boşluk 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).

Yazdırma özelliğini yalnızca hata ayıklama için kullanın

Ü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 somutlaştıran bir fonksiyondur aşamasındayız. Genel olarak, mümkün olduğunda makrolar yerine kurallar kullanın. Kullanıcının gördüğü derleme grafiği, derleme sırasında Bazel tarafından kullanılan grafikle aynı değildir. Makrolar, Bazel herhangi bir derleme grafiği analizi yapmadan önce genişletilir.

Bu nedenle, bir sorun oluştuğunda kullanıcının derleme sorunlarını gidermek için makronuzun uygulanmasını anlaması gerekir. Ayrıca, sonuçlarda gösterilen hedefler makro genişletmeden geldiği için bazel query sonuçlarının yorumlanması zor olabilir. 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.
• Bir makro tarafından tanımlanan diğer tüm hedefler olan oluşturulan hedefler şunları yapmalıdır:
  • Adlarının başında <name> veya _<name> bulunmalıdır. Örneğin, name = '%s_bar' % (name) kullanabilirsiniz.
  • Görünürlüğü kısıtlanmış (//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ı türetmek için adı kullanmayın.
• Makroda oluşturulan tüm hedefler, olacaktır.
• Makrodaki parametre adlarını tutarlı tutun. Bir parametre ana hedefe özellik değeri olarak iletilirse adını aynı tutun. Bir makro parametresi, deps gibi ortak bir kural özelliğiyle aynı amaca hizmet ediyorsa özelliği adlandırdığınız gibi adlandırın (aşağıya bakın).
• Bir makroyu çağırırken yalnızca anahtar kelime bağımsız değişkenlerini kullanın. Bu, kurallara uygundur ve okunabilirliği büyük ölçüde artırır.

Mühendisler genellikle ilgili kuralların Starlark API'si kullanıldığında makro yazarlar 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, makrolar kurallara ne kadar benzerse 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, dosya son eki olmak zorunda değildir. Örneğin, Python uzantıları olarak kullanılması amaçlanan C++ yapıları oluşturur py_extension Çoğu dil için tipik kurallar şunlardır:
  • *_library: Derleme birimi veya "modül".
  • *_binary: Yürütülebilir dosya veya dağıtım birimi oluşturan bir hedef.
  • *_test: Test hedefi. Bu işlem birden fazla test içerebilir. *_test hedefindeki tüm testlerin aynı temanın varyasyonları olmasını bekleyin (ör. tek bir kitaplığın test edilmesi).
  • *_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 verir: genellikle insan tarafından yazılmış kaynak dosyalar.
  • deps: label_list, genellikle dosyalara izin vermez: derleme bağımlılıklarını içerir.
  • data: label_list, dosyalara izin verir: test verileri gibi veri dosyaları vb.
  • 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 beyanı (attr.label_list() veya benzeri).
• Kural uygulama işlevleri neredeyse her zaman gizli işlevler olmalıdır (başta alt çizgi ile belirtilir). myrule için uygulama işlevine _myrule_impl adını vermek yaygın bir stildir.
• İyi tanımlanmış bir sağlayıcı arayüzü kullanarak kurallarınız arasında bilgi aktarın. 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.