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 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ı sırasında açıkça belirtilir.
"Make" değişkeni genişletmeye ve Bourne kabuğuna tabi olan özellikler, genellikle derleyicilere ve diğer araçlara keyfi seçenekler 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.
Örnek özellikler arasında genrule.cmd ve cc_binary.linkopts yer alır. 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 |
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 diğer girişleri 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 genellikle listelenen hedefleri 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 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ılamaz; varsayılan değer Bu hedefle ilişkili açıklayıcı bir uyarı mesajı. Bu genellikle kullanıcıları bir hedefin kullanımdan kaldırıldığı, başka bir kuralın yerini aldığı, bir pakete özel olduğu veya bir nedenle zararlı olarak değerlendirildiği konusunda bilgilendirmek 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 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 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ı, kod tabanı check-in politikasına dayalı test paketleri oluşturma konusunda 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ş yoluyla uyumsuz hedeflere bağlı olan hedeflerin kendisi de uyumsuz 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,
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
Eşdeğer olarak,
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 stub'lar ve sahte öğeler, üretime yayınlanacak aynı ikili dosyaları içeren entegrasyon testleri için de yararlı olabilir. 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ş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 değer değişiklik gösterir
Doğrudan bir BUILD dosyasında veya BUILD dosyasından çağrılan eski makrolarda tanımlanan hedefler için varsayılan değer, belirtilmişse paketin |
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 getirilmesine 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. 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 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 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. 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ı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 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 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 kullanıldığında ise hedef arm_impl.cc kullanılarak oluşturulur.
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ş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ı. Mümkün olduğunda lütfen diğer 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.)
Örtük çıkış hedefleri, genel hedef grafiğinin 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.