Genel Kurallar

Sorun bildir Kaynağı görüntüle Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Kurallar

takma ad

Kural kaynağını göster
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 takma 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, referans verdiği kural gibi davranır (ör. takma ad üzerinde testonly yok sayı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

Özellikler
name

Ad; gerekli

Bu hedef için benzersiz bir ad.

actual

Etiket; zorunlu

Bu takma adın belirttiği hedef. Kural olması gerekmez, giriş dosyası da olabilir.

config_setting

Kural kaynağını görüntüleme
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ğı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 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 ö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 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",
      ]
  )
  
Tüm bu durumlarda, yapılandırmanın derleme sırasında değişmesi mümkündür (ör. bir hedefin, dep'sinden farklı bir platform için derlenmesi gerekiyorsa). Bu, bir config_setting üst düzey komut satırı işaretleriyle eşleşmese bile bazı derleme hedefleriyle eşleşebileceği anlamına gelir.

Notlar

  • Birden fazla config_setting mevcut yapılandırma durumuyla eşleştiğinde ne olacağı için select işlevine bakın.
  • Kısaltılmış biçimleri (ör. --compilation_mode - -c) destekleyen flag'ler için values tanımları tam formu kullanmalıdır. Bunlar, iki formdan birini kullanarak çağrıları otomatik olarak eşleştirir.
  • 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" } 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ş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) 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, daha zayıf bir 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

Özellikler
name

Ad; zorunlu

Bu hedef için benzersiz bir ad.

constraint_values

Etiketler listesi; yapılandırılamaz; varsayılan değer []

Hedef platformun bu config_setting ile eşleşebilmesi için belirtmesi gereken minimum constraint_values grubu. (Yürütme platformu burada dikkate alınmaz.) Platformun sahip olduğu ek kısıtlama değerleri yoksayılır. Ayrıntılar için Yapılandırılabilir Derleme Özellikleri başlıklı makaleyi inceleyin.

İki config_setting'nin aynı select ile eşleştiği durumlarda, bu özellik config_setting'lerden birinin diğerinin uzmanlık alanı olup olmadığını belirlemek için dikkate alınmaz. Diğer bir deyişle, bir config_setting, bir platformla diğerinden daha güçlü bir şekilde eşleşemez.

define_values

Sözlük: Dize -> Dize; yapılandırılmamış; varsayılan değer {}

values ile aynı ancak özellikle --define işareti için.

--define, söz dizimi (--define KEY=VAL) nedeniyle özeldir çünkü KEY=VAL, Bazel işareti açısından bir değer

Bu, şu anlama gelir:

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

aynı anahtar (define) sözlükte iki kez göründüğü için çalışmaz. Bu özellik bu sorunu çözer:

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

bazel build //foo --define a=1 --define b=2 ile doğru şekilde eşleşiyor.

--define, normal işaret söz dizimi ile values içinde görünmeye devam edebilir ve sözlük anahtarları farklı kaldığı sürece bu özellikle serbestçe karıştırılabilir.

flag_values

Sözlük: label -> Dize; yapılandırılamaz; varsayılan değer {}

values ile aynıdır ancak kullanıcı tanımlı derleme işaretleri içindir.

Kullanıcı tanımlı işaretler etiket olarak, yerleşik işaretler ise rastgele dize olarak referans verildiğinden bu farklı bir özelliktir.

values

Sözlük: Dize -> Dize; yapılandırılamaz; varsayılan değer {}

Bu kuralla eşleşen yapılandırma değerleri grubu (derleme işaretleri olarak ifade edilir)

Bu kural, select ifadesinde kendisine referans veren yapılandırılmış hedefin yapılandırmasını devralır. Sözlükteki her giriş için yapılandırması girişin beklenen değeriyle eşleşirse sözlüğün Bazel çağrısıyla "eşleştiği" kabul edilir. Örneğin values = {"compilation_mode": "opt"}, hedef yapılandırılmış kurallardaki bazel build --compilation_mode=opt ... ve bazel build -c opt ... çağrılarıyla eşleşir.

Kolaylık sağlamak amacıyla yapılandırma değerleri, yapılandırma işaretleri olarak belirtilir (önceki "--" olmadan). Ancak bu iki değerin aynı olmadığını unutmayın. Bunun nedeni, hedeflerin aynı derleme içinde birden fazla yapılandırmada oluşturulabilmesidir. Örneğin, bir yürütme yapılandırmasının "cpu" özelliği --cpu ile değil, --host_cpu ile eşleşir. Bu nedenle, aynı config_setting'nin farklı örnekleri, bunları kullanan kuralın yapılandırmasına bağlı olarak aynı çağrıyla farklı şekilde eşleşebilir.

Bir işaret, komut satırında açıkça ayarlanmazsa varsayılan değeri kullanılır. Bir anahtar sözlükte birden çok kez görünüyorsa yalnızca son örnek kullanılır. Bir anahtar, komut satırında birden çok kez ayarlanabilen bir işarete referans veriyorsa (ör. bazel build --copt=foo --copt=bar --copt=baz ...) bu ayarlardan herhangi biri eşleşiyorsa eşleşme gerçekleşir.

dosya grubu

Kural kaynağını görüntüleme
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. Daha sonra bunlara diğer kurallardan referans verilebilir.

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 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",
        "some/subdirectory/another_file.txt",
    ],
)

Dilerseniz test verileri dizininde arama yapmak için glob kullanabilirsiniz:

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

Özellikler
name

Ad; gerekli

Bu hedef için benzersiz bir ad.

srcs

Etiketler listesi; varsayılan değer []'dir.

Dosya grubunun üyesi olan hedeflerin listesi.

srcs özelliğinin değeri için glob ifadesinin sonucunun kullanılması yaygındır.

data

Etiketler listesi; varsayılan değer []'dir.

Bu kuralın çalışma zamanında ihtiyaç duyduğu dosyaların listesi.

data özelliğinde adlandırılan hedefler, bu filegroup kuralının runfiles bölümüne eklenir. filegroup öğesine başka bir kuralın data özelliğinde referans verildiğinde, runfiles özelliği bağlı kuralın runfiles öğesine eklenir. Veri dosyalarına bağımlı olma ve veri dosyalarını kullanma hakkında daha fazla bilgi için veri bağımlılıkları bölümünü ve data ile ilgili genel dokümanları inceleyin.

output_group

Dize; varsayılan değer ""

Kaynaklardan yapıların toplanacağı çıkış grubu. Bu özellik belirtilirse varsayılan çıkış grubu yerine, bağımlılıkların belirtilen çıkış grubundaki yapı taşları dışa aktarılır.

"Çıkış grubu", bir kuralın uygulamasında belirtilen ve bir hedefin çıkış yapılarının kategorisidir.

genquery

Kural kaynağını görüntüleme
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ılığını sağlamak için sorgunun yalnızca scope özelliğinde belirtilen hedeflerin geçişli kapanışı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

Özellikler
name

Ad; gerekli

Bu hedef için benzersiz bir ad.

compressed_output

Boole; varsayılan değer False'tir

True ise sorgu çıkışı GZIP dosyası biçiminde yazılır. Bu ayar, sorgu çıktısının büyük olması beklendiğinde Bazel'in bellek kullanımında ani artışların olmasını önlemek için kullanılabilir. Bazel, bu ayarın değerinden bağımsız olarak 220 bayttan büyük sorgu çıkışlarını zaten dahili olarak sıkıştırır. Bu nedenle, bu ayarı True olarak ayarlamak, tutulan yığının boyutunu azaltmayabilir. Ancak, çıkış dosyasını yazarken Bazel'in sıkıştırmayı atlamasına olanak tanır. Bu da bellekte yoğunluğa neden olabilir.
expression

Dize; zorunlu

Yürütülecek sorgu. Komut satırının ve BUILD dosyalarındaki diğer yerlerin aksine, buradaki etiketler çalışma alanının kök dizine göre çözülür. Örneğin, a/BUILD dosyasındaki bu özellikteki :b etiketi, //:b hedefini referans alır.
opts

Dize listesi; varsayılan değer []'tir.

Sorgu motoruna iletilen seçenekler. Bunlar, bazel query'e iletilebilecek komut satırı seçeneklerine karşılık gelir. Burada bazı sorgu seçeneklerine izin verilmez: --keep_going, --query_file, --universe_scope, --order_results ve --order_output. Burada belirtilmeyen seçenekler, bazel query komut satırındaki varsayılan değerlerine sahip olur.
scope

Etiketler listesi; zorunlu

Sorgunun kapsamı. Sorgunun, bu hedeflerin geçişli kapatma işleminin dışındaki hedeflere dokunmasına izin verilmez.
strict

Boole; varsayılan değer True'tir

Doğru ise sorguları kapsamlarının geçişli kapatma işleminden kaçan hedefler oluşturulamaz. False (yanlış) değerine ayarlanırsa Bazel bir uyarı yazdırır ve onu kapsam dışına yönlendiren sorgu yolunu atlayarak sorgunun geri kalanını tamamlar.

Genrule

Kural kaynağını göster
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.

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.

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 düşünün: Derleyici, C kaynak dosyalarını kabul eder ve bir 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.

Genrule'lar için derleme sistemi, bağımlılıkların uygun şekilde oluşturulmasını sağlar: target yapılandırması için srcs oluşturulur, tools exec 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 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. Genrule'lar yalnızca dosya ve çalıştırma dosyaları 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 "Marka" değişkeni bölümüne bakın.

Genel 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 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 genrule çalıştırmadan önce gerekli üst dizinleri oluşturur. Ayrıca, başarısız bir işlem 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 sabit sıralama kullanmalı, mutlak yollar kullanmamalı, çıkışa yalnızca göreli dosya yolları yazmalı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ırmalara göre ayrılması nedeniyle, genruller sabit kodlu ve/veya mutlak yollara dayanamaz.
  • 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'ın 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).
  • Sembol 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 genel kurala referans verirken genel kuralın etiketini veya ayrı 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 oluşturur. 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

Özellikler
name

Ad; zorunlu

Bu hedef için benzersiz bir ad.


Bu kurala, diğer BUILD kurallarının srcs veya deps bölümünden adıyla referans verebilirsiniz. Kural kaynak dosyalar oluşturuyorsa srcs özelliğini kullanmanız gerekir.
srcs

Etiket listesi; varsayılan []

Bu kuralla ilgili girişlerin (ör. işlenecek kaynak dosyaları) listesi.

Bu özellik, cmd tarafından çalıştırılan araçları listelemek için uygun değildir. Bunun yerine tools özelliğini kullanın.

Derleme sistemi, genrule komutu çalıştırılmadan önce bu ön koşulların derlendiğinden emin olur. Bu ön koşullar, orijinal derleme isteğiyle aynı yapılandırma kullanılarak derlenir. Bu ön koşulların dosya adları, komut tarafından $(SRCS) içinde boşlukla ayrılmış bir liste olarak kullanılabilir. Alternatif olarak, tek bir srcs hedefi //x:y'nin yolu $(location //x:y) kullanılarak veya srcs'teki tek giriş olması koşuluyla $< kullanılarak elde edilebilir.

outs

Dosya adlarının listesi; yapılandırılamaz; zorunlu

Bu kural tarafından oluşturulan dosyaların listesi.

Çıkış dosyaları, paket sınırlarını geçmemelidir. Çıkış dosyası adları pakete göre yorumlanır.

executable işareti ayarlanmışsa outs tam olarak bir etiket içermelidir.

genrule komutunun her çıkış dosyasını önceden belirlenmiş bir konumda oluşturması beklenir. Konum, cmd üzerinde genel kurala özel "Marka" değişkenleri ($@, $(OUTS), $(@D) veya $(RULEDIR)) veya $(location) değişikliği kullanılarak mevcuttur.

cmd

Dize; varsayılan değer ""

Çalıştırılacak komut. $(location) ve "Make" değişkeni yerine koyma işlemine tabidir.
  1. İlk olarak $(location) ikame uygulanır. Bu işlemde $(location label) ve $(locations label)'in (ve execpath, execpaths, rootpath ve rootpaths ile ilgili değişkenleri kullanan benzer yapıların) tüm oluşumları değiştirilir.
  2. Ardından, "Make" değişkenleri genişletilir. Önceden tanımlanmış $(JAVA), $(JAVAC) ve $(JAVABASE) değişkenlerinin exec yapılandırması altında genişlediğini unutmayın. Böylece, derleme adımının parçası olarak çalışan Java çağrıları, paylaşılan kitaplıkları ve diğer bağımlılıkları doğru şekilde yükleyebilir.
  3. Son olarak, oluşturulan komut Bash kabuğu kullanılarak yürütülür. Çıkış kodu sıfırdan farklıysa komutun başarısız olduğu kabul edilir.
Bu, cmd_bash, cmd_ps ve cmd_bat'ın hiçbiri geçerli değilse bu değerlerin yedeğidir.

Komut satırı uzunluğu platform sınırını (Linux/macOS'te 64 KB, Windows'ta 8 KB) aşarsa genrule, komutu bir komut dosyasına yazar ve bu sorunu gidermek için komut dosyasını yürütür. Bu durum tüm cmd özellikleri (cmd, cmd_bash, cmd_ps, cmd_bat) için geçerlidir.

cmd_bash

Dize; varsayılan değer ""'tir

Çalıştırılacak Bash komutu.

Bu özelliğin önceliği cmd özelliğinden daha yüksektir. Komut genişletilir ve cmd özelliğiyle tam olarak aynı şekilde çalışır.

cmd_bat

Dize; varsayılan değer ""'tir

Windows'da çalıştırılacak toplu komut.

Bu özelliğin önceliği, cmd ve cmd_bash özelliklerine göre daha yüksek. Komut, cmd özelliğiyle benzer şekilde çalışır ancak aşağıdaki farklılıklar vardır:

  • Bu özellik yalnızca Windows'da geçerlidir.
  • Komut, aşağıdaki varsayılan bağımsız değişkenlerle cmd.exe /c ile çalışır:
    • /S - İlk ve son alıntıları ayıklayın ve diğer her şeyi olduğu gibi yürütün.
    • /E:ON: Genişletilmiş komut setini etkinleştirin.
    • /V:ON - gecikmeli değişken genişletmeyi etkinleştir
    • /D: AutoRun kayıt defteri girişlerini yoksay.
  • $(location) ve "Make" değişkeni yerine geçirildikten sonra yollar, Windows tarzı yollara (ters eğik çizgiyle) genişletilir.
cmd_ps

Dize; varsayılan değer ""'tir

Windows&#39;da çalıştırılacak PowerShell komutu.

Bu özelliğin önceliği cmd, cmd_bash ve cmd_bat'den daha yüksektir. Komut, cmd özelliğine benzer şekilde çalışır ancak aşağıdaki farklılıklar vardır:

  • Bu özellik yalnızca Windows'ta geçerlidir.
  • Komut powershell.exe /c ile çalışır.

Powershell'in kullanımının daha kolay ve hata olasılığının daha az olmasını sağlamak için genrule'da Powershell komutunu yürütmeden önce ortamı ayarlamak üzere aşağıdaki komutları çalıştırırız.

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - imzasız komut dosyalarının çalıştırılmasına izin verin.
  • $errorActionPreference='Stop': ; ile ayrılmış birden fazla komut varsa bir Powershell CmdLet başarısız olursa işlem hemen sonlandırılır ancak bu, harici komut için ÇALIŞMAZ.
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8': Varsayılan kodlamayı utf-16'dan utf-8'e değiştirin.
executable

Boole; yapılandırılamaz; varsayılan değer False'dir.

Çıkışı yürütülebilir olarak tanımlayın.

Bu işaretin Doğru değerine ayarlanması, çıktının yürütülebilir bir dosya olduğu ve run komutu kullanılarak çalıştırılabileceği anlamına gelir. Bu durumda genrule tam olarak bir çıkış oluşturmalıdır. Bu özellik ayarlanırsa run, içeriğinden bağımsız olarak dosyayı yürütmeyi dener.

Oluşturulan yürütülebilir dosya için veri bağımlılıklarının tanımlanması desteklenmiyor.

local

Boole; varsayılan değer False'tir

Doğru değerine ayarlanırsa bu seçenek, genrule'ün "yerel" stratejiyi kullanarak çalıştırılmasını zorunlu kılar. Bu durumda uzaktan yürütme, korumalı alan ve kalıcı çalışanlar kullanılamaz.

Bu, etiket olarak "local" (tags=["local"]) sağlamaya eşdeğerdir.

message

Dize; varsayılan değer ""'tir

İlerleme mesajı.

Bu derleme adımı yürütülürken yazdırılacak bir ilerleme mesajı. Varsayılan olarak "Çıkış oluşturma" mesajı (ya da eşit derecede uygunsuz bir mesaj) olur ancak daha spesifik bir mesaj sağlayabilirsiniz. Derleme aracının bu tür ilerleme mesajlarının yazdırılıp yazdırılmayacağını kontrol etmesine olanak tanıdığı için cmd komutunuzda echo veya diğer yazdırma ifadeleri yerine bu özelliği kullanın.

output_licenses

Lisans türü; varsayılan değer: ["none"]

Bkz. common attributes
output_to_bindir

Boole; yapılandırılmamış; varsayılan değer False

Bu seçenek True olarak ayarlanırsa çıkış dosyalarının genfiles dizini yerine bin dizine yazılmasına neden olur.

tools

Etiketler listesi; varsayılan değer []'dir.

Bu kuralın araç bağımlılıkları listesi. Daha fazla bilgi için bağımlılıkların tanımına bakın.

Derleme sistemi, bu ön koşulların genrule komutunu çalıştırmadan önce oluşturulmasını sağlar. Bu ön koşullar, derlemenin parçası olarak yürütüldüğü için exec yapılandırması kullanılarak oluşturulur. Bir tools hedefinin //x:y yolu, $(location //x:y) kullanılarak elde edilebilir.

cmd tarafından yürütülecek tüm *_binary veya araçlar, doğru yapılandırmada oluşturulduklarından emin olmak için srcs yerine bu listede görünmelidir.

starlark_doc_extract

Kural kaynağını göster
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 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 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

Özellikler
name

Ad; zorunlu

Bu hedef için benzersiz bir ad.

deps

Etiketler listesi; varsayılan değer []'dir.

src tarafından load() gönderilen Starlark dosyalarını sarmalayan hedeflerin listesi. Bu hedeflerin, normal kullanım altında bzl_library hedefleri olması gerekir ancak starlark_doc_extract kuralı bunu zorunlu kılmaz ve DefaultInfo içinde Starlark dosyaları sağlayan herhangi bir hedefi kabul eder.

Sarmalanmış Starlark dosyalarının kaynak ağaçtaki dosyalar olması gerektiğini unutmayın. Bazel, load() tarafından oluşturulan dosyaları kullanamaz.

src

Etiket; zorunlu

Dokümanların ayıklanacağı Starlark dosyası.

Bunun kaynak ağaçta bir dosya olması gerektiğini unutmayın. Bazel, oluşturulan dosyaları load() yapamaz.

render_main_repo_name

Boole; varsayılan değer False

Doğru ise ana depoda etiketleri, repo bileşeniyle birlikte yayınlanan dokümanda oluştur (yani //foo:bar.bzl, @main_repo_name//foo:bar.bzl olarak yayınlanır).

Ana depo için kullanılacak ad, ana deponun MODULE.bazel dosyasında (Bzlmod etkinse) module(name = ...) veya ana deponun WORKSPACE dosyasında workspace(name = ...) bölümünden alınır.

Bu özellik, yalnızca aynı depoda kullanılması amaçlanan Starlark dosyaları için doküman oluşturulurken False, diğer depolardan kullanılması amaçlanan Starlark dosyaları için doküman oluşturulurken True olarak ayarlanmalıdır.

symbol_names

Dize listesi; varsayılan değer: []

Belgelerinin ayıklanacağı, dışa aktarılan işlevlerin, kuralların, sağlayıcıların veya özelliklerin (veya iç içe yerleştirildikleri yapıların) nitelikli adlarının isteğe bağlı listesi. Burada nitelenmiş ad, bir öğenin modülün kullanıcısına sunulduğu ad anlamına gelir. Bu ad, öğenin adlandırma alanı için iç içe yerleştirildiği tüm yapıları içerir.

starlark_doc_extract, yalnızca şu durumlarda varlığa ait dokümanları yayınlar:

  1. varlığın nitelikli adının her bileşeni herkese açıktır (başka bir deyişle, nitelikli adın her bileşeninin ilk karakteri "_" değil, alfabetiktir); ve
    1. Ya symbol_names listesi boştur (varsayılan durumdur) veya
    2. varlığın tam nitelikli adı veya varlığın iç içe yerleştirildiği bir yapının tam nitelikli adı symbol_names listesindedir.

test_suite

Kural kaynağını göster
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 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

Özellikler
name

Ad; gerekli

Bu hedef için benzersiz bir ad.

tags

Dize listesi; yapılandırılamaz; varsayılan değer []

"small" veya "database" ya da "-flaky" gibi metin etiketlerinin listesi. Etiketler herhangi bir geçerli dize olabilir.

"-" karakteriyle başlayan etiketler negatif etiket olarak kabul edilir. Önceki "-" karakteri, etiketin bir parçası olarak kabul edilmez. Bu nedenle, "-small" içeren bir paket etiketi, bir testin "small" boyutuyla eşleşir. Diğer tüm etiketler pozitif etiket olarak kabul edilir.

İsteğe bağlı olarak, pozitif etiketleri daha açık hale getirmek için etiketler "+" karakteriyle de başlayabilir. Bu karakter, etiketin metninin bir parçası olarak değerlendirilmez. Bu, olumlu ve olumsuz ayrımın daha kolay okunmasını sağlar.

Yalnızca pozitif etiketlerin tümüyle ve negatif etiketlerin hiçbiriyle eşleşmeyen test kuralları test grubuna dahil edilir. Bunun, filtrelenen testlerdeki bağımlılıkları kontrol etme hatasının atlanacağı anlamına gelmediğini unutmayın.Atlanan testlere yönelik bağımlılıkların yine de yasal olması (ör. görünürlük kısıtlamaları tarafından engellenmemesi) gerekir.

manual etiket anahtar kelimesi, joker karakter hedef kalıpları içeren çağrılarda blaze test komutu tarafından gerçekleştirilen "test_suite expansion" tarafından yukarıdakinden farklı şekilde ele alınır. Burada "manuel" olarak etiketlenen test_suite hedef filtrelenir (dolayısıyla genişletilmez). Bu davranış, blaze build ve blaze test'un genel olarak joker karakter hedef kalıplarını ele alma şekliyle tutarlıdır. Süitler, manual etiketinden bağımsız olarak her zaman tests sorgu işleviyle genişletildiğinden, bunun blaze query 'tests(E)' davranışından açıkça farklı olduğunu unutmayın.

Bir testin size değerinin, filtreleme amacıyla etiket olarak kabul edildiğini unutmayın.

Birbirine hariç tutulan etiketlere sahip testleri (ör. tüm küçük ve orta testler) içeren bir test_suite'ye ihtiyacınız varsa üç test_suite kuralı oluşturmanız gerekir: biri tüm küçük testler için, biri tüm orta testler için ve biri de önceki ikisini içeren.

tests

Etiketler listesi; yapılandırılamaz; varsayılan değer []

Herhangi bir dilin test paketlerinin ve test hedeflerinin listesi.

Dilinden bağımsız olarak burada tüm *_test kabul edilir. Ancak, test çalıştırmış olsalar bile *_binary hedefleri kabul edilmez. Belirtilen tags'e göre filtreleme yalnızca doğrudan bu özellikte listelenen testler için yapılır. Bu özellik test_suite içeriyorsa bu test_suite'ler içindeki testler bu test_suite tarafından filtrelenmez (zaten filtrelenmiş kabul edilir).

tests özelliği belirtilmezse veya boşsa kural, varsayılan olarak geçerli BUILD dosyasında manual olarak etiketlenmemiş tüm test kurallarını içerir. Bu kurallar tag filtrelemesine tabi olmaya devam eder.