.bzl stil kılavuzu

Bu sayfada Starlark için temel stil yönergeleri ele alınmakta, ayrıca makrolar ve kurallarla ilgili bilgiler de verilmektedir.

Starlark, yazılımın nasıl oluşturulacağını tanımlayan bir dildir ve dolayısıyla hem programlama hem de yapılandırma dilidir.

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 dosyalarının basit ve tekrarlı olması amaçlanmıştır.

Tüm yazılımlar yazıldığından daha sık okunur. Mühendisler, hedeflerine olan bağımlılıkları ve derlemelerinin ayrıntılarını anlamak için BUILD dosyalarını okuduğundan bu durum özellikle Starlark için geçerlidir. Bu ölçüm genellikle geçerken, aceleyle veya başka bir görevi tamamlamaya paralel olarak yapılır. Sonuç olarak, kullanıcıların BUILD dosyalarını hızlı bir şekilde ayrıştırıp anlayabilmesi için basitlik ve okunabilirlik son derece önemlidir.

Kullanıcılar BUILD dosyasını açtığında dosyanın hedef listesini hızlıca öğrenmek, söz konusu C++ kitaplığının kaynak listesini incelemek veya Java ikili dosyasından bir bağımlılık kaldırmak ister. Her soyutlama katmanı eklediğinizde, kullanıcının bu görevleri yapmasını zorlaştırırsınız.

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 tutarak daha iyi araçlar elde edebilirsiniz. Kod tabanı büyüdükçe, bir kitaplığı güncellemek veya temizlemek için birçok BUILD dosyasında değişiklik yapma ihtiyacı giderek 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ünse PEP 8 stil kılavuzunu izleyin. Özellikle, Python kurallarına uymak amacıyla girinti için iki yerine dört boşluk kullanın.

Starlark, Python olmadığından, Python tarzının bazı yönleri geçerli değildir. Örneğin, PEP 8, tekil öğelerle karşılaştırmaların Starlark'ta operatör olmayan is ile yapılmasını önerir.

Açıklama satırı

Dosyaları ve işlevleri docstring kullanarak belgeleyin. Her .bzl dosyasının üst kısmında ve her herkese açık işlev için bir açıklama metni kullanın.

Belge kuralları ve özellikleri

Kurallar ve özelliklerin yanı sıra ö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ı, cc_library gibi alt çizgilerle ([a-z][a-z0-9_]*) ayrılmış kelimelerle küçük harflerle yazılır.
• Üst düzey gizli değerler bir alt çizgiyle başlar. Bazel, özel değerlerin diğer dosyalardan kullanılamayacağını zorunlu kılar. 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 kurala sıkı sıkıya uyulmaması gerekir: Düzenleyiciler 80'den fazla sütun göstermelidir, otomatik değişiklikler genellikle daha uzun satırlar oluşturur ve kullanıcıların zaten okunabilir olan satırları bölmelerine gerek yoktur.

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 edin (ör. bir kuralda boole özelliği kullanırken).

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

print() işlevini üretim kodunda kullanmayın. Bu işlev yalnızca hata ayıklama için tasarlanmıştır ve .bzl dosyanızın tüm doğrudan ve dolaylı kullanıcılarına spam gönderir. Tek istisna, varsayılan olarak devre dışı bırakılmışsa ve yalnızca kaynak düzenlenerek etkinleştirilebiliyorsa print() kullanan kod göndermenizdir. Örneğin, DEBUG tüm kullanımları if DEBUG: tarafından korunduğunda DEBUG kodu False koduna gömülüdür.print() Bu ifadelerin, okunabilirlik üzerindeki etkilerini haklı çıkarmaya yetecek kadar faydalı olup olmadığına dikkat edin.

Makrolar

Makro, yükleme aşamasında bir veya daha fazla kuralı örnekleyen bir işlevdir. Genel olarak, mümkün olduğunda makrolar yerine kuralları kullanın. Kullanıcının gördüğü derleme grafiği, oluşturma sırasında Bazel tarafından kullanılanla aynı değildir. Makrolar, Bazel herhangi bir derleme grafiği analizi yapmadan önce genişletilir.

Bu nedenle, bir şeyler ters gittiğinde kullanıcının derleme sorunlarını gidermek için makronuzun uygulaması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, yönler makrolardan haberdar olmadığından yönlere bağlı araçlar (IDE'ler ve diğerleri) başarısız olabilir.

Makrolar için güvenli bir kullanım, doğrudan Bazel KSA'da veya DERLEME dosyalarında referans alınması amaçlanan ek hedefler tanımlamaktır. Bu durumda, söz konusu hedeflerin yalnızca son kullanıcılarının bunları bilmesi gerekir ve makroların neden olduğu derleme sorunları kullanımlarından hiçbir zaman etkilenmez.

Oluşturulan hedefleri tanımlayan makrolar (KSA'da yer alması gerekmeyen veya bu makro tarafından örneklendirilmeyen hedeflere dayalı olması gereken makronun uygulama ayrıntıları) için aşağıdaki en iyi uygulamaları izleyin:

• Makrolar, name bağımsız değişkeni almalıdır ve bu ada sahip bir hedef tanımlamalıdır. Bu hedef, söz konusu makronun ana hedefi olur.
• Oluşturulan hedefler (bir makro tarafından tanımlanan diğer tüm hedefler) aşağıdaki şartları karşılamalıdır:
  • Adlarının önüne <name> veya _<name> eklenmiş. Örneğin, name = '%s_bar' % (name) kullanarak.
  • Görünürlüğü kısıtlanmış (//visibility:private) ve
  • Joker karakter hedeflerinde (:all, ..., :* vb.) genişletmeyi önlemek için bir manual etiketi kullanın.
• name, yalnızca makro tarafından tanımlanan hedeflerin adlarını türetmek için kullanılmalıdır, başka hiçbir şey için kullanılmamalıdır. Ö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, bir şekilde ana hedefe bağlanmalıdır.
• Makrodaki parametre adlarının tutarlı olmasını sağlayın. Bir parametre, ana hedefe özellik değeri olarak aktarılırsa 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, kuralın Bazel'de yerel kodda mı yoksa Starlark'ta mı tanımlandığına bakılmaksızın, ilgili kuralların Starlark API'si belirli kullanım alanları için yeterli olmadığında genellikle makro yazar. Bu sorunla karşılaşıyorsanız kuralın yazarına, hedeflerinizi gerçekleştirmek için API'yi genişletip genişletemeyeceğini sorun.

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

Ayrıca makrolar konusuna bakın.

Kurallar

• Kurallar, görünümler ve özelliklerinde küçük harf adlar ("snake_case") kullanılmalıdır.
• Kural adları, bağımlılıkları (veya yaprak kuralları için kullanıcı) açısından kural tarafından üretilen ana yapı türünü açıklayan adlardır. Bu her zaman bir dosya son eki olmayabilir. Örneğin, Python uzantıları olarak kullanılması amaçlanan C++ yapıları oluşturan bir kurala py_extension çağrılabilir. Ç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: Test hedefi. Bu işlem birden fazla test içerebilir. *_test hedefindeki tüm testlerin aynı tema üzerinde varyasyonlar olmasını bekleyin (ör. tek bir kitaplığın test edilmesi).
  • *_import: .jar veya derleme sırasında kullanılan .dll gibi önceden derlenmiş bir yapıyı kapsayan bir hedef.
• Özellikler için tutarlı adlar ve türler kullanın. Genel olarak geçerli olan bazı özellikler şunlardır:
  • 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: Derleme için gerekli olmayan çalışma zamanı bağımlılıkları.
• Açık olmayan davranışa sahip özellikler (ör. özel değiştirmelere sahip dize şablonları veya belirli koşullarla çağrılan araçlar) için özelliğin tanımında (attr.label_list() veya benzeri) doc anahtar kelime bağımsız değişkenini kullanarak doküman sağlayın.
• Kural uygulama işlevleri neredeyse her zaman özel işlevler olmalıdır (başında alt çizgi bulunan işlevler). 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. Tanıma ve belge sağlayıcı alanlarını bildirme
• Kuralınızı genişletilebilirlik göz önünde bulundurularak tasarlayın. Diğer kuralların, kuralınızla etkileşime geçmek, sağlayıcılarınıza erişmek ve oluşturduğunuz işlemleri yeniden kullanmak isteyebileceğini unutmayın.
• Kurallarınızda performans yönergelerine uyun.