Build Foundation, kurucu üyeleri kaydetmeye başladı. Posta listesine katılın, katılım sözleşmesini okuyun ve kaydolun.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

.bzl stil kılavuzu

Nightly · 9.2 · 9.1 · 9.0 · 8.7 · 8.6

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

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

BUILD dosyaları, makrolar ve derleme kuralları 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 kullanabilirsiniz.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

Biçimlendirici ve linter olarak Buildifier'ı kullanın.
Test yönergelerini uygulayın.

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 en üstünde 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 sağlayıcıların 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ılmış şekilde küçük harfler 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ılamaması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 katı 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).

Yalnızca hata ayıklama için yazdırmayı kullanın

Ü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 kodlanmışsa. Bu ifadelerin okunabilirlik üzerindeki etkisini haklı çıkaracak kadar faydalı olup olmadığına dikkat edin.

Makrolar

Makro, yükleme aşamasında bir veya daha fazla kuralı başlatan 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, yalnızca bu hedeflerin son kullanıcılarının bu hedefler hakkında bilgi sahibi olması gerekir ve makroların neden olduğu tüm derleme sorunları, makroların kullanımından çok 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.
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).
Bir makroyu çağırırken yalnızca anahtar kelime bağımsız değişkenlerini kullanın. Bu, kurallara uygundur ve okunabilirliği büyük ölçüde artırır.

Mühendisler, kuralın Bazel'de yerel kodda mı yoksa Starlark'ta mı tanımlandığına bakılmaksızın, ilgili kuralların Starlark API'si kendi özel kullanım alanı için yetersiz olduğunda genellikle makro yazar. Bu sorunla karşılaşıyorsanız kuralı yazan kişiden API'yi hedeflerinize ulaşmanızı sağlayacak şekilde genişletmesini isteyin.

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ını ("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 yapay nesne türünü açıklayan 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 bir dosya veya dağıtım birimi oluşturan 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: .jar gibi önceden derlenmiş bir yapıyı veya derleme sırasında kullanılan bir .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 derleme bağımlılıkları gibi dosyalara izin verilmez.
- 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 bildiriminde (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şletilebilirliği göz önünde bulundurarak 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ızda performans yönergelerine uyun.