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ı, kurala ad verilebilecek başka bir ad oluşturur.

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

Takma ad oluşturma, bir hedefi yeniden adlandırmak için çok sayıda dosya üzerinde değişiklik yapılmasının gerektiği büyük depolarda yardımcı olabilir. Takma ad kuralını birden fazla hedef için yeniden kullanmak istiyorsanız select işlev çağrısını depolamak için de kullanabilirsiniz.

Takma ad kuralının kendi görünürlük bildirimi vardır. Diğer tüm açılardan bakıldığında, bazı küçük istisnalarla birlikte, referansta bulunduğu kural gibi davranır (ör. takma adda test amaçlı yoksayılır; bunun yerine, referans verilen kuralın test amaçlı kullanımı kullanılır) ancak bazı küçük istisnalar söz konusudur:

• Komut satırında takma adlarından bahsedilen testler çalıştırılmaz. Başvuruda bulunulan testi çalıştıran bir takma ad tanımlamak için tests özelliğinde tek hedef bulunan bir test_suite kuralı 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 özelliklerin tetiklenmesi 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ğıdakiler, --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 FOO=bar tanımlamasını uygulayan herhangi bir derlemeyle 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ğı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 örnek, x86_64 mimarisine ve glibc sürüm 2.25'e sahip bir platformu hedefleyen tüm derlemelerle eşleşir ve //example:glibc_2_25 etiketine sahip bir constraint_value bulunduğu varsayılır. Bir platformun, bu iki kısıtlamanın dışında ek kısıtlama değerleri tanımladığı durumlarda 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ğını öğrenmek için seçim bölümüne bakın.
• Kısaltılmış biçimleri (ör. --compilation_mode - -c) destekleyen flag'ler için values tanımları tam formu kullanmalıdır. Bu çağrılar, her iki formu da kullanarak otomatik olarak eşleştirilir.
• Bir işaret birden fazla değer alırsa (--copt=-Da --copt=-Db veya liste türünde Starlark işareti gibi) "a" değerinin gerçek listenin herhangi bir yerinde bulunması halinde 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 değişiklik gösterir. Örneğin, --copt aynı örnekte birden fazla değeri desteklemez: --copt=a,b, ["a,b"] değerini üretirken --copt=a --copt=b, ["a", "b"] değerini üretir (yani 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 ikisi de ["a", "b"] oluşturur. 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şaretleri tarafından modellenmeyen koşullar tanımlamanız gerekiyorsa Starlark tarafından tanımlanan işaretleri kullanın. --define değerini de kullanabilirsiniz ancak bu, daha zayıf bir destek sunar ve önerilmez. Daha fazla tartışma için buraya bakın.
• Farklı paketlerde aynı config_setting tanımlarını tekrarlamaktan kaçının. Bunun yerine, standart pakette tanımlanan ortak bir config_setting öğesine başvurun.
• 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 bir kombinasyon 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 kolay bir ad vermek için filegroup kullanın. Bu değerler daha sonra diğer kurallardan referans olarak alınabilir.

Dizinlere doğrudan referans vermek yerine filegroup kullanılması önerilir. Derleme sistemi, dizinin altındaki tüm dosyalarla ilgili tam bilgiye sahip olmadığından bu yöntem doğru değildir. Bu nedenle, bu dosyalar değiştiğinde yeniden derleme yapılmayabilir. filegroup, glob ile birleştirildiğinde tüm dosyaların derleme sistemi tarafından açıkça bilinmesini sağlayabilir.

Örnekler

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

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

Veya bir test verisi dizini oluşturmak için bir glob kullanın:

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

Bu tanımları kullanmak için filegroup'e herhangi bir kuraldan etiketle 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 döküm.

Derlemenin tutarlılığını sağlamak için sorgunun yalnızca scope özelliğinde belirtilen hedeflerin geçişli kapanışını ziyaret etmesine izin verilir. strict belirtilmemişse veya doğru değerine ayarlanırsa bu kuralı ihlal eden sorgular yürütme sırasında 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, sorgu ifadesinde belirtilenle aynı etiketleri kapsam içinde belirtmektir.

Burada ve komut satırında izin verilen sorgular arasındaki tek fark, joker karakter hedef özellikleri (ör. //pkg:* veya //pkg:all) içeren sorgulara burada izin verilmemesidir. Bunun iki nedeni vardır. Birincisi, genquery ürününün, çıkışını etkilemesi için sorgunun geçişli olarak kapatılması dışındaki hedeflerin önlenmesi için bir kapsam belirtmesi gerekir. İkinci olarak, BUILD dosyaları joker karakter bağımlılıklarını desteklemediğinden (ö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ılmaktadı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ı Bash komutunu kullanarak bir veya daha fazla dosya oluşturur.

Genrule, 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. Yine de C++ dosyalarını derlemeniz gerekiyorsa mevcut cc_* kurallarına bağlı kalın. Tüm ağır işlemler sizin yerinize zaten yapılmıştır.

Genrule öğesinin, komut bağımsız değişkenini yorumlamak için 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.

Testleri çalıştırmak için 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. 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 kullanın.

Çapraz Derlemeyle İlgili Konular

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

Genrule'lar derleme sırasında çalışırken bunların çıkışları genellikle derleme sonrasında 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ığı makineleri tanımlamak için yönetici yapılandırmasını ve derleme çıkışının çalışması gereken makineleri açıklamak için 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.

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 ise 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 ilgili araçlara iletebileceği "Make" değişkenleri de sağlar.

Genel kuralların herhangi bir deps özelliği tanımlamaması kasıtlıdır. Diğer yerleşik kurallar, bağımlı kuralların nasıl ele alınacağını otomatik olarak belirlemek için kurallar arasında iletilen dile bağlı meta bilgileri kullanır ancak genel kurallar 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ılacak bir özel derleyici derlerse ilkinin, yürütme yapılandırması için çıktısını oluşturması gerekir. Çünkü derleyici bu aşamada diğer genel kuralda da çalışır. 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 "Yap" 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 ve birkaç diğer temel değişkenleri tanımlayan temiz bir işlem ortamında yürütür. Derlemelerin tekrarlanabilir olmasını sağlamak için kullanıcının kabuk ortamında tanımlanan çoğu değişken, genrule komutunun 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 bir genrule çalıştırmadan önce gerekli tüm üst dizinleri oluşturur. Ayrıca, hata durumunda çıkış dosyalarını da 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 sabit sıralama kullanmalı, mutlak yollar kullanmamalı, çıkışa yalnızca göreli dosya yolları yazmalıdır. Bu kurala uyulmaması, beklenmeyen derleme davranışlarına (Bazel'in beklediğiniz bir genel kuralı yeniden oluşturmamasına) ve önbellek performansının düşmesine neden olur.
• $(location) öğesini çıkışlar, araçlar ve kaynaklar için yoğun bir şekilde kullanın. Çıkış dosyalarının farklı yapılandırmalara göre ayrılması nedeniyle, genruller sabit kodlu ve/veya mutlak yollara dayanamaz.
• Aynı veya çok benzer kişilerin 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, kuralın başarılı veya başarısız olduğunu doğru şekilde gösterdiğ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. 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).
• 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 okunabilir olur, bazen diğeri: tüketici kuralının srcs öğesinde çıkışlara isme göre referans vermek, istemeden genrule'ın diğer çıktılarını toplamaktan kaçınır ancak genel kural çok sayıda çıktı üretiyorsa yorucu olabilir.

Örnekler

Bu örnek, foo.h oluşturur. Komut giriş almadığı için kaynak yok. 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 filegroup özelliğinin nasıl kullanılacağı ve başka bir genrule öğesinin çıkışları 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 veya yeniden dışa aktarılan kurallar, işlevler (makrolar dahil), özellikler ve sağlayıcılarla ilgili dokümanları ayıklar. Bu kuralın sonucu, Bazel kaynak ağacındaki stardoc_output.proto bölümünde tanımlandığı gibi bir ModuleInfo ikili programıdır.

Örtülü çıkış hedefleri

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

Uyarı: Bu kuralın çıkış biçiminin kararlı olacağı garanti edilmez. Esas olarak Stardoc tarafından dahili 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. blaze test komutu bu tür bir organizasyona uyar: blaze test //some/test:suite gibi bir çağrı için Blaze, ö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 bir 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