.bzl stil kılavuzu

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

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.

Ü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çin manual etiketi kullanın.
  • 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.