Genel Kurallar

Kurallar

• takma ad
• config_setting
• dosya grubu
• Genquery
• genrule
• starlark_doc_extract
• test_suite

takma ad

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

alias kuralı, kuralın bahsedilebileceği başka bir ad oluşturur.

Takma ad kullanma yalnızca "normal" hedefler için çalışır. Özellikle, package_group ve test_suite diğer adlarla kullanılamaz.

Takma ad kullanma, hedefi yeniden adlandırmanın çok sayıda dosya üzerinde değişiklik yapmayı gerektireceği büyük depolarda yardımcı olabilir. Bu mantığı birden çok hedef için yeniden kullanmak isterseniz bir select işlev çağrısı depolamak üzere takma ad kuralını da kullanabilirsiniz.

Takma ad kuralının kendi görünürlük beyanı vardır. Diğer tüm açılardan, bazı küçük istisnalar dışında referans aldığı kural gibi davranır (ör. takma adda testonly çıkarılır; bunun yerine referans verilen kuralın salt test durumu kullanılır):

• Komut satırında takma adlarından bahsedilmişse testler çalıştırılmaz. Başvurulan testi çalıştıran bir takma ad tanımlamak için tests özelliğinde tek hedefi olan bir test_suite kuralı kullanın.
• Ortam grupları tanımlanırken environment kurallarının takma adları desteklenmez. Bunlar --target_environment komut satırı seçeneğinde de desteklenmez.

Örnekler

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

Bağımsız değişkenler

config_setting

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

Yapılandırılabilir özellikleri tetiklemek amacıyla, beklenen bir yapılandırma durumuyla (derleme bayrakları veya platform kısıtlamaları olarak ifade edilir) eşleşir. Bu kuralın nasıl kullanılacağını öğrenmek için seçme bölümüne ve genel özelliğe genel bir bakış için Yapılandırılabilir özelliklere bakın.

Örnekler

Aşağıdaki, --compilation_mode=opt veya -c opt ayarlayan her derlemeyle eşleşir (komut satırında açık bir şekilde veya dolaylı olarak .bazelrc dosyalarından):

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

Aşağıdaki, ARM'yi hedefleyen ve FOO=bar özel tanımını uygulayan tüm derlemelerle eşleşir (örneğin, bazel build --cpu=arm --define FOO=bar ...):

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

Aşağıdakiler, kullanıcı tanımlı işareti --//custom_flags:foo=1 ayarlayan (komut satırında açıkça veya dolaylı olarak .bazelrc dosyalarından) tüm derlemelerle eşleşir:

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

Aşağıdaki, //example:glibc_2_25 etiketine sahip bir constraint_value varlığı varsa x86_64 mimarisine ve glibc sürümü 2.25'e sahip bir platformu hedefleyen tüm derlemelerle eşleşir. Bir platformun, bu ikisinin ötesinde ek kısıtlama değerleri tanımladığı takdirde yine eşleştiğini unutmayın.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

Notlar

• Geçerli yapılandırma durumuyla birden fazla config_setting eşleştiğinde ne olacağını öğrenmek için seçme bölümüne bakın.
• Kestirme biçimleri destekleyen işaretler için (ör. --compilation_mode ve -c) values tanımları için tam biçim kullanılmalıdır. Bunlar, formlardan herhangi birini kullanarak çağrıları otomatik olarak eşleştirir.
• Bir işaret birden fazla değer alıyorsa (--copt=-Da --copt=-Db veya liste türünde bir Starlark flag gibi) "a" gerçek listede herhangi bir yerde mevcutsa values = { "flag": "a" } eşleşir.

  values = { "myflag": "a,b" } aynı şekilde çalışır: Bu; --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b ve --myflag=c,b,a ile eşleşir. Kesin anlamlar, işaretler arasında farklılık gösterir. Örneğin --copt, aynı örnekte birden çok değeri desteklemez: --copt=a,b ["a,b"] değerini, --copt=a --copt=b ise ["a", "b"] sonucunu verir (dolayısıyla values = { "copt": "a,b" } ilkiyle eşleşir ancak ikincisiyle eşleşmez). Ancak --ios_multi_cpus (Apple kuralları için) şunları yapar: -ios_multi_cpus=a,b ve ios_multi_cpus=a --ios_multi_cpus=b hem ["a", "b"] üretir. Beklentileri tam olarak doğrulamak için işaret tanımlarını kontrol edin ve koşullarınızı dikkatli bir şekilde test edin.

• Yerleşik derleme işaretleri tarafından modellenmeyen koşullar tanımlamanız gerekiyorsa Starlark tarafından tanımlanan işaretleri kullanın. --define kullanabilirsiniz ancak bu daha zayıf bir destek sunar ve önerilmez. Daha fazla bilgi için buraya göz atabilirsiniz.
• Farklı paketlerde aynı config_setting tanımlarını tekrarlamayın. Bunun yerine, standart pakette tanımlanan ortak bir config_setting öğesine referans verin.
• values, define_values ve constraint_values, aynı config_setting içindeki herhangi bir kombinasyonda kullanılabilir ancak belirli bir config_setting için en az bir tanesi ayarlanmalıdır.

Bağımsız değişkenler

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

dosya grubu

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

Hedef koleksiyonuna uygun bir ad vermek için filegroup kullanın. Daha sonra bunlara diğer kurallardan referans verilebilir.

Dizinlere doğrudan referans vermek yerine filegroup kullanılması önerilir. İkincisi, derleme sistemi dizin altındaki tüm dosyalar hakkında tam bilgiye sahip olmadığından bir sorun teşkil etmez. Bu nedenle, söz konusu dosyalar değiştiğinde uygulama yeniden oluşturulmayabilir. glob ile birleştirildiğinde filegroup, tüm dosyaların derleme sistemi tarafından açık bir şekilde bilinmesini sağlayabilir.

Örnekler

İki kaynak dosyadan oluşan bir filegroup oluşturmak için şunu yapın:

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

Alternatif olarak, bir test verileri dizininde gezinmek için bir glob kullanın:

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

Bu tanımlardan yararlanmak için filegroup öğesine herhangi bir kuraldan etiketi ekleyin:

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

Bağımsız değişkenler

Genquery

genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery(), Blaze sorgu dilinde belirtilen bir sorguyu çalıştırır ve sonucu bir dosyaya aktarır.

Derlemenin tutarlı olması için sorgunun yalnızca scope özelliğinde belirtilen hedeflerin geçişli kapanışını ziyaret etmesine izin verilir. strict belirtilmezse veya doğru değerine ayarlanırsa bu kuralı ihlal eden sorgular, yürütülürken başarısız olur (strict yanlış değerine ayarlanırsa kapsam dışı hedefler bir uyarıyla atlanır). Bunun olmamasını sağlamanın en kolay yolu, kapsam içinde sorgu ifadesindeki ile aynı etiketleri belirtmektir.

Burada ve komut satırında izin verilen sorgular arasındaki tek fark, joker karakter hedef özelliklerini (ör. //pkg:* veya //pkg:all) içeren sorgulara burada izin verilmemesidir. Bunun iki nedeni vardır: Birincisi, genquery ürününün çıktısını etkilemek için sorgunun geçişli kapanması dışındaki hedefleri engellemek için bir kapsam belirtmesi gerekir.İkincisi, BUILD dosyaları joker karakter bağımlılıklarını desteklemediğinden (ör. deps=["//a/..."]'ye izin verilmez).

--output=graph|minrank|maxrank veya üst düzey işlev olarak somepath kullanıldığında, sorgun çıktısı, deterministik çıktıyı uygulamak için sözlüksel olarak sıralanır.

Çıktı dosyasının adı, kuralın adıdır.

Örnekler

Bu örnekte, belirtilen hedefin geçişli kapanışındaki etiketlerin listesini bir dosyaya yazar.

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

Bağımsız değişkenler

Genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule, kullanıcı tanımlı bir Bash komutu kullanarak bir veya daha fazla dosya oluşturur.

Kurallar, görev için belirli bir kural yoksa kullanabileceğiniz genel oluşturma kurallarıdır. Örneğin, tek satırlık bir Bash belgesi yayınlayabilirsiniz. Ancak C++ dosyalarını derlemeniz gerekiyorsa işin zor kısmını sizin yerinize zaten yapmış olduğunuzdan mevcut cc_* kurallarına bağlı kalın.

Genrule işlevinin, komut bağımsız değişkenini yorumlamak için bir kabuk gerektirdiğini unutmayın. PATH üzerinde bulunan rastgele programlara referans vermek de kolaydır, ancak bu durumda komut hermetik değildir ve yeniden oluşturulamayabilir. Yalnızca tek bir araç çalıştırmanız gerekiyorsa bunun yerine run_binary parametresini kullanabilirsiniz.

Test çalıştırmak için bir genrule kullanmayın. Testler ve test sonuçları için önbelleğe alma politikaları ve ortam değişkenleri de dahil olmak üzere özel dağıtımlar vardır. Testlerin genellikle derleme tamamlandıktan sonra ve hedef mimaride çalıştırılması gerekir. Bununla birlikte, kurallar derleme sırasında ve exec mimarisinde yürütülür (ikisi farklı olabilir). Genel amaçlı bir test kuralına ihtiyacınız varsa sh_test değerini kullanın.

Derlemeler Arasında Dikkat Edilmesi Gereken Noktalar

Çapraz derleme hakkında daha fazla bilgi için kullanıcı kılavuzuna bakın.

Genrule'lar derleme sırasında çalıştırılsa da çıkışları genellikle derlemeden sonra dağıtım veya test için kullanılır. Bir mikrodenetleyici için C kodu derleme örneğini düşünün: Derleyici, C kaynak dosyalarını kabul eder ve bir mikrodenetleyicide çalışan kod oluşturur. Oluşturulan kod, açıkçası onu oluşturmak için kullanılan CPU'da çalışamaz ancak C derleyicisinin (kaynaktan derlenmişse) bunu çalışması gerekir.

Derleme sistemi, derlemenin çalıştığı makineleri tanımlamak için exec yapılandırmasını, derleme çıktısının çalışması gereken makineleri tanımlamak için ise hedef yapılandırmayı kullanır. Bunların her birini yapılandırma seçenekleri sunar ve çakışmaları önlemek için karşılık gelen dosyaları ayrı dizinlere ayırır.

Genrule için derleme sistemi, bağımlılıkların uygun şekilde oluşturulduğundan emin olur: target yapılandırması için srcs oluşturulur (gerekirse), tools exec yapılandırması için oluşturulur ve çıkışın target yapılandırması için olduğu kabul edilir. Ayrıca, genel komutların ilgili araçlara iletebileceği "Yap" değişkenleri de sağlar.

Genel kural, herhangi bir deps özelliğini tanımlamaz. Diğer yerleşik kurallar, bağımlı kuralların nasıl işleneceğini otomatik olarak belirlemek için kurallar arasında iletilen dile bağlı meta bilgileri kullanır. Ancak türler için bu düzeyde otomasyon mümkün değildir. Genrules yalnızca dosya ve runfiles düzeyinde çalışır.

Özel Durumlar

Exec-exec derleme: Bazı durumlarda, yapı sisteminin derleme sırasında da çıkışın yürütülebilmesi için genel kuralları çalıştırması gerekir. Örneğin bir genrule, daha sonra başka bir tür tarafından kullanılacak olan özel derleyici oluşturursa ilkinin, exec yapılandırması için çıktısını oluşturması gerekir çünkü derleyici diğer tür içinde burada çalışır. Bu durumda derleme sistemi doğru şeyi otomatik olarak yapar: Yürütme yapılandırması için hedef yapılandırma yerine ilk türünün srcs ve outs öğelerini oluşturur. Daha fazla bilgi için kullanım kılavuzuna bakın.

JDK ve C++ Araçları: Derleme sistemi, JDK veya C++ derleyici paketindeki bir aracı kullanmak için kullanılacak değişken grubu sağlar. Ayrıntılar için "Oluşturma" değişkeni konusuna bakın.

Genrule Ortam

Genrule komutu, set -e -o pipefail kullanılarak bir komut veya ardışık düzen başarısız olduğunda başarısız olacak şekilde yapılandırılan Bash kabuğu tarafından yürütülür.

Derleme aracı, Bash komutunu yalnızca PATH, PWD, TMPDIR ve diğer birkaç temel değişkeni tanımlayan arındırılmış işlem ortamında yürütür. Derlemelerin yeniden oluşturulabildiğinden emin olmak için kullanıcının kabuk ortamında tanımlanan çoğu değişken, genrule komutuna iletilmez. Bununla birlikte, Bazel (Blaze değil), kullanıcının PATH ortam değişkeninin değerini geçer. PATH değerinde herhangi bir değişiklik, Bazel'ın bir sonraki derlemede komutu yeniden çalıştırmasına neden olur.

Şu anda zorunlu olmasa da genrule komutu, komutun alt öğesi olan işlemleri bağlamak dışında ağa erişmemelidir.

Derleme sistemi, mevcut çıkış dosyalarını otomatik olarak siler ancak bir tür çalıştırmadan önce gerekli üst dizinleri oluşturur. Ayrıca, hata durumunda çıkış dosyalarını da kaldırır.

Genel Tavsiye

• Bir türün yönettiği araçların deterministik ve hermetik olduğundan emin olun. Çıkışlarına zaman damgaları yazmamalı, kümeler ve haritalar için sabit bir sıralama kullanmalı, ayrıca çıkışa yalnızca göreli dosya yolları yazmalı, mutlak yol içermemelidir. Bu kurala uyulmaması, beklenmeyen derleme davranışına (Bazel'in düşündüğünüz gibi bir kuralı yeniden oluşturmamasına) neden olur ve önbellek performansını düşürür.
• Çıkışlar, araçlar ve kaynaklar için $(location) politikasını yoğun bir şekilde kullanın. Çıkış dosyalarının farklı yapılandırmalar için ayrılması nedeniyle, türler sabit kodlu ve/veya mutlak yollara dayanamaz.
• Aynı veya çok benzer türlerin birden fazla yerde kullanılması ihtimaline karşı ortak bir Starlark makrosu yazın. Oluşturma yöntemi karmaşıksa bunu bir komut dosyası veya Starlark kuralı olarak uygulamayı düşünebilirsiniz. Bu, okunabilirliği ve test edilebilirliği iyileştirir.
• Çıkış kodunun, genrule işleminin başarılı veya başarısız olduğunu doğru bir şekilde gösterdiğinden emin olun.
• stdout veya stderr'e bilgilendirici iletiler yazmayın. Hata ayıklama açısından faydalı olsa da bu, kolayca parazit haline gelebilir. Başarılı bir genrule sessiz olmalıdır. Diğer yandan, başarısız bir genel kural, iyi hata mesajları vermelidir.
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x).
• Sembolik bağlantılar ve dizinler oluşturmaktan kaçının. Bazel, Genrules tarafından oluşturulan dizin/sembolik bağlantı yapısını kopyalamaz ve dizinlerin bağımlılık kontrolü güvenilir değildir.
• Diğer kurallarda genel kurala referans verirken Genrule etiketini veya bağımsız çıkış dosyalarının etiketlerini kullanabilirsiniz. Bazen bir yaklaşım daha okunaklı olabilir, bazen diğer: Bir tüketim kuralının srcs öğesinde çıkışlara adla referans vermek, istemeden diğer genrule çıktılarının alınmasını önler, ancak genrule çok sayıda çıkış üretiyorsa yorucu olabilir.

Örnekler

Bu örnek, foo.h oluşturur. Komut herhangi bir giriş almadığı için kaynak yok. Komut tarafından çalıştırılan "binary", genrule ile aynı paketteki bir perl komut dosyasıdır.

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

Aşağıdaki örnekte filegroup öğesinin nasıl kullanılacağı ve başka bir genrule öğesinin çıktıları gösterilmektedir. Açık $(location) yönergeleri yerine $(SRCS) kullanmanın da işe yarayacağını unutmayın. Bu örnekte, açıklama amacıyla ikincisi kullanılmaktadır.

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

Bağımsız değişkenler

starlark_doc_extract

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract(), belirli bir .bzl veya .scl dosyasında tanımlanan ya da yeniden dışa aktarılan kurallar, işlevler (makrolar dahil), yönler ve sağlayıcılarla ilgili belgeleri çıkarır. Bu kuralın sonucu, Bazel kaynak ağacında stardoc_output.proto'da tanımlandığı gibi ModuleInfo ikili program protokolüdür.

Örtülü çıkış hedefleri

• name.binaryproto (varsayılan çıkış): ModuleInfo ikili protokolü.
• name.textproto (yalnızca açıkça istenirse oluşturulur): name.binaryproto metin proto sürümü.

Uyarı: Bu kuralın çıkış biçiminin kararlı olacağı garanti edilmez. Esas olarak Stardoc'un dahili kullanımı içindir.

Bağımsız değişkenler

test_suite

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite, insanlar için "yararlı" olarak kabul edilen bir dizi testi tanımlar. Bu sayede projeler, "kontrol öncesinde çalıştırmanız gereken testler", "projemizin stres testleri" veya "tümü küçük testler" gibi test grupları tanımlayabilir. blaze test komutu şu tür bir organizasyona uyar: blaze test //some/test:suite gibi bir çağrı için Blaze, öncelikle //some/test:suite hedefinin içerdiği tüm test hedeflerini geçişli olarak sıralar (buna "test_suite genişletmesi" adını veririz), ardından Blaze bu hedefleri oluşturup test eder.

Örnekler

Mevcut paketteki tüm küçük testleri çalıştırmak için bir test paketi.

test_suite(
    name = "small_tests",
    tags = ["small"],
)

Belirli bir test grubunu çalıştıran bir test paketi:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

Mevcut pakette güvenilir olmayan tüm testleri çalıştırmak için kullanılan bir test paketi.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

Bağımsız değişkenler