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 derlendiğini tanımlayan bir dildir. Bu nedenle 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ılacağı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, hedeflerinin bağımlılıklarını 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, tesadüfen veya başka bir görevi yerine getirirken gerçekleşir. Bu nedenle, 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 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 dosyaları 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.
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.
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ı,
cc_librarygibi 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ğ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 kesinlikle 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).
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 haklı çıkaracak kadar 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, yönler makrolardan haberdar olmadığından yönlere bağlı araçlar (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 (makronun CLI'de referans verilmemesi veya bu makro tarafından oluşturulmayan hedefler tarafından bağımlı olması gereken uygulama ayrıntıları) için aşağıdaki en iyi uygulamaları izleyin:
- Makro, bir
namebağımsız değişkeni almalı 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, 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, ana hedefle bir şekilde birleştirilmelidir.
- 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, 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şı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 neredeyse her zaman özel işlevler olmalıdır (başında alt çizgi bulunan işlevler).
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.