BUILD
dosya biçimlendirmesi, Go ile aynı yaklaşımı izler. Standartlaştırılmış
aracı sayesinde çoğu biçimlendirme sorununu halleder.
Derleyici, bir görevi yapılandırarak
kaynak kodu standart bir stilde yayar. Dolayısıyla her BUILD
dosyası
biçimlendirmenin sorun olmamasına neden olur. Bu nedenle,
kod yorumları vardır. Ayrıca araçların
anlaşılmasını, düzenlenmesini ve
BUILD
dosyası oluştur.
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 yorum arasında ayrım yapar ekleyebilirsiniz. Bir yorum belirli bir öğeye eklenmemişse şunu kullanın: boş bir satır olur. RACI matrisinde yapılan değişiklikler (örneğin, kuralı silerken yorumu muhafaza etme veya kaldırma).
# 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şvurulmalıdır
(..
gibi yukarı referanslar kullanmadan) Oluşturulan dosyalar
":
" ön ekini alır belirtmiyorlar. Kaynak dosyalar
:
öneki olmamalıdır. Kurallara :
ön eki eklenmelidir. Örneğin,
Örneğin, x.cc
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
hedef, genellikle söz konusu kaynaktan türetilmiş bir ada sahip olmalıdır (örneğin,
chat.cc
için cc_library
, chat
veya şunun için java_library
olarak adlandırılabilir:
DirectMessage.java
direct_message
olarak adlandırılabilir).
Bir paketin adını taşıyan hedefi (aynı ada sahip hedef içeren dizin), dizin adı. Böyle bir hedef yoksa aynı adı oluşturmayın hedefi belirleyebilirsiniz.
Aynı ada sahip bir hedefe atıfta bulunurken kısa adı kullanmayı tercih et (//x
(//x:x
yerine). Aynı paketteyseniz yerel
referans (//x
yerine :x
).
"Ayrılmış" ifadesini kullanmaktan kaçının hedef isimleri tanımlamasına yardımcı olur. Buna şunlar dâhildir:
all
, __pkg__
ve __subpackages__
, bu adlar özel
anlamları üzerinde durabilir ve kullanıldıklarında karışıklığa ve beklenmeyen davranışlara neden olabilir.
Geçerli bir ekip kongresi olmadığında bu kurallar projeyi Google'da yaygın olarak kullanılan öneriler:
- Genel olarak "snake_case" kullanın.
- Bir
src
içerenjava_library
için bu, farklı bir ad kullanılması anlamına gelir uzantısı olmayan dosya adıyla aynıdır - Java
*_binary
ve*_test
kuralları için şunu kullanın: "Üst CamelCase". Bu, hedef adınsrc
öğelerinden biriyle eşleşmesine olanak tanır. Örneğin,java_test
değeri,test_class
özelliğinin hedefin adından türetilir.
- Bir
- Belirli bir hedefin birden çok varyantı varsa
belirsizliklerini ortadan kaldırmak (örneğin,
: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ındaki çakışmaları önler.- Protoyla ilgili hedefler için:
proto_library
hedef,_proto
ile biten adlara sahip olmalıdır- Dillere özgü
*_proto_library
kuralları, temeldekiyle eşleşmelidir protokolü, ancak_proto
öğesini aşağıdakiler gibi dile özgü bir son ekle değiştirin: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, erişim izni verilmeden önce olabildiğince yakın bir şekilde ayarlanmalıdır.
ve ters bağımlılıklara
göre şekillendirebilirsiniz. __pkg__
ve __subpackages__
öğelerini şu şekilde kullan:
uygun olmalıdır.
default_visibility
paketini //visibility:public
olarak ayarlamaktan kaçının.
//visibility:public
yalnızca şuradaki hedefler için ayrı ayrı ayarlanmalıdır:
projenin herkese açık API'sini ekleyin. Bunlar, sisteme bağımlı
olarak tasarlanan kitaplıklar olabilir.
tarafından kullanılabilecek harici projeler veya ikili programlar tarafından
geliştirmenizi sağlar.
Bağımlılıklar
Bağımlılıklar doğrudan bağımlılıklarla (bağımlılıklar için gerekli). Geçişli bağımlılıkları listelemeyin.
Paket-yerel bağımlılıklar ilk olarak listelenmeli ve belirli bir şekilde atıfta bulunulmalıdır aşağıdakilerle uyumlu: Mevcut paketteki hedeflere referanslar bölümüne bakın (mutlak paket adlarına göre değil).
Bağımlılıkları doğrudan, tek bir liste olarak listelemeyi tercih edin. "Ortak" kavramı birkaç hedefin değişkene olan bağımlılıkları sürdürülebilirliği azaltır, araçların hedefin bağımlılıklarını değiştirmesi imkansızdır ve bağımlılıkları ortadan kaldırmaktır.
Küreler
"Hedef yok" belirtebilirsiniz []
ile birlikte. Hiçbir şeyle eşleşmeyen bir glob kullanmayın:
boş listelere kıyasla hataya daha açık ve daha az belirgindir.
Yinelenen
Kaynak dosyaları eşleştirmek için yinelemeli glob'ları kullanmayın (örneğin,
glob(["**/*.java"])
) bilgileri gösterilir.
Yinelemeli glob'lar, BUILD
dosya atlandığı için dosya üzerinde akıl yürütmeyi zorlaştırıyor
BUILD
dosya içeren alt dizinler.
Yinelemeli glob'lar genellikle başına bir BUILD
dosyasına sahip olmaktan daha az verimlidir
bir bağımlılık grafiği olduğundan emin olun. Bu sayede,
uzaktan önbelleğe alma ve paralellik.
Her dizin için bir BUILD
dosyası yazmak ve
bağımlılık grafiğini görebilirsiniz.
Yinelemesiz
Yinelenmeyen glob'lar genellikle kabul edilir.
Diğer kurallar
Sabit değerleri belirtmek için büyük harf ve alt çizgi kullanın (ör.
GLOBAL_CONSTANT
), Değişkenleri belirtmek için küçük harf ve alt çizgi kullanın (ör.my_variable
).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: Hedeflerin bulma ve değiştirme kolaylığı. Ayrıca okunabilirliği de iyileştirir.
Ad özelliğinin değeri, düz bir sabit dize olmalıdır ( makrolarında) yer alır. Rasyonalite: Harici araçlar, bir kuralı. 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ği gibi boole'lere dönüştürmeye devam etmektedir ancak bu önerilmez. Gerekçe:
flaky = 1
, şöyle bir şekilde yanlış anlaşılabilir: "bir kez yeniden çalıştırarak bu hedefin seviyesini düşür".flaky = True
açık bir şekilde diyor "bu test güvenilir değildir".
Python ile farklılıklar stil kılavuzu
Her ne kadar Python stil kılavuzu arasında birkaç fark vardır:
Kesin bir satır uzunluğu sınırı yoktur. Uzun yorumlar ve uzun dizeler genellikle bölünür 79 sütuna ekleyebilirsiniz, ancak bu zorunlu değildir. Kodda zorunlu kılınmamalıdır. ve ön gönderim komut dosyalarından yararlanabilirsiniz. Mantıksal: Etiketler uzun olabilir ve bunu aşabilir limit.
BUILD
dosyalarının araçlar tarafından oluşturulması veya düzenlenmesi yaygın bir durumdur. Bu, 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. İnsanın aklında olmayan bir virgül koyarak tamamen farklı bir sonuç elde edebilirsiniz. Bu durum, proje yönetiminde tercih edebilir. Bu tartışmaya da bakın.Kurallardaki anahtar kelime bağımsız değişkenleri için
=
işaretinin çevresindeki boşluklar kullanın. Gerekçe: 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ıra ekleyin. Alanlar okunabilirliği iyileştirir. Bu kongre yıl sonuna kadar uzun bir süre saklamaya devam eder ve mevcut tümBUILD
dosyalarını değiştirmeniz gerekmez.Varsayılan olarak, dizeler için çift tırnak işareti kullanın. Mantıksal: belirtilenlere benzer, ancak tutarlılık önerir. Bu yüzden yalnızca çift tırnak içeren dizeler kullanılmasına karar verdi. Birçok dilde çift tırnak işareti kullanılır kullanabilirsiniz.
İki üst düzey tanım arasında tek bir boş satır kullanın. Gerekçe:
BUILD
dosyasının yapısı tipik bir Python dosyasına benzer değildir. Yalnızca söz konusu olabilir. Tek bir boş satır kullanırsanızBUILD
dosyaları daha kısa olur.