Etiketler

Sorun bildirme Kaynağı görüntüleme Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Etiket, bir hedefin tanımlayıcısıdır. Tipik bir etiketin tam kanonik biçimi şu şekildedir:

@@myrepo//my/app/main:app_binary

Etiketin ilk kısmı, @@myrepo kod deposu adıdır. Ç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ündükleri fark etmeksizin bir hedefi açıkça tanımlar.

Kurallı depo adı genellikle @@rules_java++toolchains+local_jdk gibi görünen anlaşılması zor bir dizedir. Daha yaygın olarak görülen ise belirgin bir depo adıyla etiketlerdir. Bu etiketler şu şekilde görünür:

@myrepo//my/app/main:app_binary

Tek fark, depo adının önüne iki yerine bir @ eklenmesidir. Bu, myrepo görünen adıyla bir deposu ifade eder. Bu etiketin göründüğü bağlama göre farklı olabilir.

Bir etiketin, kullanıldığı depoyla aynı depoyu kastettiği durumlarda 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ı, paketin depo köküne göre yolu olan nitelendirilmemiş paket adıdırmy/app/main. Depo adı ve niteliksiz paket adı birlikte tam nitelikli paket adını@@myrepo//my/app/main oluşturur. Etiket, kullanıldığı paketi ifade ettiğinde 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 yöntemlerden biriyle yazılabilir:

app_binary
:app_binary

Dosyalar için iki nokta işaretinin atlanması, kurallar için ise korunması bir kuraldır ancak bu durum başka bir şekilde önemli değildir.

Etiketin iki nokta işaretinden sonraki kısmı (app_binary), niteliksiz 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, aşağıdaki iki etiket eşdeğerdir:

//my/app/lib
//my/app/lib:lib

Paketin bir alt dizinindeki dosya hedefini adı, dosyanın paket köküne (BUILD dosyasını içeren dizin) göreli yoludur. Bu dosya, deponunun my/app/main/testdata alt dizinindedir:

//my/app/main:testdata/input.txt

//my/app ve @@some_repo//my/app gibi dizelerin anlamları, kullanıldıkları bağlama göre değişir: Bazel bir etiket beklediğinde bu dizelerin anlamı sırasıyla //my/app:app ve @@some_repo//my/app:app olur. 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 kullanılmasıdır. //my/app:app ile eşdeğer olduğunu, dolayısıyla mevcut deponun my/app paketindeki app hedefini adlandırdığını unutmayın.

Ancak, paket adının mutlak olduğunu ve çalışma alanının üst düzey dizininde köklendiğini açıkça belirttiği için package_group veya .bzl dosyalarında bir pakete atıfta bulunmak için //my/app kullanılması önerilir.

Göreli etiketler, diğer paketlerdeki hedeflere atıfta bulunmak için kullanılamaz. Bu durumda depo tanımlayıcısı ve paket adı her zaman belirtilmelidir. Örneğin, kaynak ağacı hem my/app paketini hem de my/app/testdata paketini içeriyorsa (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 atıfta bulunmanın iki yolu (biri yanlış, biri doğru) vardır:

Yanlış: testdata farklı bir paket olduğundan göreli yol kullanamazsınız.

testdata/testdepot.zip

Doğru: testdata dosyasını tam yoluyla referans olarak kullanın.

//my/app/testdata:testdepot.zip

@@// ile başlayan etiketler ana depoya yapılan referanslardır ve harici depolardan bile çalışmaya devam eder. Bu nedenle, harici bir depodan referans verildiğinde @@//a/b/c, //a/b/c'ten farklıdır. İlki ana depoya geri dönerken ikincisi //a/b/c öğesini harici depoda arar. Bu, özellikle ana depoda, ana depodaki hedeflere atıfta bulunan ve harici depolardan kullanılacak kurallar yazarken önemlidir.

Hedeflere referans vermenin farklı yolları hakkında bilgi edinmek için hedef kalıpları konusuna bakın.

Bir etiketin söz dizimi özellikleri

Etiket söz dizimi, kabuk için özel anlamı olan meta karakterlerin kullanılmasını engeller. Bu, yanlışlıkla tırnak içine alma sorunlarını önlemeye yardımcı olur ve Bazel Sorgu Dili gibi etiketleri değiştiren araç ve komut dosyalarını oluşturmayı kolaylaştırır.

İzin verilen hedef adlarıyla ilgili ayrıntıları aşağıda bulabilirsiniz.

Hedef adlar: package-name:target-name

target-name, paket içindeki hedefin adıdır. Bir kuralın adı, BUILD dosyasında kuralın tanımındaki name özelliğinin değeridir; bir dosyanın adı, BUILD dosyasını içeren dizinle ilişkili yol adıdır.

Hedef adlar tamamen a-z, A-Z, 0-9 kümesinden alınan karakterlerden ve !%-@^_"#$&'()*-+,;<=>?[]{|}~/. noktalama işaretlerinden oluşmalıdır.

Dosya adları normal biçimdeki göreli yol adları olmalıdır. Yani dosya adları eğik çizgiyle başlamamalı veya bitmemelidir (örneğin, /foo ve foo/ yasaktır) ve yol ayırıcı olarak art arda birden fazla eğik çizgi içermemelidir (örneğin, foo//bar). Benzer şekilde, üst düzey referanslar (..) ve geçerli dizin referansları (./) yasaktır.

Yanlış: Diğer paketlerdeki dosyaları belirtmek için .. kullanmayın.

Doğru: //package-name:filename

Dosya hedefinin adında / kullanılması yaygın olsa da kural adlarında / kullanmaktan kaçının. Özellikle bir etiketin kısaltılmış hali kullanıldığında okuyucunun kafası karışabilir. //foo/bar/wiz etiketi, böyle bir foo/bar/wiz paketi olmasa bile her zaman //foo/bar/wiz:wiz için kısaltmadır; hedef mevcut olsa bile hiçbir zaman //foo:bar/wiz'a atıfta bulunmaz.

Ancak eğik çizginin kullanılmasının uygun olduğu veya hatta bazen gerekli olduğu bazı durumlar vardır. Örneğin, belirli kuralların adı, paketin alt dizininde bulunabilecek ana kaynak dosyalarıyla eşleşmelidir.

Paket adları: //package-name:target-name

Bir paketin adı, kapsayıcı deponun üst düzey dizine göre BUILD dosyasını içeren dizinin adıdır. Örneğin: my/app.

Bazel, teknik düzeyde aşağıdakileri zorunlu kılar:

  • Paket adlarında izin verilen karakterler a ile z arasındaki küçük harfler, A ile Z arasındaki büyük harfler, 0 ile 9 arasındaki rakamlar, ! \"#$%&'()*+,-.;<=>?@[]^_`{|} karakterleri (evet, içinde boşluk karakteri var!) ve tabii ki dizin ayırıcı olduğu için eğik çizgi /'tir.
  • Paket adları eğik çizgi karakteriyle / başlayamaz veya bitemez.
  • Paket adları // alt dizesini içeremez. Bu mantıklı değil. İlgili dizin yolu ne olur?
  • Paket adları /./ veya /../ veya /.../ vb. alt dize içeremez. Bu zorunluluk, yol dizelerindeki nokta karakterinin anlamsal anlamı göz önüne alındığında, mantıksal paket adı ile fiziksel dizin adı arasında çeviri yapılırken karışıklığı önlemek için uygulanır.

Pratik düzeyde:

  • Modül sistemi için önemli bir dizin yapısına sahip bir dil (ör. Java) söz konusu olduğunda, dilde geçerli tanımlayıcı olan dizin adları seçmek önemlidir. Örneğin, başa sayı eklemeyin ve özellikle alt çizgiler ile kısa çizgiler gibi özel karakterlerden kaçının.
  • Bazel, çalışma alanının kök paketindeki hedefleri (ör. //:foo) desteklese de tüm anlamlı paketlerin açıklayıcı adlara sahip olması için bu paketi boş bırakmak en iyisidir.

Kurallar

Kurallar, girişler ile çıkışlar arasındaki ilişkiyi ve çıkışları oluşturma adımlarını belirtir. Kurallar, Derleme Ansiklopedisi'nde açıklandığı gibi derlenmiş yürütülebilir dosyalar ve kitaplıklar, test yürütülebilir dosyaları ve diğer desteklenen çıkışlar üreten birçok farklı türden (bazen kural sınıfı olarak adlandırılır) olabilir.

BUILD dosyaları, kuralları çağırarak hedefleri tanımlar.

Aşağıdaki örnekte, cc_binary kuralı kullanılarak hedef my_app için bir bildirim görüyoruz.

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

Her kural çağrısında, BUILD dosyasının paketinde bir hedefi açıklayan bir name özelliği (geçerli bir hedef adı olmalıdır) bulunur.

Her kuralın bir özellik grubu vardır. Belirli bir kural için geçerli özellikler ve her bir özelliğin önemi ve semantiği, kuralın türüne bağlıdır. Kurallar ve ilgili ö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ı tam sayı, etiket, etiket listesi, dize, dize listesi, çıkış etiketi, çıkış etiketi listesidir. Her kuralda tüm özelliklerin belirtilmesi gerekmez. Bu nedenle özellikler, anahtarlardan (adlar) isteğe bağlı, yazılmış değerlere kadar bir sözlük oluşturur.

Birçok kuralda bulunan srcs özelliğinin türü "etiket listesi"dir; varsa değeri, her biri bu kurala giriş olan bir hedefin adı olan etiketlerin listesidir.

Bazı durumlarda kural türünün adı biraz keyfidir ve daha ilginç olan, kural tarafından oluşturulan dosyaların adlarıdır. Bu durum genrules için de geçerlidir. Daha fazla bilgi için Genel Kurallar: genrule başlıklı makaleyi inceleyin.

Diğer durumlarda ise ad önemlidir: Örneğin, *_binary ve *_test kurallarında kural adı, derleme tarafından üretilen yürütülebilir dosyanın adını belirler.

Hedefler üzerindeki bu yönlendirilmiş acyclic grafiğe hedef grafiği veya derleme bağımlılık grafiği denir ve Bazel Sorgu aracının çalıştığı alandır.

Hedefler BUILD dosyaları