Bu sayfada Starlark ile ilgili temel stil yönergelerinin yanı sıra makrolar ve kurallarla ilgili bilgiler de yer almaktadır.
Starlark, yazılımın oluşturulma biçimini tanımlayan bir dildir. Bu nedenle hem programlama hem de yapılandırma dilidir.
BUILD
dosyaları ve makroları yazmak ve kural 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
dosyalarının basit ve tekrarlı olması amaçlanmıştır.
Tüm yazılımlar yazıldığından daha sık okunur. Bu, ö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ı okuyor. Bu okuma çoğu zaman geçerken, aceleyle
veya başka bir görevi tamamlarken yapılır. Sonuç olarak
basitlik ve okunabilirlik, kullanıcıların BUILD
dosyalarını hızlı bir şekilde ayrıştırıp anlayabilmesi için çok önemlidir.
Kullanıcı bir BUILD
dosyasını açtığında, dosyadaki hedeflerin listesini hızlıca öğrenmek veya bu C++ kitaplığının kaynak listesini incelemek ya da bu Java ikili programından bir bağımlılığı kaldırmak ister. Eklediğiniz her soyutlama katmanı, kullanıcının bu görevleri yerine getirmesini zorlaştırır.
BUILD
dosyaları da birçok farklı araç tarafından analiz edilip güncellenir. Araçlar, soyutlama kullanıyorsa BUILD
dosyanızı düzenleyemeyebilir. BUILD
dosyalarınızı basit tutarak daha iyi araçlar elde edebilirsiniz. Kod tabanı büyüdükçe, kitaplığı güncellemek veya temizlik yapmak için pek çok BUILD
dosyasında değişiklik yapılması giderek daha sık hale gelir.
Genel tavsiye
- Biçimlendirici ve lint 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 uygulayın. Özellikle, Python kuralına uygun olarak 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
is
ile yapılmasını önerir. Bu, Starlark'ta bir operatör değildir.
Dize
docstrings kullanarak dosyaları ve işlevleri belgeleyin.
Her .bzl
dosyasının en üstünde bir docstring ve her genel işlev için bir docstring kullanın.
Belge kuralları ve unsurları
Kurallar ve nitelikler, özellikleriyle birlikte 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ılmış kelimeler küçük harfle yazı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 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 olan PEP 8'e uygun şekilde). Bu kural kesinlikle uygulanmamalıdır: Düzenleyiciler 80'den fazla sütun görüntülemelidir, otomatik değişiklikler çoğu zaman daha uzun satırlar getirir ve insanlar halihazırda okunabilir olan 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ş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 (örneğin, bir kuralda boole özelliği kullanırken) True
ve False
değerlerini (1
ve 0
yerine) tercih edin.
Hata ayıklama için yalnızca yazdırmayı kullanma
Üretim kodunda print()
işlevini kullanmayın. Bu işlev yalnızca hata ayıklama amaçlıdır ve .bzl
dosyanızın tüm doğrudan ve dolaylı kullanıcılarına spam yapar. Bunun tek istisnası, print()
kullanan kodu varsayılan olarak devre dışı bırakılmışsa ve yalnızca kaynağı düzenleyerek etkinleştirilebiliyorsa gönderebilirsiniz. Örneğin, DEBUG
tüm print()
kullanımları if DEBUG:
tarafından korunuyorsa ve DEBUG
kodu False
koduna gömülüyorsa. 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ı somutlaştıran bir işlevdir. Genel olarak, mümkün olduğunda makrolar yerine kuralları kullanın. Kullanıcının gördüğü yapı grafiği, oluşturma sırasında Bazel tarafından kullanılan grafikle aynı değildir. Makrolar Bazel herhangi bir yapı 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 makroların farkında değildir. Bu nedenle, unsurlara (IDE'ler ve diğerleri) bağlı araçlar başarısız olabilir.
Makrolar için güvenli bir kullanım, doğrudan Bazel KSA veya DERLEME dosyalarında referans verilmesi amaçlanan ek hedefleri tanımlamaktır: Bu durumda, bu hedeflerin yalnızca son kullanıcılarının bunları bilmesi gerekir ve makrolar tarafından oluşturulan derleme sorunları, kullanımlarından hiçbir zaman uzakta değildir.
Oluşturulan hedefleri tanımlayan makrolar için (Makronun KSA'da belirtilmesi gerekmeyen veya söz konusu makro tarafından somutlaştırılmayan hedeflerin esas alınması gerekmeyen makro uygulama ayrıntıları) aşağıdaki en iyi uygulamaları izleyin:
- Bir makro,
name
bağımsız değişkenini almalı ve bu ada sahip bir hedef tanımlamalıdır. Bu hedef, makronun ana hedefi olur. - Oluşturulan hedefler (yani, makro tarafından tanımlanan diğer tüm hedefler):
- Adlarının önüne
<name>
veya_<name>
ekleyin. Örneğin,name = '%s_bar' % (name)
kullanabilirsiniz. - Görünürlüğü kısıtlı (
//visibility:private
) ve - Joker karakter hedeflerinde (
:all
,...
,:*
vb.) genişletmeyi önlemek içinmanual
etiketi kullanın.
- Adlarının önüne
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 makroyu çağırırken yalnızca anahtar kelime bağımsız değişkenlerini kullanın. Bu, kurallarla tutarlıdır ve okunabilirliği önemli ölçüde artırır.
Mühendisler, ilgili kuralların Starlark API'si belirli kullanım alanları için yeterli olmadığında, kuralın yerel kodda Bazel'de veya Starlark'ta tanımlanıp tanımlanmadığına bakılmaksızın genellikle makrolar yazar. Bu sorunla karşılaşırsanız kural yazarına, hedeflerinize ulaşmak için API'yi genişletme imkanını sunup sunamayacağını sorun.
Genel kural olarak, kurallara ne kadar benzeyen makrolar o kadar iyi olur.
Makrolar'a da bakın.
Kurallar
- Kurallar, yönler ve özelliklerinde küçük harf adları ("yılan 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 eser türünü tanımlayan adlardır. Bunun bir dosya son eki olması gerekmez. Örneğin, Python uzantıları olarak kullanılması amaçlanan C++ yapıları oluşturan bir kuralın adı
py_extension
olabilir. Çoğu dil için genel kurallar şunlardır:*_library
- bir derleme birimi veya "modül".*_binary
: Yürütülebilir dosya veya dağıtım birimi üreten hedef.*_test
- bir test hedefi. Buna birden fazla test dahil olabilir. Bir*_test
hedefindeki tüm testlerin aynı temanın varyasyonları (örneğin, tek bir kitaplığı test etme) olmasını bekleyin.*_import
:.jar
gibi önceden derlenmiş bir yapıyı içeren hedef veya derleme sırasında kullanılan.dll
.
- Ö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 veriyor: kaynak dosyalar, genellikle insan tarafından hazırlanan dosyalar.deps
:label_list
, genellikle dosyalara izin vermez: derleme bağımlılıkları.data
:label_list
, dosyalara izin veriliyor: veri dosyaları (ör. test verileri vb.)runtime_deps
:label_list
: derleme için gerekli olmayan çalışma zamanı bağımlılıkları.
- Bariz olmayan davranışı olan özellikler (örneğin, özel değişiklikler içeren dize şablonları veya belirli gereksinimlerle çağrılan araçlar) için özelliğin bildirimine
doc
anahtar kelime bağımsız değişkenini kullanarak (attr.label_list()
veya benzeri) belge sağlayın. - Kural uygulama işlevleri neredeyse her zaman özel işlevler (başta bir alt çizgiyle adlandırılmıştır) olmalıdır. Yaygın bir stil,
myrule
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ı tanımlayın ve belgeleyin.
- Kuralınızı genişletilebilirliği göz önünde bulundurarak tasarlayın. Diğer kuralların kuralınızla etkileşime girmek, 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ızda performans kurallarına uyun.