Bu bölümde, birçok işlevde veya kural oluşturma işleminde ortak olan çeşitli terimler ve kavramlar açıklanmaktadır.
İçindekiler
- Bourne kabuğu belirtkeleme
- Etiket Genişletme
- Çoğu derleme kuralı tarafından tanımlanan tipik özellikler
- Tüm derleme kurallarında ortak özellikler
- Tüm test kurallarında ortak özellikler (*_test)
- Tüm ikili kurallarda ortak özellikler (*_binary)
- Yapılandırılabilir özellikler
- Dolaylı çıkış hedefleri
Bourne kabuğu belirtkeleme
Bazı kuralların belirli dize özellikleri, Bourne kabuğunun tokenizasyon kurallarına göre birden fazla kelimeye bölünür: Tırnak içinde olmayan boşluklar ayrı kelimeleri sınırlar. Tokenleştirmeyi önlemek için tek ve çift tırnak karakterleri ile ters eğik çizgiler kullanılır.
Bu tokenizasyona tabi olan özellikler, bu belgedeki tanımlarında açıkça belirtilmektedir.
"Make" değişken genişletmesine ve Bourne kabuğu belirtkelemeye tabi olan özellikler, genellikle derleyicilere ve diğer araçlara rastgele seçenekleri geçirmek için kullanılır. Bu tür özelliklere örnek olarak cc_library.copts ve java_library.javacopts verilebilir.
Bu değişiklikler birlikte, tek bir dize değişkeninin yapılandırmaya özel 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 //mypkg:target gibi alt dize olarak geçerli bir etiket içeriyorsa ve bu etiket mevcut kuralın bildirilmiş ön koşuluysa hedef
//mypkg:target tarafından temsil edilen dosyanın yol adına genişletilir.
Örnek özellikler arasında genrule.cmd ve cc_binary.linkopts yer alır. Ayrıntılar, göreli etiketlerin genişletilip genişletilmediği, birden fazla dosyaya genişleyen etiketlerin nasıl ele alındığı vb. gibi sorunlarda önemli ölçüde farklılık gösterebilir. 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, hepsi olmasa da birçok derleme kuralı tarafından tanımlanan özellikler açıklanmaktadır.
| Özellik | Açıklama |
|---|---|
data |
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 |
Bu hedefe ilişkin 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ılar içerenlerle sınırlar.
Bir hedefin başka bir
Çoğu zaman |
licenses |
Bu hedef için kullanılacak lisans türü dizelerinin listesi. Bu, Bazel'ın artık kullanmadığı, kullanımdan kaldırılmış bir lisanslama API'sinin bir parçasıdır. Bunu kullanmayın. |
srcs |
Bu kural tarafından işlenen veya dahil edilen dosyalar. Dosyaları genellikle doğrudan listeler ancak varsayılan çıkışlarını eklemek için kural hedeflerini ( Dile özgü kurallar, genellikle listelenen dosyaların belirli dosya uzantılarına sahip olmasını gerektirir. |
Tüm derleme kurallarında ortak özellikler
Bu bölümde, tüm derleme kurallarına dolaylı olarak eklenen özellikler açıklanmaktadır.
| Özellik | Açıklama |
|---|---|
compatible_with |
Varsayılan olarak desteklenen ortamların yanı sıra bu hedefin oluşturulabileceği ortamların listesi. Bu, kullanıcıların hangi hedeflerin birbirine bağlı olup olamayacağını bildirmesine olanak tanıyan Bazel kısıtlama sisteminin bir parçasıdır. Örneğin, harici olarak dağıtılabilir ikili programlar, şirket gizli koduna sahip kitaplıklara bağlı olmamalıdır. Ayrıntılar için ConstraintSemantics bölümüne bakın. |
deprecation |
Bu hedefle ilişkili açıklayıcı bir uyarı mesajı. Genellikle bu, kullanıcılara bir hedefin geçerliliğini yitirdiğini veya yerini başka bir kural aldığını, bir pakete özel olduğunu ya da herhangi bir nedenle zararlı olarak değerlendirildiğini bildirmek için kullanılır. İletiden kaçınmak için hangi değişikliklerin yapılması gerektiğini kolayca bulabilmek amacıyla bazı referanslar (web sayfası, hata numarası veya örnek taşıma CL'leri gibi) eklemek iyi bir fikirdir. Bunun yerine kullanılabilen yeni bir hedef varsa eski hedefin tüm kullanıcılarını taşımak iyi bir fikirdir.
Bu özelliğin, öğelerin oluşturulma şekli üzerinde herhangi bir etkisi yoktur ancak bir derleme aracının teşhis çıkışını etkileyebilir. Derleme aracı, Paket içi bağımlılıklar bu uyarıdan muaftır. Böylece, örneğin, kullanımdan kaldırılan bir kuralın testlerini oluştururken uyarı verilmez. Kullanımdan kaldırılan bir hedef, desteği sonlandırılmış başka bir hedefe bağlıysa uyarı mesajı gönderilmez. Kullanıcılar bu uygulamayı kullanmayı bıraktıktan sonra hedef kaldırılabilir. |
distribs |
Bu hedef için kullanılacak dağıtım yöntemi dizelerinin listesi. Bu, Bazel'ın artık kullanmadığı, kullanımdan kaldırılmış bir lisanslama API'sinin bir parçasıdır. Bunu kullanmayın. |
exec_compatible_with |
Bu hedef için yürütme platformunda olması gereken |
exec_properties |
Bu hedef için seçilen bir platformun Hem platform hem de hedef düzeyindeki mülklerde bir anahtar varsa değer hedeften alınır. |
features |
Özellik, bir hedefte etkinleştirilebilen veya devre dışı bırakılabilen dize etiketidir. Özelliğin anlamı, kuralın kendisine bağlıdır. Bu |
restricted_to |
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 |
Etiketler herhangi bir kuralda kullanılabilir. Test ve
Bazel, herhangi bir testin veya
Testlerdeki etiketler genellikle testin hata ayıklama ve yayınlama sürecindeki rolüne açıklama eklemek için kullanılır. Etiketler genellikle en çok çalışma zamanı notu özelliği olmayan C++ ve Python testlerinde yararlıdır. Etiketlerin ve boyut öğelerinin kullanılması, test paketlerinin derlenmesinde kod tabanı check-in politikasına göre esneklik sağlar.
Bazel, test kuralının
|
target_compatible_with |
Bu hedefin uyumlu olarak kabul edilmesi için hedef platformda olması gereken Uyumsuz hedeflere geçişli olarak bağlı olan hedeflerin kendileri uyumsuz olarak kabul edilir. Ayrıca derleme ve test için atlanırlar. Boş liste (varsayılandır), hedefin tüm platformlarla uyumlu olduğunu gösterir.
Workspace Kuralları dışındaki tüm kurallar bu özelliği destekler.
Bu özelliğin bazı kurallarda etkisi yoktur. Örneğin, bir
Uyumsuz hedef atlama hakkında daha fazla bilgi için Platformlar sayfasına bakın. |
testonly |
Doğru değerine ayarlanırsa yalnızca test hedefleri (testler gibi) bu hedefe bağlı olabilir.
Diğer bir deyişle,
Testler ( Bu özelliğin amacı, hedefin üretime yayınlanan ikili programlara dahil edilmemesi gerektiğini ifade eder. Testonly, çalışma zamanında değil, derleme zamanında zorunlu kılındığı ve bağımlılık ağacı üzerinden sanal olarak yayıldığı için mantıklı bir şekilde uygulanmalıdır. Örneğin, birim testlerinde işe yarayan koçanlar ve sahteler, üretime yayınlanacak aynı ikili programları içeren entegrasyon testleri için de yararlı olabilir. Bu nedenle, muhtemelen yalnızca test olarak işaretlenmemeleri gerekir. Öte yandan, belki de koşulsuz olarak normal davranışı geçersiz kıldığı için bağlanması bile tehlikeli olan kurallar, kesinlikle test salt test olarak işaretlenmelidir. |
toolchains |
Bu hedefin Değişkenleri oluşturma iznine sahip olduğu hedef grubu. Bu hedefler,
Bunun, platforma bağlı yapılandırma için kural uygulamaları tarafından kullanılan araç zinciri çözünürlüğü kavramından farklı olduğunu unutmayın. Bir hedefin hangi |
visibility |
Bir hedefteki |
Tüm test kurallarında ortak özellikler (*_test)
Bu bölümde, tüm test kurallarında ortak olan özellikler açıklanmaktadır.
| Özellik | Açıklama | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Bu bağımsız değişkenler, |
||||||||||||||||||||
env |
Test
Bu özellik yalnızca |
||||||||||||||||||||
env_inherit |
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 "çok büyük" olarak kabul edilir. Bazel, varsayılan zaman aşımını belirlemek için boyutu kullanır. Varsayılan zaman aşımı değeri, 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 |
Geri dönmeden önce testin ne kadar sürmesinin beklendiği.
Bir testin boyut özelliği kaynak tahminini kontrol eder, ancak testin zaman aşımı bağımsız olarak ayarlanabilir. Açıkça belirtilmediği takdirde zaman aşımı testin boyutuna bağlıdır. Test zaman aşımı
Yukarıdakilerin dışındaki zamanlarda test zaman aşımı
|
||||||||||||||||||||
flaky |
Testi güvenilir olarak işaretler. Ayarlanırsa testi en fazla üç kez yürütür ve yalnızca her başarısız olduğunda başarısız olarak işaretlenir. Varsayılan olarak bu özellik Yanlış değerine ayarlanır ve test yalnızca bir kez yürütülür. Bu özelliğin kullanılması genellikle önerilmez. Onayları onaylandığında testler güvenilir bir şekilde geçmelidir. |
||||||||||||||||||||
shard_count |
Testi çalıştırmak için kullanılacak paralel kırık sayısını belirtir. Bu değer, testin çalıştırılacağı paralel parçaların sayısını belirlemek için kullanılan tüm buluşsal yöntemleri geçersiz kılar. Bazı test kurallarında, parçalamayı öncelikle etkinleştirmek için bu parametrenin gerekli olabileceğini unutmayın. Parçalama testi etkinleştirilirse test oluşturulurken 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 parçada her testi çalıştırır. Ancak bu, istediğiniz değildir. Parçalama ile ilgili ayrıntılar için Test Ansiklopedisi'ndeki Parçalama Testi bölümüne bakın. |
||||||||||||||||||||
local |
Testi, korumalı alan olmadan yerel olarak çalıştırılmaya zorlar. Bunu Doğru değerine ayarlamak, etiket olarak "yerel" değeri sağlamakla ( |
Tüm ikili kurallarda ortak özellikler (*_binary)
Bu bölümde, tüm ikili program kurallarında ortak olan özellikler açıklanmaktadır.
| Özellik | Açıklama |
|---|---|
args |
NOT: Hedefi Bazel dışında çalıştırdığınızda (örneğin, ikili dosyayı |
env |
Hedef
Bu özellik yalnızca
NOT: Hedefi Bazel dışında çalıştırdığınızda (ör. ikili dosyayı |
output_licenses |
Bu ikili programın oluşturduğu çıkış dosyalarının lisansları. Bu, Bazel'ın artık kullanmadığı, kullanımdan kaldırılmış bir lisanslama API'sinin bir parçasıdır. Bunu kullanmayın. |
Yapılandırılabilir özellikler
Çoğu özellik "yapılandırılabilir"dir. Diğer bir deyişle, hedef farklı şekillerde oluşturulduğunda değerlerin değerleri değişebilir. Özellikle, yapılandırılabilir özellikler, Bazel komut satırına iletilen işaretlere veya hedef için hangi aşağı akış bağımlılığının istediğine bağlı olarak değişiklik gösterebilir. Bu, örneğin hedefi birden fazla platform veya derleme modu için özelleştirmek amacıyla kullanılabilir.
Aşağıdaki örnekte farklı hedef mimariler için farklı kaynaklar açıklanmaktadır. bazel build :multiplatform_lib --cpu x86
çalıştırıldığında hedef, x86_impl.cc kullanılarak derlenir, --cpu arm yerine
kullanılması ise hedefin arm_impl.cc kullanmasına neden olur.
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 karşıladığı config_setting veya constraint_value ölçütüne bağlı olarak yapılandırılabilir bir özellik için farklı alternatif değerler arasından seçim yapar.
Bazel, makrolar işlendikten sonra ve kuralları işlemeden önce (teknik olarak
yükleme ve analiz aşamaları arasında) yapılandırılabilir özellikleri değerlendirir.
select() değerlendirmesinden önceki işlemler, select() uygulamasının hangi dalı seçtiğini bilemez. Örneğin, makrolar, davranışlarını seçilen dala göre değiştiremez ve bazel query, bir hedefin yapılandırılabilir bağımlılıkları hakkında yalnızca ihtiyatlı tahminler yapabilir. Kurallar ve makrolarla select() kullanımı hakkında daha fazla bilgi için
bu SSS sayfasını inceleyin.
Dokümanlarında nonconfigurable olarak işaretlenen özellikler bu özelliği kullanamaz. Bir select() öğesinin nasıl çözümleneceğini belirlemeden önce Bazel'ın kendi değerini bilmesi gerektiğinden, bir özellik genellikle yapılandırılamaz.
Ayrıntılı genel bakış için Yapılandırılabilir Derleme Özellikleri konusuna bakın.
Örtülü çıkış hedefleri
C++'taki dolaylı çıkışlar kullanımdan kaldırılmıştır. Lütfen mümkünse başka dillerde kullanmaktan kaçının. Henüz bir kullanımdan kaldırma sürecimiz yok, ancak onlar da zaman içinde kullanımdan kaldırılacaktır.
DERLEME dosyasında bir derleme kuralı tanımladığınızda, paket içinde yeni ve adlandırılmış bir kural hedefini açıkça bildirmiş olursunuz. Birçok derleme kuralı işlevi, dolaylı olarak da içerikleri ve anlamları kurala özgü olan bir veya daha fazla çıkış dosyası hedefi içerir.
Örneğin, açık bir şekilde java_binary(name='foo', ...) kuralı bildirdiğinizde foo_deploy.jar çıkış dosyası hedefini aynı paketin üyesi olarak dolaylı olarak bildirmiş olursunuz.
(Bu hedef, dağıtıma uygun bağımsız bir Java arşividir.)
Örtük çıkış hedefleri, küresel hedef grafiğinin birinci sınıf üyeleridir. Diğer hedeflerde olduğu gibi, üst seviyedeki oluşturulmuş komutta belirtildiklerinde veya diğer derleme hedefleri için gerekli ön koşullar karşılandığında isteğe bağlı olarak oluşturulurlar. DERLEME dosyalarında bağımlılık olarak bunlara başvurulabilir 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 bildirilmesine neden olan örtülü çıkışların adlarını ve içeriklerini ayrıntılı şekilde açıklayan özel bir bölüm bulunur.
Derleme sistemi tarafından kullanılan iki ad alanı arasındaki önemli ancak küçük bir ayrım: Etiketler, kurallar veya dosyalar olabilecek hedefleri tanımlar. Dosya hedefleri ise kaynak (veya giriş) dosya hedefleri ile türetilmiş (veya çıkış) dosya hedeflerine bölünebilir. Bunlar DERLEME dosyalarında bahsedebilir, komut satırından derleme yapabilir veya bazel query kullanarak inceleyebilirsiniz. Bu, 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 bir hedefe sahip olmayan dosyalar olabilir. Örneğin, C++ derlemesi sırasında oluşturulan .o nesne dosyalarına BUILD dosyalarının içinden veya komut satırından referans verilemez.
Böylece derleme aracı, işini nasıl yaptığına dair belirli uygulama ayrıntılarını gizleyebilir. Bu konu, DERLEME Başvurusu bölümünde daha ayrıntılı bir şekilde açıklanmıştır.