Bu sayfada, yönleri kullanmanın temel özellikleri ve avantajları açıklanmakta, basit ve ileri düzey örnekler sunulmaktadır.
Yönler, derleme bağımlılık graflarını ek bilgiler ve işlemlerle genişletmenize olanak tanır. Yönleri kullanabileceğiniz bazı tipik senaryolar:
- Bazel'i entegre eden IDE'ler, proje hakkında bilgi toplamak için farklı yönleri kullanabilir.
- Kod oluşturma araçları, girişleri hedeften bağımsız şekilde yürütmek için öğelerden yararlanabilir. Örneğin,
BUILDdosyaları protobuf kitaplığı tanımlarının hiyerarşisini belirtebilir ve dile özgü kurallar, belirli bir dil için protobuf destek kodu oluşturan işlemleri eklemek üzere yönleri kullanabilir.
Aspect ile ilgili temel bilgiler
BUILD dosyaları, projenin kaynak koduyla ilgili açıklama sunar: Hangi kaynak dosyaların projenin parçası olduğu, hangi yapıların (hedefler) bu dosyalardan oluşturulması gerektiği, bu dosyalar arasındaki bağımlılıkların neler olduğu vb. Bazel, derlemeyi gerçekleştirmek için bu bilgileri kullanır. Yani yapıları oluşturmak için gereken işlem kümesini (derleyici veya bağlayıcı işlemleri çalıştırmak gibi) belirler. Bazel bunu hedefler arasında bir bağımlılık grafiği oluşturup bu işlemleri toplamak için bu grafiği ziyaret ederek başarabilir.
Şu BUILD dosyasını göz önünde bulundurun:
java_library(name = 'W', ...)
java_library(name = 'Y', deps = [':W'], ...)
java_library(name = 'Z', deps = [':W'], ...)
java_library(name = 'Q', ...)
java_library(name = 'T', deps = [':Q'], ...)
java_library(name = 'X', deps = [':Y',':Z'], runtime_deps = [':T'], ...)
Bu BUILD dosyası, aşağıdaki şekilde gösterilen bir bağımlılık grafiğini tanımlar:
Şekil 1. BUILD dosya bağımlılık grafiği.
Bazel, yukarıdaki örnekte her hedef için karşılık gelen kuralın (bu örnekte "java_library") uygulama işlevini çağırarak bu bağımlılık grafiğini analiz eder. Kural uygulama işlevleri, .jar dosyaları gibi yapılar oluşturan ve bu yapıların konumları ve adları gibi bilgileri sağlayıcılardaki hedeflerin ters bağımlılıklarına ileten işlemler oluşturur.
Yönler, işlem oluşturan ve sağlayıcı döndüren bir uygulama işlevine sahip olmaları açısından kurallara benzer. Ancak bu modellerin gücü, bağımlılıkları için oluşturulan bağımlılıklar grafiğinden gelir. Bir özelliğin bir uygulaması ve birlikte yayıldığı tüm özelliklerin listesi vardır. "deps" adlı özelliklerde dağıtılan bir A yönü olduğunu varsayalım. Bu yön, hedef X'e uygulanarak bir en boy uygulama düğümü A(X) elde edilir. A yönü, uygulanması sırasında X'in "deps" özelliğinde atıfta bulunduğu tüm hedeflere (A'nın dağıtım listesindeki tüm özellikler) yinelemeli olarak uygulanır.
Bu yüzden, A niteliğinin bir hedef X'e uygulanması tek bir eylem, aşağıdaki şekilde gösterilen hedeflerin orijinal bağımlılık grafiğinin bir "gölge grafiğini" oluşturur:
Şekil 2. Yönleri olan bir grafik oluşturun.
Gölgelenen tek kenarlar, dağıtım grubundaki özellikler boyunca uzanan kenarlardır. Bu nedenle, bu örnekte runtime_deps kenarı gölgelenmez. Ardından, gölge grafiğin tüm düğümlerinde bir görünüm uygulama işlevi çağrılır. Bu, orijinal grafiğin düğümlerinde kural uygulamalarının çağrılmasına benzer.
Basit örnek
Bu örnekte, bir kuralın ve deps özelliğine sahip tüm bağımlılarının kaynak dosyalarının nasıl yinelemeli olarak yazdırılacağını gösterilmektedir. Bu örnekte, bir özellik uygulaması, bir özellik tanımı ve Bazel komut satırından özelliğin nasıl çağrılacağı gösterilmektedir.
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
Örneği parçalarına ayırıp her birini ayrı ayrı inceleyelim.
Aspect tanımı
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
Yön özellik tanımları, kural tanımlarına benzer ve aspect işlevi kullanılarak tanımlanır.
Bir kural gibi, bir boyutun da bir uygulama işlevi vardır. Bu durumda işlev _print_aspect_impl'tür.
attr_aspects, özelliğin yayıldığı kural özelliklerinin listesidir.
Bu durumda, özellik, uygulandığı kuralların deps özelliği boyunca yayılır.
attr_aspects için yaygın olarak kullanılan bir diğer bağımsız değişken ['*'], bu bağımsız değişkeni bir kuralın tüm özelliklerine yayar.
Aspect uygulama
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
Yön özellik uygulama işlevleri, kural uygulama işlevlerine benzer. Sağlayıcılar döndürür, işlemler oluşturabilir ve iki bağımsız değişken alır:
target: Özelliğin uygulandığı hedef.ctx: Özelliklere erişmek ve çıkışlar ile işlemler oluşturmak için kullanılabilecekctxnesnesi.
Uygulama işlevi, ctx.rule.attr aracılığıyla hedef kuralın özelliklerine erişebilir. Uygulandığı hedef tarafından sağlanan sağlayıcıları inceleyebilir (target bağımsız değişkeni aracılığıyla).
Servis sağlayıcıların listesini döndürmek için yönler gereklidir. Bu örnekte, özellik hiçbir şey sağlamadığından boş bir liste döndürür.
Komut satırını kullanarak detayı çağırma
Bir özelliği uygulamanın en basit yolu, --aspects bağımsız değişkenini kullanarak komut satırını kullanmaktır. Yukarıdaki özelliğin print.bzl adlı bir dosyada tanımlandığı varsayıldığında:
bazel build //MyExample:example --aspects print.bzl%print_aspect
print_aspect öğesini, example hedefine ve deps özelliği aracılığıyla yinelenen olarak erişilebilen tüm hedef kurallarına uygular.
--aspects işareti, <extension file label>%<aspect top-level name> biçiminde boyutun bir spesifikasyonu olan bir bağımsız değişken alır.
Gelişmiş örnek
Aşağıdaki örnekte, hedeflerdeki dosyaları sayan ve potansiyel olarak uzantıya göre filtreleyen hedef kuralındaki bir özelliğin kullanıldığı gösterilmektedir. Bu örnekte, değerleri döndürmek için sağlayıcının nasıl kullanılacağı, bir bağımsız değişkeni bir özellik uygulamasına iletmek için parametrelerin nasıl kullanılacağı ve bir özelliği kuraldan nasıl çağıracağınız gösterilmektedir.
file_count.bzl dosyası:
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
BUILD.bazel dosyası:
load('//:file_count.bzl', 'file_count_rule')
cc_library(
name = 'lib',
srcs = [
'lib.h',
'lib.cc',
],
)
cc_binary(
name = 'app',
srcs = [
'app.h',
'app.cc',
'main.cc',
],
deps = ['lib'],
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
En boy tanımı
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
Bu örnekte, en boy oranının deps özelliği aracılığıyla nasıl yayıldığı gösterilmektedir.
attrs, bir yönle ilgili özellik grubunu tanımlar. Herkese açık yön özellikleri parametreleri tanımlar ve yalnızca bool, int veya string türünde olabilir.
Kural tarafından dağıtılan özellikler için int ve string parametrelerinde values belirtilmelidir. Bu örnekte, "*", "h" veya "cc" değerine sahip olmasına izin verilen extension adlı bir parametre var.
Kuralla dağıtılan görünümler için parametre değerleri, görünümü isteyen kuraldan alınır. Bu işlemde, kuralın aynı ada ve türe sahip özelliği kullanılır.
(file_count_rule tanımına bakın).
Komut satırı özellikleri için parametre değerleri, --aspects_parameters işareti kullanılarak iletilebilir. int ve string parametrelerinin values kısıtlaması atlanabilir.
Boyların label veya label_list türünde gizli özelliklere de sahip olmasına izin verilir. Özel etiket özellikleri, unsurlar tarafından oluşturulan işlemler için gerekli olan araç veya kitaplıklardaki bağımlılıkları belirtmek için kullanılabilir. Bu örnekte tanımlanmış bir gizli özellik yoktur ancak aşağıdaki kod snippet'i, bir araçta belirli bir unsura nasıl iletebileceğiniz gösterilmektedir:
...
attrs = {
'_protoc' : attr.label(
default = Label('//tools:protoc'),
executable = True,
cfg = "exec"
)
}
...
Aspect uygulama
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
Kural uygulama işlevinde olduğu gibi, bir özellik uygulama işlevi de bağımlılıkları tarafından erişilebilen bir sağlayıcı yapısı döndürür.
Bu örnekte, FileCountInfo tek bir alanı count olan bir sağlayıcı olarak tanımlanmıştır. En iyi uygulama, fields özelliğini kullanarak bir sağlayıcının alanlarını açıkça tanımlamaktır.
Bir özellik uygulaması A(X) için sağlayıcı grubu, hedef X için bir kuralın uygulanması ve özellik A'nın uygulanması sonucunda ortaya çıkan sağlayıcıların birleşimidir. Bir kural uygulamasının yaydığı sağlayıcılar, unsurlar uygulanmadan önce oluşturulur ve dondurulur ve bir açıdan değiştirilemez. Bir hedef ve ona uygulanan bir özelliğin her biri aynı türden bir sağlayıcı sağlarsa bu durum bir hatadır. Ancak OutputGroupInfo (kural ve detay farklı çıkış gruplarını belirttiği sürece birleştirilir) ve InstrumentedFilesInfo (boyuttan alınır). Bu, yön uygulamalarının hiçbir zaman DefaultInfo döndürmeyeceği anlamına gelir.
Parametreler ve gizli özellikler, ctx özelliklerinde aktarılır. Bu örnekte extension parametresi temel alınmıştır ve hangi dosyaların sayılacağını belirler.
Döndürülen sağlayıcılar için, özelliğin dağıtıldığı özelliklerin (attr_aspects listesinden) değerleri, özelliğin bunlara uygulanmasının sonuçlarıyla değiştirilir. Örneğin, hedef X'in bağımlılıkları arasında Y ve Z varsa A(X) için ctx.rule.attr.deps [A(Y), A(Z)] olur.
Bu örnekte ctx.rule.attr.deps, özelliğin uygulandığı orijinal hedefin "deps"ine özelliğin uygulanmasının sonucu olan hedef nesnelerdir.
Bu örnekte, en boy oranı toplam geçişli dosya sayısını toplamak için hedefin bağımlılıklarından FileCountInfo sağlayıcısına erişiyor.
Bir kuraldan görünümü çağırma
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
Kural uygulamasında, ctx.attr.deps üzerinden FileCountInfo'e nasıl erişileceği gösterilmektedir.
Kural tanımında, bir parametrenin (extension) nasıl tanımlanacağı ve parametreye nasıl varsayılan değer (*) verileceği gösterilmektedir. Boyut tanımında parametreye uygulanan kısıtlamalar nedeniyle "cc", "h" veya "*" dışında bir varsayılan değer kullanılmasının hata olacağını unutmayın.
Hedef kural aracılığıyla bir yönü çağırma
load('//:file_count.bzl', 'file_count_rule')
cc_binary(
name = 'app',
...
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
Bu örnekte, extension parametresinin kural aracılığıyla görünüme nasıl geçirileceği gösterilmektedir. extension parametresi, kuralın uygulanmasında varsayılan bir değere sahip olduğundan extension, isteğe bağlı bir parametre olarak kabul edilir.
file_count hedefi oluşturulduğunda, yönümüz kendi başına ve deps aracılığıyla yinelemeli olarak erişilebilen tüm hedefler için değerlendirilir.