.bzl stil kılavuzu

Sorun bildirin Kaynağı göster

Bu sayfada Starlark için temel stil yönergelerinin yanı sıra makrolar ve kurallarla ilgili bilgiler de yer almaktadır.

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ı 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. Mühendisler hedeflerinin bağımlılıklarını ve derlemelerinin ayrıntılarını anlamak için BUILD dosyalarını okuduğundan bu özellikle Starlark için geçerli. 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 çok önemlidir.

Kullanıcılar bir BUILD dosyasını açtığında dosyadaki hedeflerin listesini hemen öğrenmek veya C++ kitaplığının kaynak listesini incelemek ya da bu Java ikili programından bir bağımlılığı 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. Araçlar soyutlama kullanıyorsa BUILD dosyanızı düzenleyemeyebilir. BUILD dosyalarınızı basit tutmak daha iyi araçlar elde etmenizi sağlar. Kod tabanı büyüdükçe, bir kitaplığı güncellemek veya temizleme yapmak için çok sayıda BUILD dosyasında değişiklik yapma sıklığı da artar.

Genel tavsiye

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, singletonlarla karşılaştırmaların Starlark'ta bir operatör olmayan is ile yapılmasını önerir.

Belge dizesi

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

Kuralları ve unsurları belgeleyin

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ında, alt çizgiyle ([a-z][a-z0-9_]*) ayrılan kelimelerde küçük harf kullanılır (ör. cc_library).
  • Ü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

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, Python'un stil kılavuzu PEP 8'e göre her satırda en fazla 79 karakter kullanmaya çalışın. Bu kural sıkı bir şekilde uygulanmamalıdır: Düzenleyiciler 80'den fazla sütun görüntülemelidir, otomatik değişiklikler sık sık daha uzun satırlara neden olur ve insanlar, hâlihazırda okunabilen satırları bölmek için zaman harcamamalıdır.

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 (ör. bir kuralda boole özelliği kullanırken) True ve False değerlerini (1 ve 0 yerine) tercih edin.

Üretim kodunda print() işlevini kullanmayın. Bu işlev yalnızca hata ayıklama amacıyla 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 bir kod gönderebilmenizdir. Örneğin, tüm print() kullanımları if DEBUG: tarafından korunduğunda DEBUG kodu False koduna gömülürse. Bu ifadelerin, okunabilirlik üzerindeki etkilerini kanıtlamak için yeterince yararlı olup olmadığına dikkat edin.

Makrolar

Makro, yükleme aşamasında bir veya daha fazla kural somutlaştıran 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, bazı unsurlar makroların farkında değildir. Bu nedenle, özelliklere bağlı olarak araç oluşturma (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 uzakta değildir.

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:

  • 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) aşağıdaki şartları karşılamalıdır:
    • Adlarının başında <name> veya _<name> bulunmalıdır. Örneğin, name = '%s_bar' % (name) kullanarak.
    • Görünürlüğü kısıtlı (//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, bu adı makronun kendisi tarafından oluşturulmayan bir bağımlılık veya giriş dosyası türetmek için 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ı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, kurallarla tutarlıdır ve okunabilirliği büyük ölçüde iyileştirir.

Mühendisler genellikle ilgili kuralların Starlark API'si belirli kullanım alanları için yetersiz olduğunda, kuralın yerel kodda Bazel'de veya Starlark'ta tanımlanmasından bağımsız olarak makrolar yazarlar. 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, özellikler ve özelliklerde küçük harfli adlar ("yılan büyük harf") 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 - bir test hedefi. Buna birden fazla test dahil olabilir. *_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 özelliklerden bazıları şunlardır:
    • srcs: label_list, dosyalara izin verir: kaynak dosyalar, genellikle gerçek kişiler tarafından yazılmıştır.
    • deps: label_list, genellikle dosyalara izin vermez: derleme bağımlılıkları.
    • data: label_list, dosyalara izin verir: test verileri gibi veri dosyaları.
    • runtime_deps: label_list: Derleme için gerekli olmayan çalışma zamanı bağımlılıkları.
  • Belirgin olmayan davranışa sahip tüm özellikler (örneğin, özel ikame değerler içeren dize şablonları veya belirli şartlarla çağrılan araçlar) için özelliğin bildirimine (attr.label_list() veya benzeri) doc anahtar kelime bağımsız değişkenini kullanarak belge sağlayın.
  • Kural uygulama işlevleri, hemen hemen 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. Tanıma ve belge sağlayıcı alanlarını belirtin.
  • Kuralınızı tasarlarken genişletilebilirliği göz önünde bulundurun. 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 göz önünde bulundurun.
  • Kurallarınızdaki performans yönergelerini uygulayın.