BUILD
dosya biçimlendirmesi, Go ile aynı yaklaşımı izler. Bu yaklaşımda, standartlaştırılmış bir araç çoğu biçimlendirme sorununu çözer.
Buildifier, kaynak kodunu standart bir stille ayrıştırıp yayınlayan bir araçtır. Bu nedenle, her BUILD
dosyası aynı otomatik şekilde biçimlendirilir. Böylece, kod incelemeleri sırasında biçimlendirmenin bir sorun olmaması sağlanır. Ayrıca, araçların BUILD
dosyalarını anlamasını, düzenlemesini ve oluşturmasını kolaylaştırır.
BUILD
dosya biçimi, buildifier
sonucuyla eşleşmelidir.
Biçimlendirme örneği
# Test code implementing the Foo controller.
package(default_testonly = True)
py_test(
name = "foo_test",
srcs = glob(["*.py"]),
data = [
"//data/production/foo:startfoo",
"//foo",
"//third_party/java/jdk:jdk-k8",
],
flaky = True,
deps = [
":check_bar_lib",
":foo_data_check",
":pick_foo_port",
"//pyglib",
"//testing/pybase",
],
)
Dosya yapısı
Öneri: Aşağıdaki sırayı kullanın (her öğe isteğe bağlıdır):
Paket açıklaması (yorum)
Tüm
load()
hesap özetleripackage()
işlevi.Kural ve makro çağrıları
Buildifier, bağımsız yorumlar ile bir öğeye eklenmiş yorumlar arasında ayrım yapar. Bir yorum belirli bir öğeye eklenmemişse yorumdan sonra boş bir satır kullanın. Bu ayrım, otomatik değişiklikler yaparken (örneğin, bir kuralı silerken yorumu tutmak veya kaldırmak için) önemlidir.
# Standalone comment (such as to make a section in a file)
# Comment for the cc_library below
cc_library(name = "cc")
Geçerli paketteki hedeflere referanslar
Dosyalara, paket dizine göreli yollarıyla referans verilmelidir (..
gibi üst referanslar kullanılmamalıdır). Oluşturulan dosyaların ön eklerine, kaynak olmadıklarını belirtmek için ":
" eklenmelidir. Kaynak dosyaların önüne :
eklenmemelidir. Kurallar :
ile başlamalıdır. Örneğin, x.cc
öğesinin bir kaynak dosya olduğu varsayıldığında:
cc_library(
name = "lib",
srcs = ["x.cc"],
hdrs = [":gen_header"],
)
genrule(
name = "gen_header",
srcs = [],
outs = ["x.h"],
cmd = "echo 'int x();' > $@",
)
Hedef adlandırma
Hedef adları açıklayıcı olmalıdır. Bir hedef tek bir kaynak dosya içeriyorsa hedefin adı genellikle bu kaynaktan türetilmelidir (örneğin, chat.cc
için bir cc_library
chat
olarak adlandırılabilir veya DirectMessage.java
için bir java_library
direct_message
olarak adlandırılabilir).
Bir paketin aynı ada sahip hedefi (içeren dizinle aynı ada sahip hedef), dizin adıyla açıklanan işlevi sağlamalıdır. Böyle bir hedef yoksa aynı ada sahip bir hedef oluşturmayın.
Aynı ada sahip bir hedeften bahsederken kısa adı tercih edin (//x:x
yerine //x
). Aynı paketteyseniz yerel referansı tercih edin (//x
yerine :x
).
Özel anlamı olan "ayrılmış" hedef adları kullanmaktan kaçının. all
, __pkg__
ve __subpackages__
de bu kapsamdadır. Bu adlar özel anlamlara sahiptir ve kullanıldığında karışıklıklara ve beklenmedik davranışlara neden olabilir.
Geçerli bir ekip kuralının olmadığı durumlarda, Google'da yaygın olarak kullanılan ve bağlayıcı olmayan bazı öneriler şunlardır:
- Genel olarak, "snake_case" kullanın
- Bir
src
içerenjava_library
için bu, uzantı olmadan dosya adıyla aynı olmayan bir ad kullanmak anlamına gelir. - Java
*_binary
ve*_test
kuralları için "Büyük CamelCase" kullanın. Bu, hedef adınınsrc
değerlerinden biriyle eşleşmesini sağlar.java_test
için bu,test_class
özelliğinin hedefin adından çıkarılmasını sağlar.
- Bir
- Belirli bir hedefin birden çok varyantı varsa belirsizleştirmek için sonek ekleyin (ör.
:foo_dev
,:foo_prod
veya:bar_x86
,:bar_x64
) _test
,_unittest
,Test
veyaTests
ile_test
son eki hedefleri_lib
veya_library
gibi anlamsız son ekler kullanmaktan kaçının (_library
hedefi ile ilgili_binary
arasında çakışmaları önlemek için gerekli olmadığı sürece)- Proto ile ilgili hedefler için:
proto_library
hedef,_proto
ile biten adlara sahip olmalıdır- Dillere özgü
*_proto_library
kuralları, temel proto ile eşleşmelidir ancak_proto
, aşağıdaki gibi dile özgü bir son ek ile değiştirilmelidir:cc_proto_library
:_cc_proto
java_proto_library
:_java_proto
java_lite_proto_library
:_java_proto_lite
Görünürlük
Görünürlük kapsamı mümkün olduğunca sıkı bir şekilde ayarlanmalı, aynı zamanda testlerle ve ters bağımlılıklarla erişim sağlanmalıdır. Uygun durumlarda __pkg__
ve __subpackages__
özelliğini kullanın.
default_visibility
paketini //visibility:public
olarak ayarlamaktan kaçının.
//visibility:public
yalnızca projenin herkese açık API'sindeki hedefler için ayrı ayrı ayarlanmalıdır. Bunlar, harici projeler tarafından bağımlı olacak şekilde tasarlanmış kitaplıklar veya harici bir projenin derleme süreci tarafından kullanılabilecek ikili dosyalar olabilir.
Bağımlılıklar
Bağımlılıklar doğrudan bağımlılıklarla (kuralda listelenen kaynakların ihtiyaç duyduğu bağımlılıklar) sınırlandırılmalıdır. Geçişli bağımlılıkları listelemeyin.
Paket yerel bağımlılıkları önce listelenmeli ve yukarıdaki Mevcut paketteki hedeflere referanslar bölümüyle uyumlu bir şekilde referans verilmelidir (mutlak paket adlarıyla değil).
Bağımlılıkları doğrudan tek bir liste halinde listelemeyi tercih edin. Birkaç hedefin "yaygın" bağımlılıklarını bir değişkene yerleştirmek sürdürülebilirliği azaltır, araçların bir hedefin bağımlılıklarını değiştirmesini imkansız kılar ve kullanılmayan bağımlılıklara yol açabilir.
Globs
"Hedef yok"u []
ile belirtin. Hiçbir şeyle eşleşmeyen bir glob kullanmayın. Bu, boş bir listeye göre daha hataya açık ve daha az belirgindir.
Yinelemeli
Kaynak dosyaları eşleştirmek için yinelemeli glob'ları kullanmayın (örneğin, glob(["**/*.java"])
).
Yinelenen glob'lar, BUILD
dosyaları içeren alt dizinleri atladığından BUILD
dosyalarının anlaşılmasını zorlaştırır.
Yinelenen glob'lar, daha iyi uzaktan önbelleğe alma ve paralellik sağladığı için genellikle dizin başına bir BUILD
dosyası ve aralarında tanımlanmış bir bağımlılık grafiği bulundurmaktan daha az verimlidir.
Her dizinde bir BUILD
dosyası oluşturmak ve aralarında bir bağımlılık grafiği tanımlamak iyi bir uygulamadır.
Yinelemesiz
Yinelenen olmayan globlar genellikle kabul edilir.
Diğer sözleşmeler
Sabitler için büyük harf ve alt çizgi (
GLOBAL_CONSTANT
gibi), değişkenler için küçük harf ve alt çizgi (my_variable
gibi) kullanın.79 karakterden uzun olsa bile etiketler hiçbir zaman bölünmemelidir. Etiketler mümkün olduğunda dize değişmezleri olmalıdır. Mantıksal: Bulma ve değiştirme işlemini kolaylaştırır. Ayrıca okunabilirliği de artırır.
Ad özelliğinin değeri, değişmez bir dize olmalıdır (makrolarda hariç). Mantık: Harici araçlar, bir kurala atıfta bulunmak için ad özelliğini kullanır. Kodu yorumlamak zorunda kalmadan kuralları bulmaları gerekir.
Boole türündeki özellikleri ayarlarken tam sayı değerleri değil, boole değerleri kullanın. Eskiden olduğu gibi kurallar, gerektiğinde tam sayıları doğru veya yanlış değerlere dönüştürmeye devam eder ancak bu işlemden kaçınılması önerilir. Açıklama:
flaky = 1
, "bu hedefi bir kez yeniden çalıştırarak deflake et" şeklinde yanlış anlaşılabilir.flaky = True
açık bir şekilde "bu testte kesintisiz" diyor.
Python ile farklılıklar stil kılavuzu
Python stil kılavuzu ile uyumluluk hedef olsa da birkaç fark vardır:
Satır uzunluğu için katı bir sınır yoktur. Uzun yorumlar ve uzun dizeler genellikle 79 sütuna bölünür ancak bu zorunlu değildir. Kod incelemelerinde veya göndermeden önce komut dosyalarında zorunlu kılınmamalıdır. Mantıksal: Etiketler uzun olabilir ve bu sınırı aşabilir.
BUILD
dosyalarının araçlar tarafından oluşturulması veya düzenlenmesi yaygın bir durumdur. Bu da satır uzunluğu sınırıyla uyumlu değildir.Örtülü dize birleştirme desteklenmez.
+
operatörünü kullanın. Mantık:BUILD
dosyaları birçok dize listesi içerir. Virgülü unutmak kolaydır ve bu da tamamen farklı bir sonuca yol açar. Bu durum geçmişte birçok hataya yol açmıştır. Bu tartışmaya da göz atın.Kurallardaki anahtar kelime bağımsız değişkenleri için
=
işaretinin etrafında boşluk kullanın. Mantıksal: Adlandırılmış bağımsız değişkenler Python'da olduğundan çok daha sık kullanılır ve her zaman ayrı bir satırda yer alır. Boşluklar okunabilirliği artırır. Bu kural uzun zamandır kullanılıyor ve mevcut tümBUILD
dosyalarını değiştirmeye değmez.Varsayılan olarak, dizelerde çift tırnak kullanın. Rasyonale: Bu, Python stil kılavuzunda belirtilmemiş olsa da tutarlılık önermektedir. Bu nedenle, yalnızca çift tırnak içine alınmış dizeleri kullanmaya karar verdik. Birçok dil, dize değişmezleri için çift tırnak kullanır.
İki üst düzey tanım arasında tek bir boş satır kullanın. Mantık:
BUILD
dosyasının yapısı, tipik bir Python dosyasına benzemez. Yalnızca üst düzey ifadeler içerir. Tek boş satır kullanmakBUILD
dosyalarını kısaltır.