.bzl stil kılavuzu

Bu sayfada, Starlark ile ilgili temel stil yönergeleri ve makrolar ile kurallar hakkında bilgiler yer almaktadır.

Starlark, yazılımın nasıl oluşturulduğunu tanımlayan bir dildir. Bu nedenle hem programlama hem de yapılandırma dilidir.

BUILD dosyalarını, makroları ve derleme kurallarını yazmak için Starlark'ı kullanırsınız. Makrolar ve kurallar aslında meta dillerdir. BUILD dosyalarının nasıl yazılacağını tanımlarlar. BUILD dosyaları basit ve tekrarlayan nitelikte olmalıdır.

Tüm yazılımlar, yazıldığından daha sık okunur. Bu durum özellikle Starlark için geçerlidir. Mühendisler, hedeflerinin bağımlılıklarını ve derlemelerinin ayrıntılarını anlamak için BUILD dosyalarını okur. Bu okuma genellikle geçici olarak, aceleyle veya başka bir görevi tamamlarken paralel olarak yapılır. Bu nedenle, kullanıcıların BUILD dosyalarını hızlıca ayrıştırıp anlaması için basitlik ve okunabilirlik çok önemlidir.

Bir kullanıcı BUILD dosyasını açtığında dosyadaki hedeflerin listesini hızlıca öğrenmek, C++ kitaplığının kaynak listesini incelemek veya Java ikilisinden bir bağımlılığı kaldırmak ister. Her soyutlama katmanı eklediğinizde kullanıcının bu görevleri yapması zorlaşır.

BUILD dosyalar da birçok farklı araç tarafından analiz edilip güncellenir. Araçlar, soyutlamalar kullanılıyorsa BUILD dosyanızı düzenleyemeyebilir. Dosyalarınızı basit tutarak daha iyi araçlar elde edebilirsiniz.BUILD Kod tabanı büyüdükçe bir kitaplığı güncellemek veya temizlik yapmak için birçok BUILD dosyasında değişiklik yapmak giderek daha sık hale gelir.

Genel tavsiye

• Buildifier'ı biçimlendirici ve linter olarak kullanın.
• Test yönergelerini uygulayın.

Stil

Python stili

Emin olmadığınız durumlarda mümkün olduğunca PEP 8 stil kılavuzunu takip edin. Özellikle Python kuralına uymak için girintilemede iki yerine dört boşluk kullanın.

Starlark, Python olmadığından, Python stilinin 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.

Docstring

Docstring kullanarak dosya ve işlevleri belgeleme. Her .bzl dosyasının üst kısmında ve her herkese açık işlev için bir docstring kullanın.

Belge kuralları ve yönleri

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

Adlandırma kuralı

• Değişkenler ve işlev adlarında, kelimeler alt çizgilerle ([a-z][a-z0-9_]*) ayrılmış şekilde küçük harfler kullanılır (ör. cc_library).
• En üst düzeydeki özel değerler tek bir alt çizgiyle başlar. Bazel, özel değerlerin diğer dosyalarda kullanılmasını zorunlu kılar. Yerel değişkenler, alt çizgi önekini 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'ın stil kılavuzu PEP 8'e uygun olarak). Bu yönerge katı bir şekilde uygulanmamalıdır: Düzenleyiciler 80'den fazla sütun göstermelidir, otomatik değişiklikler genellikle daha uzun satırlar oluşturur ve insanlar zaten okunabilir olan satırları bölmekle zaman harcamamalıdır.

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

Anahtar kelime bağımsız değişkenlerinde eşittir işaretinin etrafındaki 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 True ve False değerlerini (1 ve 0 yerine) tercih edin (ör. bir kuralda Boole özelliği kullanırken).

Yalnızca hata ayıklama için yazdırmayı kullanma

Ü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 kod gönderebilmenizdir. Örneğin, print()'nın tüm kullanımları if DEBUG: ile korunuyorsa ve DEBUG, False olarak sabit kodlanmışsa. Bu ifadelerin, okunabilirlik üzerindeki etkilerini haklı çıkaracak kadar faydalı olup olmadığına dikkat edin.

Makrolar

Makro, yükleme aşamasında bir veya daha fazla kuralı başlatan bir işlevdir. Genel olarak, mümkün olduğunda makrolar yerine kuralları kullanın. Kullanıcının gördüğü derleme grafiği, Bazel'in derleme sırasında kullandığıyla 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 nasıl uygulandığını anlaması gerekir. Ayrıca, sonuçlarda gösterilen hedefler makro genişletmeden geldiği için bazel query sonuçlarını yorumlamak zor olabilir. Son olarak, yönler makroların farkında olmadığından yönlere bağlı araçlar (IDE'ler ve diğerleri) başarısız olabilir.

Makroların güvenli bir kullanım alanı, Bazel CLI'da veya BUILD dosyalarında doğrudan referans verilmesi amaçlanan ek hedefleri tanımlamaktır: Bu durumda, bu hedeflerin yalnızca son kullanıcılarının bu hedefler hakkında bilgi sahibi olması gerekir ve makroların neden olduğu tüm derleme sorunları, kullanımlarının çok uzağında değildir.

Oluşturulan hedefleri tanımlayan makrolar için (makronun, CLI'da referans verilmemesi veya bu makro tarafından oluşturulmayan hedefler tarafından bağlı olunmaması gereken uygulama ayrıntıları) aşağıdaki en iyi uygulamaları izleyin:

• Makro, name bağımsız değişkenini almalı ve bu adla bir hedef tanımlamalıdır. Bu hedef, makronun ana hedefi olur.
• Oluşturulan hedefler (yani bir makro tarafından tanımlanan diğer tüm hedefler) şu özelliklere sahip olmalıdır:
  • Adlarının önüne <name> veya _<name> eklenir. Örneğin, name = '%s_bar' % (name) kullanma.
  • Görünürlüğü kısıtlanmış (//visibility:private) ve
  • Joker karakter hedeflerinde (:all, ..., :* vb.) genişlemeyi önlemek için manual etiketi kullanın.
• name yalnızca makro tarafından tanımlanan hedeflerin adlarını türetmek için kullanılmalıdır ve başka hiçbir amaçla kullanılmamalıdır. Örneğin, makronun kendisi tarafından oluşturulmayan bir bağımlılık veya giriş dosyası elde etmek için adı kullanmayın.
• Makroda oluşturulan tüm hedefler bir şekilde ana hedefle eşleştirilmelidir.
• Geleneksel olarak, makro tanımlarken name ilk bağımsız değişken olmalıdır.
• Makrodaki parametre adlarını tutarlı tutun. Bir parametre ana hedefe özellik değeri olarak iletiliyorsa adını aynı tutun. Bir makro parametre, ortak bir kural özelliğiyle (ör. deps) aynı amaca hizmet ediyorsa özelliği adlandırır 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, ilgili kuralların Starlark API'si kendi özel kullanım alanları için yeterli olmadığında, kuralın Bazel'de yerel kodda mı yoksa Starlark'ta mı tanımlandığına bakılmaksızın genellikle makrolar yazar. Bu sorunla karşılaşıyorsanız kuralı yazan kişiden, API'yi hedeflerinize ulaşmanızı sağlayacak şekilde genişletmesini isteyin.

Genel bir kural olarak, makrolar kurallara ne kadar çok benzerse o kadar iyi olur.

Ayrıca makrolar hakkında bilgi edinin.

Kurallar

• Kurallar, yönler ve bunların özellikleri lower_case adlar ("snake case") kullanmalıdır.
• Kural adları, bağımlılıkları açısından (veya yaprak kurallar için kullanıcı açısından) kural tarafından üretilen ana türdeki yapıyı tanımlayan isimlerdir. Bu, dosya soneki olmak zorunda değildir. Örneğin, Python uzantıları olarak kullanılmak üzere C++ yapıları oluşturan bir kurala py_extension adı verilebilir. Çoğu dildeki tipik kurallar şunlardır:
  • *_library - derleme birimi veya "modül".
  • *_binary - yürütülebilir dosya veya dağıtım birimi üreten bir hedef.
  • *_test - bir test hedefi. Bu, birden fazla testi içerebilir. *_test hedefindeki tüm testlerin aynı tema üzerinde varyasyonlar olmasını bekleyin. Örneğin, tek bir kitaplığı test etme.
  • *_import: Derleme sırasında kullanılan .jar veya .dll gibi önceden derlenmiş bir yapıyı kapsayan hedef.
• Özellikler için tutarlı adlar ve türler kullanın. Genel olarak geçerli olan bazı özellikler şunlardır:
  • srcs: label_list, allowing files: source files, typically human-authored.
  • deps: label_list, genellikle dosyalara izin vermez: derleme bağımlılıkları.
  • data: label_list, dosyalara izin veriliyor: test verileri gibi veri dosyaları
  • runtime_deps: label_list: Derleme için gerekli olmayan çalışma zamanı bağımlılıkları.
• Davranışı açık olmayan tüm özellikler (ör. özel değiştirmeler içeren dize şablonları veya belirli koşullarla çağrılan araçlar) için özelliğin bildiriminde (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 (başında alt çizgiyle adlandırılmış) olmalıdır. Yaygın bir stil, myrule için uygulama işlevine _myrule_impl adını vermektir.
• İyi tanımlanmış bir sağlayıcı arayüzü kullanarak kurallarınız arasında bilgi aktarın. Sağlayıcı alanlarını bildirin ve belgeleyin.
• Kuralınızı genişletilebilirliği göz önünde bulundurarak 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.