Kural, Bazel'in girişlerde gerçekleştirdiği ve bir dizi çıkış üreten bir dizi işlem tanımlar. Bu çıkışlara, kuralın uygulama işlevi tarafından döndürülen sağlayıcılarda referans verilir. Örneğin, bir C++ ikili kuralı şu şekilde olabilir:
- Bir dizi
.cpp
kaynak dosyası (giriş) alın. - Kaynak dosyalarda
g++
'ü çalıştırın (işlem). - Yürütülebilir çıkışı ve çalışma zamanında kullanılabilmesi için diğer dosyaları içeren
DefaultInfo
sağlayıcıyı döndürün. CcInfo
sağlayıcısını, hedeften ve bağımlılıklarından toplanan C++'a özgü bilgilerle iade edin.
Bazel'in bakış açısından g++
ve standart C++ kitaplıkları da bu kuralın girişleridir. 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. Derlemenin üç aşamasını (yükleme, analiz ve yürütme) anlamanız önemlidir. Kurallar ile makrolar arasındaki farkı anlamak için makrolar hakkında bilgi edinmeniz de faydalı olacaktır. Başlamak için önce Kurallar Eğitimi'ni inceleyin. Ardından, bu sayfayı referans olarak kullanın.
Bazel'in kendisine yerleştirilmiş birkaç kural vardır. cc_library
ve java_binary
gibi bu yerel kurallar, belirli diller için temel düzeyde destek sağlar.
Kendi kurallarınızı tanımlayarak Bazel'in doğal olarak desteklemediği diller ve araçlar için benzer destek ekleyebilirsiniz.
Bazel, Starlark dilini kullanarak kurallar 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 destekleyeceğine ve çıkışlarını nasıl oluşturacağına siz karar verirsiniz.
Kuralın implementation
işlevi, analiz aşaması sırasındaki tam davranışını tanımlar. Bu işlev harici komut çalıştırmaz. Bunun yerine, daha sonra yürütme aşamasında kuralın çıkışlarını oluşturmak için kullanılacak işlemleri kaydeder (gerekirse).
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 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. İkincisi ise kural bir test kuralı olur ve kuralın adı _test
ile bitmelidir.
Hedef örneklendirme
Kurallar BUILD
dosyalarında yüklenebilir ve ç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 örneklenmesi denir. Bu, yeni hedef için bir ad ve hedefin özelliklerinin değerlerini belirtir.
Kurallar, Starlark işlevlerinden çağrılabilir ve .bzl
dosyalarına yüklenebilir.
Kuralları çağıran Starlark işlevlerine Starlark makroları denir.
Starlark makroları nihayetinde BUILD
dosyalarından çağrılmalıdır ve yalnızca BUILD
dosyalarının hedefleri örneklemek için değerlendirildiği yükleme aşamasında çağrılabilir.
Özellikler
Özellik, bir kural bağımsız değişkenidir. Özellikler, bir hedefin uygulanması için belirli değerler sağlayabilir veya diğer hedeflere atıfta bulunarak bağımlılık grafiği oluşturabilir.
srcs
veya deps
gibi kurala özgü özellikler, özellik adlarından şemalara (attr
modülü kullanılarak oluşturulur) bir eşleme geçirilerek rule
'nin attrs
parametresine iletilerek tanımlanır.
name
ve visibility
gibi ortak özellikler tüm kurallara dolaylı olarak eklenir. Ek özellikler özellikle yürütülebilir ve test kurallarına dolaylı olarak eklenir. Bir kurala dolaylı olarak eklenen özellikler, attrs
parametresine iletilen sözlüğe dahil edilemez.
Bağımlılık özellikleri
Kaynak kodunu işleyen kurallar genellikle çeşitli bağımlılıkları işlemek için aşağıdaki özellikleri tanımlar:
srcs
, bir hedefin işlemleri tarafından işlenen kaynak dosyaları belirtir. Özellik şeması genellikle, kuralın işlediği kaynak dosya türü 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 hedefin kod bağımlılıklarını belirtir. Özellik şeması, bu bağımlılıkların hangi sağlayıcılar tarafından sağlanacağını belirtmelidir. (Örneğin,cc_library
,CcInfo
sağlar.)data
, bir hedefe bağlı olan tüm yürütülebilir dosyalara çalışma zamanında kullanıma sunulacak dosyaları belirtir. Bu sayede, istediğiniz dosyaları belirtebilirsiniz.
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ş etiketini belirten tüm özellikler (attr.label_list
, attr.label
veya attr.label_keyed_string_dict
ile tanımlananlar), hedef tanımlanırken etiketleri (veya ilgili Label
nesneleri) bu özellikte listelenen hedefler ile hedef arasında belirli bir türde bağımlılıkları belirtir. Bu etiketlerin depolama alanı ve muhtemelen yolu, tanımlanan hedefe göre çözülür.
example_library(
name = "my_target",
deps = [":other_target"],
)
example_library(
name = "other_target",
...
)
Bu örnekte other_target
, my_target
'un bir bağımlısıdır ve bu nedenle önce other_target
analiz edilir. Hedeflerin bağımlılık grafiğinde döngü varsa hata oluşur.
Ö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şlevi içinde bu, 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 özellikleri genellikle yalnızca gizli bağımlılıklarda kullanmak mantıklı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, kullanıcı etiketini giriş olarak iletmemiş olsa bile example_library
'ün uygulama işlevinin derleyiciyi çağıran işlemler oluşturmasına olanak tanır. _compiler
özel bir özellik olduğundan ctx.attr._compiler
, bu kural türünün tüm hedeflerinde her zaman //tools:example_compiler
değerini işaret eder. Alternatif olarak, özelliği alt çizgi olmadan compiler
olarak adlandırabilir ve 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.
Örtük bağımlılıklar genellikle kural uygulamasıyla aynı depoda bulunan araçlar için kullanılır. Araç çalışma platformundan veya farklı bir depodan geliyorsa kural, bu aracı bir araç zincirinden almalıdır.
Çıkış özellikleri
attr.output
ve attr.output_list
gibi çıkış özellikleri, hedefin oluşturduğu bir çıkış dosyasını belirtir. Bu özellikler, bağımlılık özelliklerinden iki şekilde farklıdır:
- Başka bir yerde tanımlanan hedeflere başvurmak yerine çıkış dosyası hedeflerini tanımlarlar.
- Çıkış dosyası hedefleri, örneklenen kural hedefine bağlıdır. Bunun tersi olmaz.
Çıkış özellikleri genellikle yalnızca bir kuralın, hedef ada dayandırılamayan kullanıcı tanımlı adlarla çıkış oluşturması gerektiğinde kullanılır. Bir kuralın bir çıkış özelliği varsa kural genellikle out
veya outs
olarak adlandırılır.
Çıkış özellikleri, önceden bildirilmiş çıkışlar oluşturmanın tercih edilen yoludur. Bu çıkışlara özel olarak bağımlı olunabilir veya komut satırında istenebilir.
Uygulama işlevi
Her kural için bir implementation
işlevi gerekir. Bu işlevler yalnızca analiz aşamasında yürütülür ve yükleme aşamasında oluşturulan hedef grafiğini, yürütme aşamasında gerçekleştirilecek işlemler grafiğine dönüştürür. Bu nedenle, uygulama işlevleri aslında dosyaları okuyamaz veya yazamaz.
Kural uygulama işlevleri genellikle özeldir (başında alt çizgi bulunan bir adla adlandırılır). Geleneksel olarak kurallarıyla aynı şekilde adlandırılır ancak son ekleri _impl
ile belirtilir.
Uygulama işlevleri tam olarak bir parametre alır: Geleneksel olarak ctx
olarak adlandırılan bir kural bağlamı. Sağlayıcıların listesini döndürürler.
Hedefler
Bağımlılıklar, analiz sırasında Target
nesneleri olarak temsil edilir. Bu nesneler, hedefin uygulama işlevi yürütüldüğünde oluşturulan sağlayıcıları içerir.
ctx.attr
, her bağımlılık özelliğinin adlarına karşılık gelen alanlara sahiptir. Bu alanlar, ilgili özellik aracılığıyla her doğrudan bağımlılığı temsil eden Target
nesneleri içerir. 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 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 genel değişkenleri olarak kullanılabilen yerel kurallar için sağlayıcılar olabilir.
Örneğin, bir kural hdrs
özelliği aracılığıyla üstbilgi dosyalarını alır ve bunları hedefin ve tüketicilerinin derleme işlemlerine sağlarsa bunları aşağıdaki gibi toplayabilir:
def _example_library_impl(ctx):
...
transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs]
Hedefin uygulama işlevinden sağlayıcı nesneleri listesi yerine struct
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 stilin kullanılması önerilmez ve kurallar bu stilde taşınmamalıdır.
Dosyalar
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, işlem grafiğinin parçalarını oluşturmak için işlem yayınlayan işlevlere (ctx.actions
bölümüne bakın) iletilir.
File
, kaynak dosya veya oluşturulmuş 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 ctx.files
'un ilgili 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 çalışır ancak yalnızca spesifikasyonları executable=True
ayarlayan bağımlılık özelliklerinin alanlarını içerir.
Çıktıları beyan etme
Analiz aşamasında, bir kuralın uygulama işlevi çıkışlar oluşturabilir.
Yükleme aşamasında tüm etiketlerin bilinmesi gerektiğinden bu ek çıkışlarda etiket yoktur. Çıkışlar için File
nesneleri ctx.actions.declare_file
ve ctx.actions.declare_directory
kullanılarak oluşturulabilir. Çıktıların adları genellikle hedefin adına göre belirlenir (ctx.label.name
):
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ışlar için ctx.outputs
'nin ilgili alanlarından File
nesneleri alınabilir.
İşlemler
İşlem, bir giriş grubundan nasıl bir çıkış grubu oluşturulacağını açıklar. Örneğin, "hello.c üzerinde gcc'yi çalıştır ve hello.o dosyasını al". Bazel, bir işlem oluşturulduğunda 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
içinde tanımlanır:
ctx.actions.run
, yürütülebilir bir dosyayı çalıştırmak için.ctx.actions.run_shell
, kabuk komutu çalıştırmak içinctx.actions.write
, bir dosyaya dize yazmak için kullanılır.ctx.actions.expand_template
simgesini tıklayarak şablondan dosya oluşturabilirsiniz.
ctx.actions.args
, işlemlere ait bağımsız değişkenleri verimli bir şekilde toplamak için kullanılabilir. Yürütme zamanına kadar depsetlerin 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ış dosyası 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şleminizde unzip komutu çalıştırılıyorsa hangi dosyaların şifresinin çözülmesini beklediğinizi belirtmeniz gerekir (unzip komutunu çalıştırmadan önce). Dahili olarak değişken sayıda dosya oluşturan işlemler, bu dosyaları tek bir dosyaya (ör. zip, tar veya başka bir arşiv biçimi) sarmalayabilir.
İşlemlerde tüm girişler listelenmelidir. Kullanılmayan girişlerin listelenmesine izin verilir ancak bu durum verimsizdir.
İşlemler, tüm çıkışlarını oluşturmalıdır. Diğer dosyaları yazabilirler ancak çıktılarda olmayan hiçbir şey tüketicilere sunulmaz. Tanımlanan tüm çıkışlar bir işlem tarafından yazılmalıdır.
İşlemler, saf işlevlerle benzerdir: Yalnızca sağlanan girişlere bağlı olmalı ve bilgisayar bilgileri, kullanıcı adı, saat, ağ veya G/Ç cihazlarına (giriş okuma ve çıkış yazma hariç) erişmekten kaçınmalıdır. Çıkış önbelleğe alınıp 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 kendisine bağlı diğer kurallara gösterdiği bilgi parçalarıdır. Bu veriler arasında çıkış dosyaları, kitaplıklar, bir aracın komut satırında iletilecek parametreler veya hedefin tüketicilerinin bilmesi gereken başka herhangi bir şey bulunabilir.
Bir kuralın uygulama işlevi yalnızca örneklendirilmiş hedefin doğrudan bağımlılıklarındaki sağlayıcıları okuyabildiğinden, kuralların hedefin bağımlılıkları arasından hedefin tüketicileri tarafından bilinmesi gereken tüm bilgileri genellikle bir depset
içinde toplayarak iletmesi gerekir.
Bir hedefin sağlayıcıları, uygulama işlevi tarafından döndürülen Provider
nesnelerinin listesi ile belirtilir.
Eski uygulama işlevleri, uygulama işlevinin sağlayıcı nesneleri listesi yerine struct
döndürdüğü eski bir tarzda da yazılabilir. Bu stil kesinlikle önerilmez ve kuralların kendisinden taşınması gerekir.
Varsayılan çıkışlar
Bir hedefin varsayılan çıkışları, hedefin komut satırında derlenmesi istendiğinde varsayılan olarak istenen çıkışlardır. Örneğin, java_library
hedefi //pkg:foo
varsayılan çıkış olarak foo.jar
değerine sahiptir. Bu nedenle, bazel build //pkg:foo
komutu tarafından oluşturulur.
Varsayılan çıkışlar, DefaultInfo
öğesinin files
parametresi tarafından belirtilir:
def _example_library_impl(ctx):
...
return [
DefaultInfo(files = depset([output_file]), ...),
...
]
DefaultInfo
bir kural uygulaması tarafından döndürülmezse veya files
parametresi belirtilmezse DefaultInfo.files
varsayılan olarak tüm önceden tanımlanmış çıkışlara (genellikle çıkış özellikleri tarafından oluşturulanlar) ayarlanır.
İşlem gerçekleştiren kurallar, bu çıktıların doğrudan kullanılması beklenmese bile varsayılan çıktılar sağlamalıdır. İstenen çıkışların grafiğinde bulunmayan işlemler budanır. Bir çıkış yalnızca bir hedefin tüketicileri tarafından kullanılıyorsa hedef tek başına oluşturulduğunda bu işlemler gerçekleştirilmez. Yalnızca başarısız hedefi yeniden oluşturmak hatayı yeniden oluşturmayacağından bu durum, hata ayıklamayı daha zor hale getirir.
Çalışma dosyaları
Çalışma dosyaları, bir hedefin çalışma zamanında (derleme zamanı yerine) kullandığı bir dosya grubudur. Bazel, yürütme aşamasında çalışma dosyalarına işaret eden sembolik bağlantılar içeren bir dizin ağacı oluşturur. Bu işlem, çalışma zamanında çalışma dosyalarına erişebilmesi için ortamda ikili dosyayı hazırlar.
Çalıştırma dosyaları, kural oluşturma sırasında manuel olarak eklenebilir.
runfiles
nesneleri, kural bağlamındaki runfiles
yöntemi tarafından ctx.runfiles
oluşturulabilir ve DefaultInfo
'deki runfiles
parametresine iletilebilir. Yürütülebilir kuralların yürütülebilir çıkışı, çalışma dosyalarına dolaylı olarak eklenir.
Bazı kurallar, genellikle data
olarak adlandırılan ve çıkışları hedeflerin çalışma dosyalarına eklenen özellikleri belirtir. Runfile'ler, data
'ten ve genellikle srcs
(ilişkili data
'ye sahip filegroup
hedefler içerebilir) ve deps
'tan da 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
Kuralla ilgili bilgileri iletmek için provider
işlevi kullanılarak sağlayıcılar 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.",
})
Kural uygulama işlevleri daha sonra 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 olarak başlatılması
Özel ön işleme ve doğrulama mantığıyla bir sağlayıcının oluşturulmasını korumak mümkündür. Bu, tüm sağlayıcı örneklerinin belirli değişmezlik kurallarına uymasını sağlamak veya kullanıcılara örnek elde etmek için daha temiz bir API sunmak için kullanılabilir.
Bu işlem, provider
işlevine bir init
geri çağırma işlevi geçirilerek yapılır. Bu geri çağırma işlevi sağlanırsa provider()
işlevinin döndürdüğü tür, iki değerden oluşan bir tuple olarak değişir: init
kullanılmadığında normal döndürülen değer olan sağlayıcı simgesi ve "ham kurucu".
Bu durumda, sağlayıcı sembolü çağrıldığında doğrudan yeni bir örnek döndürmek yerine bağımsız değişkenleri init
geri çağırma işlevine iletir. 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şlevinin herhangi bir imzaya sahip olabileceğini ve bağımsız değişkenler imzayla eşleşmezse geri çağırma işlevi doğrudan çağrılmış gibi bir hata bildirildiğ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 ön işleme almak ve doğrulamak için init
kullanılı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 kurucu, init
mantığından geçmeyen alternatif herkese açık fabrika işlevleri tanımlamak için kullanılabilir. Örneğin, exampleinfo.bzl dosyasında şunları tanımlayabiliriz:
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)
Ham kurucu genellikle adı alt çizgiyle başlayan bir değişkene (yukarıdaki _new_exampleinfo
) bağlanır. Böylece kullanıcı kodu, kurucuyu yükleyemez ve rastgele sağlayıcı örnekleri oluşturamaz.
init
'ün başka bir kullanımı, kullanıcının sağlayıcı simgesini çağırmasını tamamen engellemek ve bunun yerine kullanıcıyı 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, bazel run
komutu tarafından çağrılabilecek hedefleri tanımlar.
Test kuralları, hedefleri bazel test
komutuyla da çağrılabilecek özel bir tür çalıştırılabilir kuraldı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 bulunmamalı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ş olabilir veya bildirilmemiş olabilir) oluşturmalıdır. Bazel'e, bir kuralın çıktılarından hangisinin bu yürütülebilir dosya olarak kullanılacağını bildirmek için döndürülen bir DefaultInfo
sağlayıcı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şlemleri 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 iletin.
Eski davranış olarak, yürütülebilir kuralların özel bir ctx.outputs.executable
önceden tanımlanmış çıkışı vardır. DefaultInfo
kullanarak bir dosya belirtmezseniz bu dosya varsayılan yürütülebilir dosya olarak kullanılır. Aksi takdirde kullanılmamalıdır. Bu çıkış mekanizması, analiz sırasında yürütülebilir dosyanın adını özelleştirmeyi desteklemediği için desteği sonlandırılmıştır.
Yürütülebilir kural ve test kuralı örneklerini inceleyin.
Yürütülebilir kurallar ve test kuralları, tüm kurallar için eklenenlere ek olarak, 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(
...
)
Çalışma dosyası konumu
Bir yürütülebilir hedef bazel run
(veya test
) ile çalıştırıldığında, runfiles dizininin kökü yürütülebilir dosyanın yanındadır. 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 dizini altındaki bir File
'nin yolu File.short_path
'ye 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, bir ortam veya komut satırı bağımsız değişkeni/işareti kullanarak çalıştırma dosyası kökünü parametre olarak kabul etmenin bir yolunu sağlamalıdır. Bu sayede ikili dosyalar, çağırdığı ikili dosyalara doğru standart çalışma dosyası kökünü iletebilir. Bu ayar yapılmazsa bir ikili, çağrılan ilk ikili olduğunu tahmin edebilir ve bitişik bir runfiles dizini arayabilir.
İleri seviye konular
Çıkış dosyaları isteğinde bulunma
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 istenen bu dosyaları ve doğrudan veya dolaylı olarak bu dosyalara bağlı olan dosyaları derleyebilir. (İşlem grafiği açısından 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, komut satırında açıkça istenebilecek herhangi bir önceden bildirilmiş çıkış vardır. 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
nesneleri elde etmek üzere ctx.outputs
'in ilgili özelliğini kullanın. Kurallar, hedef ada göre ö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. Bu bilgiler --output_groups
ile istenebilir. Örneğin, bir hedef //pkg:mytarget
, debug_files
çıkış grubuna sahip bir kural türüne sahipse bu dosyalar bazel build //pkg:mytarget
--output_groups=debug_files
çalıştırılarak oluşturulabilir. Önceden tanımlanmamış çıkışların etiketi olmadığından yalnızca varsayılan çıkışlarda veya bir çıkış grubunda görünerek istenebilirler.
Çı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 yön hem de bu yönün uygulandığı kural hedefi tarafından döndürülebilir. Bu durumda, ortaya çıkan sağlayıcılar birleştirilir.
OutputGroupInfo
değerinin genellikle bir hedeften tüketicilerinin işlemlerine belirli dosya türlerini iletmek için kullanılmaması gerektiğini unutmayın. Bunun yerine kurala özgü sağlayıcılar tanımlayın.
Yapılandırmalar
Farklı bir mimari için C++ ikili dosyası oluşturmak istediğinizi varsayalım. Derleme karmaşık olabilir ve birden fazla adım içerebilir. Derleyiciler ve kod oluşturucular gibi bazı ara ikili dosyaların yürütme platformunda (barındırma sunucunuz veya uzak bir yürütücü olabilir) çalıştırılması gerekir. Nihai çıkış gibi bazı ikili dosyalar, hedef mimari için derlenmelidir.
Bu nedenle Bazel'de "yapılandırmalar" ve geçişler kavramı vardır. En üstteki hedefler ("target" yapılandırmasında oluşturulan, komut satırında istenen hedefler) "target" yapılandırmasında, yürütme platformunda çalıştırılması gereken araçlar ise "exec" yapılandırmasında oluşturulur. Kurallar, yapılandırmaya bağlı olarak farklı işlemler oluşturabilir (ör. derleyiciye iletilen CPU mimarisini değiştirmek için). Bazı durumlarda, farklı yapılandırmalar için aynı kitaplığa ihtiyaç duyulabilir. Bu durumda, analiz edilir ve muhtemelen birden çok kez oluşturulur.
Bazel, varsayılan olarak bir hedefin bağımlılarını hedefin kendisiyle aynı yapılandırmada, yani geçişler 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ılarının yürütme platformu için derlenmesine neden olur.
Bağımlılıkların aynı yapılandırmada mı yoksa bir yürütme yapılandırmasına mı oluşturulacağına karar vermek için her bağımlılık özelliğinde cfg
kullanabilirsiniz.
Bir bağımlılık özelliğinde executable=True
işareti varsa cfg
açıkça ayarlanmalıdır. Bu, yanlış yapılandırma için yanlışlıkla bir araç oluşturmaya karşı önlem almaktır.
Örneğe bakın
Genel olarak, çalışma zamanında ihtiyaç duyulacak kaynaklar, bağımlı kitaplıklar ve yürütülebilir dosyalar aynı yapılandırmayı kullanabilir.
Derleme işleminin bir parçası olarak çalıştırılan araçlar (ör. derleyiciler veya kod oluşturucular) bir exec yapılandırması için derlenmelidir. Bu durumda, özellikte cfg="exec"
değerini belirtin.
Aksi takdirde, çalışma zamanında kullanılan yürütülebilir dosyalar (ör. bir testin parçası olarak) hedef yapılandırma için derlenmelidir. Bu durumda, özellikte cfg="target"
değerini belirtin.
cfg="target"
aslında hiçbir şey yapmaz: Yalnızca kural tasarımcılarının niyetleri konusunda net olmalarına yardımcı olmak için kullanılan bir kolaylık değeridir. executable=False
olduğunda (cfg
isteğe bağlıdır), bu seçeneği yalnızca okunabilirliği gerçekten artırdığı durumlarda ayarlayın.
cfg=my_transition
simgesini kullanarak kullanıcı tanımlı geçişler de kullanabilirsiniz. Bu geçişler, kural yazarlarına yapılandırmaları değiştirme konusunda çok fazla esneklik sağlar. Bunun dezavantajı ise derleme grafiğinin daha büyük ve daha az anlaşılır hale gelmesidir.
Not: Bazel'de geçmişte yürütme platformu kavramı yoktu ve bunun yerine tüm derleme işlemlerinin ana makinede çalıştığı kabul ediliyordu. Bu nedenle, tek bir "ana makine" yapılandırması ve ana makine yapılandırmasında bağımlılık oluşturmak için kullanılabilecek bir "ana makine" geçişi vardır. Birçok kural, araçları için hâlâ "host" geçişini kullanıyor ancak bu geçiş şu anda desteği sonlandırılmış durumda ve mümkün olduğunda "exec" geçişlerinin kullanılması için taşınıyor.
"Ana makine" ve "yürütücü" yapılandırmaları arasında birçok fark vardır:
- "host" terminaldir, "exec" değildir: "host" yapılandırmasında bir bağımlılık oluşturulduktan sonra başka geçişe izin verilmez. "exec" yapılandırmasına başladıktan sonra başka yapılandırma geçişleri yapmaya devam edebilirsiniz.
- "host" monolitik, "exec" ise değildir: Yalnızca bir "ana makine" yapılandırması vardır ancak her yürütme platformu için farklı bir "yürütme" yapılandırması olabilir.
- "ana makine", araçları Bazel ile aynı makinede veya önemli ölçüde benzer bir makinede çalıştırdığınızı varsayar. Bu artık geçerli değil: Derleme işlemlerini yerel makinenizde veya uzaktaki bir yürütücüde çalıştırabilirsiniz. Ayrıca, uzak yürütücünün yerel makinenizle aynı CPU ve işletim sistemi olduğunun garantisi yoktur.
Hem "exec" hem de "host" yapılandırmaları aynı seçenek değişikliklerini uygular (örneğin, --host_compilation_mode
yerine --compilation_mode
ayarlayın, --host_cpu
yerine --cpu
ayarlayın vb.). Aralarındaki fark, "ana makine" yapılandırmasının diğer tüm işaretlerin varsayılan değerleriyle başlaması ve "exec" yapılandırmasının, hedef yapılandırmaya bağlı olarak flag'lerin geçerli değerleriyle başlamasıdır.
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 bildirilmelidir:
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
...
)
ctx.fragments
yalnızca hedef yapılandırma için yapılandırma parçaları sağlar. Ana makine yapılandırması için parçalara erişmek istiyorsanız bunun yerine ctx.host_fragments
kullanın.
Runfiles sembolik bağlantıları
Normalde, bir dosyanın runfiles ağacındaki göreli yolu, söz konusu dosyanın kaynak ağaç veya oluşturulan çıkış ağacındaki göreli yolu ile aynıdır. Bu değerlerin bir nedenle farklı olması gerekiyorsa root_symlinks
veya symlinks
bağımsız değişkenlerini belirtebilirsiniz. root_symlinks
, yolları dosyalarla eşleyen bir sözlüktür. Bu yolların referans noktası, runfiles dizininin köküdür. symlinks
sözlüğü aynıdır ancak yolların önüne çalışma alanının adı gizli olarak eklenir.
...
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ı, çalıştırma dosyaları ağacında 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 hedeflerin yanı sıra bu hedeflere bağlı her tür hedef için yapılır. Bu durum, aracınızın başka bir araç tarafından aktarmalı olarak kullanılması muhtemelse özellikle risklidir. Simge bağlantısı adları, bir aracın çalışma dosyalarında ve tüm bağımlılıklarında benzersiz olmalıdır.
Kod kapsamı
coverage
komutu çalıştırıldığında derlemenin belirli hedefler için kapsam araçları eklemesi gerekebilir. Derleme, enstrümante edilen 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 (bir hedefin kaynaklarının özel olarak enstrümante edilip edilmediği), ctx.configuration.coverage_enabled değerine göre koşullandırılabilir.
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 zamanı 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 ayrıca, coverage_common.instrumented_files_info
kullanılarak oluşturulan InstrumentedFilesInfo
sağlayıcıyla kapsam için hangi özelliklerin alakalı olduğu hakkında 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ı da dahil olmak üzere tüm çalışma zamanı bağımlılık özelliklerini listelemelidir. Kapsam enstrümantasyonu eklenebilirse source_attributes
parametresi, kuralın kaynak dosya ö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. (srcs
gibi özellikleri source_attributes
yerine dependency_attributes
içine yerleştirdiği için bu ideal bir davranış değildir ancak bağımlılık zincirindeki tüm kurallar için açık kapsam yapılandırması gerekmesini önler.)
Doğrulama İşlemleri
Bazen derlemeyle ilgili bir şeyi doğrulamanız gerekir ve bu doğrulamayı yapmak için gereken bilgiler yalnızca yapı taşlarında (kaynak dosyalar veya oluşturulan dosyalar) bulunur. Bu bilgiler yapılarda olduğu için kurallar dosyaları okuyamadığından analiz sırasında bu doğrulamayı yapamaz. Bunun yerine, işlemlerin bu doğrulamayı yürütme sırasında 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, linting, bağımlılık ve tutarlılık kontrolleri ve stil kontrolleri verilebilir.
Doğrulama işlemleri, yapı oluşturmak için gerekli olmayan işlem parçalarını ayrı işlemlere taşıyarak derleme performansını iyileştirmeye de yardımcı olabilir. Örneğin, derleme ve linting yapan tek bir işlem, derleme işlemi ve linting işlemi olarak ayrılabilirse linting işlemi, doğrulama işlemi olarak ve diğer işlemlerle paralel olarak çalıştırılabilir.
Bu "doğrulama işlemleri" genellikle yalnızca girişleriyle ilgili iddialarda bulunmaları gerektiğinden derlemede başka bir yerde kullanılan bir şey üretmez. Ancak bu durum bir sorun teşkil eder: Bir doğrulama işlemi, derlemede başka bir yerde kullanılan bir şey üretmiyorsa kural, işlemi nasıl çalıştırır? Geçmişte, doğrulama işleminin boş bir dosya oluşturması ve bu çıktıyı derlemedeki diğer önemli işlemlerin girişlerine yapay olarak eklemesi yaklaşımı benimseniyordu:
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.
Derleme işlemi yerine derlemedeki diğer işlemler çalışabilirse doğrulama işlemlerinin boş çıkışlarının bu işlemlere de eklenmesi gerekir (örneğin,
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ğrulama Çıktı Grubu, doğrulama işlemlerinin aksi takdirde kullanılmayan çıkışlarını tutmak için tasarlanmış bir çıkış grubudur. Böylece, diğer işlemlerin girişlerine yapay olarak eklenmeleri gerekmez.
Bu grup, --output_groups
işaretinin değerinden ve hedefin nasıl bağımlı olduğundan (örneğin, komut satırında, bağımlılık olarak veya hedefin gizli çıkışları aracılığıyla) bağımsız olarak çıkışlarının her zaman istenmesi açısından özeldir. Normal önbelleğe alma ve artımlılığın geçerliliğini koruduğunu unutmayın: Doğrulama işleminin girişleri değişmediyse ve doğrulama işlemi daha önce başarılı olduysa doğrulama işlemi çalıştırılmaz.
Bu çıkış grubunu kullanmak için doğrulama işlemlerinin boş olsa bile bir dosya oluşturması gerekir. Bu işlem, normalde çıkış oluşturmayan bazı araçları sarmalayarak dosya oluşturmayı gerektirebilir.
Bir hedefin doğrulama işlemleri üç durumda çalıştırılmaz:
- Hedef bir araç olarak kullanıldığında
- 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ı derlemelerinin ve testlerinin olduğu varsayılır.
Doğrulamalar Çıkış Grubu'nu kullanma
Doğrulama Çıkış Grubu _validation
olarak adlandırılır ve diğer tüm çı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. Bu tür bir kuralın hedefi için doğrulama işlemi, hedef etikete bağlıysa veya hedefin herhangi bir gizli çıkışına doğrudan ya da dolaylı olarak bağlıysa yine de çalışır.
Paralellik kazançlarının ortadan kalkabileceği için doğrulama işlemlerinin çıktılarının genellikle yalnızca doğrulama çıkış grubuna gitmesi ve diğer işlemlerin girişlerine eklenmemesi önemlidir. Ancak Bazel'in şu anda bunu zorunlu kılacak özel bir kontrolü olmadığını unutmayın. Bu nedenle, doğrulama işlemi çıkışlarının Starlark kurallarıyla ilgili testlerdeki işlemlerin girişlerine 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 olan --run_validations
komut satırı işaretçisi tarafından kontrol edilir.
Kullanımdan kaldı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
'ınoutputs
parametresi, önceden tanımlanmış çıkış etiketleri oluşturmak için çıkış özellik adları ile dize şablonları arasında bir eşleme belirtir. Önceden tanımlanmamış çıkışları kullanmayı ve çıkışlarıDefaultInfo.files
'e açıkça 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 tanımlanmış bir yürütülebilir çıkışa başvurur. Çıktıyı açıkça belirtmeyi tercih edin (ör.ctx.actions.declare_file(ctx.label.name)
ile) ve yürütülebilir dosyayı oluşturan komutun izinlerini yürütmeye izin verecek şekilde ayarladığından emin olun. Yürütülebilir çıkışıDefaultInfo
işlevininexecutable
parametresine açıkça iletin.
Kullanılmaması gereken çalışma dosyası özellikleri
ctx.runfiles
ve runfiles
türü, çoğu eski nedenlerle korunan karmaşık bir özellik grubuna sahiptir.
Aşağıdaki öneriler karmaşıklığı azaltmaya yardımcı olur:
ctx.runfiles
'incollect_data
vecollect_default
modlarını kullanmaktan kaçının. Bu modlar, belirli kodlanmış bağımlılık kenarlarında çalışma dosyalarını dolaylı olarak kafa karıştırıcı şekillerde toplar. Bunun yerine,ctx.runfiles
dosyasınınfiles
veyatransitive_files
parametrelerini kullanarak ya da bağımlılıklardaki çalışma dosyalarınırunfiles = runfiles.merge(dep[DefaultInfo].default_runfiles)
ile birleştirerek dosya ekleyin.DefaultInfo
kurucusunundata_runfiles
vedefault_runfiles
özelliklerini kullanmaktan 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
).runfiles
'üDefaultInfo
'dan alırken (genellikle yalnızca mevcut kural ile bağımlılıkları arasındaki çalıştırma dosyalarını birleştirmek için)DefaultInfo.data_runfiles
'i değilDefaultInfo.default_runfiles
kullanın.
Eski sağlayıcılardan taşıma
Bazel sağlayıcıları daha önce Target
nesnesinde basit alanlardı. Nokta operatörü kullanılarak erişilen bu alanlar, alanın kuralın uygulama işlevi tarafından döndürülen bir yapıya yerleştirilmesiyle oluşturulmuştur.
Bu stilin desteği sonlandırılmıştır ve yeni kodlarda kullanılmamalıdır; taşıma işleminde size 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 tüm kodların sağlayıcı simgesini kullanarak bu örneği almasını zorunlu kılarak veri gizleme özelliğini de destekler.
Şu an için, eski sağlayıcılar desteklenmektedir. Bir kural, aşağıdaki gibi hem eski hem de modern sağlayıcıları 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 yapı, providers
'e ek olarak özel anlamı olan (ve dolayısıyla ilgili eski sağlayıcıyı oluşturmayan) başka alanlar da alabilir:
files
,runfiles
,data_runfiles
,default_runfiles
veexecutable
alanları,DefaultInfo
'teki aynı adlı alanlara karşılık gelir.DefaultInfo
sağlayıcısı döndürürken bu alanlardan herhangi birinin belirtilmesine izin verilmez.output_groups
alanı bir yapı değeri alır ve birOutputGroupInfo
değerine karşılık gelir.
Kuralların provides
bildirimlerinde ve bağımlılık özelliklerinin providers
bildirimlerinde eski sağlayıcılar dize olarak, modern sağlayıcılar ise *Info
sembolleriyle iletilir. Taşıma işlemi sırasında dizelerden sembollere geçtiğ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ı, modern sağlayıcıyı kullanacak şekilde değiştirin. Herhangi bir özellik beyanı eski sağlayıcıyı gerektiriyorsa bunları modern sağlayıcıyı gerektirecek şekilde de güncelleyin. İsterseniz bu çalışmayı 1. adımla birlikte yürütebilirsiniz. Bunun için tüketicilerin sağlayıcılardan birini kabul etmesini/zorunlu tutmasını sağlayın:
hasattr(target, 'foo')
kullanarak eski sağlayıcının varlığını veyaFooInfo in target
kullanarak yeni sağlayıcının varlığını test edin.Eski sağlayıcıyı tüm kurallardan tamamen kaldırın.