Peraturan Umum

Laporkan masalah Lihat sumber Malam · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Aturan

alias

Lihat sumber aturan 
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

Aturan alias membuat nama lain yang dapat disebut sebagai nama aturan.

Nama alias hanya berfungsi untuk "reguler" target. Khususnya, package_group dan test_suite tidak dapat diberi alias.

{i>Aliasing<i} mungkin bisa membantu dalam repositori besar di mana perlunya mengubah nama target perubahan pada banyak {i>file<i}. Anda juga dapat menggunakan aturan alias untuk menyimpan sebuah select panggilan fungsi jika Anda ingin menggunakan kembali logika tersebut untuk beberapa target.

Aturan alias memiliki pernyataan visibilitasnya sendiri. Selain itu, perilakunya juga seperti aturan yang direferensikannya (mis. hanya pengujian pada alias diabaikan; status hanya pengujian dari aturan yang direferensikan akan digunakan sebagai gantinya) dengan beberapa pengecualian kecil:

  • Pengujian tidak akan dijalankan jika aliasnya disebutkan di command line. Untuk menentukan alias yang menjalankan pengujian yang direferensikan, gunakan test_suite aturan dengan satu target di tests .
  • Saat menentukan grup lingkungan, alias aturan environment tidak didukung. Alat tersebut tidak didukung di command line --target_environment pilihan.

Contoh

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
actual

Label; wajib diisi

Target yang dirujuk alias ini. Tidak harus berupa aturan, bisa juga berupa input .

config_setting

Lihat sumber aturan 
config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

Mencocokkan status konfigurasi yang diharapkan (dinyatakan sebagai flag build atau batasan platform) untuk dengan tujuan memicu atribut yang dapat dikonfigurasi. Lihat pilihan untuk cara menggunakan aturan ini dan Atribut yang dapat dikonfigurasi untuk melihat ringkasan fitur umum.

Contoh

Berikut ini cocok dengan build apa pun yang menetapkan --compilation_mode=opt atau -c opt (baik secara eksplisit di command line maupun secara implisit dari file .bazelrc): 

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

Yang berikut ini cocok dengan build apa pun yang menargetkan ARM dan menerapkan definisi kustom FOO=bar (misalnya, bazel build --cpu=arm --define FOO=bar ...): 

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

Yang berikut ini cocok dengan build apa pun yang menetapkan flag yang ditentukan pengguna --//custom_flags:foo=1 (baik secara eksplisit di command line maupun secara implisit dari .bazelrc): 

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

Berikut ini cocok dengan build apa pun yang menargetkan platform dengan arsitektur x86_64 dan glibc versi 2.25, dengan asumsi keberadaan constraint_value dengan label //example:glibc_2_25. Perhatikan bahwa platform masih cocok jika mendefinisikan membatasi nilai di luar keduanya. 

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
Dalam semua kasus ini, konfigurasi bisa saja berubah di dalam build, misalnya jika target perlu dibangun untuk platform yang berbeda dari dependensinya. Ini berarti bahwa bahkan ketika config_setting tidak cocok dengan tanda command line tingkat teratas, mungkin masih cocok beberapa target build.

Catatan

  • Lihat pilihan untuk mengetahui apa yang terjadi jika beberapa config_setting cocok dengan status konfigurasi saat ini.
  • Untuk tanda yang mendukung formulir singkat (misalnya, --compilation_mode vs. -c), definisi values harus menggunakan bentuk lengkap. Keduanya secara otomatis mencocokkan pemanggilan menggunakan salah satu bentuk tersebut.
  • Jika flag menggunakan beberapa nilai (seperti --copt=-Da --copt=-Db atau jenis daftar flag Starlark), values = { "flag": "a" } cocok jika "a" tampilkan di mana saja dalam daftar yang sebenarnya.

    values = { "myflag": "a,b" } berfungsi dengan cara yang sama: cocok --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b, dan --myflag=c,b,a. Semantik yang tepat bervariasi antara penanda. Misalnya, --copt tidak mendukung beberapa nilai dalam satu instance: --copt=a,b menghasilkan ["a,b"] sedangkan --copt=a --copt=b menghasilkan ["a", "b"] (jadi values = { "copt": "a,b" } cocok dengan yang pertama, tetapi tidak dengan yang kedua). Namun, --ios_multi_cpus (untuk aturan Apple) melakukan: -ios_multi_cpus=a,b dan ios_multi_cpus=a --ios_multi_cpus=b menghasilkan ["a", "b"]. Periksa definisi tanda dan uji kondisi dengan cermat untuk memverifikasi ekspektasi yang tepat.

  • Jika Anda perlu menentukan kondisi yang tidak dimodelkan oleh flag build bawaan, gunakan Tanda yang ditentukan Starlark. Anda juga dapat menggunakan --define, tetapi cara ini menawarkan dukungan teknis IT dan tidak direkomendasikan. Lihat di sini untuk diskusi lebih lanjut.
  • Hindari pengulangan definisi config_setting yang identik dalam paket yang berbeda. Sebagai gantinya, referensikan config_setting umum yang ditentukan dalam paket kanonis.
  • values, define_values, dan constraint_values dapat digunakan dalam kombinasi apa pun dalam config_setting yang sama tetapi setidaknya salah satunya harus ditetapkan untuk config_setting tertentu.

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
constraint_values

Daftar label; tidak dapat dikonfigurasi; defaultnya adalah []

Kumpulan minimum constraint_values yang harus ditentukan oleh platform target agar cocok dengan config_setting ini. (Platform eksekusi tidak dipertimbangkan di sini.) Nilai batasan tambahan apa pun yang dimiliki platform akan diabaikan. Lihat Atribut Build yang Dapat Dikonfigurasi untuk mengetahui detailnya.

Jika dua config_setting cocok dalam select yang sama dan satu memiliki semua flag dan constraint_setting yang sama dengan yang lainnya ditambah satu tambahan, satu dengan lebih banyak pengaturan akan dipilih. Hal ini dikenal sebagai "spesialisasi". Misalnya, config_setting yang cocok dengan x86 dan Linux mengkhususkan diri config_setting cocok dengan x86.

Jika dua config_setting cocok dan keduanya memiliki constraint_value tidak ada di tampilan lain, ini adalah error.

define_values

Kamus: String -> String; tidak dapat dikonfigurasi; default adalah {}

Sama seperti values tetapi khusus untuk flag --define.

--define bersifat khusus karena sintaksisnya (--define KEY=VAL) berarti KEY=VAL adalah nilai dari perspektif tanda Bazel.

Artinya: 

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

tidak berfungsi karena kunci yang sama (define) muncul dua kali di kata kunci. Atribut ini menyelesaikan masalah tersebut: 

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

cocok dengan bazel build //foo --define a=1 --define b=2.

--define masih dapat muncul di values dengan sintaksis flag normal, dan dapat dicampur secara bebas dengan atribut ini selama kunci kamus tetap berbeda.

flag_values

Kamus: label -> String; tidak dapat dikonfigurasi; defaultnya adalah {}

Sama seperti values tetapi untuk flag build yang ditentukan pengguna.

Ini adalah atribut berbeda karena tanda yang ditentukan pengguna dirujuk sebagai label saat {i>built-in flag<i} disebut sebagai {i>string<i} arbitrer.

values

Kamus: String -> String; tidak dapat dikonfigurasi; default adalah {}

Kumpulan nilai konfigurasi yang cocok dengan aturan ini (dinyatakan sebagai flag build)

Aturan ini mewarisi konfigurasi target yang dikonfigurasi yang merujuknya dalam pernyataan select. Dianggap "kecocokan" pemanggilan Bazel jika, untuk setiap entri dalam kamus, cocok dengan nilai entri yang diharapkan. Misalnya values = {"compilation_mode": "opt"} cocok dengan pemanggilan bazel build --compilation_mode=opt ... dan bazel build -c opt ... pada aturan yang dikonfigurasi target.

Demi kemudahan, nilai konfigurasi ditetapkan sebagai flag build (tanpa "--" sebelumnya). Namun perlu diingat bahwa keduanya tidak sama. Ini adalah karena target dapat dibangun dalam beberapa konfigurasi dalam buat. Misalnya, "cpu" konfigurasi {i>exec<i} cocok dengan nilai --host_cpu, bukan --cpu. Jadi, berbagai contoh config_setting yang sama dapat cocok dengan pemanggilan yang sama secara berbeda bergantung pada konfigurasi aturan yang menggunakannya.

Jika tanda tidak ditetapkan secara eksplisit pada command line, nilai defaultnya akan digunakan. Jika kunci muncul beberapa kali dalam kamus, hanya instance terakhir yang akan digunakan. Jika kunci merujuk ke flag yang bisa disetel beberapa kali pada command line (mis. bazel build --copt=foo --copt=bar --copt=baz ...), kecocokan akan terjadi jika salah satu setelan tersebut cocok.

grup file

Lihat sumber aturan 
filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

Gunakan filegroup untuk mengumpulkan output dari kumpulan target dalam satu output label.

filegroup bukan pengganti target listingan di command line atau di atribut aturan lain, karena target memiliki banyak properti selain output, yang tidak dikumpulkan dengan cara yang sama. Namun, ini masih berguna dalam dalam beberapa kasus, misalnya, dalam atribut srcs genrule, atau atribut data dari aturan *_binary.

Sebaiknya gunakan filegroup, bukan mereferensikan direktori secara langsung. Contoh yang kedua tidak bagus karena sistem build tidak memiliki pengetahuan penuh tentang semua file di bawah direktori, sehingga tidak bisa dibuat ulang ketika file-file ini berubah. Bila digabungkan dengan glob, filegroup dapat memastikan bahwa semua file secara eksplisit dikenal oleh sistem build.

Contoh

Untuk membuat filegroup yang terdiri dari dua file sumber, lakukan 

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

Atau, gunakan glob untuk memfilter direktori testdata: 

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

Untuk memanfaatkan definisi ini, referensikan filegroup dengan label dari aturan apa pun: 

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
srcs

Daftar label; default adalah []

Daftar target yang merupakan anggota grup file.

Hasil ekspresi glob biasanya digunakan untuk nilai atribut srcs.

data

Daftar label; default adalah []

Daftar file yang diperlukan oleh aturan ini saat runtime.

Target yang disebutkan dalam atribut data akan ditambahkan ke runfiles dari aturan filegroup ini. Jika filegroup direferensikan dalam atribut data aturan lain, runfiles-nya akan ditambahkan ke runfiles dari aturan dependen. Lihat dependensi data dan dokumentasi umum data untuk mengetahui informasi selengkapnya tentang cara mengandalkan dan menggunakan file data.

output_group

String; default-nya adalah ""

Grup output yang digunakan untuk mengumpulkan artefak dari sumber. Jika atribut ini ditetapkan, artefak dari grup output yang ditentukan dari dependensi akan diekspor alih-alih grup {i>output<i} {i>default<i}.

"Grup output" adalah kategori artefak output dari target, yang ditentukan dalam penerapan aturan.

{i>genquery<i}

Lihat sumber aturan 
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() menjalankan kueri yang ditentukan dalam Bahasa kueri Bazel dan menghapus hasilnya menjadi file.

Agar build tetap konsisten, kueri hanya diizinkan membuka penutupan transitif target yang ditentukan dalam scope . Kueri yang melanggar aturan ini akan gagal selama eksekusi jika strict tidak ditentukan atau benar (jika strict salah, target di luar cakupan akan dilewati begitu saja dengan peringatan). Tujuan cara termudah untuk memastikan hal ini tidak terjadi adalah dengan menyebutkan label yang sama ke dalam cakupan seperti di ekspresi kueri.

Satu-satunya perbedaan antara kueri yang diizinkan di sini dan pada perintah adalah kueri yang berisi spesifikasi target karakter pengganti (mis. //pkg:* atau //pkg:all) tidak diizinkan di sini. Alasannya ada dua: pertama, karena genquery memiliki untuk menentukan cakupan guna mencegah target di luar penutupan transitif {i>query <i}untuk mempengaruhi {i>outputnya<i}; dan kedua, karena file BUILD tidak mendukung dependensi karakter pengganti (misalnya, deps=["//a/..."] tidak diizinkan).

Output genquery diurutkan secara leksikografis untuk menegakkan output deterministik, dengan pengecualian --output=graph|minrank|maxrank atau jika somepath digunakan sebagai fungsi tingkat atas.

Nama file output adalah nama aturan.

Contoh

Contoh ini menulis daftar label dalam penutupan transitif dari target yang ditentukan ke file. 

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
compressed_output

Boolean; default-nya adalah False

Jika True, output kueri ditulis dalam format file GZIP. Setelan ini dapat digunakan untuk menghindari lonjakan penggunaan memori Bazel ketika {i>output<i} kueri diperkirakan besar. Roti Bazel sudah secara internal mengompresi output kueri lebih besar dari 220 byte terlepas dari nilai setelan ini, jadi menetapkan ini ke True tidak dapat mengurangi nilai oleh sistem operasi heap. Namun, hal ini memungkinkan Bazel melewati dekompresi saat menulis file output, yang dapat menguras memori.
expression

String; wajib diisi

Kueri yang akan dieksekusi. Berbeda dengan baris perintah dan tempat lain dalam file BUILD, label di sini telah diselesaikan sesuai dengan direktori utama ruang kerja. Misalnya, label :b dalam atribut ini di file a/BUILD akan merujuk ke target //:b
opts

Daftar {i>string<i}; default-nya adalah []

Opsi yang diteruskan ke mesin kueri. Ini berhubungan dengan baris perintah opsi yang dapat diteruskan ke bazel query. Beberapa opsi kueri tidak diizinkan di sini: --keep_going, --query_file, --universe_scope, --order_results dan --order_output. Opsi tidak ditentukan di sini akan memiliki nilai defaultnya seperti pada command line bazel query.
scope

Daftar label; wajib diisi

Cakupan kueri. Kueri tidak diizinkan menyentuh target di luar transitif target akhir dari target ini.
strict

Boolean; default-nya adalah True

Jika true (benar), target yang kuerinya lolos dari penutupan transitif cakupannya akan gagal buat. Jika {i>false<i}, Bazel akan mencetak peringatan dan melewati jalur kueri apa pun yang mengarahkannya keluar dari ruang lingkup, sambil menyelesaikan sisa kueri.

Genrule

Lihat sumber aturan 
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 menghasilkan satu atau beberapa file menggunakan perintah Bash yang ditentukan pengguna.

Genrules adalah aturan build generik yang dapat Anda gunakan jika tidak ada aturan khusus untuk tugas tersebut. Misalnya, Anda dapat menjalankan satu baris Bash. Namun, jika Anda perlu mengompilasi file C++, ke aturan cc_* yang ada, karena semua bagian pekerjaan yang sulit telah dilakukan keamanan untuk Anda.

Perlu diperhatikan bahwa genrule memerlukan shell untuk menafsirkan argumen perintah. Juga mudah untuk mereferensikan program arbitrer yang tersedia di PATH, namun ini membuat perintah non-hermetik dan mungkin tidak dapat direproduksi. Jika Anda hanya perlu menjalankan satu alat, pertimbangkan untuk menggunakan run_binary sebagai gantinya.

Seperti tindakan lainnya, tindakan yang dibuat oleh genrules tidak boleh mengasumsikan apa pun tentang {i>working directory<i}; semua jaminan Bazel adalah bahwa input yang mereka nyatakan akan tersedia di jalur yang ditampilkan $(location) untuk labelnya. Misalnya, jika tindakan dijalankan dalam {i>sandbox <i}atau jarak jauh, implementasi {i>sandbox <i} atau eksekusi jarak jauh akan menentukan direktori kerja. Jika dijalankan secara langsung (menggunakan strategi standalone), performa akan menjadi root eksekusi, yaitu hasil dari bazel info execution_root.

Jangan gunakan genrule untuk menjalankan pengujian. Ada dispensasi khusus untuk tes dan tes hasil, termasuk kebijakan penyimpanan dalam cache dan variabel lingkungan. Pengujian umumnya perlu dijalankan setelah build selesai dan sesuai pada arsitektur target, sedangkan genrules dijalankan selama arsitektur build dan exec (keduanya mungkin berbeda). Jika Anda memerlukan tujuan umum aturan pengujian, gunakan sh_test.

Pertimbangan kompilasi silang

Lihat panduan pengguna untuk info selengkapnya tentang kompilasi silang.

Meskipun genrules berjalan selama build, outputnya sering kali digunakan setelah build, untuk deployment atau pengujian. Pertimbangkan contoh kompilasi kode C untuk mikrokontroler: compiler menerima C file sumber dan menghasilkan kode yang berjalan pada mikrokontroler. Kode yang dihasilkan jelas tidak dapat berjalan pada CPU yang digunakan untuk membangunnya, tetapi {i>compiler<i} C (jika dikompilasi dari sumber) itu sendiri.

Sistem build menggunakan konfigurasi exec untuk mendeskripsikan mesin tempat build berjalan dan konfigurasi target untuk mendeskripsikan mesin yang output build-nya yang seharusnya berjalan. Class ini menyediakan opsi untuk mengkonfigurasi masing-masing dan memisahkan file yang sesuai ke dalam direktori terpisah untuk menghindari konflik.

Untuk genrules, sistem build memastikan bahwa dependensi dibangun dengan tepat: srcs dibuat (jika perlu) untuk konfigurasi target, tools dibuat untuk konfigurasi exec, dan output-nya dianggap untuk konfigurasi target. Kode ini juga menyediakan "Buat" variabel yang dapat diteruskan oleh perintah genrule ke alat yang sesuai.

Secara sengaja, genrule menentukan tidak ada atribut deps: aturan bawaan lainnya menggunakan informasi meta yang bergantung pada bahasa yang diteruskan di antara aturan untuk secara otomatis menentukan cara menangani aturan dependen, tetapi tingkat otomatisasi seperti ini tidak mungkin dilakukan untuk genrules. Cara kerja genrules hanya di tingkat file dan {i>runfile<i}.

Kasus Khusus

Kompilasi eksekusi-exec: dalam beberapa kasus, sistem build perlu menjalankan genrules sedemikian rupa sehingga juga dapat dijalankan selama proses build. Misalnya, jika genrule membangun compiler kustom yang kemudian digunakan oleh genrule lain, yang pertama harus menghasilkan output-nya untuk {i>exec<i}, karena di situlah kompilator akan berjalan di genrule lain. Dalam kasus ini, sistem build melakukan hal yang benar secara otomatis: membangun srcs dan outs genrule pertama untuk konfigurasi exec, bukan target konfigurasi Anda. Lihat panduan pengguna untuk informasi selengkapnya info.

JDK & Alat C++: untuk menggunakan alat dari JDK atau rangkaian compiler C++, sistem build menyediakan seperangkat variabel untuk digunakan. Lihat "Merek" variabel untuk spesifikasi pendukung.

Lingkungan Genrule

Perintah genrule dijalankan oleh {i>shell Bash<i} yang dikonfigurasi untuk gagal saat sebuah perintah atau pipeline gagal, menggunakan set -e -o pipefail.

Alat {i>build<i} mengeksekusi perintah Bash dalam lingkungan proses yang bersih yang hanya menentukan variabel inti seperti PATH, PWD, TMPDIR, dan beberapa lainnya. Untuk memastikan bahwa build dapat direproduksi, sebagian besar variabel ditentukan dalam shell pengguna tidak diteruskan ke perintah genrule. Namun, Bazel (tapi tidak Blaze) meneruskan nilai variabel lingkungan PATH pengguna. Setiap perubahan pada nilai PATH akan menyebabkan Bazel menjalankan ulang perintah untuk build berikutnya.

Perintah {i>genrule<i} tidak boleh mengakses jaringan kecuali untuk menghubungkan proses yang turunan dari perintah itu sendiri, meskipun saat ini tidak diterapkan.

Sistem build akan otomatis menghapus semua file output yang ada, tetapi membuat file induk yang diperlukan direktori sebelum menjalankan suatu genrule. Alat ini juga menghapus file output jika terjadi kegagalan.

Saran Umum

  • Pastikan bahwa alat yang dijalankan dengan genrule bersifat determenistik dan hermetik. Mereka tidak boleh menulis stempel waktu ke outputnya, dan harus menggunakan pengurutan yang stabil untuk set dan peta, serta hanya menulis jalur file relatif ke {i>output<i}, tanpa jalur absolut. Jika aturan ini tidak diikuti, menyebabkan perilaku build yang tidak terduga (Bazel tidak membangun ulang genaturan yang Anda kira) dan menurunkan performa cache.
  • Gunakan $(location) secara ekstensif, untuk output, alat, dan sumber. Karena pemisahan file output untuk berbagai konfigurasi, genrules tidak dapat mengandalkan dan/atau absolut.
  • Tulis makro Starlark umum jika genrules yang sama atau sangat mirip digunakan di beberapa tempat. Jika genrule bersifat kompleks, pertimbangkan untuk menerapkannya dalam skrip atau sebagai Aturan Starlark. Hal ini meningkatkan keterbacaan dan kemampuan pengujian.
  • Pastikan bahwa kode keluar menunjukkan keberhasilan atau kegagalan genrule dengan benar.
  • Jangan menulis pesan informasi ke {i>stdout<i} atau {i>stderr<i}. Meskipun berguna untuk {i>debugging<i}, hal ini dapat mudah menjadi {i>noise<i}; pembuatan aturan yang berhasil harus dilakukan di diam. Di sisi lain, genrule yang gagal akan memunculkan pesan {i>error<i} yang baik.
  • $$ 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).
  • Hindari membuat symlink dan direktori. Bazel tidak menyalin direktori/symlink struktur yang dibuat oleh genrules dan pemeriksaan dependensinya terhadap direktori tidak terdengar.
  • Saat mereferensikan genrule di aturan lain, Anda bisa menggunakan label genrule atau label dari setiap file {i>output<i}. Kadang-kadang satu pendekatan lebih mudah dibaca, kadang-kadang other: mereferensikan output berdasarkan nama dalam srcs aturan yang memakai akan menghindari secara tidak sengaja mengambil {i>output<i} lain dari genrule, tetapi bisa melelahkan menghasilkan banyak {i>output<i}.

Contoh

Contoh ini menghasilkan foo.h. Tidak ada sumber, karena perintahnya tidak mengambil input apa pun. "Biner" yang dijalankan dengan perintah adalah skrip perl dalam paket yang sama dengan genrule. 

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

Contoh berikut menunjukkan cara menggunakan filegroup dan output genrule lainnya. Perlu diperhatikan bahwa menggunakan $(SRCS) sebagai gantinya direktif $(location) eksplisit juga akan berfungsi; contoh ini menggunakan yang terakhir untuk untuk demonstrasi. 

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) > $@",
)

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.


Anda dapat merujuk ke aturan ini berdasarkan nama di Bagian srcs atau deps dari BUILD lainnya aturan. Jika aturan membuat file sumber, Anda harus menggunakan metode Atribut srcs.
srcs

Daftar label; default adalah []

Daftar input untuk aturan ini, seperti file sumber yang akan diproses.

Atribut ini tidak cocok untuk mencantumkan alat yang dieksekusi oleh cmd; penggunaan atribut tools untuk keduanya.

Sistem build memastikan prasyarat ini dibangun sebelum menjalankan genrule perintah; dibangun menggunakan konfigurasi yang sama dengan permintaan {i>build <i}asli. Tujuan nama file prasyarat ini tersedia untuk perintah sebagai daftar yang dipisahkan spasi di $(SRCS); jalur seseorang Target //x:y srcs dapat diperoleh menggunakan $(location //x:y), atau menggunakan $< asalkan ini adalah satu-satunya entri di srcs.

outs

Daftar nama file; tidak dapat dikonfigurasi; wajib diisi

Daftar file yang dibuat oleh aturan ini.

File output tidak boleh melewati batas paket. Nama file output ditafsirkan sebagai relatif terhadap paket.

Jika tanda executable ditetapkan, outs harus berisi tepat satu label.

Perintah genrule diharapkan membuat setiap file output di lokasi yang telah ditentukan. Lokasi tersedia di cmd menggunakan Buat" khusus genrule variabel ($@, $(OUTS), $(@D), atau $(RULEDIR)) atau menggunakan Substitusi $(location).

cmd

String; default-nya adalah ""

Perintah yang akan dijalankan. Tunduk kepada $(location) dan "Buat" variabel.
  1. Penggantian $(location) pertama diterapkan, menggantikan semua kemunculan $(location label) dan $(locations label) (dan yang serupa konstruksi menggunakan variabel terkait execpath, execpaths, rootpath dan rootpaths).
  2. Berikutnya, "Buat" variabel diperluas. Perlu diketahui bahwa variabel yang telah ditetapkan $(JAVA), $(JAVAC), dan $(JAVABASE) diperluas di bawah konfigurasi exec, sehingga pemanggilan Java yang berjalan sebagai bagian dari langkah build dapat memuat pustaka bersama dan {i>library<i} lainnya dependensi.
  3. Akhirnya, perintah yang dihasilkan dieksekusi dengan menggunakan {i>shell Bash<i}. Jika exit code-nya adalah bukan nol, perintah itu dianggap gagal.
Ini adalah penggantian dari cmd_bash, cmd_ps, dan cmd_bat, jika tidak ada yang berlaku.

Jika panjang command line melebihi batas platform (64K di Linux/macOS, 8K di Windows), kemudian genrule akan menulis perintah ke suatu skrip dan mengeksekusi skrip itu untuk mengatasinya. Ini berlaku untuk semua atribut cmd (cmd, cmd_bash, cmd_ps, cmd_bat).

cmd_bash

String; default-nya adalah ""

Perintah Bash untuk dijalankan.

Atribut ini memiliki prioritas lebih tinggi daripada cmd. Perintah ini diperluas dan berjalan dengan cara yang sama persis dengan atribut cmd.

cmd_bat

String; default-nya adalah ""

Perintah Batch yang akan dijalankan di Windows.

Atribut ini memiliki prioritas lebih tinggi daripada cmd dan cmd_bash. Perintah ini berjalan dengan cara yang sama seperti atribut cmd, yaitu dengan perbedaan berikut:

  • Atribut ini hanya berlaku di Windows.
  • Perintah ini berjalan dengan cmd.exe /c dengan argumen default berikut:
    • /S - menghapus tanda kutip pertama dan terakhir, lalu mengeksekusi yang lainnya sebagaimana adanya.
    • /E:ON - mengaktifkan set perintah yang diperluas.
    • /V:ON - mengaktifkan perluasan variabel yang tertunda
    • /D - mengabaikan entri registry AutoRun.
  • Setelah $(location) dan "Buat" variabel, jalur akan diperluas ke jalur gaya Windows (dengan garis miring terbalik).
cmd_ps

String; default-nya adalah ""

Perintah Powershell untuk dijalankan di Windows.

Atribut ini memiliki prioritas lebih tinggi daripada cmd, cmd_bash, dan cmd_bat. Perintah berjalan dengan cara yang sama seperti cmd , dengan perbedaan berikut:

  • Atribut ini hanya berlaku di Windows.
  • Perintah ini dijalankan dengan powershell.exe /c.

Agar Powershell lebih mudah digunakan dan tidak rentan mengalami error, kami menjalankan untuk menyiapkan lingkungan sebelum mengeksekusi perintah Powershell di genrule.

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - izinkan lari skrip yang tidak ditandatangani.
  • $errorActionPreference='Stop' - Jika ada beberapa perintah dipisahkan oleh ;, tindakan akan segera keluar jika {i>Powershell CmdLet<i} gagal, tetapi ini TIDAK berfungsi untuk perintah eksternal.
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8' - mengubah default pengkodean dari utf-16 ke utf-8.
executable

Boolean; tidak dapat dikonfigurasi; default adalah False

Mendeklarasikan output agar dapat dieksekusi.

Menyetel tanda ini ke Benar (True) berarti outputnya adalah file yang dapat dieksekusi dan dapat dijalankan menggunakan Perintah run. Dalam hal ini, genrule harus menghasilkan tepat satu output. Jika atribut ini ditetapkan, run akan mencoba mengeksekusi file, terlepas dari kontennya.

Mendeklarasikan dependensi data untuk file yang dapat dieksekusi yang dihasilkan tidak didukung.
local

Boolean; default-nya adalah False

Jika disetel ke Benar (True), opsi ini akan memaksa genrule ini berjalan menggunakan metode "local" penting, yang berarti tidak ada eksekusi jarak jauh, tanpa sandbox, tanpa pekerja persisten.

Ini sama dengan menyediakan 'local' sebagai tag (tags=["local"]).

message

String; default-nya adalah ""

Pesan progres.

Pesan progres yang akan dicetak saat langkah build ini dijalankan. Secara default, pesan "Menghasilkan output" (atau sesuatu yang sama hambarnya), tetapi Anda dapat memberikan yang lebih spesifik. Gunakan atribut ini, bukan echo atau cetakan foto lainnya dalam perintah cmd, karena ini memungkinkan alat build mengontrol apakah pesan kemajuan tersebut akan dicetak atau tidak.

output_licenses

Jenis lisensi; default-nya adalah ["none"]

Lihat common attributes
output_to_bindir

Boolean; tidak dapat dikonfigurasi; default adalah False

Jika disetel ke Benar (True), opsi ini akan menyebabkan file output ditulis ke dalam bin bukan direktori genfiles.

tools

Daftar label; default adalah []

Daftar dependensi alat untuk aturan ini. Lihat definisi dependensi untuk informasi selengkapnya.

Sistem build memastikan prasyarat ini dibangun sebelum menjalankan perintah genrule; file dibuat menggunakan exec , karena alat ini dieksekusi sebagai bagian dari build. Jalur dari target tools individu //x:y dapat diperoleh menggunakan $(location //x:y).

Setiap *_binary atau alat yang akan dieksekusi oleh cmd harus muncul di bukan di srcs, untuk memastikan semuanya dibuat dalam konfigurasi yang benar.

starlark_doc_extract

Lihat sumber aturan 
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() mengekstrak dokumentasi untuk aturan dan fungsi (termasuk makro), aspek, dan penyedia yang ditentukan atau diekspor ulang dalam .bzl atau File .scl. Output aturan ini adalah proto biner ModuleInfo seperti yang ditentukan inci stardoc_output.proto dalam hierarki sumber Bazel.

Target output implisit

  • name.binaryproto (output default): A Protokol biner ModuleInfo.
  • name.textproto (hanya dibuat jika diminta secara eksplisit): teks versi proto name.binaryproto.

Peringatan: format output aturan ini tidak dijamin stabil. Ini terutama ditujukan untuk penggunaan internal oleh Stardoc.

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
deps

Daftar label; default adalah []

Daftar target yang menggabungkan file Starlark yang diberi load() src. Target tersebut harus dalam penggunaan normal bzl_library targetnya, tetapi aturan starlark_doc_extract tidak menerapkannya, dan menerima target apa pun yang menyediakan file Starlark dalam DefaultInfo-nya.

Perhatikan bahwa file Starlark yang digabungkan harus berupa file di hierarki sumber; Bazel tidak boleh load() file yang dibuat.

src

Label; wajib diisi

File Starlark yang digunakan untuk mengekstrak dokumentasi.

Perhatikan bahwa ini harus berupa file dalam hierarki sumber; Bazel tidak boleh load() file yang dihasilkan.

render_main_repo_name

Boolean; default-nya adalah False

Jika benar, render label di repositori utama dalam dokumentasi yang dimunculkan dengan komponen repo (dengan kata lain, //foo:bar.bzl akan ditampilkan sebagai @main_repo_name//foo:bar.bzl).

Nama yang akan digunakan untuk repositori utama diperoleh dari module(name = ...) di file MODULE.bazel repositori utama (jika Bzlmod diaktifkan), atau dari workspace(name = ...) dalam file WORKSPACE repositori utama.

Atribut ini harus ditetapkan ke False saat membuat dokumentasi untuk File Starlark yang dimaksudkan untuk digunakan hanya di dalam repositori yang sama, dan untuk True saat membuat dokumentasi untuk file Starlark yang dimaksudkan untuk digunakan dari repositori lain.

symbol_names

Daftar {i>string<i}; default-nya adalah []

Daftar opsional nama-nama yang memenuhi syarat dari fungsi, aturan, penyedia, atau aspek yang diekspor (atau struktur tempat mereka disusun bertingkat) untuk mengekstrak dokumentasi. Di sini, instance kualifikasi name berarti nama tempat entity tersedia untuk pengguna modul, termasuk semua struct tempat entity disarangkan untuk namespace.

starlark_doc_extract memberikan dokumentasi untuk entity jika dan hanya jika

  1. setiap komponen nama entitas yang memenuhi syarat bersifat publik (dengan kata lain, karakter setiap komponen nama yang memenuhi syarat adalah abjad, bukan "_"); dan
    1. salah satu daftar symbol_names kosong (yang merupakan default kasus), atau
    2. nama entitas yang memenuhi syarat, atau nama struct tempat entitas bertingkat, berada dalam daftar symbol_names.

test_suite

Lihat sumber aturan 
test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite menentukan kumpulan pengujian yang dianggap "berguna" manusia. Ini mengizinkan project untuk mendefinisikan rangkaian pengujian, seperti "pengujian yang harus Anda jalankan sebelum checkin", " {i>stress test<i} suatu proyek" atau “semua pengujian kecil.” Perintah bazel test mengikuti pengurutan ini organisasi: Untuk pemanggilan seperti bazel test //some/test:suite, Bazel terlebih dahulu menghitung semua target pengujian yang disertakan secara transitif oleh target //some/test:suite (kami sebut "ekspansi test_suite"), lalu Bazel akan membangun dan menguji target tersebut.

Contoh

Paket pengujian untuk menjalankan semua pengujian kecil dalam paket saat ini.

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

Paket pengujian yang menjalankan serangkaian pengujian tertentu:

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

Paket pengujian untuk menjalankan semua pengujian dalam paket saat ini yang tidak stabil.

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

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
tags

Daftar {i>string<i}; tidak dapat dikonfigurasi; default adalah []

Daftar tag teks, seperti "small" atau "database" atau "-tidak stabil". Tag dapat berupa string yang valid.

Tag yang diawali dengan "-" karakter, dianggap sebagai tag negatif. Tujuan sebelum "-" tidak dianggap sebagai bagian dari tag, jadi tag suite dari "-small" cocok dengan "small" pengujian ukuran. Semua tag lainnya dianggap tag positif.

Atau, untuk membuat tag positif lebih eksplisit, tag juga dapat diawali dengan "+" , yang tidak akan dievaluasi sebagai bagian dari teks tag. Ini hanya membuat perbedaan positif dan negatif lebih mudah dibaca.

Hanya uji aturan yang cocok dengan semua tag positif dan tidak satu pun tag negatif yang baru akan disertakan dalam paket pengujian. Perhatikan bahwa ini bukan berarti bahwa pemeriksaan {i>error<i} untuk dependensi pada pengujian yang difilter akan dilewati; dependensi yang dilewati pengujian tetap harus legal (mis. tidak diblokir oleh batasan visibilitas).

Kata kunci tag manual diperlakukan secara berbeda dengan yang di atas oleh "perluasan test_suite" dilakukan oleh perintah bazel test pada pemanggilan melibatkan karakter pengganti pola target. Di sana, test_suite menargetkan dengan tag "manual" disaring (dan dengan demikian tidak diperluas). Perilaku ini konsisten dengan cara bazel build dan bazel test menangani pola target karakter pengganti secara umum. Perhatikan bahwa ini adalah secara eksplisit berbeda dari perilaku bazel query 'tests(E)', karena suite selalu diperluas oleh fungsi kueri tests, terlepas dari tag manual.

Perhatikan bahwa size pengujian dianggap sebagai tag untuk tujuan pemfilteran.

Jika Anda memerlukan test_suite yang berisi pengujian dengan tag yang saling eksklusif (misalnya, semua pengujian kecil dan menengah), Anda harus membuat tiga test_suite aturan: satu untuk semua pengujian kecil, satu untuk semua pengujian sedang, dan satu lagi yang mencakup dua pertanyaan sebelumnya.

tests

Daftar label; tidak dapat dikonfigurasi; defaultnya adalah []

Daftar rangkaian pengujian dan target pengujian dari bahasa apa pun.

Semua *_test diterima di sini, apa pun bahasanya. Lain kali Namun, *_binary target diterima, meskipun kebetulan target tersebut menjalankan pengujian. Pemfilteran berdasarkan tags yang ditentukan hanya dilakukan untuk pengujian yang tercantum langsung di atribut ini. Jika atribut ini berisi test_suite, pengujian di dalam ini tidak akan difilter oleh test_suite ini (mereka dianggap sudah difilter).

Jika atribut tests tidak ditentukan atau kosong, aturan akan ditetapkan secara default ke menyertakan semua aturan pengujian di file BUILD saat ini yang tidak diberi tag manual. Aturan ini masih tunduk pada pemfilteran tag.