Genel Kurallar

Kurallar

• alias
• config_setting
• filegroup
• genquery
• genrule
• 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.

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

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 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ı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 formu kullanan ç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" } da 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 fazla değeri desteklemez: --copt=a,b, ["a,b"] sonucunu verirken --copt=a --copt=b, ["a", "b"] sonucunu verir (bu nedenle values = { "copt": "a,b" }, ikincisiyle değil, ilkiyle eşleşir). Ancak --ios_multi_cpus (Apple kuralları için) şunu yapar: -ios_multi_cpus=a,b ve ios_multi_cpus=a --ios_multi_cpus=b ifadelerinin her ikisi de ["a", "b"] sonucunu verir. İşaret tanımlarını kontrol edin ve koşullarınızı dikkatlice test ederek beklentilerinizi doğrulayın.

• Yerleşik derleme işaretleriyle modellenmeyen koşullar tanımlamanız gerekiyorsa Starlark ile tanımlanan işaretleri kullanın. --define da kullanabilirsiniz ancak bu 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)

Bir hedef koleksiyonuna uygun bir ad vermek için filegroup simgesini kullanın. Bu değerlere daha sonra diğer kurallardan referans verilebilir.

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, 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. Bu durum, strict belirtilmemişse veya doğruysa geçerlidir (strict 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/..."] kullanılamaz).

Genquery'nin çıkışı, deterministik çıkışı zorunlu kılmak için --order_output=full kullanılarak 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, exec_tools, 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ü ağır işlerin tümü sizin için yapılmıştır.

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 genrule'lar derleme sırasında ve ana makine 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, oluşturulmasında kullanılan CPU'da çalışamaz ancak C derleyicinin (kaynaktan derlendiyse) çalışması gerekir.

Derleme sistemi, derlemenin üzerinde çalıştığı makineyi/makineleri tanımlamak için ana makine yapılandırmasını, derlemenin çıktısının üzerinde çalışması gereken makineyi/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 Hedef yapılandırması için (gerekirse) oluşturulur, tools Ana makine yapılandırması için oluşturulur 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'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

Ana makine-ana makine derlemesi: Bazı durumlarda, derleme sisteminin, çıkışın derleme sırasında da yürütülebileceği şekilde genrule'ları çalıştırması gerekir. Örneğin, bir genrule daha sonra başka bir genrule tarafından kullanılan özel bir derleyici oluşturuyorsa, derleyici diğer genrule'da çalışacağı için birincisi çıkışını ana makine yapılandırması için üretmelidir. Bu durumda, derleme sistemi doğru şeyi otomatik olarak yapar: hedef yapılandırma yerine ana makine 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şkenine bakın.

Genrule Ortamı

genrule komutu, set -e -o pipefail kullanılarak 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 yürütülür.

Derleme aracı, yalnızca PATH, PWD, TMPDIR gibi temel değişkenleri ve birkaç değişkeni daha 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çleri bağlamak 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ını 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. 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 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ığı için 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 ikincisi 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

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ı" olduğu düşünülen 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