Genel Kurallar

Kurallar

• takma ad
• 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ı, kuralın atıfta bulunabileceği başka bir ad oluşturur.

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

Takma ad, bir hedefin yeniden adlandırılmasının çok sayıda dosyada değişiklik yapılmasını gerektirdiği büyük depolarda yararlı olabilir. Bu mantığı birden fazla hedef için yeniden kullanmak isterseniz select işlev çağrısını 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, referans verdiği kural gibi davranır (ör. takma ad üzerinde testonly yoksayılır; bunun yerine, referans verilen kuralın testonly özelliği kullanılır) ancak bazı küçük istisnalar vardır:

• Komut satırında takma adlarından bahsedilen testler çalıştırılmaz. Referans verilen testi çalıştıran bir takma ad tanımlamak için tests özelliğinde tek bir hedefi olan bir test_suite kuralını kullanın.
• Ortam grupları tanımlanırken environment kurallarının takma 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ı nasıl kullanacağınızı öğrenmek için select'e, genel özelliğe genel bakış için ise Configurable attributes (Yapılandırılabilir özellikler) başlıklı makaleye bakın.

Ö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 ifade, ARM'i hedefleyen ve özel tanımlama FOO=bar'yi (örneğin, bazel build --cpu=arm --define FOO=bar ...) uygulayan tüm derlemelerle eşleşir:

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

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

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

Aşağıdaki ifade, //example:glibc_2_25 etiketli bir constraint_value bulunduğu varsayılarak x86_64 mimarisine ve glibc 2.25 sürümüne sahip bir platformu hedefleyen tüm derlemelerle eşleşir. Bir platformun, bu ikisinin dışında ek kısıtlama değerleri tanımlaması durumunda da eşleştiğini unutmayın.

  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ğı için select işlevine bakın.
• Kısaltma biçimlerini destekleyen işaretler (ör. --compilation_mode ve -c) için values tanımlarında tam biçim kullanılmalıdır. Bu çağrılar, her iki formu da kullanarak otomatik olarak eşleştirilir.
• Bir işaret birden fazla değer alıyorsa (--copt=-Da --copt=-Db veya liste türüne sahip bir Starlark işareti gibi) values = { "flag": "a" }, "a" gerçek listede herhangi bir yerde varsa eşleşir.

  values = { "myflag": "a,b" } de 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 değişir. Örneğin, --copt aynı örnekte birden çok değeri desteklemez: --copt=a,b ["a,b"], --copt=a --copt=b ise ["a", "b"] değerini döndürür (bu nedenle values = { "copt": "a,b" }, birinciyle eşleşir ancak ikinciyle eşleşmez). Ancak --ios_multi_cpus (Apple kuralları için) böyledir: -ios_multi_cpus=a,b ve ios_multi_cpus=a --ios_multi_cpus=b her ikisi de ["a", "b"] değerini döndürür. Tam olarak ne beklediğinizi doğrulamak için işaret tanımlarını kontrol edin ve koşullarınızı dikkatlice test edin.

• Yerleşik derleme işaretleriyle modellenmeyen koşulları tanımlamanız gerekiyorsa Starlark tarafından tanımlanan işaretleri kullanın. --define değerini de kullanabilirsiniz ancak bu yöntem daha az 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'ye referans verin.
• values, define_values ve constraint_values aynı config_setting içinde herhangi bir kombinasyonda kullanılabilir ancak belirli bir config_setting için en az biri 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)

Bir hedef grubunun çıktılarını tek bir etiket altında toplamak için filegroup değerini kullanın.

Hedeflerin çıktıları dışında, aynı şekilde toplanmayan birçok özelliği olduğundan filegroup, hedefleri komut satırında veya başka bir kuralın özelliğinde listelemenin yerini almaz. Ancak yine de bazı durumlarda kullanışlıdır. Örneğin, bir genrule kuralının srcs özelliğinde veya *_binary kuralının data özelliğinde.

Dizinlere doğrudan referans vermek yerine filegroup kullanılması önerilir. Derleme sistemi, dizinin altındaki tüm dosyalarla ilgili tam bilgiye sahip olmadığından doğrudan dizinlere referans vermenin önerilmez. Bu nedenle, bu dosyalar değiştiğinde yeniden derleme yapılmayabilir. filegroup, glob ile birlikte kullanıldığında tüm dosyaların derleme sisteminin açıkça bildiğinden emin olabilir.

Örnekler

İki kaynak dosyadan oluşan bir filegroup oluşturmak için:

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "//a/library:target",
        "//a/binary:target",
    ],
)

Dilerseniz test verileri dizinini tamamen taramak için glob kullanabilirsiniz:

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

Bu tanımları kullanmak için herhangi bir kuraldan etiket içeren filegroup'e 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(), Bazel 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çirgen kapatmasını ziyaret etmesine izin verilir. strict belirtilmezse veya doğruysa bu kuralı ihlal eden sorgular yürütme sırasında başarısız olur (strict yanlışsa kapsam dışındaki hedefler bir uyarıyla atlanır). Bunun olmasını önlemenin en kolay yolu, kapsamda sorgu ifadesiyle aynı etiketlerden bahsetmektir.

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

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

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

Örnekler

Bu örnekte, belirtilen hedefin geçişli kapatma işlemindeki etiketlerin listesi bir dosyaya yazılır.

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 tüm ağır işler sizin için zaten yapıldığından mevcut cc_* kurallarına uyun.

genrule'un, komut bağımsız değişkenini yorumlamak için bir kabuk gerektirdiğini unutmayın. PATH'te bulunan herhangi bir programa referans vermek de kolaydır ancak bu, komutun hermetik olmasını engeller ve komut tekrar oluşturulamayabilir. Yalnızca tek bir aracı çalıştırmanız gerekiyorsa bunun yerine run_binary işlevini kullanabilirsiniz.

Diğer tüm işlemler gibi, genrules tarafından oluşturulan işlem de çalışma dizini hakkında hiçbir varsayımda bulunmamalıdır. Bazel, yalnızca beyan edilen girişlerin $(location)'nin etiketi için döndürdüğü yolda bulunacağını garanti eder. Örneğin, işlem korumalı alanda veya uzaktan çalıştırılırsa çalışma dizini, korumalı alanın uygulanması veya uzaktan yürütme işlemine göre belirlenir. Doğrudan çalıştırılırsa (standalone stratejisi kullanılarak) çalışma dizini, yürütme kökü yani bazel info execution_root sonucu olur.

Test çalıştırmak için genrule kullanmayın. Testler ve test sonuçları için önbelleğe alma politikaları ve ortam değişkenleri dahil olmak üzere özel muafiyetler vardır. Testlerin genellikle derleme tamamlandıktan sonra ve hedef mimaride çalıştırılması gerekir. Buna karşılık, 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 değerini kullanın.

Çapraz Derlemeyle İlgili Konular

Ç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. Bir mikrodenetleyici için C kodunu derleme örneğini düşünün: Derleyici, C kaynak dosyalarını kabul eder ve mikrodenetleyicide çalışan kod oluşturur. Oluşturulan kod, derlenmesi için kullanılan CPU'da çalışamaz ancak C derleyicisinin (kaynaktan derlenmişse) çalışması gerekir.

Derleme sistemi, derlemenin çalıştırıldığı makineleri tanımlamak için exec yapılandırmasını, derlemenin çıktısının çalıştırılması 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 ilgili dosyaları ayrı dizinlere ayırır.

Derleme sistemi, genrules için bağımlılıkların uygun şekilde derlendiğinden emin olur: srcs, gerekirse hedef yapılandırması için derlenir, tools, exec yapılandırması için derlenir ve çıkışın hedef 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'un deps özelliğini tanımlamaması bilinçli bir seçimdir: 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 genrules için bu düzeyde otomasyon mümkün değildir. Genrules yalnızca dosya ve çalıştırılabilir dosya düzeyinde çalışır.

Özel Durumlar

Yürütme-yürütme derlemesi: Bazı durumlarda, derleme sisteminin genrules'i, çıkışın derleme sırasında da yürütülebilmesi için çalıştırması gerekir. Örneğin, bir genrule daha sonra başka bir genrule tarafından kullanılan bazı özel derleyiciler oluşturursa ilk genrule'ün, derleyicinin diğer genrule'de çalışacağı yer olduğu için exec yapılandırması için çıkışını üretmesi gerekir. Bu durumda, derleme sistemi otomatik olarak doğru işlemi yapar: Hedef yapılandırma yerine yürütme yapılandırması için ilk genrule'nin 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 paketindeki bir aracı 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 ardışık düzen başarısız olduğunda set -e -o pipefail kullanılarak başarısız olacak şekilde yapılandırılan bir Bash kabuğu tarafından yürütülür.

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

genrule komutu, komutun alt işlemleri olan işlemleri bağlamak dışında ağa erişmemelidir. Ancak bu şu anda zorunlu kılınmamıştır.

Derleme sistemi, mevcut çıkış dosyalarını otomatik olarak siler ancak 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

• Bir 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 kararlı sıralama kullanmalı ve çıkışa yalnızca göreli dosya yolları yazmalı, mutlak yollar yazmamalıdır. Bu kurala uyulmaması, beklenmedik derleme davranışlarına (Bazel, yeniden oluşturacağınızı düşündüğünüz bir genrule'yi yeniden oluşturmaz) neden olur ve önbellek performansını düşürür.
• Çıkışlar, araçlar ve kaynaklar için $(location)'ü yoğun şekilde kullanın. Çıkış dosyalarının farklı yapılandırmalar için ayrılması nedeniyle genrules, kodlanmış ve/veya mutlak yollara güvenemez.
• Aynı veya çok benzer genrules'ın birden fazla yerde kullanılması ihtimaline karşı ortak bir Starlark makrosu yazın. genrule karmaşıksa bir komut dosyası 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 belirttiğinden emin olun.
• Bilgilendirme mesajlarını stdout veya stderr'ye yazmayın. Hata ayıklama için yararlı olsa da bu, kolayca gürültüye dönüşebilir. Başarılı bir genrule sessiz olmalıdır. Öte yandan, başarısız 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).
• Simge bağlantıları ve dizinler oluşturmaktan kaçının. Bazel, genrules tarafından oluşturulan dizin/yönlendirme bağlantısı yapısını kopyalamamakta ve dizinlerdeki bağımlılık kontrolü güvenilir değildir.
• Diğer kurallarda genrule'ye referans verirken genrule'nin etiketini veya ayrı çıkış dosyalarının etiketlerini kullanabilirsiniz. Bazen bir yaklaşım daha okunaklı, bazen de diğeri daha okunaklı olur: Tüketen kuralın srcs bölümünde çıkışlara isme göre referans vermek, gen kuralın diğer çıkışlarının yanlışlıkla alınmasını önler ancak gen kural çok fazla çıkış üretiyorsa can sıkıcı olabilir.

Örnekler

Bu örnek foo.h değerini döndürür. Komut herhangi bir giriş almadığı için kaynak yoktur. Komut tarafından çalıştırılan "ikili", 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, bir filegroup ve başka bir genrule'ın çıkışlarının nasıl kullanılacağı gösterilmektedir. Açık $(location) yönergeleri yerine $(SRCS) kullanılmasının da işe yarayacağını unutmayın. Bu örnekte, açıklama amacıyla açık yönergeler 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), görünümler ve sağlayıcılarla ilgili dokümanları ayıklayıp çıkarır. Bu kuralın çıktısı, Bazel kaynak ağacındaki stardoc_output.proto dosyasında tanımlandığı şekilde bir ModuleInfo ikili protodur.

Örtülü çıkış hedefleri

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

Uyarı: Bu kuralın çıkış biçiminin kararlı olacağı garanti edilmez. Bu API, temel olarak Stardoc tarafından şirket içi kullanım için tasarlanmış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, kullanıcılar için "yararlı" kabul edilen bir dizi testi tanımlar. Bu sayede projeler "check-in yapmadan önce çalıştırmanız gereken testler", "projemizin stres testleri" veya "tüm küçük testler" gibi test grupları tanımlayabilir. bazel test komutu bu tür bir organizasyona uyar: bazel test //some/test:suite gibi bir çağrı için Bazel, önce //some/test:suite hedefi tarafından geçişli olarak dahil edilen tüm test hedeflerini (buna "test_suite genişletmesi" denir) listeler, ardından bu hedefleri oluşturup test eder.

Örnekler

Mevcut paketteki tüm küçük testleri çalıştıracak bir test paketi.

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

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

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

Mevcut paketteki tüm testleri çalıştıracak, kararlı olmayan bir test paketi.

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

Bağımsız değişkenler