Etiketler

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 standart depo adı olduğunu gösterir. Bu ad, çalışma alanında benzersizdir. 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~7.1.0~toolchains~local_jdk gibi görünen gizemli bir dizedir. Çok daha yaygın olarak görülen ise açık depo adları 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 dosyalar için atlanması, kurallar için ise korunması bir gelenektir ancak başka bir önemi yoktur.

İki noktadan sonraki etiket kısmı (app_binary), tam nitelikli olmayan hedef addı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, bu amaçla kullanılamaz. 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 sembolünün bir paketi belirtmek için kullanılması, paket adının mutlak olduğunu ve çalışma alanının üst düzey dizininde kök saldığını net bir şekilde ilettiği için package_group belirtiminde veya .bzl dosyalarında önerilir.

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 önemlidir.

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: `//package-name:filename` ifadesini kullanın.

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 okuyucunun kafası karışabilir. //foo/bar/wiz etiketi, foo/bar/wiz paketi olmasa bile her zaman //foo/bar/wiz:wiz için kısa bir ifadedir. 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.

Paket adları tamamen A-Z, a–z, 0–9, "/", "-", ".", "@" ve "_" karakterlerinden oluşmalı ve eğik çizgiyle başlamamalıdır.

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.

Bazel, çalışma alanının kök paketindeki hedefleri (örneğin, //:foo) desteklese de tüm anlamlı paketlerin açıklayıcı adlara sahip olması için bu paketi boş bırakmak en iyisidir.

Paket adları // alt dizesini içeremez ve eğik çizgiyle bitemez.

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ğinin (geçerli bir hedef adı olmalıdır) bulunduğu BUILD dosyasının paketindeki bir hedef bildirilir.

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 çalıştırılabilir 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.