Genel Kurallar

Kurallar

• alias
• config_setting
• filegroup
• 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ı, bir kuralın adlandırılacağı başka bir ad oluşturur.

Takma ad yalnızca "normal" hedefler için çalışır. Özellikle package_group ve test_suite için takma ad oluşturulamaz.

Hedefin yeniden adlandırılması için birçok dosyada değişiklik yapılması gereken büyük depolarda diğer adlandırma yararlı olabilir. Ayrıca, bu mantığı birden fazla hedef için yeniden kullanmak istiyorsanız select işlev çağrısını depolamak için diğer ad kuralını da kullanabilirsiniz.

Takma ad kuralının kendi görünürlük bildirimi vardır. Diğer tüm açılardan, referans verdiği kural gibi davranır (ör.takma ad üzerindeki testonly yoksayılır; bunun yerine referans verilen kuralın testonly özelliği kullanılır). Ancak bazı küçük istisnalar vardır:

• Takma adları komut satırında belirtilen testler çalıştırılmaz. Referans verilen testi çalıştıran bir takma ad tanımlamak için test_suite kuralını tests özelliğinde tek bir hedefle kullanın.
• Ortam grupları tanımlarken environment kurallarının diğer adları desteklenmez. --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 işaretleri veya platform kısıtlamaları olarak ifade edilir) eşleşir. Bu kuralın nasıl kullanılacağı hakkında bilgi edinmek için select, genel özelliklere genel bakış için Yapılandırılabilir özellikler başlıklı makaleyi inceleyin.

Örnekler

Aşağıdaki, --compilation_mode=opt veya -c opt değerini ayarlayan tüm derlemelerle eşleşir (komut satırında açıkça veya .bazelrc dosyalarından dolaylı olarak):

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

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

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

Aşağıdaki, user-defined flag'i ayarlayan tüm derlemelerle eşleşir --//custom_flags:foo=1 (komut satırında açıkça veya .bazelrc dosyalarından örtülü olarak):

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

Aşağıdaki, x86_64 mimarisine ve glibc sürüm 2.25'e sahip bir platformu hedefleyen tüm derlemelerle eşleşir. Bu eşleşme, //example:glibc_2_25 etiketli bir constraint_value öğesinin varlığı varsayılarak yapılır. Bir platform, bu ikisinin ötesinde ek kısıtlama değerleri tanımlasa bile eşleşmeye devam eder.

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

Notlar

• Birden fazla config_setting mevcut yapılandırma durumuyla eşleştiğinde ne olacağını öğrenmek için select bölümüne bakın.
• Kısa biçimleri destekleyen işaretler (ör. --compilation_mode ve -c) için values tanımları tam biçimde olmalıdır. Bunlar, her iki biçimdeki çağırmalarla otomatik olarak eşleşir.
• Bir işaret birden fazla değer alıyorsa (ör. --copt=-Da --copt=-Db veya liste türünde bir Starlark işareti), "a" gerçek listede herhangi bir yerde bulunuyorsa 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. Tam 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"] değerini üretir (bu nedenle values = { "copt": "a,b" }, ikincisiyle değil, ilkiyle eşleşir). Ancak --ios_multi_cpus (Apple kuralları için) yapılır: -ios_multi_cpus=a,b ve ios_multi_cpus=a --ios_multi_cpus=b ifadeleri ["a", "b"] sonucunu verir. İşaret tanımlarını kontrol edin ve koşullarınızı dikkatlice test ederek beklentilerinizi karşıladığını doğrulayın.

• Yerleşik derleme işaretleriyle modellenmeyen koşullar tanımlamanız gerekiyorsa Starlark ile tanımlanan işaretleri kullanın. --define karakterini de kullanabilirsiniz ancak bu karakter daha zayıf destek sunar ve önerilmez. Daha fazla bilgi için buraya göz atın.
• Farklı paketlerde aynı config_setting tanımlarını tekrarlamaktan kaçının. Bunun yerine, standart bir pakette tanımlanan ortak bir config_setting öğesine referans verin.
• values, define_values ve constraint_values aynı config_setting içinde herhangi bir kombinasyonla kullanılabilir ancak herhangi bir config_setting için en az birinin ayarlanması gerekir.

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",
                })
          

filegroup

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 simgesini kullanın. Bunlar daha sonra diğer kurallardan referans alınabilir.

Dizinlere doğrudan referans vermek yerine filegroup kullanılması önerilir. Derleme sistemi, dizinin altındaki tüm dosyalar hakkında tam bilgiye sahip olmadığından bu dosyalar değiştiğinde yeniden derleme yapmayabilir. Bu nedenle, ikinci yöntem güvenilir değildir. glob ile birlikte kullanıldığında filegroup, tüm dosyaların derleme sistemi tarafından açıkça bilinmesini sağlayabilir.

Örnekler

İki kaynak dosyasından oluşan bir filegroup oluşturmak için

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

Alternatif olarak, bir testdata dizinini taramak için glob kullanın:

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

Bu tanımlardan yararlanmak için herhangi bir kuraldan alınan bir etiketle filegroup öğesine referans verin:

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ı kalması için sorgunun yalnızca scope özelliğinde belirtilen hedeflerin geçişli kapanışını ziyaret etmesine izin verilir. Bu kuralı ihlal eden sorgular, yürütme sırasında başarısız olur. Bunun nedeni, strict değerinin belirtilmemiş olması veya doğru olmasıdır (strict değeri yanlışsa kapsam dışı hedefler uyarı verilerek atlanır). Bu durumun yaşanmaması için en kolay yöntem, sorgu ifadesindekiyle aynı etiketleri kapsamda belirtmektir.

Burada ve komut satırında izin verilen sorgular arasındaki tek fark, joker karakter hedef spesifikasyonları (ör. //pkg:* veya //pkg:all) içeren sorgulara burada izin verilmemesidir. Bunun iki nedeni vardır: Birincisi, genquery, sorgunun geçişli kapanışının dışındaki hedeflerin çıkışını etkilemesini önlemek için bir kapsam belirtmelidir.İkincisi ise BUILD dosyaları, joker karakter bağımlılıklarını desteklemez (ör. deps=["//a/..."] izin verilmez).

--output=graph|minrank|maxrank veya somepath üst düzey işlev olarak kullanıldığında hariç olmak üzere, deterministik çıkışı zorunlu kılmak için genquery'nin çıkışı sözlükbilimsel olarak sıralanır.

Çıkış dosyasının adı, kuralın adıdır.

Örnekler

Bu örnek, belirtilen hedefin geçişli kapanımı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.

Genrules, görev için belirli bir kural yoksa kullanabileceğiniz genel derleme kurallarıdır. Örneğin, tek satırlık bir Bash komutu çalıştırabilirsiniz. Ancak C++ dosyalarını derlemeniz gerekiyorsa mevcut cc_* kurallarına uymanız gerekir. Çünkü tüm ağır işler sizin için zaten yapılmıştır.

genrule'un komut bağımsız değişkenini yorumlamak için bir kabuk gerektirdiğini unutmayın. PATH'te bulunan rastgele programlara başvurmak da kolaydır ancak bu, komutu hermetik olmayan bir hale getirir ve tekrarlanamayabilir. Yalnızca tek bir aracı çalıştırmanız gerekiyorsa bunun yerine run_binary'yi kullanabilirsiniz.

Testleri çalıştırmak için genrule kullanmayın. Önbelleğe alma politikaları ve ortam değişkenleri de dahil olmak üzere testler ve test sonuçları için özel muafiyetler vardır. Testlerin genellikle derleme tamamlandıktan sonra ve hedef mimaride çalıştırılması gerekirken genrules, derleme sırasında ve yürütme mimarisinde (ikisi farklı olabilir) yürütülür. Genel amaçlı bir test kuralına ihtiyacınız varsa sh_test kuralını kullanın.

Çapraz Derlemeyle İlgili Dikkat Edilmesi Gerekenler

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

Genrules, derleme sırasında çalıştırılır ancak çıktıları genellikle derlemeden sonra dağıtım veya test için kullanılır. Mikrodenetleyici için C kodu derleme örneğini ele alalım: Derleyici, C kaynak dosyalarını kabul eder ve mikrodenetleyicide çalışan kod oluşturur. Oluşturulan kod, derlenmesinde kullanılan CPU'da çalışamaz ancak C derleyicinin (kaynaktan derlendiyse) çalışması gerekir.

Derleme sistemi, derlemenin üzerinde çalıştığı makineleri tanımlamak için exec yapılandırmasını, derlemenin çıktısının üzerinde çalışması gereken makineleri tanımlamak için ise hedef yapılandırmayı kullanır. Bu seçeneklerin her birini yapılandırma imkanı sunar ve çakışmaları önlemek için ilgili dosyaları ayrı dizinlere ayırır.

Derleme sistemi, genrules için bağımlılıkların uygun şekilde oluşturulmasını sağlar: srcs target yapılandırması için (gerekirse) oluşturulur, tools exec yapılandırması için oluşturulur ve çıkışın target yapılandırması için olduğu kabul edilir. Ayrıca, genrule komutlarının ilgili araçlara iletebileceği "Make" değişkenleri de sağlar.

Genrule'da deps özelliği tanımlanmaması kasıtlıdır: Diğer yerleşik kurallar, bağımlı kuralların nasıl işleneceğini otomatik olarak belirlemek için kurallar arasında aktarılan dile bağlı meta bilgileri kullanır ancak genrule'larda bu düzeyde bir otomasyon mümkün değildir. Genrules yalnızca dosya ve runfiles düzeyinde çalışır.

Özel Durumlar

Exec-exec derlemesi: Bazı durumlarda, derleme sisteminin genrules'u, çıkışın derleme sırasında da yürütülebileceği şekilde çalıştırması gerekir. Örneğin, bir genrule daha sonra başka bir genrule tarafından kullanılan özel bir derleyici oluşturuyorsa, ilki çıkışını exec yapılandırması için üretmelidir. Çünkü derleyici, diğer genrule'da bu yapılandırmada çalışır. Bu durumda, derleme sistemi doğru şeyi otomatik olarak yapar: hedef yapılandırma yerine yürütme yapılandırması için ilk genrule'un srcs ve outs öğelerini oluşturur. Daha fazla bilgi için kullanım kılavuzuna bakın.

JDK ve C++ Araçları: JDK veya C++ derleyici paketinden bir araç kullanmak için derleme sistemi, kullanılacak bir dizi değişken sağlar. Ayrıntılar için "Marka" değişkeni bölümüne bakın.

Genrule Ortamı

genrule komutu, bir komut veya işlem hattı başarısız olduğunda başarısız olacak şekilde yapılandırılmış bir Bash kabuğu tarafından set -e -o pipefail kullanılarak yürütülür.

Derleme aracı, yalnızca PATH, PWD, TMPDIR gibi temel değişkenleri tanımlayan temizlenmiş bir işlem ortamında Bash komutunu yürütür. Derlemelerin yeniden üretilebilir olmasını sağlamak için kullanıcının kabuk ortamında tanımlanan değişkenlerin çoğu genrule'un komutuna iletilmez. Ancak Bazel (Blaze değil), kullanıcının PATH ortam değişkeninin değerini geçirir. PATH değerinde yapılan herhangi bir değişiklik, Bazel'in komutu bir sonraki derlemede yeniden yürütmesine neden olur.

Bir genrule komutu, şu anda zorunlu kılınmamış olsa da, komutun alt işlemleri olan süreçlere bağlanmak dışında ağa erişmemelidir.

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

Genel Tavsiye

• Genrule tarafından çalıştırılan araçların deterministik ve hermetik olduğundan emin olun. Çıkışlarına zaman damgaları yazmamalı, kümeler ve haritalar için sabit sıralama kullanmalı ve çıkışa yalnızca göreli dosya yolları yazmalı, mutlak yollar yazmamalıdır. Bu kurala uyulmaması durumunda: Beklenmedik derleme davranışları (Bazel'in, derleyeceğini düşündüğünüz bir genrule'u yeniden derlememesi) ortaya çıkar. Önbellek performansı düşer.
• Çıkışlar, araçlar ve kaynaklar için $(location)'ı kapsamlı bir şekilde kullanın. Farklı yapılandırmalar için çıkış dosyalarının ayrılması nedeniyle, genrules sabit kodlanmış ve/veya mutlak yollara dayanamaz.
• Aynı veya çok benzer genrule'lar birden fazla yerde kullanılıyorsa ortak bir Starlark makrosu yazın. Genrule karmaşıksa bunu bir komut dosyasında veya Starlark kuralı olarak uygulamayı düşünebilirsiniz. Bu, okunabilirliğin yanı sıra test edilebilirliği de artırır.
• Çıkış kodunun, genrule'un başarılı veya başarısız olduğunu doğru şekilde gösterdiğinden emin olun.
• stdout veya stderr'ye bilgilendirici mesajlar yazmayın. Bu, hata ayıklama için yararlı olsa da kolayca gürültüye dönüşebilir. Başarılı bir genrule sessiz olmalıdır. Öte yandan, başarısız olan bir genrule 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 genrule'a referans verirken genrule'un etiketini veya tek tek çıkış dosyalarının etiketlerini kullanabilirsiniz. Bazen bir yaklaşım daha okunabilir olur, bazen de diğeri: Tüketici kuralının srcs bölümünde çıkışlara adlarıyla referans vermek, genrule'un diğer çıkışlarının yanlışlıkla alınmasını önler ancak genrule çok sayıda çıkış üretiyorsa bu işlem sıkıcı olabilir.

Örnekler

Bu örnek foo.h oluşturur. Komut herhangi bir giriş almadığından kaynak yoktur. 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 ve başka bir genrule öğesinin çıkışlarının nasıl kullanılacağı gösterilmektedir. Açık $(location) yönergeleri yerine $(SRCS) kullanmanın da işe yarayacağını unutmayın. Bu örnekte, gösterim amacıyla $(location) kullanılmıştı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 dokümanları ayıklar. Bu kuralın çıkışı, Bazel kaynak ağacındaki stardoc_output.proto içinde tanımlanan bir ModuleInfo ikili proto'dur.

Örtülü çıkış hedefleri

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

Uyarı: Bu kuralın çıkış biçiminin sabit olacağı garanti edilmez. Bu doküman, esas olarak Stardoc'un şirket içi kullanımı için hazırlanmıştır.

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 "faydalı" olarak kabul edilen bir dizi testi tanımlar. Bu özellik, projelerin "check-in işleminden önce çalıştırmanız gereken testler", "projemizin yük testleri" veya "tüm küçük testler" gibi test kümeleri tanımlamasına olanak tanır. blaze test komutu bu tür bir sıralamaya uyar: blaze test //some/test:suite gibi bir çağırma işleminde Blaze önce //some/test:suite hedefi tarafından geçişli olarak dahil edilen tüm test hedeflerini numaralandırır (buna "test_suite genişletme" diyoruz), ardından Blaze bu hedefleri oluşturur ve test eder.

Örnekler

Mevcut paketteki tüm küçük testleri çalıştırmak için kullanılan 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 paketteki kararsız 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