Etiket, bir hedefin tanımlayıcısıdır. Tam kanonik biçimdeki tipik bir etiket şu şekilde görünür:
@@myrepo//my/app/main:app_binary
Etiketin ilk bölümü, depo adıdır (@@myrepo). Çift @ söz dizimi, bunun Workspace'te benzersiz olan bir standart depo adı olduğunu gösterir. Standart depo adlarına sahip etiketler, hangi bağlamda görünürlerse görünsünler hedefi net bir şekilde tanımlar.
Kurallı depo adı genellikle @@rules_java++toolchains+local_jdk gibi görünen gizemli bir dizedir. Çok daha yaygın olarak görülen ise açık depo adını içeren etiketlerdir. Bu etiketler şu şekilde görünür:
@myrepo//my/app/main:app_binary
Tek fark, depo adının iki yerine bir @ ile başlamasıdır.
Bu, myrepo adlı bir depoyu ifade eder. Bu ad, etiketin göründüğü bağlama bağlı olarak farklı olabilir.
Bir etiketin, kullanıldığı aynı depoyu ifade ettiği normal durumda, depo adı kısmı atlanabilir. Bu nedenle, @@myrepo içinde ilk etiket genellikle şu şekilde yazılır:
//my/app/main:app_binary
Etiketin ikinci kısmı, niteliksiz paket adı my/app/main, paketin depodaki köke göre yolu. Depo adı ve niteliksiz paket adı birlikte tam nitelikli paket adını oluşturur
@@myrepo//my/app/main. Etiket, kullanıldığı paketle aynı paketi ifade ediyorsa paket adı (ve isteğe bağlı olarak iki nokta üst üste) atlanabilir. Bu nedenle, @@myrepo//my/app/main içinde bu etiket aşağıdaki şekillerde yazılabilir:
app_binary
:app_binary
İki nokta üst üste işaretinin dosyalarda atlanması, kurallarda ise korunması bir gelenektir ancak bunun dışında önemli bir anlamı yoktur.
İki noktadan sonraki etiket kısmı (app_binary), tam olmayan hedef adıdır. Paket yolunun son bileşeniyle eşleştiğinde bu bileşen ve iki nokta üst üste işareti atlanabilir. Bu nedenle, şu iki etiket eşdeğerdir:
//my/app/lib
//my/app/lib:lib
Paketin bir alt dizinindeki hedef dosyanın adı, dosyanın paket köküne (BUILD dosyasını içeren dizin) göreli yoludur. Bu nedenle, dosya deponun my/app/main/testdata alt dizinindedir:
//my/app/main:testdata/input.txt
//my/app ve @@some_repo//my/app gibi dizeler, kullanıldıkları bağlama bağlı olarak iki anlama gelir: Bazel bir etiket beklediğinde sırasıyla //my/app:app ve @@some_repo//my/app:app anlamına gelirler. Ancak Bazel bir paket beklediğinde (ör. package_group spesifikasyonlarında) bu etiketi içeren pakete referans verir.
BUILD dosyalarında yaygın olarak yapılan bir hata, bir pakete veya paketteki tüm hedeflere atıfta bulunmak için //my/app özelliğinin kullanılmasıdır. Bu özellik, paketteki tüm hedeflere atıfta bulunmaz. Bu komutun //my/app:app ile eşdeğer olduğunu unutmayın. Bu nedenle, mevcut deponun my/app paketindeki app hedefini adlandırır.
Ancak //my/app işaretinin bir pakete atıfta bulunmak için kullanılması, package_group belirtiminde veya .bzl dosyalarında önerilir. Çünkü bu işaret, paket adının mutlak olduğunu ve çalışma alanının üst düzey dizininde bulunduğunu net bir şekilde belirtir.
Diğer paketlerdeki hedeflere başvurmak için göreli etiketler kullanılamaz. Bu durumda, her zaman depo tanımlayıcısı ve paket adı belirtilmelidir.
Örneğin, kaynak ağacında hem my/app paketi hem de my/app/testdata paketi varsa (bu iki dizinin her birinin kendi BUILD dosyası vardır) ikinci paket, testdepot.zip adlı bir dosya içerir. //my/app:BUILD içinde bu dosyaya başvurmanın iki yolu (biri yanlış, biri doğru) aşağıda verilmiştir:
Yanlış: testdata farklı bir paket olduğundan göreli yol kullanamazsınız.
testdata/testdepot.zip
Doğru: testdata öğesine tam yoluyla referans verin.
//my/app/testdata:testdepot.zip@@// ile başlayan etiketler, harici depolardan bile çalışmaya devam edecek olan ana depoya yapılan referanslardır.
Bu nedenle, harici bir depodan referans verildiğinde @@//a/b/c, //a/b/c'den farklıdır.
Birincisi ana depoya geri dönerken ikincisi, harici depoda //a/b/c araması yapar.
Bu durum, özellikle ana depodaki hedeflere atıfta bulunan ve harici depolardan kullanılacak kurallar ana depoda yazılırken geçerlidir.
Hedeflere başvurmanın farklı yolları hakkında bilgi için hedef kalıpları konusuna bakın.
Etiketin sözcüksel özellikleri
Etiket söz dizimi, kabuk için özel anlamı olan meta karakterlerin kullanılmasını engeller. Bu, yanlışlıkla alıntı yapma sorunlarını önlemeye yardımcı olur ve Bazel Sorgu Dili gibi etiketleri değiştiren araçlar ve komut dosyaları oluşturmayı kolaylaştırır.
İzin verilen hedef adlarla ilgili ayrıntıları aşağıda bulabilirsiniz.
Hedef adları: package-name:target-name
target-name, paketteki hedefin adıdır. Bir kuralın adı, BUILD dosyasındaki kural bildiriminde name özelliğinin değeridir. Bir dosyanın adı ise BUILD dosyasını içeren dizine göre dosya yoludur.
Hedef adları tamamen a–z, A–Z, 0–9 karakterleri ve !%-@^_"#$&'()*-+,;<=>?[]{|}~/. noktalama simgelerinden oluşmalıdır.
Dosya adları, normal biçimde göreli yol adları olmalıdır. Bu nedenle, ne eğik çizgiyle başlamalı ne de eğik çizgiyle bitmelidir (örneğin, /foo ve foo/ yasaktır). Ayrıca, yol ayırıcı olarak birden fazla ardışık eğik çizgi içermemelidir (örneğin, foo//bar). Benzer şekilde, üst düzey referanslar (..) ve mevcut dizin referansları (./) yasaktır.
Yanlış: Diğer paketlerdeki dosyalara referans vermek için .. kullanmayın.
Doğru: Kullanım
//package-name:filename
Hedef dosyanın adında / kullanılması yaygın olsa da kuralların adlarında / kullanmaktan kaçının. Özellikle bir etiketin kısa biçimi kullanıldığında okuyucu kafası karışabilir. //foo/bar/wiz etiketi, foo/bar/wiz gibi bir paket olmasa bile her zaman //foo/bar/wiz:wiz için kısa bir ifade biçimidir. Bu etiket, hedef mevcut olsa bile hiçbir zaman //foo:bar/wiz öğesini ifade etmez.
Ancak, eğik çizginin kullanışlı olduğu, hatta bazen gerekli olduğu durumlar da vardır. Örneğin, belirli kuralların adı, paketin bir alt dizininde bulunabilen asıl kaynak dosyasıyla eşleşmelidir.
Paket adları: //package-name:target-name
Paketin adı, BUILD dosyasını içeren dizinin adıdır ve kapsayan deponun üst düzey dizinine göre belirlenir.
Örneğin: my/app.
Teknik düzeyde Bazel, aşağıdakileri zorunlu kılar:
- Paket adlarında küçük harfler (
a-z), büyük harfler (A-Z), rakamlar (0-9), karakterler (! \"#$%&'()*+,-.;<=>?@[]^_`{|}) ve eğik çizgi (/) kullanılabilir. - Paket adları eğik çizgi karakteriyle
/başlayamaz veya bitemez. - Paket adları,
//alt dizesini içeremez. Bu mantıklı olmaz. Karşılık gelen dizin yolu ne olurdu? - Paket adları
/./,/../veya/.../gibi alt dizeleri içeremez. Bu yaptırım, nokta karakterinin yol dizelerindeki anlamsal anlamı göz önüne alındığında, mantıksal bir paket adı ile fiziksel bir dizin adı arasında çeviri yapılırken karışıklığı önlemek için uygulanır.
Pratik düzeyde:
- Modül sistemi için dizin yapısı önemli olan bir dilde (ör. Java) dizin adlarını dilde geçerli tanımlayıcılar olacak şekilde seçmek önemlidir. Örneğin, başa rakam koymayın ve özel karakterlerden (özellikle alt çizgi ve kısa çizgi) kaçının.
- Bazel, çalışma alanının kök paketindeki hedefleri desteklese de (örneğin,
//:foo), tüm anlamlı paketlerin açıklayıcı adlara sahip olması için bu paketi boş bırakmak en iyisidir.
Kurallar
Bir kural, girişler ve çıkışlar arasındaki ilişkiyi ve çıkışları oluşturma adımlarını belirtir. Kurallar, derlenmiş yürütülebilir dosyalar ve kitaplıklar, test yürütülebilir dosyaları ve Build Encyclopedia'da açıklandığı gibi desteklenen diğer çıkışları üreten birçok farklı türde (bazen kural sınıfı olarak adlandırılır) olabilir.
BUILD dosyaları, kuralları çağırarak hedefler bildirir.
Aşağıdaki örnekte, my_app hedefinin cc_binary kuralı kullanılarak bildirimi gösterilmektedir.
cc_binary(
name = "my_app",
srcs = ["my_app.cc"],
deps = [
"//absl/base",
"//absl/strings",
],
)
Her kural çağrısında, name özelliği (geçerli bir hedef adı olmalıdır) bulunur. Bu özellik, BUILD dosyasının paketindeki bir hedefi bildirir.
Her kuralın bir dizi özelliği vardır. Belirli bir kural için geçerli olan özellikler ile her özelliğin önemi ve anlamı, kuralın türüne bağlıdır. Kuralların ve bunlara karşılık gelen özelliklerin listesi için Build Encyclopedia'ya bakın. Her özelliğin bir adı ve türü vardır. Bir özelliğin sahip olabileceği yaygın türlerden bazıları şunlardır: tam sayı, etiket, etiket listesi, dize, dize listesi, çıkış etiketi, çıkış etiketi listesi. Her kuralda tüm özelliklerin belirtilmesi gerekmez. Bu nedenle özellikler, anahtarlardan (adlar) isteğe bağlı, türü belirlenmiş değerlere kadar bir sözlük oluşturur.
Birçok kuralda bulunan srcs özelliği "etiket listesi" türündedir. Varsa değeri, her biri bu kurala giriş olan bir hedefin adı olan etiketlerin listesidir.
Bazı durumlarda, kural türünün adı biraz rastgeledir. Kural tarafından oluşturulan dosyaların adları daha ilgi çekicidir. Bu durum, genrules için de geçerlidir. Daha fazla bilgi için Genel Kurallar: genrule başlıklı makaleye bakın.
Diğer durumlarda ise ad önemlidir: Örneğin, *_binary ve *_test kurallarında kural adı, derleme tarafından oluşturulan yürütülebilir dosyanın adını belirler.
Hedefler üzerindeki bu yönlendirilmiş döngüsüz grafiğe hedef grafiği veya derleme bağımlılığı grafiği adı verilir ve Bazel Query aracı bu alan üzerinde çalışır.
| Hedefler | BUILD dosyaları |