Kural, kuralın uygulama işlevi tarafından döndürülen sağlayıcılarda referans verilen bir dizi çıkış oluşturmak için Bazel'in girişlerde gerçekleştirdiği bir dizi işlemi tanımlar. Örneğin, bir C++ ikili kuralı şu şekilde olabilir:
.cpp
kaynak dosyası (giriş) alın.- Kaynak dosyalarda
g++
komutunu çalıştırın (işlem). - Çalışma zamanında kullanılabilir hale getirmek için, yürütülebilir çıktıyı ve diğer dosyaları içeren
DefaultInfo
sağlayıcısını iade edin. CcInfo
sağlayıcısını, hedeften ve bağımlılıklarından toplanan C++'a özel bilgilerle iade edin.
Bazel açısından, g++
ve standart C++ kitaplıkları da bu kurala girilir. Kural yazarı olarak, yalnızca kural için kullanıcı tarafından sağlanan girişleri değil, işlemleri yürütmek için gereken tüm araçları ve kitaplıkları da göz önünde bulundurmalısınız.
Herhangi bir kuralı oluşturmadan veya değiştirmeden önce Bazel'ın derleme aşamaları hakkında bilgi sahibi olduğunuzdan emin olun. Bir derlemenin üç aşamasını (yükleme, analiz ve yürütme) anlamak önemlidir. Kurallar ve makrolar arasındaki farkı anlamak için makrolar hakkında bilgi edinmek de faydalı olur. Başlamak için önce Kurallar Eğitimi'ni inceleyin. Ardından, bu sayfayı referans olarak kullanın.
Bazel'in kendisinde birkaç kural oluşturulmuştur. cc_library
ve java_binary
gibi bu yerel kurallar, belirli diller için bazı temel destek sağlar.
Kendi kurallarınızı tanımlayarak Bazel'in yerel olarak desteklemediği diller ve araçlar için benzer bir destek ekleyebilirsiniz.
Bazel, Starlark dilini kullanarak kural yazmak için bir genişletilebilirlik modeli sağlar. Bu kurallar, doğrudan BUILD
dosyadan yüklenebilen .bzl
dosyalarında yazılır.
Kendi kuralınızı tanımlarken hangi özellikleri desteklediğine ve sonuçlarını nasıl ürettiğine karar vermeniz gerekir.
Kuralın implementation
işlevi, analiz aşamasında tam davranışını tanımlar. Bu işlev harici komut çalıştırmaz. Bunun yerine, gerektiğinde kuralın çıktılarını oluşturmak için yürütme aşamasının sonlarında kullanılacak işlemleri kaydeder.
Kural oluşturma
Bir .bzl
dosyasında, yeni bir kural tanımlamak için rule işlevini kullanın ve sonucu, genel değişkende depolayın. rule
çağrısı, özellikleri ve bir uygulama işlevini belirtir:
example_library = rule(
implementation = _example_library_impl,
attrs = {
"deps": attr.label_list(),
...
},
)
Bu, example_library
adlı bir kural türünü tanımlar.
rule
çağrısı, kuralın executable=True
ile bir yürütülebilir çıktı mı (executable=True
ile) yoksa özellikle test=True
ile yürütülebilir bir test mi oluşturacağını da belirtmelidir. İkincisiyse kural bir test kuralı olur ve kuralın adı _test
ile bitmelidir.
Hedef örneklendirme
Kurallar yüklenebilir ve BUILD
dosyalarında çağrılabilir:
load('//some/pkg:rules.bzl', 'example_library')
example_library(
name = "example_target",
deps = [":another_target"],
...
)
Bir derleme kuralına yapılan her çağrı, hiçbir değer döndürmez ancak bunun bir hedef tanımlama gibi yan etkisi vardır. Buna, kuralın tetiklenmesi denir. Bu, yeni hedef için bir ad ve hedefin özelliklerinin değerlerini belirtir.
Kurallar, Starlark işlevlerinden de çağrılabilir ve .bzl
dosyalarına yüklenebilir.
Kuralları çağıran Starlark işlevleri Starlark makroları olarak adlandırılır.
Starlark makroları sonuçta BUILD
dosyalarından çağrılmalıdır ve yalnızca hedefleri örneklendirmek için BUILD
dosyalarının değerlendirildiği yükleme aşamasında çağrılabilir.
Özellikler
Özellik, bir kural bağımsız değişkenidir. Özellikler, bir hedefin uygulamasına belirli değerler sağlayabilir veya başka hedeflere referans vererek bir bağımlılık grafiği oluşturabilir.
srcs
veya deps
gibi kurala özgü özellikler, bir eşlemenin özellik adlarından şemalara (attr
modülü kullanılarak oluşturulan) rule
attrs
parametresine geçirilmesiyle tanımlanır.
name
ve visibility
gibi ortak özellikler tüm kurallara dolaylı olarak eklenir. Ek özellikler, özel olarak yürütülebilir ve test kurallarına dolaylı olarak eklenir. Kurala dolaylı olarak eklenen özellikler, attrs
ürününe iletilen sözlüğe dahil edilemez.
Bağımlılık özellikleri
Kaynak kodu işleyen kurallar, genellikle çeşitli bağımlılık türlerini yönetmek için aşağıdaki özellikleri tanımlar:
srcs
, hedefin işlemleri tarafından işlenen kaynak dosyaları belirtir. Özellik şeması genellikle kuralın işlediği kaynak dosya sıralaması için hangi dosya uzantılarının beklendiğini belirtir. Başlık dosyalarına sahip dillerin kuralları, bir hedef ve tüketicileri tarafından işlenen başlıklar için genellikle ayrı birhdrs
özelliği belirtir.deps
, bir hedef için kod bağımlılıklarını belirtir. Özellik şeması, bu bağımlılıkların hangi sağlayıcıları sağlaması gerektiğini belirtmelidir. (Örneğin,cc_library
,CcInfo
değerini sağlar.)data
, hedefe bağlı olan yürütülebilir dosyalar için çalışma zamanında kullanıma sunulacak dosyaları belirtir. Bu, rastgele dosyaların belirtilmesine izin verir.
example_library = rule(
implementation = _example_library_impl,
attrs = {
"srcs": attr.label_list(allow_files = [".example"]),
"hdrs": attr.label_list(allow_files = [".header"]),
"deps": attr.label_list(providers = [ExampleInfo]),
"data": attr.label_list(allow_files = True),
...
},
)
Bunlar, bağımlılık özelliklerine örnektir. Giriş etiketi belirten tüm özellikler (attr.label_list
, attr.label
veya attr.label_keyed_string_dict
ile tanımlananlar), hedef tanımlandığında bir hedef ile etiketleri (veya karşılık gelen Label
nesneleri) listelenen hedefler arasındaki belirli bir türdeki bağımlılıkları belirtir. Bu etiketlerin deposu ve muhtemelen yolu, tanımlanan hedefe göre çözümlenir.
example_library(
name = "my_target",
deps = [":other_target"],
)
example_library(
name = "other_target",
...
)
Bu örnekte other_target
, my_target
bağımlılığıdır ve bu nedenle önce other_target
analiz edilir. Hedeflerin bağımlılık grafiğinde bir döngü varsa bu bir hatadır.
Özel özellikler ve örtülü bağımlılıklar
Varsayılan değere sahip bir bağımlılık özelliği dolaylı bağımlılık oluşturur. Kullanıcının BUILD
dosyasında belirtmediği hedef grafiğin bir parçası olduğu için örtülüdür. Örtülü bağımlılıklar, bir kural ile araç (derleyici gibi bir derleme zamanı bağımlılığı) arasındaki ilişkinin sabit bir şekilde kodlanması için yararlıdır. Çünkü kullanıcının çoğu, kuralın hangi aracı kullandığını belirtmekle ilgilenmez. Kuralın uygulama işlevinde bu durum, diğer bağımlılıklarla aynı şekilde ele alınır.
Kullanıcının bu değeri geçersiz kılmasına izin vermeden örtülü bir bağımlılık sağlamak istiyorsanız alt çizgi (_
) ile başlayan bir ad vererek özelliği gizli hale getirebilirsiniz. Özel özelliklerin varsayılan değerleri olmalıdır. Özel özelliklerin yalnızca örtülü bağımlılıklar için kullanılması genellikle anlamlıdır.
example_library = rule(
implementation = _example_library_impl,
attrs = {
...
"_compiler": attr.label(
default = Label("//tools:example_compiler"),
allow_single_file = True,
executable = True,
cfg = "exec",
),
},
)
Bu örnekte, example_library
türündeki her hedef //tools:example_compiler
derleyicisine dolaylı bir bağımlılığa sahiptir. Bu sayede, kullanıcı etiketini giriş olarak iletmemiş olsa bile example_library
uygulama işlevi, derleyiciyi çağıran işlemler oluşturabilir. _compiler
gizli bir özellik olduğundan, ctx.attr._compiler
bu kural türünün tüm hedeflerinde her zaman //tools:example_compiler
öğesini gösterir. Alternatif olarak, compiler
özelliğini alt çizgi olmadan adlandırıp varsayılan değeri koruyabilirsiniz. Bu, kullanıcıların gerekirse farklı bir derleyici yerine koymasına olanak tanır, ancak derleyici etiketi hakkında bilgi sahibi olmayı gerektirmez.
Dolaylı bağımlılıklar, genellikle kural uygulamasıyla aynı depoda bulunan araçlar için kullanılır. Araç, bunun yerine yürütme platformundan veya farklı bir depodan geliyorsa kural, aracı bir araç zincirinden edinmelidir.
Çıkış özellikleri
attr.output
ve attr.output_list
gibi çıkış özellikleri, hedefin oluşturduğu bir çıkış dosyasını bildirir. Bunlar bağımlılık özelliklerinden iki şekilde ayrılır:
- Bu uzantılar, başka bir yerde tanımlanan hedeflere başvurmak yerine çıkış dosyası hedeflerini tanımlar.
- Çıkış dosyası hedefleri, örneklenen kural hedefine bağlıdır. Bunun tersi olmaz.
Genel olarak çıkış özellikleri, yalnızca bir kuralın hedef ada dayalı olamayan kullanıcı tanımlı adlara sahip çıkışlar oluşturması gerektiğinde kullanılır. Bir kuralın tek bir çıkış özelliği varsa genellikle out
veya outs
olarak adlandırılır.
Önceden tanımlanmış çıkışlar oluşturmanın tercih edilen yöntemi çıkış özellikleridir. Bu çıkışlara özellikle bağlı olabilir veya komut satırında istenebilir.
Uygulama işlevi
Her kural için bir implementation
işlevi gerekir. Bu işlevler, sıkı bir şekilde analiz aşamasında yürütülür ve yükleme aşamasında oluşturulan hedeflerin grafiğini, yürütme aşamasında gerçekleştirilecek işlemlerin grafiğine dönüştürür. Dolayısıyla, uygulama işlevleri aslında dosyaları okuyamaz veya yazamaz.
Kural uygulama işlevleri genellikle gizlidir (başta alt çizgiyle belirtilir). Geleneksel olarak kurallarıyla aynı şekilde adlandırılır ancak son ekleri _impl
ile belirtilir.
Uygulama işlevleri için tam olarak tek bir parametre kullanılır: Geleneksel olarak ctx
olarak adlandırılan kural bağlamı. Bir sağlayıcı listesi döndürürler.
Hedefler
Bağımlılıklar analiz zamanında Target
nesneleri olarak temsil edilir. Bu nesneler, hedefin uygulama işlevi yürütüldüğünde oluşturulan providers içerir.
ctx.attr
, her bağımlılık özelliğinin adlarına karşılık gelen alanlara sahiptir. Bu alanlarda, bu özellik aracılığıyla her bir doğrudan bağımlılığı temsil eden Target
nesne bulunur. label_list
özellikleri için bu, Targets
öğesinin bir listesidir. label
özellikleri için bu, tek bir Target
veya None
değeridir.
Bir hedefin uygulama işlevi, sağlayıcı nesnelerinin bir listesini döndürür:
return [ExampleInfo(headers = depset(...))]
Bunlara, anahtar olarak sağlayıcı türü ile dizin gösterimi ([]
) kullanılarak erişilebilir. Bunlar, Starlark'ta tanımlanan özel sağlayıcılar veya Starlark global değişkenleri olarak kullanılabilen yerel kural sağlayıcıları olabilir.
Örneğin, bir kural başlık dosyalarını hdrs
özelliği aracılığıyla alıyor ve bunları hedef ile tüketicilerinin derleme işlemlerine sağlıyorsa bunları şu şekilde toplayabilir:
def _example_library_impl(ctx):
...
transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs]
struct
öğesinin, sağlayıcı nesneleri listesi yerine bir hedefin uygulama işlevinden döndürüldüğü eski stil için:
return struct(example_info = struct(headers = depset(...)))
Sağlayıcılar, Target
nesnesinin ilgili alanından alınabilir:
transitive_headers = [hdr.example_info.headers for hdr in ctx.attr.hdrs]
Bu stil kesinlikle önerilmez ve kuralların kendisinden taşınması gerekir.
Files
Dosyalar File
nesneleriyle temsil edilir. Bazel analiz aşamasında dosya G/Ç işlemi gerçekleştirmediğinden bu nesneler, dosya içeriğini doğrudan okumak veya yazmak için kullanılamaz. Bunun yerine, eylem grafiğinin parçalarını oluşturmak için işlem yayan işlevlere (bkz. ctx.actions
) yönlendirilirler.
File
, bir kaynak dosya veya oluşturulmuş bir dosya olabilir. Oluşturulan her dosya, tam olarak bir işlemin sonucu olmalıdır. Kaynak dosyalar, herhangi bir işlemin sonucu olamaz.
Her bağımlılık özelliği için karşılık gelen ctx.files
alanı, bu özellik aracılığıyla tüm bağımlılıkların varsayılan çıkışlarının bir listesini içerir:
def _example_library_impl(ctx):
...
headers = depset(ctx.files.hdrs, transitive=transitive_headers)
srcs = ctx.files.srcs
...
ctx.file
, spesifikasyonları allow_single_file=True
olarak ayarlanmış bağımlılık özellikleri için tek bir File
veya None
içerir.
ctx.executable
, ctx.file
ile aynı şekilde davranır ancak yalnızca özellikleri executable=True
olarak ayarlanmış bağımlılık özellikleri için alanlar içerir.
Çıkışları bildirme
Analiz aşamasında, bir kuralın uygulama işlevi çıktılar oluşturabilir.
Yükleme aşamasında tüm etiketlerin bilinmesi gerektiğinden bu ek çıkışların etiketi yoktur. ctx.actions.declare_file
ve ctx.actions.declare_directory
kullanılarak çıkışlar için File
nesne oluşturulabilir. Çıkışların adları genellikle hedefin adına (ctx.label.name
) dayanır:
def _example_library_impl(ctx):
...
output_file = ctx.actions.declare_file(ctx.label.name + ".output")
...
Çıkış özellikleri için oluşturulanlar gibi önceden bildirilmiş çıkışlarda, File
nesneleri ctx.outputs
öğesinin karşılık gelen alanlarından alınabilir.
İşlemler
İşlem, bir dizi girişten nasıl çıkış grubu oluşturulacağını açıklar. Örneğin, "hello.c'de gcc'yi çalıştır ve hello.o'yu al". Bir işlem oluşturulduğunda Bazel, komutu hemen çalıştırmaz. Eylemi bağımlılıklar grafiğine kaydeder, çünkü bir eylem başka bir eylemin sonucuna bağlı olabilir. Örneğin, C'de bağlayıcı, derleyiciden sonra çağrılmalıdır.
İşlem oluşturan genel amaçlı işlevler ctx.actions
bölümünde tanımlanmıştır:
- Yürütülebilir bir dosyayı çalıştırmak için
ctx.actions.run
. ctx.actions.run_shell
: Kabuk komutu çalıştırmak için.ctx.actions.write
: Dosyaya dize yazmak için.ctx.actions.expand_template
: Şablondan dosya oluşturmak için
ctx.actions.args
, eylemler için bağımsız değişkenleri
verimli bir şekilde toplamak amacıyla kullanılabilir. Yürütme zamanına kadar noktaların düzleştirilmesini önler:
def _example_library_impl(ctx):
...
transitive_headers = [dep[ExampleInfo].headers for dep in ctx.attr.deps]
headers = depset(ctx.files.hdrs, transitive=transitive_headers)
srcs = ctx.files.srcs
inputs = depset(srcs, transitive=[headers])
output_file = ctx.actions.declare_file(ctx.label.name + ".output")
args = ctx.actions.args()
args.add_joined("-h", headers, join_with=",")
args.add_joined("-s", srcs, join_with=",")
args.add("-o", output_file)
ctx.actions.run(
mnemonic = "ExampleCompile",
executable = ctx.executable._compiler,
arguments = [args],
inputs = inputs,
outputs = [output_file],
)
...
İşlemler, giriş dosyalarının bir listesini veya alt kümesini alır ve çıkış dosyalarının (boş olmayan) bir listesini oluşturur. Giriş ve çıkış dosyaları grubu analiz aşamasında bilinmelidir. Bağımlılıklardan gelen sağlayıcılar da dahil olmak üzere özelliklerin değerine bağlı olabilir ancak yürütmenin sonucuna bağlı olamaz. Örneğin, işleminiz sıkıştırılmış dosya açma komutunu çalıştırıyorsa, hangi dosyaların şişirilmesini beklediğinizi (sıkıştırma açmayı çalıştırmadan önce) belirtmeniz gerekir. Dahili olarak değişken sayıda dosya oluşturan işlemler, bunları tek bir dosyaya (zip, tar veya başka bir arşiv biçimi gibi) sarmalayabilir.
İşlemlerde tüm girişler listelenmelidir. Kullanılmayan girişleri listelemeye izin verilir, ancak bu yöntem verimsizdir.
İşlemler tüm çıkışlarını oluşturmalıdır. Başka dosyalar yazabilirler ama çıktılarda olmayan hiçbir şey tüketicilerin kullanımına sunulmaz. Beyan edilen tüm çıkışlar bir işlemle yazılmalıdır.
Eylemler salt işlevlerle karşılaştırılabilir: Yalnızca sağlanan girişlere bağlı olmalı ve bilgisayar bilgilerine, kullanıcı adına, saate, ağa veya G/Ç cihazlarına (okuma girişleri ve yazma çıkışları hariç) erişilmemelidir. Çıkış önbelleğe alınacağı ve yeniden kullanılacağı için bu önemlidir.
Bağımlılıklar Bazel tarafından çözülür. Bazel, hangi işlemlerin yürütüleceğine karar verir. Bağımlılık grafiğinde bir döngü varsa bu bir hatadır. Bir eylemin oluşturulması, yürütüleceğini garanti etmez. Bu, çıktılarının derleme için gerekli olup olmadığına bağlıdır.
Sağlayıcılar
Sağlayıcılar, bir kuralın diğer kurallara bağlı olduğu bilgilerdir. Bu veriler arasında çıkış dosyaları, kitaplıklar, bir aracın komut satırında iletilecek parametreler veya hedef tüketicilerinin bilmesi gereken diğer her şey yer alabilir.
Bir kuralın uygulama işlevi, sağlayıcıları yalnızca belirlenen hedefin doğrudan bağımlılıklarından okuyabildiğinden, kuralların bir hedefin tüketicileri tarafından bilinmesi gereken bir hedef bağımlılıklarından gelen tüm bilgileri, genellikle bir depset
olarak toplayarak iletmesi gerekir.
Bir hedefin sağlayıcıları, uygulama işlevi tarafından döndürülen Provider
nesnelerinin listesiyle belirtilir.
Eski uygulama işlevleri, uygulama işlevinin sağlayıcı nesneleri listesi yerine bir struct
döndürdüğü eski bir stilde de yazılabilir. Bu stil kesinlikle önerilmez ve kuralların kendisinden taşınması gerekir.
Varsayılan çıkışlar
Bir hedefin varsayılan çıkışları, komut satırında derleme için hedef istendiğinde varsayılan olarak istenen çıkışlardır. Örneğin, java_library
hedefi //pkg:foo
için varsayılan çıkış foo.jar
olduğundan bu, bazel build //pkg:foo
komutuyla derlenir.
Varsayılan çıkışlar, DefaultInfo
işlevinin files
parametresiyle belirtilir:
def _example_library_impl(ctx):
...
return [
DefaultInfo(files = depset([output_file]), ...),
...
]
Bir kural uygulaması tarafından DefaultInfo
döndürülmezse veya files
parametresi belirtilmezse DefaultInfo.files
varsayılan olarak tüm önceden beyan edilmiş çıkışları (genellikle çıkış özellikleri tarafından oluşturulanlar) alır.
İşlem gerçekleştiren kurallar, doğrudan kullanılması beklenmiyor olsa bile varsayılan çıkışlar sağlamalıdır. İstenen çıkışların grafiğinde olmayan işlemler kısaltılır. Bir çıkış yalnızca hedefin tüketicileri tarafından kullanılıyorsa hedef bağımsız olarak oluşturulduğunda bu işlemler gerçekleştirilmez. Bu da başarısız olan hedefi yeniden oluşturmak hatayı yeniden oluşturmayacağı için hata ayıklamayı da zorlaştırır.
Çalıştırma dosyaları
Çalıştırma dosyaları, bir hedef tarafından çalışma zamanında (derleme zamanı yerine) kullanılan dosya kümesidir. Yürütme aşamasında, Bazel çalıştırma dosyalarını işaret eden sembolik bağlantıları içeren bir dizin ağacı oluşturur. Bu işlem, ikili program ortamını aşamalayarak çalışma zamanında çalıştırma dosyalarına erişebilmesini sağlar.
Çalıştırma dosyaları, kural oluşturulurken manuel olarak eklenebilir.
runfiles
nesneleri, kural bağlamında ctx.runfiles
üzerinde runfiles
yöntemi ile oluşturulabilir ve DefaultInfo
tarihinde runfiles
parametresine iletilebilir. Yürütülebilir kuralların yürütülebilir çıktısı, dolaylı olarak çalıştırma dosyalarına eklenir.
Bazı kurallar, genellikle data
adlı özellikleri belirtir. Bu özellikler, çıkışları hedeflerin çalıştırma dosyalarına eklenir. Ayrıca çalıştırma dosyaları, data
ve nihai yürütme için kod sağlayabilecek tüm özelliklerden, genellikle srcs
(ilişkili data
ile filegroup
hedefleri içerebilir) ve deps
özelliklerinden de birleştirilmelidir.
def _example_library_impl(ctx):
...
runfiles = ctx.runfiles(files = ctx.files.data)
transitive_runfiles = []
for runfiles_attr in (
ctx.attr.srcs,
ctx.attr.hdrs,
ctx.attr.deps,
ctx.attr.data,
):
for target in runfiles_attr:
transitive_runfiles.append(target[DefaultInfo].default_runfiles)
runfiles = runfiles.merge_all(transitive_runfiles)
return [
DefaultInfo(..., runfiles = runfiles),
...
]
Özel sağlayıcılar
Sağlayıcılar, kurala özel bilgileri aktarmak için provider
işlevi kullanılarak tanımlanabilir:
ExampleInfo = provider(
"Info needed to compile/link Example code.",
fields={
"headers": "depset of header Files from transitive dependencies.",
"files_to_link": "depset of Files from compilation.",
})
Daha sonra kural uygulama işlevleri, sağlayıcı örneklerini oluşturup döndürebilir:
def _example_library_impl(ctx):
...
return [
...
ExampleInfo(
headers = headers,
files_to_link = depset(
[output_file],
transitive = [
dep[ExampleInfo].files_to_link for dep in ctx.attr.deps
],
),
)
]
Sağlayıcıların özel başlatılması
Özel ön işleme ve doğrulama mantığıyla sağlayıcının örneklendirmesini korumak mümkündür. Bu, tüm sağlayıcı örneklerinin belirli değişken değerlere uymasını sağlamak veya kullanıcılara örnek almaları için daha net bir API sunmak amacıyla kullanılabilir.
Bu işlem, provider
işlevine bir init
geri çağırması geçirilerek yapılır. Bu geri çağırma verilirse provider()
işleminin dönüş türü, iki değerin toplamı olacak şekilde değişir: init
kullanılmadığında normal döndürülen değer olan sağlayıcı simgesi ve "ham oluşturucu".
Bu durumda, provider simgesi çağrıldığında, doğrudan yeni bir örnek döndürmek yerine bağımsız değişkenleri init
geri çağırmasına yönlendirir. Geri çağırmanın döndürülen değeri, değerler ile alan adları (dizeler) eşleştirilen bir dize olmalıdır. Bu, yeni örneğin alanlarını başlatmak için kullanılır. Geri çağırma işleminin herhangi bir imzası olabileceğini ve bağımsız değişkenlerin imzayla eşleşmemesi durumunda, geri çağırma doğrudan çağrılmış gibi bir hata bildirileceğini unutmayın.
Buna karşılık, ham oluşturucu init
geri çağırmasını atlar.
Aşağıdaki örnekte, bağımsız değişkenlerini önceden işlemek ve doğrulamak için init
kullanılmaktadır:
# //pkg:exampleinfo.bzl
_core_headers = [...] # private constant representing standard library files
# It's possible to define an init accepting positional arguments, but
# keyword-only arguments are preferred.
def _exampleinfo_init(*, files_to_link, headers = None, allow_empty_files_to_link = False):
if not files_to_link and not allow_empty_files_to_link:
fail("files_to_link may not be empty")
all_headers = depset(_core_headers, transitive = headers)
return {'files_to_link': files_to_link, 'headers': all_headers}
ExampleInfo, _new_exampleinfo = provider(
...
init = _exampleinfo_init)
export ExampleInfo
Daha sonra bir kural uygulaması, sağlayıcıyı şu şekilde örneklendirebilir:
ExampleInfo(
files_to_link=my_files_to_link, # may not be empty
headers = my_headers, # will automatically include the core headers
)
Ham oluşturucu, init
mantığından geçmeyen alternatif kamu fabrikası işlevlerini tanımlamak için kullanılabilir. Örneğin, exampleinfo.bzl'de:
def make_barebones_exampleinfo(headers):
"""Returns an ExampleInfo with no files_to_link and only the specified headers."""
return _new_exampleinfo(files_to_link = depset(), headers = all_headers)
Genellikle ham oluşturucu, adı alt çizgiyle (yukarıda _new_exampleinfo
) başlayan bir değişkene bağlıdır. Bu nedenle, kullanıcı kodu bu değişkeni yükleyemez ve rastgele sağlayıcı örnekleri oluşturamaz.
init
için başka bir kullanım da kullanıcının sağlayıcı simgesini tamamen çağırmasını engelleyip kullanıcıyı bunun yerine fabrika işlevini kullanmaya zorlamaktır:
def _exampleinfo_init_banned(*args, **kwargs):
fail("Do not call ExampleInfo(). Use make_exampleinfo() instead.")
ExampleInfo, _new_exampleinfo = provider(
...
init = _exampleinfo_init_banned)
def make_exampleinfo(...):
...
return _new_exampleinfo(...)
Yürütülebilir kurallar ve test kuralları
Yürütülebilir kurallar, bir bazel run
komutu tarafından çağrılabilecek hedefleri tanımlar.
Test kuralları, hedefleri bir bazel test
komutuyla da çağrılabilen, yürütülebilir özel bir kural türüdür. Yürütülebilir ve test kuralları, rule
çağrısında ilgili executable
veya test
bağımsız değişkeni True
değerine ayarlanarak oluşturulur:
example_binary = rule(
implementation = _example_binary_impl,
executable = True,
...
)
example_test = rule(
implementation = _example_binary_impl,
test = True,
...
)
Test kurallarının adları _test
ile biten adlara sahip olmalıdır. (Test hedef adları da genellikle kurallara göre _test
ile biter, ancak bu zorunlu değildir.) Test dışı kurallarda bu son ek olmamalıdır.
Her iki kural türü de run
veya test
komutları tarafından çağrılacak yürütülebilir bir çıkış dosyası (önceden bildirilmiş veya bildirilmemiş olabilir) oluşturmalıdır. Bazel'a bir kural çıkışlarından hangilerinin yürütülebilir olarak kullanılacağını bildirmek için bunu, döndürülen DefaultInfo
sağlayıcısının executable
bağımsız değişkeni olarak iletin. Bu executable
, kuralın varsayılan çıkışlarına eklenir (böylece bunu hem executable
hem de files
öğesine aktarmanız gerekmez). Ayrıca, runfiles'e dolaylı olarak eklenir:
def _example_binary_impl(ctx):
executable = ctx.actions.declare_file(ctx.label.name)
...
return [
DefaultInfo(executable = executable, ...),
...
]
Bu dosyayı oluşturan işlem, dosyadaki yürütülebilir biti ayarlamalıdır. ctx.actions.run
veya ctx.actions.run_shell
işlemi için bu işlem, işlem tarafından çağrılan temel araç tarafından yapılmalıdır. ctx.actions.write
işlemi için is_executable=True
değerini geçin.
Eski davranış olarak, yürütülebilir kuralların önceden beyan edilmiş özel bir ctx.outputs.executable
çıkışı vardır. Bu dosya, DefaultInfo
kullanarak bir dosya belirtmezseniz varsayılan yürütülebilir dosya olarak sunulur, aksi takdirde kullanılmamalıdır. Bu çıkış mekanizması, yürütülebilir dosyanın adının analiz sırasında özelleştirilmesini desteklemediği için kullanımdan kaldırılmıştır.
Yürütülebilir kural ve test kuralı örneklerine göz atın.
Tüm kurallar için eklenenlere ek olarak, yürütülebilir kurallar ve test kuralları da dolaylı olarak tanımlanmış ek özelliklere sahiptir. Dolaylı olarak eklenen özelliklerin varsayılanları değiştirilemez ancak bu durum, özel bir kuralın varsayılan değeri değiştiren bir Starlark makrosu içine sarmalanmasıyla çözülebilir:
def example_test(size="small", **kwargs):
_example_test(size=size, **kwargs)
_example_test = rule(
...
)
Runfiles konumu
bazel run
(veya test
) ile yürütülebilir bir hedef çalıştırıldığında, Runfiles dizininin kökü, yürütülebilir dosyanın bitişiğinde olur. Yollar aşağıdaki gibi ilişkilidir:
# Given launcher_path and runfile_file:
runfiles_root = launcher_path.path + ".runfiles"
workspace_name = ctx.workspace_name
runfile_path = runfile_file.short_path
execution_root_relative_path = "%s/%s/%s" % (
runfiles_root, workspace_name, runfile_path)
Runfiles dizinindeki File
yolu File.short_path
değerine karşılık gelir.
Doğrudan bazel
tarafından yürütülen ikili program, runfiles
dizininin köküne bitişiktir. Ancak çalıştırma dosyalarından from olarak adlandırılan ikili programlar aynı varsayımı yapamaz. Bu sorunu azaltmak için her ikili program, bir ortam veya komut satırı bağımsız değişkeni/işaretleme kullanarak çalıştırma dosyası kökünü parametre olarak kabul edebileceğimiz bir yöntem sağlamalıdır. Bu, ikili programların doğru standart çalıştırma dosyası kökünü çağırdığı ikili programlara iletmesini sağlar. Bu ayar belirtilmezse ikili program, çağrılan ilk ikili program olduğunu tahmin edip bitişik bir runfiles dizinini arayabilir.
İleri düzey konular
Çıkış dosyalarını isteme
Tek bir hedefin birden fazla çıkış dosyası olabilir. Bir bazel build
komutu çalıştırıldığında, komuta verilen hedeflerin bazı çıkışlarının istendiği kabul edilir. Bazel yalnızca bu istenen dosyaları ve bunların doğrudan veya dolaylı olarak bağımlı olduğu dosyaları oluşturur. (Eylem grafiği söz konusu olduğunda Bazel, yalnızca istenen dosyaların geçişli bağımlılıkları olarak erişilebilen işlemleri yürütür.)
Varsayılan çıkışlara ek olarak önceden bildirilmiş herhangi bir çıkış, komut satırında açıkça istenebilir. Kurallar, çıktı özellikleri aracılığıyla önceden bildirilen çıkışları belirtebilir. Bu durumda, kullanıcı kuralı örneklendirirken çıkışlar için açıkça etiketler seçer. Çıkış özellikleri için File
nesnelerini almak amacıyla ilgili ctx.outputs
özelliğini kullanın. Kurallar, hedef ada göre de önceden bildirilmiş çıkışları dolaylı olarak tanımlayabilir ancak bu özelliğin desteği sonlandırılmıştır.
Varsayılan çıkışlara ek olarak, birlikte istenebilecek çıkış dosyası koleksiyonları olan çıkış grupları da vardır. Bunları --output_groups
ile talep edebilirsiniz. Örneğin, hedef //pkg:mytarget
, debug_files
çıkış grubuna sahip bir kural türündeyse bu dosyalar bazel build //pkg:mytarget
--output_groups=debug_files
çalıştırılarak oluşturulabilir. Önceden bildirilmemiş çıkışların etiketleri bulunmadığından yalnızca varsayılan çıkışlarda veya bir çıkış grubunda görünerek istenebilir.
Çıkış grupları OutputGroupInfo
sağlayıcısıyla belirtilebilir. Birçok yerleşik sağlayıcıdan farklı olarak OutputGroupInfo
, rastgele adlara sahip parametreleri alarak bu ada sahip çıkış gruplarını tanımlar:
def _example_library_impl(ctx):
...
debug_file = ctx.actions.declare_file(name + ".pdb")
...
return [
DefaultInfo(files = depset([output_file]), ...),
OutputGroupInfo(
debug_files = depset([debug_file]),
all_files = depset([output_file, debug_file]),
),
...
]
Ayrıca çoğu sağlayıcının aksine OutputGroupInfo
, aynı çıkış gruplarını tanımlamadıkları sürece hem bir en boy hem de bu özelliğin uygulandığı kural hedefi tarafından döndürülebilir. Bu durumda, sonuçta ortaya çıkan sağlayıcılar birleştirilir.
OutputGroupInfo
etiketinin genellikle belirli dosya türlerini bir hedeften tüketicilerin eylemlerine aktarmak için kullanılmaması gerektiğini unutmayın. Bunun yerine bunun için kurala özel sağlayıcılar tanımlayın.
Yapılandırmalar
Farklı bir mimari için C++ ikili programı derlemek istediğinizi düşünün. Derleme karmaşık olabilir ve birkaç adımdan oluşabilir. Derleyiciler ve kod oluşturucular gibi bazı ara ikili programların, yürütme platformunda (ana makineniz veya bir uzak yürütücü olabilir) çalışması gerekir. Nihai çıkış gibi bazı ikili programlar hedef mimariye göre derlenmelidir.
Bu nedenle, Bazel'in "yapılandırmalar" ve geçişler kavramı vardır. En üstteki hedefler (komut satırında istenenler) "hedef" yapılandırmasında oluşturulurken yürütme platformunda çalışması gereken araçlar ise "exec" yapılandırmasında oluşturulur. Kurallar, yapılandırmaya bağlı olarak farklı işlemler (ör. derleyiciye iletilen cpu mimarisini değiştirmek) oluşturabilir. Bazı durumlarda farklı yapılandırmalar için aynı kitaplık gerekli olabilir. Böyle bir durumda analiz yapılacak ve muhtemelen birden fazla kez derlenecektir.
Varsayılan olarak Bazel, hedef bağımlılıklarını hedefin kendisiyle aynı yapılandırmada, yani geçiş olmadan oluşturur. Bağımlılık, hedefin oluşturulmasına yardımcı olması için gereken bir araç olduğunda ilgili özellik, yönetici yapılandırmasına geçişi belirtmelidir. Bu, aracın ve tüm bağımlılıklarının yürütme platformu için derleme yapmasına neden olur.
Her bir bağımlılık özelliği için bağımlılıkların aynı yapılandırmada derlenmesi veya bir yönetici yapılandırmasına geçiş yapılması gerekip gerekmediğine karar vermek için cfg
kullanabilirsiniz.
Bir bağımlılık özelliği executable=True
işaretine sahipse cfg
açıkça ayarlanmalıdır. Bunun amacı, yanlış yapılandırmaya yönelik bir aracın yanlışlıkla oluşturulmasını önlemektir.
Örneği inceleyin
Genel olarak, çalışma zamanında gerekli olacak kaynaklar, bağımlı kitaplıklar ve yürütülebilir dosyalar aynı yapılandırmayı kullanabilir.
Derlemenin bir parçası olarak yürütülen araçlar (derleyiciler veya kod oluşturucular gibi) bir yönetici yapılandırması için derlenmelidir. Bu durumda, özellikte cfg="exec"
değerini belirtin.
Aksi takdirde, çalışma zamanında kullanılan (örneğin bir testin parçası olarak) yürütülebilir dosyalar hedef yapılandırma için derlenmelidir. Bu durumda, özellikte cfg="target"
değerini belirtin.
cfg="target"
aslında hiçbir şey yapmaz. Kural tasarımcılarının amaçları konusunda açık olmalarına yardımcı
olan bir kolaylık değeridir. cfg
değerinin isteğe bağlı olduğu executable=False
durumunda, yalnızca okunabilirliğe gerçekten yardımcı olduğu durumlarda bunu ayarlayın.
cfg=my_transition
'yi kullanıcı tanımlı geçişleri kullanmak için de kullanabilirsiniz. Bu geçişler, derleme grafiğini daha geniş ve daha az anlaşılır hale getirme dezavantajı sayesinde kural yazarlarına yapılandırma değiştirme konusunda büyük esneklik sağlar.
Not: Geçmişte Bazel'de yürütme platformu kavramı yoktu. Bunun yerine, tüm derleme işlemlerinin ana makinede çalıştırılacağı kabul ediliyordu. 6.0'dan önceki Bazel sürümleri, bunu temsil etmek için ayrı bir "ana makine" yapılandırması oluşturuyordu. Kodda veya eski belgelerde "barındırıcı" ifadelerinin kullanılması buna işaret eder. Kavramsal oluşan bu ek yükten kaçınmak için Bazel 6.0 veya daha yeni bir sürüm kullanmanızı öneririz.
Yapılandırma parçaları
Kurallar cpp
, java
ve jvm
gibi yapılandırma parçalarına erişebilir. Ancak erişim hatalarını önlemek için gerekli tüm parçaların bildirilmesi gerekir:
def _impl(ctx):
# Using ctx.fragments.cpp leads to an error since it was not declared.
x = ctx.fragments.java
...
my_rule = rule(
implementation = _impl,
fragments = ["java"], # Required fragments of the target configuration
host_fragments = ["java"], # Required fragments of the host configuration
...
)
Runfiles sembolik bağlantıları
Normalde çalıştırma dosyaları ağacındaki bir dosyanın göreli yolu, kaynak ağacındaki veya oluşturulan çıkış ağacındaki ilgili dosyanın göreli yoluyla aynıdır. Herhangi bir nedenle bunların farklı olması gerekiyorsa root_symlinks
veya symlinks
bağımsız değişkenlerini belirtebilirsiniz. root_symlinks
, dosyalarla sözlükleri eşleyen bir sözlüktür. Burada yollar, Runfiles dizininin köküne göre belirlenir. symlinks
sözlüğü aynıdır ancak yollara örtülü olarak ana çalışma alanının adı eklenir (geçerli hedefi içeren deponun adı değil).
...
runfiles = ctx.runfiles(
root_symlinks = {"some/path/here.foo": ctx.file.some_data_file2}
symlinks = {"some/path/here.bar": ctx.file.some_data_file3}
)
# Creates something like:
# sometarget.runfiles/
# some/
# path/
# here.foo -> some_data_file2
# <workspace_name>/
# some/
# path/
# here.bar -> some_data_file3
symlinks
veya root_symlinks
kullanılıyorsa iki farklı dosyayı Runfiles ağacındaki aynı yola eşlememeye dikkat edin. Bu, derlemenin çakışmayı açıklayan bir
hatayla başarısız olmasına neden olur. Bunu düzeltmek için çakışmayı kaldırmak için ctx.runfiles
bağımsız değişkenlerinizi değiştirmeniz gerekir. Bu kontrol, kuralınızı kullanan tüm hedefler ve bu hedeflere bağlı olan her tür hedef için yapılır. Aracınızın başka bir araç tarafından geçişli olarak kullanılması ihtimali yüksekse bu durum özellikle risklidir. Sembolik bağlantı adlarının bir aracın çalışma dosyaları ve tüm bağımlılıkları genelinde benzersiz olması gerekir.
Kod kapsamı
coverage
komutu çalıştırıldığında derlemenin belirli hedefler için kapsam araçları eklemesi gerekebilir. Derleme, gerekli kılınan kaynak dosyaların listesini de toplar. Değerlendirmeye alınan hedeflerin alt kümesi, --instrumentation_filter
işaretiyle kontrol edilir.
--instrument_test_targets
belirtilmediği sürece test hedefleri hariç tutulur.
Bir kural uygulaması, derleme sırasında kapsam araçları eklerse bunu uygulama işlevinde dikkate alması gerekir. Bir hedefin kaynaklarının enstrümantasyonu olması gerekiyorsa ctx.coverage_instrumented, kapsam modunda doğru değerini döndürür:
# Are this rule's sources instrumented?
if ctx.coverage_instrumented():
# Do something to turn on coverage for this compile action
Kapsam modunda her zaman açık olması gereken mantık (hedef kaynaklarının özellikle gerekli olup olmadığına bakılmaksızın), ctx.configuration.coverage_enabled
Kural, derlemeden önce bağımlılıklarından gelen kaynakları doğrudan içeriyorsa (başlık dosyaları gibi) ve bağımlılıkların kaynaklarının izlenmesi gerektiğinde derleme süresi enstrümantasyonunu da etkinleştirmesi gerekebilir:
# Are this rule's sources or any of the sources for its direct dependencies
# in deps instrumented?
if (ctx.configuration.coverage_enabled and
(ctx.coverage_instrumented() or
any([ctx.coverage_instrumented(dep) for dep in ctx.attr.deps]))):
# Do something to turn on coverage for this compile action
Kurallar, hangi özelliklerin coverage_common.instrumented_files_info
kullanılarak oluşturulan InstrumentedFilesInfo
sağlayıcısının kapsamıyla ilgili olduğu hakkında da bilgi sağlamalıdır.
instrumented_files_info
öğesinin dependency_attributes
parametresi, deps
gibi kod bağımlılıkları ve data
gibi veri bağımlılıkları dahil olmak üzere tüm çalışma zamanı bağımlılık özelliklerini listelemelidir. Kapsam araçları eklenebilecekse source_attributes
parametresi, kuralın kaynak dosyaları özelliklerini listelemelidir:
def _example_library_impl(ctx):
...
return [
...
coverage_common.instrumented_files_info(
ctx,
dependency_attributes = ["deps", "data"],
# Omitted if coverage is not supported for this rule:
source_attributes = ["srcs", "hdrs"],
)
...
]
InstrumentedFilesInfo
döndürülmezse dependency_attributes
içinde
cfg
, özellik şemasında "host"
veya "exec"
olarak ayarlanmayan her bir araç dışı bağımlılık özelliği ile varsayılan bir öğe oluşturulur. (Bu ideal bir davranış değildir çünkü source_attributes
yerine dependency_attributes
içinde srcs
gibi özellikler koyar, ancak bağımlılık zincirindeki tüm kurallar için açık kapsam yapılandırmasına ihtiyaç duyulmaz.)
Doğrulama İşlemleri
Bazen derlemeyle ilgili bir şeyi doğrulamanız gerekir ve bu doğrulamayı yapmak için gereken bilgiler yalnızca yapılarda (kaynak dosyalar veya oluşturulan dosyalar) bulunur. Bu bilgiler yapılarda bulunduğundan, kurallar dosyaları okuyamadığından kurallar analiz zamanında bu doğrulamayı yapamaz. Bunun yerine, yürütme sırasında bu doğrulamayı yapması gerekir. Doğrulama başarısız olursa işlem ve dolayısıyla derleme başarısız olur.
Çalıştırılabilecek doğrulamalara örnek olarak statik analiz, hata analizi, bağımlılık ve tutarlılık kontrolleri ve stil kontrolleri verilebilir.
Doğrulama işlemleri, yapıları oluşturmak için gerekli olmayan işlem bölümlerini ayrı işlemlere taşıyarak derleme performansının iyileştirilmesine de yardımcı olabilir. Örneğin, derleme ve hata analizi yapan tek bir işlem bir derleme işlemine ve bir hata analizi işlemine ayrılabiliyorsa hata analizi işlemi, doğrulama işlemi olarak çalıştırılabilir ve diğer işlemlerle paralel olarak çalıştırılabilir.
Bu "doğrulama işlemleri" yalnızca girişleriyle ilgili bir şeyler belirtmeleri gerektiğinden genellikle derlemenin başka bir yerinde kullanılan herhangi bir şey üretmez. Ancak bu durum bir sorun teşkil eder: Bir doğrulama işlemi derlemenin başka bir yerinde kullanılan hiçbir şey üretmezse kural, işlemin çalıştırılmasını nasıl sağlar? Eskiden yaklaşım, doğrulama işleminin boş bir dosya çıktısını sağlamak ve bu çıktıyı derlemedeki diğer önemli bir işlemin girişlerine yapay olarak eklemekti:
Bu yöntem işe yarar çünkü Bazel, derleme işlemi çalıştırıldığında her zaman doğrulama işlemini çalıştıracak olsa da bunun önemli dezavantajları da vardır:
Doğrulama işlemi, derlemenin kritik yolundadır. Bazel, derleme işlemini çalıştırmak için boş çıkışın gerekli olduğunu düşündüğünden, derleme işlemi girişi yoksaysa bile önce doğrulama işlemini çalıştırır. Bu, paralelliği azaltır ve derlemeleri yavaşlatır.
Derlemedeki diğer işlemler derleme işlemi yerine çalıştırılabilirse doğrulama işlemlerinin boş çıkışlarının da bu işlemlere eklenmesi gerekir (ör.
java_library
kaynak jar çıkışı). Bu durum ayrıca, derleme işlemi yerine çalıştırılabilecek yeni işlemlerin daha sonra eklenmesi ve boş doğrulama çıkışının yanlışlıkla bırakılması durumunda da soruna neden olur.
Bu sorunların çözümü Doğrulamalar Çıktı Grubu'nu kullanmaktır.
Doğrulamalar Çıkış Grubu
Doğrulamalar Çıkış Grubu, doğrulama işlemlerinin aksi halde kullanılmayan çıkışlarını, diğer işlemlerin girişlerine yapay olarak eklenmeleri gerekmeyecek şekilde tutmak için tasarlanmış bir çıkış grubudur.
Bu grup, --output_groups
işaretinin değerinden bağımsız olarak ve hedefin nasıl bağlı olduğuna bakılmaksızın (örneğin, komut satırında, bağımlılık olarak veya hedefin örtülü çıkışları aracılığıyla) çıkışlarının her zaman istenmesi açısından özeldir. Normal önbelleğe alma ve artımlılığın geçerli olmaya devam ettiğini unutmayın: Doğrulama işlemi için yapılan girişler değişmediyse ve doğrulama işlemi daha önce başarılıysa doğrulama işlemi çalıştırılmaz.
Bu çıkış grubunun kullanılması, doğrulama işlemlerinin boş olsa bile bazı dosyalar üretmesini gerektirir. Bu işlem, bir dosyanın oluşturulması için normalde çıkış oluşturmayan bazı araçların sarmalanmasını gerektirebilir.
Bir hedefin doğrulama işlemleri üç durumda çalıştırılmaz:
- Hedefe bir araç olarak ihtiyaç duyulduğunda
- Hedefe örtülü bir bağımlılık yapıldığında (örneğin, "_" ile başlayan bir özellik)
- Hedef, ana makine veya yönetici yapılandırmasında oluşturulduğunda.
Bu hedeflerin, doğrulama hatalarını ortaya çıkaracak kendi ayrı derleme ve testlerine sahip olduğu varsayılır.
Doğrulamalar Çıkış Grubunu Kullanma
Doğrulamalar Çıkış Grubu _validation
olarak adlandırılır ve diğer çıkış grupları gibi kullanılır:
def _rule_with_validation_impl(ctx):
ctx.actions.write(ctx.outputs.main, "main output\n")
ctx.actions.write(ctx.outputs.implicit, "implicit output\n")
validation_output = ctx.actions.declare_file(ctx.attr.name + ".validation")
ctx.actions.run(
outputs = [validation_output],
executable = ctx.executable._validation_tool,
arguments = [validation_output.path])
return [
DefaultInfo(files = depset([ctx.outputs.main])),
OutputGroupInfo(_validation = depset([validation_output])),
]
rule_with_validation = rule(
implementation = _rule_with_validation_impl,
outputs = {
"main": "%{name}.main",
"implicit": "%{name}.implicit",
},
attrs = {
"_validation_tool": attr.label(
default = Label("//validation_actions:validation_tool"),
executable = True,
cfg = "exec"),
}
)
Doğrulama çıkış dosyasının DefaultInfo
bölümüne veya başka bir işlemin girişlerine eklenmediğine dikkat edin. Hedefin etikete bağlı olduğu veya hedefin örtülü çıkışlarından herhangi birine doğrudan ya da dolaylı olarak bağımlıysa bu kural türündeki bir hedefle ilgili doğrulama işlemi çalışmaya devam eder.
Genellikle doğrulama işlemleri çıktılarının yalnızca doğrulama çıkış grubuna gitmesi ve diğer işlemlerin girişlerine eklenmemesi önemlidir. Çünkü bu, paralellik kazançlarını geçersiz kılabilir. Ancak, Bazel'in şu anda bunu uygulamak için özel bir denetimi olmadığını unutmayın. Bu nedenle, Starlark kurallarının testlerindeki hiçbir işlemin girişlerine doğrulama işlemi çıkışlarının eklenip eklenmediğini test etmeniz gerekir. Örneğin:
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
def _validation_outputs_test_impl(ctx):
env = analysistest.begin(ctx)
actions = analysistest.target_actions(env)
target = analysistest.target_under_test(env)
validation_outputs = target.output_groups._validation.to_list()
for action in actions:
for validation_output in validation_outputs:
if validation_output in action.inputs.to_list():
analysistest.fail(env,
"%s is a validation action output, but is an input to action %s" % (
validation_output, action))
return analysistest.end(env)
validation_outputs_test = analysistest.make(_validation_outputs_test_impl)
Doğrulama İşlemleri İşareti
Doğrulama işlemlerinin çalıştırılması, varsayılan olarak "doğru" değerini alan --run_validations
komut satırı işaretiyle kontrol edilir.
Desteği sonlandırılan özellikler
Desteği sonlandırılan önceden beyan edilmiş çıkışlar
Önceden beyan edilmiş çıkışları kullanmanın desteği sonlandırılmış iki yöntemi vardır:
rule
öğesininoutputs
parametresi, önceden beyan edilmiş çıkış etiketleri oluşturmak için çıkış özelliği adları ile dize şablonları arasında bir eşleme belirtir. Önceden bildirilmemiş çıkışları kullanmayı ve çıkışları açıkçaDefaultInfo.files
öğesine eklemeyi tercih edin. Önceden beyan edilmiş bir çıkışın etiketi yerine çıkışı tüketen kurallar için giriş olarak kural hedefinin etiketini kullanın.Yürütülebilir kurallar için
ctx.outputs.executable
, kural hedefiyle aynı ada sahip önceden bildirilmiş yürütülebilir bir çıkışı ifade eder. Çıkışı açıkça (örneğin,ctx.actions.declare_file(ctx.label.name)
ile) beyan etmeyi tercih edin ve yürütülebilir dosyayı oluşturan komutun izinleri yürütülebilecek şekilde ayarladığından emin olun. Yürütülebilir çıkışı açık bir şekildeDefaultInfo
öğesininexecutable
parametresine iletin.
Kaçınılması gereken Runfiles özellikleri
ctx.runfiles
ve runfiles
türü, birçoğu eski nedenlerle saklanan bir dizi karmaşık özelliğe sahiptir.
Aşağıdaki öneriler karmaşıklığı azaltmaya yardımcı olur:
ctx.runfiles
collect_data
vecollect_default
modlarını kullanmaktan kaçının. Bu modlar, çalışma dosyalarını sabit kodlu belirli bağımlılık kenarlarında karmaşık yöntemlerle, dolaylı olarak toplar. Bunun yerine,ctx.runfiles
öğesininfiles
veyatransitive_files
parametrelerini kullanarak ya da bağımlılardan gelen çalıştırma dosyalarınırunfiles = runfiles.merge(dep[DefaultInfo].default_runfiles)
ile birleştirerek dosya ekleyin.DefaultInfo
oluşturucunundata_runfiles
vedefault_runfiles
kullanımından kaçının. Bunun yerineDefaultInfo(runfiles = ...)
değerini belirtin. "Varsayılan" ve "veri" çalıştırma dosyaları arasındaki ayrım, eski nedenlerle korunur. Örneğin, bazı kurallar varsayılan çıkışlarınıdata_runfiles
konumuna yerleştirir, ancakdefault_runfiles
içine koymaz. Kurallarındata_runfiles
kullanmak yerine varsayılan çıkışları içermesi ve çalıştırma dosyaları sağlayan özelliklerdendefault_runfiles
içinde birleştirilmesi gerekir (genellikledata
).DefaultInfo
öğesindenrunfiles
alırken (genellikle yalnızca geçerli kural ve bağımlılıkları arasında çalıştırma dosyalarını birleştirmek için)DefaultInfo.data_runfiles
değerini kullanmayın.DefaultInfo.default_runfiles
kullanın.
Eski sağlayıcılardan taşıma
Geçmişte Bazel sağlayıcıları Target
nesnesindeki basit alanlardı. Bu uygulamalara nokta operatörü kullanılarak erişildi ve alan, kuralın uygulama işlevi tarafından döndürülen bir struct'ın içine yerleştirilerek oluşturuldu.
Bu stil kullanımdan kaldırıldı ve yeni kodda kullanılmamalıdır. Geçiş yapmanıza yardımcı olabilecek bilgiler için aşağıya bakın. Yeni sağlayıcı mekanizması, ad çakışmalarını önler. Ayrıca, sağlayıcı örneğine erişen kodların sağlayıcı sembolünü kullanarak almasını zorunlu kılarak veri gizlemeyi de destekler.
Şu an için, eski sağlayıcılar desteklenmektedir. Bir kural, hem eski hem de modern sağlayıcıları aşağıdaki gibi döndürebilir:
def _old_rule_impl(ctx):
...
legacy_data = struct(x="foo", ...)
modern_data = MyInfo(y="bar", ...)
# When any legacy providers are returned, the top-level returned value is a
# struct.
return struct(
# One key = value entry for each legacy provider.
legacy_info = legacy_data,
...
# Additional modern providers:
providers = [modern_data, ...])
dep
, bu kuralın bir örneği için sonuçta ortaya çıkan Target
nesnesiyse sağlayıcılar ve içerikleri dep.legacy_info.x
ve dep[MyInfo].y
olarak alınabilir.
Döndürülen struct, providers
'e ek olarak özel anlamı olan birkaç başka alanı da alabilir (dolayısıyla buna karşılık gelen bir eski sağlayıcı oluşturmaz):
files
,runfiles
,data_runfiles
,default_runfiles
veexecutable
alanları,DefaultInfo
öğesinin aynı adlı alanlarına karşılık gelir. BirDefaultInfo
sağlayıcısı döndürürken bu alanlardan herhangi birinin belirtilmesine izin verilmez.output_groups
alanı bir struct değeri alır ve birOutputGroupInfo
değerine karşılık gelir.
provides
kural bildirimlerinde ve providers
bağımlılık özelliği bildirimlerinde, eski sağlayıcılar dize olarak, modern sağlayıcılar ise *Info
sembolleri ile aktarılır. Taşıma sırasında dizeleri semboller
olarak değiştirdiğinizden emin olun. Tüm kuralların atomik olarak güncellenmesinin zor olduğu karmaşık veya büyük kural kümeleri için aşağıdaki adım sırasını uygulamanız daha kolay olabilir:
Yukarıdaki söz dizimini kullanarak eski sağlayıcıyı oluşturan kuralları hem eski hem de modern sağlayıcıları oluşturacak şekilde değiştirin. Eski sağlayıcıyı iade ettiğini belirten kurallar için bu beyanı hem eski hem de modern sağlayıcıları içerecek şekilde güncelleyin.
Eski sağlayıcıyı kullanan kuralları, bunun yerine modern sağlayıcıyı kullanacak şekilde değiştirin. Herhangi bir özellik bildirimleri için eski sağlayıcı gerekiyorsa bunları da modern sağlayıcıyı gerektirecek şekilde güncelleyin. İsteğe bağlı olarak, tüketicilerin
hasattr(target, 'foo')
kullanarak eski sağlayıcının varlığını test etme veyaFooInfo in target
kullanarak yeni sağlayıcıdan birini kabul etmesini/zorunlu kılmasını sağlayarak bu çalışmayı 1. adıma ekleyebilirsiniz.Eski sağlayıcıyı tüm kurallardan tamamen kaldırın.