.bzl stil kılavuzu

Sorun bildir Kaynağı görüntüle Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bu sayfada, Starlark ile ilgili temel stil yönergeleri ve makrolar ile kurallar hakkında bilgiler yer almaktadır.

Starlark, yazılımın nasıl oluşturulduğunu tanımlayan bir dildir. Bu nedenle hem bir programlama dili hem de bir yapılandırma dilidir.

BUILD dosyalarını, makroları ve derleme kurallarını yazmak için Starlark'ı kullanırsınız. Makrolar ve kurallar aslında meta dillerdir. BUILD dosyalarının nasıl yazılacağını tanımlarlar. BUILD dosyaları basit ve tekrarlayan nitelikte olmalıdır.

Tüm yazılımlar, yazıldığından daha sık okunur. Bu durum ö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ı okur. Bu okuma genellikle geçici olarak, aceleyle veya başka bir görevi tamamlarken paralel olarak yapılır. Bu nedenle, kullanıcıların BUILD dosyalarını hızlıca ayrıştırıp anlaması için basitlik ve okunabilirlik çok önemlidir.

Bir kullanıcı BUILD dosyasını açtığında dosyadaki hedeflerin listesini hızlıca öğrenmek, C++ kitaplığının kaynak listesini incelemek veya Java ikilisinden bir bağımlılığı kaldırmak ister. Her soyutlama katmanı eklediğinizde kullanıcının bu görevleri yapması zorlaşır.

BUILD dosyaları da birçok farklı araç tarafından analiz edilip güncellenir. Araçlar, soyutlamalar kullanılıyorsa BUILD dosyanızı düzenleyemeyebilir. Dosyalarınızı basit tutarak daha iyi araçlar elde edebilirsiniz.BUILD Kod tabanı büyüdükçe bir kitaplığı güncellemek veya temizlik yapmak için birçok BUILD dosyasında değişiklik yapmak giderek daha sık hale gelir.

Genel tavsiye

Stil

Python stili

Emin olmadığınız durumlarda mümkün olduğunca PEP 8 stil kılavuzunu takip edin. Özellikle Python kuralına uymak için girintide 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 is ile yapılmasını önerir. Bu, Starlark'ta bir operatör değildir.

Docstring

Docstring'leri kullanarak dosya ve işlevleri belgeleme Her .bzl dosyasının üst kısmında ve her herkese açık işlev için bir docstring kullanın.

Belge kuralları ve yönleri

Kurallar ve yönler, bunların özellikleri, sağlayıcılar ve alanları doc bağımsız değişkeni kullanılarak belgelendirilmelidir.

Adlandırma kuralı

  • Değişkenler ve işlev adlarında, kelimeler alt çizgilerle ([a-z][a-z0-9_]*) ayrılarak küçük harfler kullanılır (ör. cc_library).
  • En üst düzeydeki özel değerler bir alt çizgiyle başlar. Bazel, özel değerlerin diğer dosyalarda kullanılmasını zorunlu kılar. Yerel değişkenler alt çizgi önekini 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'ın stil kılavuzu PEP 8'e uygun olarak). Bu yönerge kesin bir şekilde uygulanmamalıdır: Düzenleyiciler 80'den fazla sütun göstermelidir, otomatik değişiklikler genellikle daha uzun satırlar oluşturur ve insanlar zaten okunabilir olan satırları bölmekle 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 True ve False değerlerini (1 ve 0 yerine) tercih edin (ör. bir kuralda Boole özelliği kullanırken).

Üretim kodunda print() işlevini kullanmayın. Bu işlev yalnızca hata ayıklama amacıyla tasarlanmıştır ve .bzl dosyanızın tüm doğrudan ve dolaylı kullanıcılarına spam gönderir. Tek istisna, varsayılan olarak devre dışı bırakılmışsa ve yalnızca kaynak düzenlenerek etkinleştirilebiliyorsa print() kullanan kod gönderebilmenizdir. Örneğin, print()'nın tüm kullanımları if DEBUG: ile korunuyorsa ve DEBUG, False olarak sabit kodlanmışsa. Bu ifadelerin, okunabilirlik üzerindeki etkilerini haklı çıkaracak kadar faydalı 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, Bazel'in derleme sırasında kullandığıyla 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 nasıl uygulandığını anlaması gerekir. Ayrıca, sonuçlarda gösterilen hedefler makro genişletmeden geldiği için bazel query sonuçlarını yorumlamak zor olabilir. Son olarak, yönler makroların farkında olmadığından yönlere bağlı araçlar (IDE'ler ve diğerleri) başarısız olabilir.

Makroların güvenli bir kullanım alanı, Bazel CLI'da veya BUILD dosyalarında doğrudan referans verilmesi amaçlanan 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 derleme sorunları, makroların kullanımından asla uzak değildir.

Oluşturulan hedefleri tanımlayan makrolar için (makronun, komut satırında referans verilmemesi veya bu makro tarafından oluşturulmayan hedefler tarafından bağlı olunmaması gereken uygulama ayrıntıları) aşağıdaki en iyi uygulamaları izleyin:

  • Makro, name bağımsız değişkenini almalı ve bu adla bir hedef tanımlamalıdır. Bu hedef, 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> eklenir. Örneğin, name = '%s_bar' % (name) kullanma.
    • Görünürlüğü kısıtlanmış (//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ı türetmek için kullanılmalıdır ve başka hiçbir amaçla kullanılmamalıdır. Örneğin, makronun kendisi tarafından oluşturulmayan bir bağımlılık veya giriş dosyası elde etmek için adı kullanmayın.
  • Makroda oluşturulan tüm hedefler bir şekilde ana hedefle eşleştirilmelidir.
  • Geleneksel olarak, makro tanımlarken ilk bağımsız değişken name olmalıdır.
  • Makrodaki parametre adlarını tutarlı tutun. Bir parametre ana hedefe özellik değeri olarak iletiliyorsa adını aynı tutun. Bir makro parametre, ortak bir kural özelliğiyle (ör. deps) aynı amaca hizmet ediyorsa özelliği adlandırır gibi adlandırın (aşağıya bakın).
  • 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 artırır.

Mühendisler, kuralın Bazel'de yerel kodda veya Starlark'ta tanımlanıp tanımlanmadığına bakılmaksızın, ilgili kuralların Starlark API'si kendi özel kullanım alanları için yeterli olmadığında genellikle makro yazar. Bu sorunla karşılaşıyorsanız kuralı yazan kişiden, hedeflerinize ulaşmak için API'yi genişletip genişletemeyeceğini sorun.

Genel bir kural olarak, makrolar kurallara ne kadar çok benzerse o kadar iyi olur.

Ayrıca makrolar hakkında bilgi edinin.

Kurallar

  • Kurallar, yönler ve bunların özellikleri lower_case adlar ("snake case") kullanmalıdır.
  • Kural adları, bağımlılıkları açısından (veya yaprak kurallar için kullanıcı açısından) kural tarafından üretilen ana türdeki yapıyı tanımlayan isimlerdir. Bu, dosya soneki olmak zorunda değildir. Örneğin, Python uzantıları olarak kullanılmak üzere C++ yapıları oluşturan bir kurala py_extension adı verilebilir. Çoğu dildeki tipik kurallar şunlardır:
    • *_library - derleme birimi veya "modül".
    • *_binary - yürütülebilir veya dağıtım birimi üreten bir hedef.
    • *_test - bir test hedefi. Bu, birden fazla testi içerebilir. Bir *_test hedefindeki tüm testlerin aynı tema üzerinde varyasyonlar olmasını bekleyin. Örneğin, tek bir kitaplığı test etme.
    • *_import: Derleme sırasında kullanılan .jar gibi önceden derlenmiş bir yapıyı veya .dll'ı 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, allowing files: source files, typically human-authored.
    • deps: label_list, genellikle izin verilmeyen dosyalar: derleme bağımlılıkları.
    • data: label_list, dosyalara izin veriliyor: test verileri gibi veri dosyaları
    • runtime_deps: label_list: Derleme için gerekli olmayan çalışma zamanı bağımlılıkları.
  • Davranışı açık olmayan tüm özellikler (ör. özel değiştirmeler içeren dize şablonları veya belirli koşullarla çağrılan araçlar) için özelliğin bildirimine (attr.label_list() veya benzeri) doc anahtar kelime bağımsız değişkenini kullanarak doküman sağlayın.
  • Kural uygulama işlevleri neredeyse her zaman özel işlevler (başında alt çizgiyle adlandırılmış) olmalıdır. 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. Sağlayıcı alanlarını beyan edin ve belgeleyin.
  • Kuralınızı genişletilebilirlik özelliğini göz önünde bulundurarak tasarlayın. Diğer kuralların, kuralınızla etkileşim kurmak, 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.