Bu bölümde, birçok işlev veya derleme kuralında ortak olan çeşitli terim ve kavramları tanımlar.
İç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 dize bölme kurallarına göre birden çok kelimeye bölünür: Tek tırnak içine alınmamış boşluklar ayrı kelimeleri sınırlandırır ve dize bölme işlemini önlemek için tek ve çift tırnak karakterleri ile ters eğik çizgiler 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şletmeye tabidir: Bu dizeler alt dize olarak //mypkg:target gibi geçerli bir etiket içeriyorsa ve bu etiket geçerli kuralın bildirilen bir ön koşuluysa ilgili hedef
//mypkg:target ile temsil edilen dosyanın yol adına genişletilir.
genrule.cmd ve cc_binary.linkopts, örnek özelliklere örnek olarak verilebilir. Ayrıntılar, her durumda önemli ölçüde değişiklik gösterebilir. Örneğin, göreli etiketlerin genişletilip genişletilmeyeceği, birden fazla dosyaya genişleyen etiketlerin nasıl ele alınacağı vb. konularla ilgili ayrıntılar 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 |
Etiket listesi; varsayılan 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 hedefleri listelenir. (Bazı kurallar dosyaların doğrudan Dile özgü kurallar, listelenen hedefleri genellikle belirli sağlayıcılara sahip olanlarla sınırlandırır.
Bir hedefin
|
licenses |
Dize listesi; yapılandırılamaz;
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 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 programlar şirket gizli kodu içeren kitaplıklara bağlı olmamalıdır. Ayrıntılar için ConstraintSemantics'i inceleyin. |
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ılan bir kuralın testlerinin derlenmesi uyarıyla karşılaşmaz. 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 artık uygulamayı 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 bir 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 oluşturulabileceğ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 bir testin hata ayıklama ve yayınlama sürecinizdeki rolünü açıklamak 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 Uyumsuz hedeflere geçişli olarak bağlı olan hedeflerin kendisi de 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.
Bu özellik bazı kurallar için etkili değildir. Örneğin,
Uyumsuz hedef atlama hakkında daha fazla bilgi için Platformlar sayfasına bakın. |
testonly |
Boole; yapılandırılmamış; test ve test paketi hedefleri hariç varsayılan değer
Eşdeğer olarak,
Testler ( Bu özelliğin amacı, hedefin üretime yayınlanan ikili programlara dahil edilmemesi 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. Diğer taraftan, belki de koşulsuz olarak normal davranışı geçersiz kıldığı için bağlantı oluşturulması bile tehlikeli olan kurallar, yalnızca test amaçlı olarak işaretlenmelidir. |
toolchains |
Etiketler listesi;
yapılandırılamaz; varsayılan değer
Bu hedefin Değişken oluştur işlevine 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ında 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ı" belirtir: Çalıştırılması için ne kadar süreye/kaynağa ihtiyaç duyulur? 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:
Test oluşturulurken |
||||||||||||||||||||
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. Açıkça belirtilmediği takdirde zaman aşımı, test boyutuna göre belirlenir. Test zaman aşımı,
Yukarıdakiler dışındaki zamanlarda test zaman aşımı,
Testi üretirken |
||||||||||||||||||||
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 parça sayısını belirtir. Ayarlanırsa bu değer, testi çalıştıracak paralel parça sayısını belirlemek için kullanılan tüm sezgisel kuralları geçersiz kılar. Bazı test kuralları için, parçalamayı etkinleştirmek amacıyla öncelikle bu parametrenin gerekli olabileceğini unutmayın. Test parçalama etkinleştirilirse, testi oluştururken ortam değişkeni Parçalama için test çalıştırıcının test parçalama 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. Bölme hakkında ayrıntılı bilgi için Test Ansiklopedisi'ndeki Test Bölme bölümüne bakın. |
||||||||||||||||||||
local |
Boole; yapılandırılmamış; 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 olan özellikler (*_binary)
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 programı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. Örneğin bu, 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, hedef yapılandırmasının config_setting veya constraint_value ölçütlerine göre yapılandırılabilir özellik için farklı alternatif değerler arasından seçim yapar.
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şlemler, select()'nin hangi dalı seçtiğini bilmez. Ö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()'yi kurallar ve makrolarla kullanma hakkında daha fazla bilgi için
bu SSS bölümünü inceleyin.
Dokümanlarında nonconfigurable işaretli özellikler bu özelliği kullanamaz. Bazel, bir select() değerini nasıl çözeceğini belirlemeden önce değerini dahili olarak bilmesi gerektiğinden, genellikle özellikler yapılandırılamaz.
Ayrıntılı bir genel bakış için Yapılandırılabilir Derleme Özellikleri başlıklı makaleyi inceleyin.
Örtülü çıkış hedefleri
C++'taki örtük çıkışlara verilen destek sonlandırıldı. 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 hedeflerde olduğu gibi bu hedefler de üst düzey derleme komutta belirtildiklerinde 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 belirtebileceğiniz, komut satırından derleyebileceğiniz veya bazel query kullanarak inceleyebileceğiniz şeylerdir. Bu, hedef ad alanıdır. Her dosya hedefi, diskteki gerçek bir dosyaya ("dosya sistemi ad alanı") karşılık gelir. Her kural hedefi, diskteki sıfır veya 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.