Bu bölümde, birçok işlev veya derleme kuralında ortak olan çeşitli terimler ve kavramlar tanımlanmaktadır.
İçindekiler
- Bourne kabuğu jeton oluşturma
- Etiket genişletme
- Çoğu derleme kuralı tarafından tanımlanan tipik özellikler
- Tüm derleme kuralları için ortak özellikler
- Tüm test kurallarında ortak olan özellikler (*_test)
- Tüm ikili kurallara ortak özellikler (*_binary)
- Yapılandırılabilir özellikler
- Yarı açık çıkış hedefleri
Bourne kabuğu parçalama
Bazı kuralların belirli dize özellikleri, Bourne kabuğunun tokenizasyon kurallarına göre birden fazla kelimeye bölünür: Tırnak işareti içinde olmayan boşluklar ayrı kelimeleri sınırlar ve tek ve çift tırnaklı karakterler ile ters eğik çizgiler, belirteçlemeyi önlemek için kullanılır.
Bu jeton oluşturmaya tabi olan özellikler, bu dokümanda tanımları
"Yap" değişken genişletmesine ve Bourne kabuk belirteçleştirmesine tabi özellikler, genellikle rastgele seçenekleri derleyicilere ve diğer araçlara iletmek için kullanılır. Bu tür özelliklere örnek olarak cc_library.copts ve java_library.javacopts verilebilir.
Bu ikameler birlikte, tek bir dize değişkeninin yapılandırmaya özgü bir seçenek kelimeleri listesine genişlemesine olanak tanır.
Etiket genişletme
Çok az sayıda kuralın bazı dize özellikleri etiket genişletmesine tabidir: Bu dizeler, alt dize olarak geçerli bir etiket (ör. //mypkg:target) içeriyorsa ve bu etiket geçerli kuralın tanımlanmış bir ön koşuluysa hedef //mypkg:target ile temsil edilen dosyanın yol adı olarak genişletilir.
genrule.cmd ve cc_binary.linkopts, örnek özelliklere örnek olarak verilebilir. Ayrıntılar, göreli etiketlerin genişletilip genişletilmediği ve birden çok dosyaya genişleyen etiketlerin nasıl ele alındığı gibi sorunlara göre her durumda önemli ölçüde farklılık gösterebilir. Ayrıntılı bilgi için kural özelliği dokümanlarına bakın.
Çoğu derleme kuralı tarafından tanımlanan tipik özellikler
Bu bölümde, birçok derleme kuralı tarafından tanımlanan özellikler açıklanmaktadır.
| Özellik | Açıklama |
|---|---|
data |
Etiketler listesi; varsayılan değer Bu kuralın çalışma zamanında ihtiyaç duyduğu dosyalar. Dosya veya kural hedeflerini listeleyebilir. Genellikle tüm hedeflere izin verir.
Yeni kurallar, çalışma zamanında başka girişler kullanabilecek girişleri işlerse bir |
deps |
Etiketler listesi; varsayılan değer
Bu hedefin bağımlılıkları. Genellikle yalnızca kural hedeflerini listelemelidir. (Bazı kurallar, dosyaların doğrudan Dile özgü kurallar, listelenen hedefleri genellikle belirli sağlayıcılara sahip olanlarla sınırlar.
Bir hedefin
|
licenses |
Dize listesi; yapılandırılabilir olmayan;
varsayılan değer Bu hedef için kullanılacak lisans türü dizelerinin listesi. Bu, Bazel'in artık kullanmadığı, desteği sonlandırılmış bir lisanslama API'sinin bir parçasıdır. Bunu kullanmayın. |
srcs |
Etiketler listesi; varsayılan değer
Bu kural tarafından işlenen veya dahil edilen dosyalar. Genellikle dosyaları doğrudan listeler ancak varsayılan çıkışlarını içerecek şekilde kural hedeflerini ( Dile özgü kurallar genellikle listelenen dosyaların belirli dosya uzantılarına sahip olmasını gerektirir. |
Tüm derleme kuralları için ortak özellikler
Bu bölümde, tüm derleme kurallarına dolaylı olarak eklenen özellikler açıklanmaktadır.
| Özellik | Açıklama |
|---|---|
compatible_with |
Etiketler listesi;
yapılandırılamaz; varsayılan değer Varsayılan olarak desteklenen ortamlara ek olarak bu hedefin oluşturulabileceği ortamların listesi. Bu, kullanıcıların hangi hedeflerin birbirine bağlı olabileceğini ve hangilerinin bağlı olamayacağını belirtmesine olanak tanıyan Bazel'in kısıtlama sisteminin bir parçasıdır. Örneğin, harici olarak dağıtılabilir ikili dosyalar, şirket gizli kodu içeren kitaplıklara bağlı olmamalıdır. Ayrıntılar için ConstraintSemantics bölümüne bakın. |
deprecation |
Dize; yapılandırılabilir değil; varsayılan değer Bu hedefle ilişkili açıklayıcı bir uyarı mesajı. Bu genellikle bir hedefin eskidiğini veya başka bir kural tarafından yerini aldığını, bir pakete özel olduğunu ya da herhangi bir nedenle zararlı olduğunu bildirmek için kullanılır. Mesajın gösterilmesini önlemek için hangi değişikliklerin yapılması gerektiğini kolayca anlayabilmeleri amacıyla bir referans (ör. web sayfası, hata numarası veya örnek taşıma CL'leri) eklemek iyi bir fikirdir. Doğrudan değiştirme olarak kullanılabilecek yeni bir hedef varsa eski hedefin tüm kullanıcılarını taşımak iyi bir fikirdir.
Bu özelliğin, derleme şekli üzerinde bir etkisi yoktur ancak derleme aracının teşhis çıktısını etkileyebilir. Derleme aracı, Paket içi bağımlılıklar bu uyarıdan muaftır. Böylece, örneğin, desteği sonlandırılmış bir kuralın testleri oluşturulduğunda bir uyarıyla karşılaşmazsınız. Desteği sonlandırılan bir hedef, desteği sonlandırılan başka bir hedefe bağlıysa uyarı mesajı gönderilmez. Kullanıcılar bu kampanyayı kullanmayı bıraktıktan sonra hedef kaldırılabilir. |
distribs |
Dize listesi; yapılandırılamaz;
varsayılan değer Bu hedef için kullanılacak dağıtım yöntemi dizelerinin listesi. Bu, Bazel'in artık kullanmadığı, desteği sonlandırılmış bir lisanslama API'sinin parçasıdır. Bunu kullanmayın. |
exec_compatible_with |
Etiketler listesi;
yapılandırılamaz; varsayılan değer
Bu hedefin yürütme platformunda bulunması gereken |
exec_properties |
Dize sözlüğü; varsayılan değer Bu hedef için seçilen bir platformun Hem platform hem de hedef düzeyindeki özelliklerde bir anahtar varsa değer hedeften alınır. |
features |
Özellik dizelerinin listesi; varsayılan değer Özellik, bir hedefte etkinleştirilebilen veya devre dışı bırakılabilen dize etiketidir. Bir özelliğin anlamı, kuralın kendisine bağlıdır. Bu |
restricted_to |
Etiketler listesi;
yapılandırılamaz; varsayılan değer Varsayılan olarak desteklenen ortamlar yerine bu hedefin derlenebileceği ortamların listesi.
Bu, Bazel'in kısıtlama sisteminin bir parçasıdır. Ayrıntılar için |
tags |
Dize listesi; yapılandırılamaz;
varsayılan değer
Etiketler herhangi bir kuralda kullanılabilir. Test ve
Bazel, herhangi bir testin veya
Testlerdeki etiketler, genellikle hata ayıklama ve yayınlama sürecinizde testin rolüne ek açıklama eklemek için kullanılır. Etiketler genellikle, çalışma zamanında ek açıklama özelliği olmayan C++ ve Python testlerinde en yararlı olur. Etiketlerin ve boyut öğelerinin kullanılması, test paketlerinin kod tabanı kontrol politikasına göre derlenmesinde esneklik sağlar.
Bazel, test kuralının
|
target_compatible_with |
Etiketler listesi; varsayılan değer
Bu hedefin uyumlu olarak kabul edilmesi için hedef platformda bulunması gereken Geçişli olarak uyumsuz hedeflere bağlı olan hedefler kendi başına uyumsuz olarak kabul edilir. Ayrıca derleme ve test için atlanır. Boş bir liste (varsayılan değerdir) hedefin tüm platformlarla uyumlu olduğunu gösterir.
Workspace Kuralları dışındaki tüm kurallar bu özelliği destekler.
Bazı kurallarda bu özelliğin herhangi bir etkisi yoktur. Örneğin,
Uyumlu olmayan hedef atlama hakkında daha fazla bilgi için Platformlar sayfasına bakın. |
testonly |
Boole; yapılandırılamaz; test ve test grubu hedefleri hariç varsayılan değer
Benzer şekilde,
Testler ( Bu özelliğin amacı, hedefin üretime sunulan ikili dosyalarda bulunmaması gerektiğidir. testonly, çalışma zamanında değil derleme zamanında uygulanır ve bağımlılık ağacında viral olarak yayılır. Bu nedenle, testonly dikkatli bir şekilde uygulanmalıdır. Örneğin, birim testleri için yararlı olan saplama ve sahte öğeler, üretime yayınlanacak aynı ikili programları içeren entegrasyon testleri için de yararlı olabilir ve bu nedenle muhtemelen yalnızca test olarak işaretlenmemelidir. Buna karşılık, normal davranışı koşulsuz olarak geçersiz kıldığı için bağlantı oluşturmak bile tehlikeli olan kurallar kesinlikle testonly olarak işaretlenmelidir. |
toolchains |
Etiketler listesi;
yapılandırılamaz; varsayılan değer
Bu hedefin Değişkenleri oluşturma özelliğine erişmesine izin verilen hedef grubu. Bu hedefler,
Bunun, platforma bağımlı yapılandırma için kural uygulamalarında kullanılan araç zinciri çözümü kavramından farklı olduğunu unutmayın. Bir hedefin hangi |
visibility |
Etiketler listesi;
yapılandırılamaz;
varsayılan olarak, belirtilmişse paket'ten
Bir hedefteki |
Tüm test kuralları için ortak özellikler (*_test)
Bu bölümde, tüm test kuralları için ortak olan özellikler açıklanmaktadır.
| Özellik | Açıklama | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Dize listesi; $(location) ve "Değişken oluştur" yerine koyma işlemine ve Bourne kabuğu jetonuna tabidir; varsayılan değer Bazel,
Bu bağımsız değişkenler, |
||||||||||||||||||||
env |
Dize dizini; değerler $(location) ve "Değişken oluştur" yerine koyma işlemine tabidir; varsayılan değer
Test,
Bu özellik yalnızca |
||||||||||||||||||||
env_inherit |
Dize listesi; varsayılan değer: Test
Bu özellik yalnızca |
||||||||||||||||||||
size |
Bir test hedefinin "ağırlığını", yani çalıştırılması için ne kadar zaman/kaynak gerektiğini belirtir. Birim testleri "küçük", entegrasyon testleri "orta" ve uçtan uca testler "büyük" veya "devasa" olarak kabul edilir. Bazel, varsayılan zaman aşım süresini belirlemek için boyutu kullanır. Bu süre, Test boyutları aşağıdaki varsayılan zaman aşımlarına ve varsayılan en yüksek yerel kaynak kullanımlarına karşılık gelir:
|
||||||||||||||||||||
timeout |
Testin sonuç döndürmeden önce ne kadar süre çalışacağı.
Bir testin boyut özelliği, kaynak tahminini kontrol ederken testin zaman aşımı bağımsız olarak ayarlanabilir. Belirtilmemişse zaman aşımı, testin boyutuna göre belirlenir. Test zaman aşımı,
Yukarıdakilerden farklı zamanlarda, test zaman aşımı
|
||||||||||||||||||||
flaky |
Boole; yapılandırılamaz;
varsayılan değer Testi kararsız olarak işaretler. Ayarlanırsa testi üç defaya kadar yürütür ve yalnızca her defasında başarısız olursa testi başarısız olarak işaretler. Varsayılan olarak bu özellik False olarak ayarlanır ve test yalnızca bir kez çalıştırılır. Bu özelliğin kullanılması genellikle önerilmez. İddialar doğru olduğunda testler güvenilir bir şekilde geçmelidir. |
||||||||||||||||||||
shard_count |
50'den küçük veya 50'ye eşit pozitif tam sayı; varsayılan değer Testi çalıştırmak için kullanılacak paralel kırık sayısını belirtir. Bu değer ayarlanırsa bu değer, testin yürütüleceği paralel parça sayısını belirlemek için kullanılan tüm buluşsal yöntemleri geçersiz kılar. Bazı test kurallarında, parçalamanın en baştan etkinleştirilmesi için bu parametrenin gerekli olabileceğini unutmayın. Test bölme işlemi etkinse Bölme işlemi için test çalıştırıcısının test bölme protokolünü desteklemesi gerekir. Aksi takdirde, büyük olasılıkla her testi her parçada çalıştırır. Bu da istediğiniz şey değildir. Parçalama hakkında ayrıntılı bilgi için Test Ansiklopedisi'ndeki Test Parçalama bölümüne bakın. |
||||||||||||||||||||
local |
Boole; yapılandırılamaz;
varsayılan değer Testin, korumalı alan olmadan yerel olarak çalıştırılmasını zorunlu kılar. Bu değerin True olarak ayarlanması, etiket olarak "local" ( |
Tüm ikili kurallarda ortak özellikler (*_ikili)
Bu bölümde, tüm ikili kurallarda ortak olan özellikler açıklanmaktadır.
| Özellik | Açıklama |
|---|---|
args |
Dize listesi; $(location) ve "Değişken oluştur" yerine koyma işlemine ve Bourne kabuğu jetonuna tabidir; yapılandırılamaz; varsayılan değer
Bazel'in
NOT: Hedefi Bazel dışında çalıştırdığınızda (örneğin, |
env |
Dize sözlüğü; değerler $(location) ve "Değişken oluştur" yerine koyma işlemine tabidir; varsayılan değer Hedef,
Bu özellik yalnızca
NOT: Hedefi Bazel dışında çalıştırdığınızda (örneğin, |
output_licenses |
Dize listesi; varsayılan değer: Bu ikili dosyanın oluşturduğu çıkış dosyalarının lisansları. Bu, Bazel'in artık kullanmadığı, desteği sonlandırılmış bir lisanslama API'sinin parçasıdır. Bunu kullanmayın. |
Yapılandırılabilir özellikler
Çoğu özellik "yapılandırılabilir"dir. Yani hedef farklı şekillerde oluşturulduğunda değerleri değişebilir. Özellikle, yapılandırılabilir özellikler Bazel komut satırına iletilen işaretlere veya hedefin alt akıştaki bağımlılığından gelen isteğe bağlı olarak değişebilir. Bu, örneğin, hedefi birden fazla platform veya derleme modu için özelleştirmek amacıyla kullanılabilir.
Aşağıdaki örnekte, farklı hedef mimarileri için farklı kaynaklar belirtilmektedir. bazel build :multiplatform_lib --cpu x86 çalıştırıldığında hedef x86_impl.cc kullanılarak oluşturulur. --cpu arm yerine arm_impl.cc kullanması için --cpu arm yerine arm_impl.cc yazın.
cc_library(
name = "multiplatform_lib",
srcs = select({
":x86_mode": ["x86_impl.cc"],
":arm_mode": ["arm_impl.cc"]
})
)
config_setting(
name = "x86_mode",
values = { "cpu": "x86" }
)
config_setting(
name = "arm_mode",
values = { "cpu": "arm" }
)
select() işlevi, yapılandırılabilir bir özellik için farklı alternatif değerler arasından seçim yapar. Bu seçim, hedefin yapılandırmasının karşıladığı config_setting veya constraint_value ölçütlerine göre yapılır.
Bazel, yapılandırılabilir özellikleri makroları işledikten sonra ve kuralları işlemeden önce (teknik olarak loading ve analysis aşamaları arasında) değerlendirir.
select() değerlendirmesinden önceki işlemlerde select() öğesinin hangi dalı seçtiği bilinemez. Örneğin, makrolar davranışlarını seçilen dala göre değiştiremez ve bazel query yalnızca bir hedefin yapılandırılabilir bağımlılıkları hakkında ihtiyatlı tahminler yürütebilir. select() öğesini kurallar ve makrolarla kullanma hakkında daha fazla bilgi için
bu SSS bölümüne bakın.
Dokümanlarında nonconfigurable işaretli özellikler bu özelliği kullanamaz. Genellikle bir özellik yapılandırılamaz. Bunun nedeni, Bazel'in bir select() sorununun nasıl çözümleneceğini belirleyebilmesi için Bazel'in dahili olarak değerini bilmesi gerekir.
Ayrıntılı bir genel bakış için Yapılandırılabilir Derleme Özellikleri bölümüne bakın.
Örtülü çıkış hedefleri
C++'taki örtülü çıkışlar kullanımdan kaldırılmıştır. Lütfen mümkünse başka dillerde kullanmaktan kaçının. Henüz desteği sonlandırılma planımız yok ancak bu sürümler de zaman içinde desteği sonlandırılacak.
Bir BUILD dosyasında derleme kuralı tanımladığınızda, pakette açıkça yeni, adlandırılmış bir kural hedefi beyan etmiş olursunuz. Birçok derleme kuralı işlevi, içeriği ve anlamı kurala özgü olan bir veya daha fazla çıkış dosyası hedefini dolaylı olarak da içerir.
Örneğin, bir java_binary(name='foo', ...) kuralını açıkça bildirdiğinizde, aynı paketin üyesi olarak bir çıkış dosyası hedefini foo_deploy.jar dolaylı olarak da bildirmiş olursunuz.
(Bu hedef, dağıtıma uygun, kendi kendine yeten bir Java arşividir.)
Dolaylı çıkış hedefleri, global hedef grafiğin birinci sınıf üyeleridir. Diğer hedefler gibi, bunlar da üst düzey derleme komutunda belirtildiğinde veya diğer derleme hedefleri için gerekli ön koşullar olduğunda isteğe bağlı olarak oluşturulur. Bunlar, BUILD dosyalarında bağımlılık olarak referans verilebilir ve bazel query gibi analiz araçlarının çıktısında gözlemlenebilir.
Her derleme kuralı türü için kuralın dokümanlarında, bu tür bir kuralın beyanının gerektirdiği tüm gizli çıkışların adlarını ve içeriklerini ayrıntılı olarak açıklayan özel bir bölüm bulunur.
Derleme sistemi tarafından kullanılan iki adlandırma alanı arasında önemli ancak biraz ince bir fark vardır: Etiketler, kural veya dosya olabilecek hedefleri tanımlar. Dosya hedefleri ise kaynak (veya giriş) dosya hedefleri ve türetilmiş (veya çıkış) dosya hedefleri olarak ikiye ayrılabilir. Bunlar, BUILD dosyalarında bahsedebileceğiniz, komut satırından derleyebileceğiniz veya bazel query kullanarak inceleyebileceğiniz öğelerdir; bunlar hedef ad alanıdır. Her dosya hedefi, diskteki bir gerçek dosyaya ("dosya sistemi ad alanı") karşılık gelir. Her kural hedefi, diskteki sıfır, bir veya daha fazla gerçek dosyaya karşılık gelebilir.
Diskte, karşılık gelen hedefi olmayan dosyalar olabilir. Örneğin, C++ derlemesi sırasında üretilen .o nesne dosyalarına BUILD dosyalarından veya komut satırından referans verilemez.
Bu sayede derleme aracı, görevini nasıl yerine getirdiğiyle ilgili belirli uygulama ayrıntılarını gizleyebilir. Bu konu BUILD Kavram Referansı'nda daha ayrıntılı olarak açıklanmıştır.