.bzl dosyaları

_ ile başlayan gizli özellikler varsayılan değerlere ve label veya label_list türüne sahip olmalıdır.

Açık atıf özellikleri string türüne sahip olmalı ve values kısıtlamasını kullanmalıdır. Belirli özellikler, görünümün yalnızca kısıtlamaya göre aynı ada, türe ve geçerli değerlere sahip özellikler içeren kurallarla kullanılmasını kısıtlar.

Tanımlanmış özellikler, None değerini varsayılan değere dönüştürür.

İç içe yerleştirilmemiş bir sağlayıcı listesi, otomatik olarak tek bir sağlayıcı listesi içeren bir listeye dönüştürülür. Yani [FooInfo, BarInfo], otomatik olarak [[FooInfo, BarInfo]]'e dönüştürülecek.

Bazı kuralların (ör. some_rule) hedeflerinin bir görünüme görünür olması için some_rule'ün, gerekli sağlayıcı listelerinden en az birinde bulunan tüm sağlayıcıların reklamını yapması gerekir. Örneğin, bir özelliğin required_providers değeri [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] ise bu özellik, some_rule FooInfo, veya BarInfo, veya hem BazInfo ve QuxInfo sağladığı takdirde some_rule hedeflerini görebilir.

İç içe yerleştirilmemiş bir sağlayıcı listesi, otomatik olarak tek bir sağlayıcı listesi içeren bir listeye dönüştürülür. Yani [FooInfo, BarInfo], otomatik olarak [[FooInfo, BarInfo]]'e dönüştürülecek.

Başka bir yönü (ör. other_aspect) bu yönü tarafından görünür hale getirmek için other_aspect, listelerden en az birindeki tüm sağlayıcıları sağlamalıdır. [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] örneğinde bu özellik, other_aspect yalnızca FooInfo, veya BarInfo, veya hem BazInfo hem de QuxInfo sağladığında other_aspect'i görebilir.

Uygulama işlevi, burada listelenen sağlayıcı türlerinden herhangi birini dönüş değerinden çıkarırsa hata oluşur. Ancak uygulama işlevi, burada listelenmeyen ek sağlayıcılar döndürebilir.

Listenin her öğesi, provider() tarafından döndürülen bir *Info nesnesi olmasına rağmen eski bir sağlayıcı, dize adıyla temsil edilir.Kuralın bir hedefi, zorunlu bir sağlayıcıyı açıklayan bir hedefin bağımlılığı olarak kullanıldığında bu sağlayıcıyı burada belirtmeniz gerekmez. Uygulama işlevinin bunu döndürmesi yeterlidir. Ancak zorunlu olmasa da bunu belirtmek en iyi uygulama olarak kabul edilir. Ancak bir yönün required_providers alanında, sağlayıcıların burada belirtilmesi gerekir.

Örneğin, bir özelliğin "deps" özelliği aracılığıyla aktarmalı olarak yayıldığını ve "alpha" hedefine uygulandığını varsayalım. "alpha"nın "deps = [':beta_output']" değerine sahip olduğunu varsayalım. Burada "beta_output", bir "beta" hedefinin tanımlanmış bir çıkışıdır. "beta"nın "deps" özelliklerinden biri olarak "charlie" hedefinin olduğunu varsayalım. Özellik için "apply_to_generating_rules=True" ise özellik "alpha", "beta" ve "charlie" aracılığıyla yayılır. Yanlış ise özellik yalnızca "alpha"ya yayılır.

Varsayılan olarak yanlıştır.

Kural olarak, uygulama işlevinde makronun "ana" olmayan hedeflere incelemesi, değiştirmesi veya iletmesi gereken tüm özellikler için adlandırılmış bir parametre bulunmalıdır. "Ana" hedefe değiştirilmeden iletilecek "toplu" devralınan özellikler ise **kwargs olarak iletilir.

Uygulama işlevi bir değer döndürmemelidir. Bunun yerine uygulama işlevi, kural veya makro simgelerini çağırarak hedefleri tanımlar.

Bir sembolik makro tarafından tanımlanan herhangi bir hedefin veya iç sembolik makronun adı (makronun uygulama işlevinin geçişli olarak çağırdığı tüm Starlark işlevleri dahil), name'e eşit olmalı (buna "ana" hedef denir) veya name ile başlamalı, ardından bir ayırıcı karakter ("_", "-" veya ".") ve bir dize son eki gelmelidir. (Bu adlandırma şemasını ihlal eden hedeflerin tanımlanmasına izin verilir ancak bu hedefler oluşturulamaz, yapılandırılamaz veya bunlara bağımlı olunamaz.)

Varsayılan olarak, sembolik bir makro tarafından tanımlanan hedefler (makronun uygulama işlevinin geçişli olarak çağırdığı tüm Starlark işlevleri dahil) yalnızca makroyu tanımlayan .bzl dosyasını içeren pakette görünür. Hedefleri harici olarak görünür olarak beyan etmek için (sembol makrosunu çağıran dahil), uygulama işlevi visibility'yi uygun şekilde ayarlamalıdır. Bu genellikle, visibility = visibility çağrılan kurala veya makro sembolüne iletilerek yapılır.

Aşağıdaki API'ler, makro uygulama işlevinde ve bu işlevin aktarmalı olarak çağırdığı Starlark işlevlerinde kullanılamaz:

• package(), licenses()
• environment_group()
• native.glob(): Bunun yerine, etiket listesi özelliği aracılığıyla makroya bir glob iletebilirsiniz
• native.subpackages()
• (yalnızca kural sonlandırıcılarda izin verilir, aşağıdaki finalizer bölümüne bakın) native.existing_rules(), native.existing_rule()
• (WORKSPACE iş parçacığı için) workspace(), register_toolchains(), register_execution_platforms(), bind(), depo kuralı örneklendirme

Özel name özelliği önceden bildirilir ve sözlüğe dahil edilmemelidir. visibility özellik adı ayrılmıştır ve sözlüğe dahil edilmemelidir.

Adları _ ile başlayan özellikler özeldir ve kuralın çağrı sitesinde iletilemez. Bu tür özelliklere, etikete gizli bir bağımlılık oluşturmak için varsayılan bir değer (attr.label(default="//pkg:foo")'te olduğu gibi) atanabilir.

Bellek kullanımını sınırlamak için tanımlanabilecek özellik sayısına bir sınır uygulanır.

inherit_attrs, "common" dizesine ayarlanırsa makro, tüm Starlark kuralları tarafından kullanılan ortak kural özelliği tanımlarını devralır.

rule() veya macro() işlevinin döndürdüğü değer bir .bzl dosyasında global bir değişkene atanmamışsa bu tür bir değerin kural veya makro sembolü olarak kaydedilmediğini ve bu nedenle inherit_attrs için kullanılamayacağını unutmayın.

Miras mekanizması şu şekilde çalışır:

1. Özel name ve visibility özellikleri hiçbir zaman devralınmaz;
2. Gizli özellikler (adları "_" ile başlayanlar) hiçbir zaman devralınmaz;
3. Adları attrs sözlüğünde tanımlanmış özellikler hiçbir zaman devralınmaz (attrs'teki giriş önceliklidir; makroda bu ada sahip bir özelliğin tanımlanmaması için bir girişin None olarak ayarlanabileceğini unutmayın);
4. Diğer tüm özellikler kuraldan veya makrodan devralınır ve attrs sözlüğüne etkili bir şekilde birleştirilir.

Zorunlu olmayan bir özellik devralındığında, özelliğin varsayılan değeri, orijinal kuralda veya makroda ne belirtilmiş olursa olsun None olarak geçersiz kılınır. Bu, makro özelliğin değerini sarmalanmış kuralın veya makronun bir örneğine ilettiğinde (ör. değiştirilmemiş **kwargs ileterek) dış makronun çağrısında bulunmayan bir değerin iç kuralın veya makronun çağrısında da bulunmamasını sağlar (None'un bir özelliğe iletilmesi, özelliğin atlanması ile aynı şekilde değerlendirilir). Bir özelliğin atlanması, görünen varsayılan değerinin iletilmesinden farklı bir anlam taşıdığından bu durum önemlidir. Özellikle, atlanan özellikler bazı bazel query çıkış biçimlerinde gösterilmez ve hesaplanan varsayılanlar yalnızca değer atlandığında yürütülür. Makro'nun, devralınan bir özelliği incelemesi veya değiştirmesi gerekiyorsa (ör. devralınan bir tags özelliğine değer eklemek için) makronun uygulama işlevinde None durumunu ele almanız gerekir.

Örneğin, aşağıdaki makro, cxxopts (özellik listesinden kaldırılır) ve copts (yeni bir tanım verilir) hariç olmak üzere native.cc_library'teki tüm özellikleri devralır. Ayrıca, ek bir etiket eklemeden önce devralınan tags özelliğinin varsayılan None değerini kontrol eder.

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

inherit_attrs ayarlanmışsa makronun uygulama işlevinde **kwargs artık anahtar kelime parametresi olmalıdır.

Kural olarak, bir makro, devralınan ve geçersiz kılınmayan özellikleri, makronun sarmaladığı "ana" kurala veya makro simgesine değiştirilmeden iletmelidir. Genellikle, devralınan özelliklerin çoğunun uygulama işlevinin parametre listesinde bir parametresi olmaz ve **kwargs aracılığıyla iletilir. Makro'nun bu özellikleri hem "ana" hem de "ana" olmayan hedeflere iletmesi gerekiyorsa uygulama işlevinin bazı devralınan özellikler (genellikle tags ve testonly) için açık parametrelere sahip olması uygun olabilir. Ancak makro'nun bu özellikleri incelemesi veya değiştirmesi de gerekiyorsa zorunlu olmayan devralınan özelliklerin None varsayılan değerini işlemeye özen göstermeniz gerekir.

Normal sembolik makroların aksine kural sonlandırıcılar, mevcut pakette tanımlanan sonlandırıcı olmayan kural hedeflerinin kümesini sorgulamak için native.existing_rule() ve native.existing_rules() çağrılabilir. native.existing_rule() ve native.existing_rules()'un, bu kural dahil olmak üzere herhangi bir kural tamamlayıcısı tarafından tanımlanan hedeflere erişemediğini unutmayın.

• alan listesi:
  

  provider(fields = ['a', 'b'])

• dictionary field name -> documentation:
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

Aşağıda bu konuyla ilgili net bir açıklama verilmiştir. Anlaşılır bir tartışma ve kullanım alanları için Kurallar (Sağlayıcıların özel başlatılması) başlıklı makaleyi inceleyin.

P, provider() çağrısı yapılarak oluşturulan sağlayıcı sembolü olsun. Kavramsal olarak, P örneği, aşağıdakileri yapan varsayılan bir oluşturucu işlevi c(*args, **kwargs) çağrılarak oluşturulur:

• args boş değilse hata oluşur.
• provider() çağrılırken fields parametresi belirtilmişse ve kwargs, fields'te listelenmeyen bir anahtar içeriyorsa hata meydana gelir.
• Aksi takdirde c, kwargs içindeki her k: v girişi için v değerine sahip k adlı bir alana sahip yeni bir örnek döndürür.

MyInfo = provider()
m = MyInfo(foo = 1)

Ancak init belirtilirse P(*args, **kwargs) çağrısı bunun yerine aşağıdaki adımları gerçekleştirir:

1. Geri çağırma işlevi init(*args, **kwargs) olarak çağrılır. Yani P'a iletilen konumsal ve anahtar kelime bağımsız değişkenleriyle tam olarak aynı şekilde çağrılır.
2. init işlevinin döndürdüğü değerin, anahtarları alan adı dizeleri olan bir sözlük (d) olması beklenir. Aksi takdirde hata oluşur.
3. P sınıfının yeni bir örneği, c(**d) örneğinde olduğu gibi d girişlerini anahtar kelime bağımsız değişkenleri olarak kullanarak varsayılan kurucuyu çağırmış gibi oluşturulur.

Not: Yukarıdaki adımlar, *args veya **kwargs, init'nin imzasıyla eşleşmezse, init'nin gövdesinin değerlendirilmesi başarısız olursa (belki de fail() çağrısı yoluyla kasıtlı olarak) veya init'nin döndürdüğü değer beklenen şemaya sahip bir sözlük değilse bir hata oluştuğunu gösterir.

Bu şekilde init geri çağırma işlevi, ön işleme ve doğrulama için konumsal bağımsız değişkenlere ve keyfi mantığa izin vererek normal sağlayıcı oluşumunu genelleştirir. İzin verilen fields listesinin etrafından dolanmayı etkinleştirmez.

init belirtildiğinde provider()'un döndürdüğü değer bir tuple (P, r) olur. Burada r, ham kurucu olur. Aslında r işlevinin davranışı, yukarıda açıklanan varsayılan oluşturucu işlevi c ile tamamen aynıdır. Genellikle r, adının önüne alt çizgi eklenen bir değişkene bağlanır. Böylece yalnızca mevcut .bzl dosyası buna doğrudan erişebilir:

MyInfo, _new_myinfo = provider(init = ...)

Tanımlanmış özellikler, None değerini varsayılan değere dönüştürür.

Tanımlanmış özellikler, None değerini varsayılan değere dönüştürür.

Önceden beyan edilen çıkışları tanımlamak için kullanılan bir şema. output ve output_list özelliklerinden farklı olarak, kullanıcı bu dosyaların etiketlerini belirtmez. Önceden bildirilmiş çıkışlar hakkında daha fazla bilgi için Kurallar sayfasına bakın.

Bu bağımsız değişkenin değeri bir sözlük veya sözlük oluşturan bir geri çağırma işlevidir. Geri çağırma işlevi, hesaplanmış bağımlılık özelliklerine benzer şekilde çalışır: İşlevin parametre adları, kuralın özellikleriyle eşleştirilir. Örneğin, outputs = _my_func parametresini def _my_func(srcs, deps): ... tanımı ile iletirseniz işlev srcs ve deps özelliklerine erişebilir. Sözlük doğrudan veya bir işlev aracılığıyla belirtilmiş olsun, aşağıdaki şekilde yorumlanır.

Sözlükteki her giriş, anahtarın bir tanımlayıcı ve değerin, çıktının etiketini belirleyen bir dize şablonu olduğu önceden bildirilmiş bir çıktı oluşturur. Kuralın uygulama işlevinde tanımlayıcı, ctx.outputs içindeki çıkışın File alanına erişmek için kullanılan alan adı olur. Çıktının etiketi, kuralla aynı pakete sahiptir ve paketten sonraki kısım, "%{ATTR}" biçimindeki her yer tutucunun ATTR özelliğinin değerinden oluşturulan bir dizeyle değiştirilmesiyle üretilir:

• Dize türündeki özellikler olduğu gibi değiştirilir.
• Etiket türündeki özellikler, paketten sonra dosya uzantısı çıkarılarak etiketin bir parçası olur. Örneğin, "//pkg:a/b.c" etiketi "a/b" olur.
• Çıkış türündeki özellikler, dosya uzantısı da dahil olmak üzere paketten sonra etiketin bir parçası olur (yukarıdaki örnekte "a/b.c").
• Yer tutucularda kullanılan tüm liste türündeki özelliklerin (örneğin, attr.label_list) tam olarak bir öğeye sahip olması gerekir. Dönüşümleri, liste dışı sürümleriyle (attr.label) aynıdır.
• Diğer özellik türleri yer tutucularda görünmeyebilir.
• Özel özellik olmayan yer tutucular %{dirname} ve %{basename}, paketi hariç olmak üzere kuralın etiketinin bu bölümlerini genişletir. Örneğin, "//pkg:a/b.c" dosyasında dirname a, basename ise b.c olur.

Uygulamada en yaygın yer tutucu "%{name}"'tür. Örneğin, "foo" adlı bir hedef için çıkışlar sözlüğü {"bin": "%{name}.exe"}, uygulama işlevinde ctx.outputs.bin olarak erişilebilen foo.exe adlı bir çıkışı önceden bildirir.

Uygulama işlevi, burada listelenen sağlayıcı türlerinden herhangi birini dönüş değerinden çıkarırsa hata oluşur. Ancak uygulama işlevi, burada listelenmeyen ek sağlayıcılar döndürebilir.

Listenin her öğesi, provider() tarafından döndürülen bir *Info nesnesi olmasına rağmen eski bir sağlayıcı, dize adıyla temsil edilir.Kuralın bir hedefi, zorunlu bir sağlayıcıyı açıklayan bir hedefin bağımlılığı olarak kullanıldığında bu sağlayıcıyı burada belirtmeniz gerekmez. Uygulama işlevinin bunu döndürmesi yeterlidir. Ancak zorunlu olmasa da bunu belirtmek en iyi uygulama olarak kabul edilir. Ancak bir yönün required_providers alanında, sağlayıcıların burada belirtilmesi gerekir.

Not: Analiz testi kuralları, temel Starlark kitaplıklarında sağlanan altyapı kullanılarak tanımlanır. Yardım için Test bölümüne bakın.

Bir kural analiz testi kuralı olarak tanımlanırsa özelliklerinde analysis_test_transition kullanılarak tanımlanan yapılandırma geçişlerinin kullanılmasına izin verilir ancak bazı kısıtlamalar etkinleştirilir:

• Bu kuralın hedefleri, sahip olabilecekleri geçişli bağımlılık sayısı açısından sınırlıdır.
• Kural, test kuralı olarak kabul edilir (test=True ayarlanmış gibi). Bu, test değerinin yerini alır.
• Kural uygulama işlevi işlemleri kaydedemeyebilir. Bunun yerine, AnalysisTestResultInfo sağlayarak başarılı/başarısız sonucunu kaydetmelidir.

İşlev, kuralın her örneği için yükleme sırasında çağrılır. name ve kural tarafından tanımlanan herkese açık özelliklerin değerleriyle çağrılır (tags gibi genel özelliklerle değil).

Özellik adlarından istenen değerlere giden bir sözlük döndürmelidir. Döndürülmeyen özellikler bu durumdan etkilenmez. Değer olarak None döndürülmesi, özellik tanımında belirtilen varsayılan değerin kullanılmasına neden olur.

Başlatıcılar, bir özellik tanımında belirtilen varsayılan değerlerden önce değerlendirilir. Sonuç olarak, başlatıcının imzasında bir parametre varsayılan değerler içeriyorsa özellik tanımındaki varsayılan değerin üzerine yazılır (None döndürülmesi hariç).

Benzer şekilde, başlatıcının imzasında varsayılan değeri olmayan bir parametre varsa bu parametre zorunlu hale gelir. Bu gibi durumlarda, özellik tanımında varsayılan/zorunlu ayarları çıkarmak iyi bir uygulamadır.

İşlenmeyen özellikler için **kwargs kullanmak iyi bir uygulamadır.

Genişletilmiş kurallar söz konusu olduğunda, tüm başlatıcılar alt öğeden üst öğelere doğru çağrılır. Her başlatıcıya yalnızca bildiği herkese açık özellikler iletilir.

Alt kurallarda yalnızca etiket türüne sahip gizli özellikler (ör. etiket veya etiket listesi) bulunabilir. Bu etiketlere karşılık gelen çözümlenmiş değerler, Bazel tarafından alt kuralın uygulama işlevine adlandırılmış bağımsız değişkenler olarak otomatik olarak iletilir (bu nedenle uygulama işlevinin, özellik adlarıyla eşleşen adlandırılmış parametreleri kabul etmesi gerekir). Bu değerlerin türleri şunlardır:

• executable=True ile etiket özellikleri için FilesToRunProvider
• allow_single_file=True ile etiket özellikleri için File
• Diğer tüm etiket özellikleri için Target
• Tüm etiket listesi özellikleri için [Target]

rule(), aspect() ve repository_rule()'ten farklı olarak, tanımlanan özelliklerin None değerini varsayılan değere dönüştürmeyeceğini unutmayın. Varsayılanın kullanılması için özelliğin arayan tarafından tamamen atlanması gerekir.

Paket özellikleri, negatif paket özelliklerine izin verilmemesi dışında package_group ile aynı biçimi izler. Yani bir spesifikasyon şu biçimlerde olabilir:

• "//foo": //foo paketi
• "//foo/...": //foo paketi ve tüm alt paketleri.
• "public" veya "private": sırasıyla tüm paketler veya hiçbir paket

"@" söz dizimine izin verilmez; tüm özellikler geçerli modülün deposuna göre yorumlanır.

value bir dize listesiyse bu modüle görünürlük verilen paket grubu, her spesifikasyonla temsil edilen paketlerin birleşimidir. (Boş liste, private ile aynı etkiye sahiptir.) value tek bir dize ise [value] tek öğeli liste gibi işlenir.

--incompatible_package_group_has_public_syntax ve --incompatible_fix_package_group_reporoot_syntax işaretlerinin bu bağımsız değişken üzerinde hiçbir etkisi olmadığını unutmayın. "public" ve "private" değerleri her zaman kullanılabilir. "//..." ise her zaman "mevcut depoda bulunan tüm paketler" olarak yorumlanır.