BUILD
dosya biçimlendirmesi, çoğu biçimlendirme sorununun standart bir araç tarafından ele alındığı Go ile aynı yaklaşımı uygular.
Buildifier, kaynak kodunu standart bir stilde ayrıştırıp yayan 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ı da kolaylaştırır.
BUILD
dosya biçimlendirmesi, buildifier
çıktısıyla 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)
load()
ekstresinin tümüpackage()
işlevi.Kurallara ve makrolara yapılan çağrılar
Derleyici, bağımsız bir yorum ile bir öğeye ekli yorum arasında ayrım yapar. Bir yorum belirli bir öğeye ekli değilse arkasından 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 dizinine göre kendi yollarıyla başvuruda bulunulmalıdır (..
gibi yukarı referanslar hiç kullanılmadan). Oluşturulan dosyalara kaynak olmadıklarını belirtmek için ":
" öneki eklenmelidir. Kaynak dosyalara :
ön eki eklenmemelidir. Kurallara :
ön eki eklenmelidir. Örneğin, x.cc
değerinin 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, bir kaynak dosya içeriyorsa hedefin genellikle bu kaynaktan türetilmiş bir adı olmalıdır (örneğin, chat.cc
için cc_library
, chat
veya DirectMessage.java
için java_library
olarak direct_message
adlandırılabilir).
Bir paketin adını taşıyan hedefi (içeren dizinle aynı ada sahip hedef), dizin adında 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 hedefe atıfta bulunurken kısa adı kullanmayı 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. Buna all
, __pkg__
ve __subpackages__
dahildir. Bu adlar özel anlamlara sahiptir ve kullanıldıklarında karışıklığa ve beklenmeyen 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 kullanılması anlamına gelir - Java
*_binary
ve*_test
kuralları için "Upper CamelCase" değerini kullanın. Bu, hedef adınsrc
öğelerinden biriyle eşleşmesine olanak tanır.java_test
için bu,test_class
özelliğinin hedef adından çıkarılabilmesini 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
son eki,_test
,_unittest
,Test
veyaTests
ile hedeflenir_lib
veya_library
gibi anlamsız son ekler kullanmaktan kaçının (_library
hedefi ile karşılık gelen_binary
arasında çakışmaları önlemek için gerekli olmadığı sürece)- Protoyla ilgili hedefler için:
proto_library
hedef,_proto
ile biten adlara sahip olmalıdır- Dillere özgü
*_proto_library
kuralları, temel alınan protokolle eşleşmeli ancak_proto
yerine aşağıdaki gibi bir dile özgü sonek eklemelidir: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. __pkg__
ve __subpackages__
öğelerini uygun şekilde 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 projelerden yararlanmak üzere tasarlanmış kitaplıklar veya harici bir projenin derleme sürecinde kullanılabilecek ikili programlar 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, yukarıdaki Mevcut paketteki hedeflere yapılan referanslar bölümünde (mutlak paket adlarıyla değil) uyumlu şekilde listelenmeli ve bunlara atıfta bulunulmalıdır.
Bağımlılıkları doğrudan, tek bir liste olarak 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 hedef bağımlılıklarını değiştirmesini imkansız kılar ve kullanılmayan bağımlılıklara yol açabilir.
Küreler
[]
ile "hedef yok" belirtebilirsiniz. Hiçbir şeyle eşleşmeyen bir glob kullanmayın. Bu, boş bir listeye göre daha hataya açık ve daha az belirgindir.
Yinelenen
Kaynak dosyaları eşleştirmek için yinelemeli glob'ları kullanmayın (örneğin, glob(["**/*.java"])
).
Yinelemeli glob'lar, BUILD
dosyalarını içeren alt dizinleri atladıkları için BUILD
dosyalarını akıl yürütmeyi zorlaştırır.
Yinelemeli glob'lar, daha iyi uzaktan önbelleğe alma ve paralellik sağladığından, aralarında bağımlılık grafiği bulunan bir dizin başına BUILD
dosyasına sahip olmaktan genellikle daha az verimlidir.
Her dizin için bir BUILD
dosyası yazmak ve bunlar arasında bir bağımlılık grafiği tanımlamak iyi bir uygulamadır.
Yinelemesiz
Yinelenmeyen glob'lar genellikle kabul edilir.
Diğer kurallar
Sabit değerleri (ör.
GLOBAL_CONSTANT
) bildirmek için büyük harf ve alt çizgi, değişkenleri (ör.my_variable
) bildirmek için küçük harf ve alt çizgi kullanın.79 karakterden uzun olsa bile etiketler hiçbir zaman bölünmemelidir. Etiketler, mümkün olduğunda dize değişmez değeri olmalıdır. Mantıksal: Bulma ve değiştirme işlemini kolaylaştırır. Ayrıca okunabilirliği de iyileştirir.
Ad özelliğinin değeri, sabit bir sabit dize olmalıdır (makrolar hariç). Rasyonalite: Harici araçlar, bir kuralı belirtmek için ad özelliğini kullanır. Kodu yorumlamak zorunda kalmadan kuralları bulmaları gerekir.
Boole türündeki özellikleri ayarlarken tam sayı değerlerini değil, boole değerlerini kullanın. Eski nedenlerden dolayı, kurallar tam sayıları gerektiğinde boole'lere dönüştürmeye devam eder ancak bu önerilmez. Mantıksal:
flaky = 1
, "bu hedefin tabanını bir kez yeniden çalıştırarak boşaltın" şeklinde yanlış okunabilir.flaky = True
açık bir şekilde "bu testte kesintisiz" diyor.
Python ile farklılıklar stil kılavuzu
Python stil kılavuzuyla uyumluluk hedef olsa da bazı farklılıklar vardır:
Kesin bir satır uzunluğu 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 ön gönderme 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 durum, satır uzunluğu sınırlamasına uygun değildir.Örtülü dize birleştirmesi desteklenmez.
+
operatörünü kullanın. Mantıksal:BUILD
dosyaları çok sayıda dize listesi içeriyor. Virgül kolayca unutulabiliyor. Bu da tamamen farklı bir sonuç doğuruyor. Bu durum geçmişte birçok hataya yol açmıştır. Bu tartışmaya da bakın.Kurallardaki anahtar kelime bağımsız değişkenleri için
=
işaretinin çevresindeki boşluklar 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. Alanlar okunabilirliği iyileştirir. Bu kural uzun zamandır kullanılıyor ve mevcut tümBUILD
dosyalarını değiştirmenize değmez.Varsayılan olarak, dizeler için çift tırnak işareti kullanın. Rasyonale: Bu, Python stil kılavuzunda belirtilmemiş olsa da tutarlılık önermektedir. Bu yüzden yalnızca çift tırnak içeren dizeler kullanmaya karar verdik. Birçok dil, düz dizeler için çift tırnak işareti kullanır.
İki üst düzey tanım arasında tek bir boş satır kullanın. Mantıksal:
BUILD
dosyasının yapısı, tipik bir Python dosyasına benzer değildir. Yalnızca üst düzey ifadeler vardır. Tek bir boş satır kullanırsanızBUILD
dosyaları daha kısa olur.