.bzl stil kılavuzu

Sorun bildirin Kaynağı göster

Bu sayfa, Starlark için temel stil yönergelerini kapsar ve ayrıca makrolar ve kurallarla ilgili bilgileri de içerir.

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

BUILD dosyalarını, makrolarını ve kuralları oluşturmak için Starlark'ı kullanacaksınız. Makrolar ve kurallar aslında meta dillerdir. BUILD dosyalarının nasıl yazıldığını tanımlarlar. BUILD dosyaları basit ve birbirini tekrar edecek şekilde tasarlanmıştır.

Tüm yazılımlar yazıldığından daha sık okunur. Bu durum özellikle Starlark için geçerlidir. Çünkü mühendislerin, hedeflerinin bağımlılıklarını ve derlemelerinin ayrıntılarını anlamak için BUILD dosyalarını okumaları gerekir. Bu ölçüm genellikle geçilir, acele edilir veya başka bir görevin gerçekleştirilmesine paralel olarak gerçekleşir. Sonuç olarak, basit ve okunabilir olması son derece önemlidir. Böylece kullanıcılar BUILD dosyalarını hızlıca ayrıştırabilir ve anlayabilir.

Bir kullanıcı BUILD dosyasını açtığında, dosyadaki hedeflerin listesini hızlı bir şekilde öğrenmek veya bu C++ kitaplığının kaynak listesini incelemek ya da Java ikili programından 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 dosyaları ayrıca birçok farklı araç tarafından analiz edilir ve güncellenir. Soyutlama kullanan araçlar BUILD dosyanızı düzenleyemeyebilir. BUILD dosyalarınızı basit tutarak daha iyi araçlara sahip olabilirsiniz. Kod tabanı büyüdükçe, kitaplığı güncellemek veya temizlik yapmak için birçok BUILD dosyasında değişiklik yapma sıklığı da artar.

Genel tavsiye

Stil

Python stili

Şüpheye düşerseniz mümkün olduğunda PEP 8 stil kılavuzunu takip edin. Özellikle, Python kurallarını uygulamak için girintili yerine iki yerine dört boşluk kullanın.

Starlark Python olmadığından Python stilinin bazı özellikleri geçerli değildir. Örneğin, PEP 8, Startonk'ta operatör olmayan is ile beton karşılaştırmalarının yapılmasını önermektedir.

Dokümanlar

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

Doküman kuralları ve özellikleri

Kurallar ve özelliklerle birlikte, bunların özellikleri, sağlayıcılar ve alanları da doc bağımsız değişkeni kullanılarak belgelenmelidir.

Adlandırma kuralı

  • Değişkenler ve işlev adları, cc_library gibi alt çizgilerle ([a-z][a-z0-9_]*) ayrılmış kelimelerle küçük harf kullanır.
  • Üst düzey özel değerler tek bir alt çizgiyle başlar. Bazel, diğer dosyalardan özel değerlerin 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ği için katı bir satır uzunluğu sınırı yoktur. Mümkünse satır başına en fazla 79 karakter kullanmaya çalışın (Python'un stil kılavuzu PEP 8'i izleyerek). Bu kural sıkı bir şekilde uygulanmamalıdır: Düzenleyiciler 80'den fazla sütun görüntülemeli, otomatik değişiklikler genellikle daha uzun satırlar sunmalıdır ve insanlar zaten okunabilir olan satırları bölmeye zaman harcamamalıdır.

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

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

Üretim kodunda print() işlevini kullanmayın. Bu işlev yalnızca hata ayıklama için tasarlanmıştır ve .bzl dosyanızın doğrudan ve dolaylı tüm kullanıcılarına spam yapar. Bunun tek istisnası, print() kullanan kodu varsayılan olarak devre dışı olduğu ve yalnızca kaynağı düzenleyerek etkinleştirilebildiği takdirde göndermenizdir. Örneğin, print() kullanımlarının tamamı DEBUG tarafından False olarak sabitlenmiş olarak if DEBUG: tarafından korunuyorsa. Bu ifadelerin okunabilirlik üzerindeki etkilerini gerekçelendirecek kadar 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, makrolar yerine mümkün olduğunda kuralları kullanın. Kullanıcının gördüğü derleme grafiği, derleme sırasında Bazel tarafından kullanılan grafikle aynı değildir. Makrolar, Bael 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ğinden, bazel query sonuçlarının yorumlanması zor olabilir. Son olarak, makrolar farkına varmadığından, özelliklere (IDE'ler ve diğerleri) bağlı araçlar kullanılamayabilir.

Makrolar için güvenli bir kullanım, doğrudan Bazel KSA'da veya DERLE dosyalarında başvurulabilecek ek hedeflerin tanımlanmasıdır: Bu durumda, bu hedeflerin yalnızca son kullanıcılarının bunları bilmesi gerekir ve makroların neden olduğu yapı sorunları hiçbir zaman kullanımlarının dışında değildir.

Oluşturulan hedefleri tanımlayan makrolar (CLI'de başvurulmaması gereken veya makronun somutlaştırmadığı hedeflere bağımlı olan 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 ada sahip bir hedef tanımlamalıdır. Söz konusu hedef, bu makronun ana hedefi olur.
  • Bir makro tarafından tanımlanan diğer tüm hedefler olan oluşturulan hedefler şunları yapmalıdır:
    • Adlarının başında <name> veya _<name> bulunmalıdır. Örneğin, name = '%s_bar' % (name) kullanımı.
    • Görünürlüğün kısıtlı olması (//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ı elde etmek için kullanılmalıdır; başka hiçbir şey için kullanılmaz. Örneğin, makronun kendisi tarafından oluşturulmayan bir bağımlılık veya giriş dosyası elde etmek için bu adı kullanmayın.
  • Makroda oluşturulan tüm hedefler, ana hedefle bir şekilde eşleştirilmelidir.
  • Makrodaki parametre adlarını tutarlı tutun. Bir parametre ana hedefe özellik değeri olarak iletilirse, adını aynı tutun. Bir makro parametresi, deps gibi ortak kural kuralıyla aynı amaca hizmet ediyorsa bu adı aynı şekilde 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 ilgili kuralın Starlark API'si kendi özel kullanım alanları için yeterli olmadığında genellikle kuralın, yerel kodda Bazel'da veya Starlark'ta tanımlanmasından bağımsız olarak makro yazar. Bu sorunla karşılaşıyorsanız kural yazarına, hedeflerinizi gerçekleştirmek için API'yi genişletip genişletemeyeceğini sorun.

Genel bir kural olarak, kurallara ne kadar çok makro benzer olursa o kadar iyidir.

Makrolara da bakın.

Kurallar

  • Kurallar, yönler ve özellikleri küçük harfli adlar ("yıllık büyük harf") kullanmalıdır.
  • Kural adları, bağımlılık tarafından (veya yaprak kuralları için kullanıcı açısından) kural tarafından oluşturulan ana yapı türünü açıklayan 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 py_extension olarak adlandırılabilir. Çoğu dil için tipik kurallar şunlardır:
    • *_library - bir derleme birimi veya "Modül".
    • *_binary - Yürütülebilir veya dağıtım birimi oluşturan bir hedef.
    • *_test - test hedefi. Bu, birden çok testi içerebilir. Bir *_test hedefindeki tüm testlerin aynı temada varyasyon olması beklenir (örneğin, tek bir kitaplığı test etmek).
    • *_import: Önceden derlenmiş bir yapıyı (ör. .jar veya derleme sırasında kullanılan .dll) kapsayan bir hedef.
  • Özellikler için tutarlı adlar ve türler kullanın. Genel olarak geçerli bazı özellikler şunlardır:
    • srcs: label_list: Dosyalara izin verilir: Genellikle insan tarafından oluşturulan kaynak dosyalar.
    • deps: label_list, genellikle dosyalara izin verilmez: derleme derleme bağımlıları.
    • data: label_list. Şu dosyalara izin verilir: test dosyaları gibi veri dosyaları.
    • runtime_deps: label_list: Derleme için gerekli olmayan çalışma zamanı bağımlılıkları.
  • Belirgin olmayan davranışları olan tüm özellikler (ör. özel yerine kullanılan dize şablonları veya belirli koşullarla çağrılan araçlar) özelliğin beyanına doc anahtar kelime öbeğini (attr.label_list() veya benzeri) kullanarak doküman sağlayın.
  • Kural uygulama işlevleri neredeyse her zaman gizli işlevler olmalıdır (başında alt çizgi bulunur). 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. Beyan ve doküman sağlayıcı alanları.
  • Kuralınızı genişletilebilirliği göz önünde bulundurarak tasarlayın. Diğer kuralların kuralınızla etkileşimde bulunmak, sağlayıcılarınıza erişmek ve oluşturduğunuz işlemleri yeniden kullanmak isteyebileceğini unutmayın.
  • Kurallarınızdaki performans yönergelerini uygulayın.