Bu sayfada, makroların kullanımıyla ilgili temel bilgiler, tipik kullanım alanları, hata ayıklama ve kurallar ele alınmaktadır.
Makro, BUILD
dosyasından çağrılan ve kuralları örneklendirebilen bir işlevdir.
Makrolar, çoğunlukla mevcut kurallar ile diğer makroların kapsüllenmesi ve yeniden kullanılması için kullanılır. Yükleme aşamasının sonunda makrolar artık mevcut değildir ve Bazel yalnızca örneklenmiş, somut kurallar kümesini görür.
Kullanım
Makroların tipik kullanım alanı, kuralı yeniden kullanmak istediğiniz durumlardır.
Örneğin, BUILD
dosyasındaki genrule, //:generator
komutunu kullanarak some_arg
bağımsız değişkenini komuta sabitlemiş bir dosya oluşturur:
genrule(
name = "file",
outs = ["file.txt"],
cmd = "$(location //:generator) some_arg > $@",
tools = ["//:generator"],
)
Farklı bağımsız bağımsız değişkenlere sahip daha fazla dosya oluşturmak istiyorsanız bu kodu bir makro işlevine çıkartmak isteyebilirsiniz. name
ve arg
parametrelerine sahip olan file_generator
makrosuna diyelim. Genrule'ı şununla değiştirin:
load("//path:generator.bzl", "file_generator")
file_generator(
name = "file",
arg = "some_arg",
)
file_generator(
name = "file-two",
arg = "some_arg_two",
)
file_generator(
name = "file-three",
arg = "some_arg_three",
)
Burada, //path
paketinde bulunan bir .bzl
dosyasından file_generator
simgesini yüklersiniz. Makro işlevi tanımlarını ayrı bir .bzl
dosyasına koyarak BUILD
dosyalarınızın temiz ve bildirim temelli olmasını sağlarsınız. .bzl
dosyası, çalışma alanındaki herhangi bir paketten yüklenebilir.
Son olarak, path/generator.bzl
dilinde, orijinal genrule tanımını kapsüllemek ve parametreleştirmek için makronun tanımını yazın:
def file_generator(name, arg, visibility=None):
native.genrule(
name = name,
outs = [name + ".txt"],
cmd = "$(location //:generator) %s > $@" % arg,
tools = ["//:generator"],
visibility = visibility,
)
Makroları, kuralları birbirine bağlamak için de kullanabilirsiniz. Bu örnekte, bir genrule üyesinin önceki bir genrulenin çıkışlarını giriş olarak kullandığı zincirlenmiş genel kurallar gösterilmektedir:
def chained_genrules(name, visibility=None):
native.genrule(
name = name + "-one",
outs = [name + ".one"],
cmd = "$(location :tool-one) $@",
tools = [":tool-one"],
visibility = ["//visibility:private"],
)
native.genrule(
name = name + "-two",
srcs = [name + ".one"],
outs = [name + ".two"],
cmd = "$(location :tool-two) $< $@",
tools = [":tool-two"],
visibility = visibility,
)
Örnek yalnızca ikinci nesile bir görünürlük değeri atar. Bu, makro yazarlarının ara kuralların çıkışlarının çalışma alanındaki diğer hedefler tarafından bağımlı kalmasının engellenmesini sağlar.
Genişletme makroları
Bir makronun işlevini incelemek istediğinizde, genişletilmiş formu görmek için query
komutunu --output=build
ile birlikte kullanın:
$ bazel query --output=build :file
# /absolute/path/test/ext.bzl:42:3
genrule(
name = "file",
tools = ["//:generator"],
outs = ["//test:file.txt"],
cmd = "$(location //:generator) some_arg > $@",
)
Yerel kuralları örneklendirme
Yerel kurallar (load()
ifadesi gerektirmeyen kurallar) yerel modülünden oluşturulabilir:
def my_macro(name, visibility=None):
native.cc_library(
name = name,
srcs = ["main.cc"],
visibility = visibility,
)
Paket adını (örneğin, makroyu hangi BUILD
dosyasının çağırdığını) bilmeniz gerekiyorsa native.package_name() işlevini kullanın.
native
öğesinin yalnızca .bzl
dosyalarında kullanılabileceğini, WORKSPACE
veya BUILD
dosyalarında kullanılamayacağını unutmayın.
Makrolarda etiket çözünürlüğü
Makrolar yükleme aşamasında değerlendirildiğinden, bir makroda oluşan "//foo:bar"
gibi etiket dizeleri, makronun tanımlandığı .bzl
dosyasına göre değil, makronun içinde kullanıldığı BUILD
dosyasına göre yorumlanır. Bu davranış genellikle diğer depolarda kullanılması amaçlanan makrolar için (örneğin, yayınlanan bir Starlark kural grubunun parçası olmaları gibi) istenmeyen bir davranıştır.
Starlark kurallarıyla aynı davranışı elde etmek için etiket dizelerini Label
oluşturucuyla sarmalayın:
# @my_ruleset//rules:defs.bzl
def my_cc_wrapper(name, deps = [], **kwargs):
native.cc_library(
name = name,
deps = deps + select({
# Due to the use of Label, this label is resolved within @my_ruleset,
# regardless of its site of use.
Label("//config:needs_foo"): [
# Due to the use of Label, this label will resolve to the correct target
# even if the canonical name of @dep_of_my_ruleset should be different
# in the main workspace, such as due to repo mappings.
Label("@dep_of_my_ruleset//tools:foo"),
],
"//conditions:default": [],
}),
**kwargs,
)
Hata ayıklama
bazel query --output=build //my/path:all
, değerlendirmeden sonraBUILD
dosyasının nasıl göründüğünü gösterir. Tüm makrolar, glob'lar, döngüler genişletilir. Bilinen sınırlama: Şu andaselect
ifadeleri çıkışta gösterilmemektedir.Sonucu, kuralları oluşturan
generator_function
işlevine veyagenerator_name
özelliğine (makronun ad özelliği) göre filtreleyebilirsiniz:bash $ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'
foo
kuralınınBUILD
dosyasında tam olarak nerede oluşturulduğunu öğrenmek için aşağıdaki işlemi deneyebilirsiniz. Bu satırıBUILD
dosyasının üst kısmına yakın bir yere ekleyin:cc_library(name = "foo")
. Bazel'i çalıştırın.foo
kuralı oluşturulduğunda (ad çakışması nedeniyle) bir istisna alırsınız. Bu istisna size tam yığın izlemeyi gösterir.Hata ayıklama için yazdırma yöntemini de kullanabilirsiniz. Yükleme aşamasında bu mesajı bir
DEBUG
günlük satırı olarak gösterir. Nadir durumlar dışında,print
çağrılarını kaldırın veya kodu depoya göndermeden önce varsayılan olarakFalse
değerine sahip birdebugging
parametresi altında koşullu hale getirin.
Hatalar
Hata vermek istiyorsanız fail işlevini kullanın.
Kullanıcıya sorunun ne olduğunu ve BUILD
dosyasının nasıl düzeltileceğini net bir şekilde açıklayın.
Hata yakalanamaz.
def my_macro(name, deps, visibility=None):
if len(deps) < 2:
fail("Expected at least two values in deps")
# ...
Kongreler
Kural başlatan tüm herkese açık işlevler (alt çizgi ile başlamayan işlevler) için
name
bağımsız değişkeni olmalıdır. Bu bağımsız değişken isteğe bağlı olmamalıdır (varsayılan değer vermeyin).Herkese açık işlevler, Python kurallarına uygun bir docstring kullanmalıdır.
BUILD
dosyalarında, makrolarınname
bağımsız değişkeni bir anahtar kelime bağımsız değişkeni olmalıdır (konumsal bağımsız değişken değil).Bir makro tarafından oluşturulan kuralların
name
özelliği, ad bağımsız değişkenini ön ek olarak içermelidir. Örneğin,macro(name = "foo")
, bircc_library
foo
ve bir genelfoo_gen
oluşturabilir.Çoğu durumda, isteğe bağlı parametreler için varsayılan değer
None
olmalıdır.None
doğrudan yerel kurallara iletilebilir. Bu kurallar, herhangi bir bağımsız değişkeni geçmemişsiniz gibi davranır. Dolayısıyla, bu amaç için bu değeri0
,False
veya[]
ile değiştirmenize gerek yoktur. Varsayılan değerleri karmaşık olabileceğinden veya zaman içinde değişebileceğinden, makro bunun yerine oluşturduğu kurallara uyar. Ayrıca, açıkça varsayılan değerine ayarlanmış bir parametre, sorgu dili veya derleme sistemi dahili ayarlarından erişildiğinde hiçbir zaman ayarlanmayan (veyaNone
olarak ayarlanmayan) bir parametreden farklı görünür.Makroların isteğe bağlı bir
visibility
bağımsız değişkeni olmalıdır.