.bzl stil kılavuzu

Sorun bildir Kaynağı görüntüleyin Nightly · 7.4 .

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ı ve makroları yazmak ve kuralları 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. Mühendisler, hedeflerine olan bağımlılıkları 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, aceleyle veya başka bir görevi yerine getirirken yapılır. 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 bir BUILD dosyasını açtığında dosyadaki hedeflerin listesini hemen öğrenmek veya C++ kitaplığının kaynak listesini incelemek ya da bu Java ikili programından bir 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 dosya 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 yapma ihtiyacı giderek artar.

Önemli: Yalnızca BUILD dosyalarında tekrardan kaçınmak için değişken veya makro oluşturmayın. BUILD dosyanız hem geliştiriciler hem de araçlar tarafından kolayca okunabilmelidir. DRY prensibi burada pek geçerli değildir.

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, singletonlarla karşılaştırmaların Starlark'ta bir operatör olmayan is ile yapılmasını önerir.

Açıklama satırı

docstrings kullanarak doküman dosyaları ve işlevleri. Her .bzl dosyasının üst kısmında bir docstring ve her bir genel işlev için bir docstring 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ında, alt çizgiyle ([a-z][a-z0-9_]*) ayrılan kelimelerde küçük harf kullanılır (ör. cc_library).
• Ü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 sıkı sıkıya 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 (ör. bir kuralda boole özelliği kullanırken) True ve False değerlerini (1 ve 0 yerine) tercih edin.

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 (KSA'da yer alması gerekmeyen veya bu makro tarafından örneklendirilmeyen hedeflere dayalı olması gereken makronun uygulama ayrıntıları) için aşağıdaki en iyi uygulamaları izleyin:

• Makrolar, name bağımsız değişkeni almalıdır ve bu ada sahip bir hedef tanımlamalıdır. Bu hedef, makronun ana hedefi haline gelir.
• Oluşturulan hedefler (yani bir makro tarafından tanımlanan diğer tüm hedefler) şu özelliklere sahip olmalıdır:
  • Adlarının başında <name> veya _<name> bulunmalıdır. Örneğin, name = '%s_bar' % (name) kullanabilirsiniz.
  • Görünürlüğü kısıtlı (//visibility:private) ve
  • Joker karakterli hedeflerde (: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 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, bir şekilde ana hedefe bağlanmalıdır.
• Geleneksel olarak, bir makro tanımlanırken 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 iletilirse adını aynı tutun. Bir makro parametresi, deps gibi 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 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 genellikle ilgili kuralların Starlark API'si belirli kullanım alanları için yetersiz olduğunda, kuralın yerel kodda Bazel'de veya Starlark'ta tanımlanmasından bağımsız olarak makrolar yazarlar. 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ı, bağımlılıkları (veya yaprak kuralları için kullanıcı) açısından kural tarafından üretilen ana yapı türünü açıklayan adlardır. Bu, dosya son eki olmak zorunda değildir. Örneğin, Python uzantıları olarak kullanılmak üzere C++ yapıları üreten bir kural py_extension olarak adlandırılabilir. Çoğu dilde 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. *_test hedefindeki tüm testlerin aynı temanın varyasyonları olmasını bekleyin (ör. tek bir kitaplığın test edilmesi).
  • *_import: .jar veya derleme sırasında kullanılan .dll gibi önceden derlenmiş bir yapıyı 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ı.
• Belirgin olmayan davranışa sahip tüm özellikler (örneğin, özel ikame değerler içeren dize şablonları veya belirli şartlarla ç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 belge sağlayın.
• Kural uygulama işlevleri neredeyse her zaman özel işlevler olmalıdır (başında alt çizgi bulunan işlevler). myrule için uygulama işlevine _myrule_impl adı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ızdaki performans yönergelerini uygulayın.