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 temel olarak 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 okuma genellikle hızlıca, aceleyle veya başka bir görevi yerine getirirken 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 kuralına uymak için girinti için 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, singletonlarla karşılaştırmaların Starlark'ta bir 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 özellikleri, sağlayıcılar ve alanları ile birlikte 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 özel 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 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 1 ve 0 yerine True ve False değerlerini tercih edin (ör. bir kuralda boole özelliği kullanırken).
Yazdırma özelliğini yalnızca hata ayıklama için kullanın
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. Bunun tek istisnası, varsayılan olarak devre dışı bırakılmışsa ve yalnızca kaynağı düzenleyerek etkinleştirilebiliyorsa print() kullanan kod gönderebilmenizdir. Örneğin, print()'ün tüm kullanımları if DEBUG: tarafından korunuyorsa ve DEBUG False olarak kodlanmışsa. 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ı ö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, derleme 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 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. Bu nedenle, özelliklere bağlı olarak araç oluşturma (IDE'ler ve diğerleri) başarısız olabilir.
Makroların güvenli kullanımı, doğrudan Bazel CLI'de veya BUILD dosyalarında referans verilecek 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ından çok 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:
- Makrolar,
namebağı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 (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>eklenmiş. Örneğin,name = '%s_bar' % (name)kullanabilirsiniz. - Görünürlüğü kısıtlanmış (
//visibility:private) ve - Joker karakterli hedeflerde (
:all,...,:*vb.) genişletmeyi önlemek içinmanualetiketi kullanın.
- Adlarının önüne
nameyalnızca makro tarafından tanımlanan hedeflerin adlarını türetmek için kullanılmalıdır, başka 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, ana hedefle bir şekilde birleştirilmelidir.
- Geleneksel olarak, bir makro tanımlanırken ilk bağımsız değişken
nameolmalıdır. - Makrodaki parametre adlarını tutarlı tutun. Bir parametre ana hedefe özellik değeri olarak iletilirse adını aynı tutun. Bir makro parametresi,
depsgibi 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 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şırsanız kuralın yazarına, API'yi hedeflerinizi gerçekleştirecek şekilde genişletip genişletemeyeceğini sorun.
Genel kural olarak, makrolar kurallara ne kadar benzerse o kadar iyidir.
Makrolar konusuna da göz atın.
Kurallar
- Kurallar, görünümler ve özelliklerinde küçük harf adlar ("snake_case") kullanılmalıdır.
- Kural adları, kural tarafından üretilen ana yapı türünü, bağımlılıkların (veya alt kural için kullanıcının) bakış açısından tanımlayan isimlerdir. Bu, dosya son eki olmak zorunda değildir. Örneğin, Python uzantıları olarak kullanılmak üzere C++ yapıları üreten bir kural
py_extensionolarak adlandırılabilir. Çoğu dil için tipik kurallar şunlardır:*_library: Derleme birimi veya "modül".*_binary: Yürütülebilir bir dosya veya dağıtım birimi üreten bir hedef.*_test: Test hedefi. Bu işlem birden fazla test içerebilir.*_testhedefindeki tüm testlerin aynı temanın varyasyonları olmasını bekleyin (ör. tek bir kitaplığın test edilmesi).*_import:.jargibi önceden derlenmiş bir yapıyı veya derleme sırasında kullanılan bir.dllöğesini 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)docanahtar kelime bağımsız değişkenini kullanarak doküman sağlayın. - Kural uygulama işlevleri, hemen hemen her zaman gizli işlevler olmalıdır (başta alt çizgi ile belirtilir).
myruleiçin uygulama işlevine_myrule_impladını vermek yaygın bir stildir. - İyi tanımlanmış bir sağlayıcı arayüzü kullanarak kurallarınız arasında bilgi aktarın. Sağlayıcı alanlarını tanımlayın ve belgeleyin.
- 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.