Peraturan Umum

Laporkan masalah Lihat sumber Nightly · 7.4 . 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.

Alias hanya berfungsi untuk target "biasa". Secara khusus, package_group dan test_suite tidak dapat diberi alias.

Aliasing dapat sangat membantu pada repositori besar di mana mengganti nama target akan memerlukan perubahan pada banyak file. Anda juga dapat menggunakan aturan alias untuk menyimpan panggilan fungsi select jika Anda ingin menggunakan kembali logika tersebut untuk beberapa target.

Aturan alias memiliki deklarasi visibilitasnya sendiri. Dalam hal lainnya, alias ini berperilaku seperti aturan yang dirujuknya (misalnya, testonly di alias diabaikan; sifat testonly dari aturan yang dirujuk akan digunakan) dengan beberapa pengecualian kecil:

  • Pengujian tidak akan dijalankan jika aliasnya disebutkan di command line. Untuk menentukan alias yang menjalankan pengujian yang dirujuk, gunakan aturan test_suite dengan satu target dalam atribut tests nya.
  • Saat menentukan grup lingkungan, alias ke aturan environment tidak didukung. Opsi tersebut juga tidak didukung dalam opsi command line --target_environment.

Contoh

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

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

Argumen

Atribut
name

Nama; wajib

Nama unik untuk target ini.
actual

Label; wajib diisi

Target yang dirujuk oleh alias ini. Tidak harus berupa aturan, tetapi juga dapat berupa file input.

config_setting

Melihat 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 tujuan memicu atribut yang dapat dikonfigurasi. Lihat select untuk mengetahui cara menggunakan aturan ini dan Atribut yang dapat dikonfigurasi untuk mengetahui ringkasan fitur umum.

Contoh

Kode berikut 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"}
  )

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

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

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 file .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 menentukan nilai batasan tambahan di luar dua nilai ini. 

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
Dalam semua kasus ini, konfigurasi dapat berubah dalam build, misalnya jika target perlu di-build untuk platform yang berbeda dengan dependensinya. Artinya, meskipun config_setting tidak cocok dengan flag command line tingkat teratas, config_setting mungkin masih cocok dengan beberapa target build.

Catatan

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

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

  • Jika Anda perlu menentukan kondisi yang tidak dimodelkan oleh flag build bawaan, gunakan flag yang ditentukan Starlark. Anda juga dapat menggunakan --define, tetapi cara ini menawarkan dukungan yang lebih lemah dan tidak direkomendasikan. Lihat di sini untuk diskusi lebih lanjut.
  • Hindari mengulangi 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 di config_setting yang sama, tetapi setidaknya satu harus ditetapkan untuk config_setting tertentu.

Argumen

Atribut
name

Nama; wajib

Nama unik untuk target ini.
constraint_values

Daftar label; tidak dapat dikonfigurasi; defaultnya adalah []

Kumpulan minimum constraint_values yang harus ditentukan 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, atribut ini tidak dipertimbangkan untuk tujuan menentukan apakah salah satu config_setting merupakan spesialisasi dari yang lain. Dengan kata lain, satu config_setting tidak dapat mencocokkan platform dengan lebih kuat daripada yang lain.

define_values

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

Sama seperti values, tetapi khusus untuk flag --define.

--define bersifat khusus karena sintaksisnya (--define KEY=VAL) berarti KEY=VAL adalah nilai dari perspektif flag 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 dalam kamus. Atribut ini mengatasi 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 digabungkan secara bebas dengan atribut ini selama kunci kamus tetap berbeda.

flag_values

Kamus: label -> String; nonconfigurable; defaultnya adalah {}

Sama seperti values, tetapi untuk flag build yang ditentukan pengguna.

Ini adalah atribut yang berbeda karena flag yang ditentukan pengguna direferensikan sebagai label, sedangkan flag bawaan direferensikan sebagai string arbitrer.

values

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

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

Aturan ini mewarisi konfigurasi target yang dikonfigurasi yang mereferensikannya dalam pernyataan select. Ini dianggap "cocok" dengan pemanggilan Bazel jika, untuk setiap entri dalam kamus, konfigurasinya 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.

Untuk memudahkan, nilai konfigurasi ditentukan sebagai flag build (tanpa "--" sebelumnya). Namun, perlu diingat bahwa keduanya tidak sama. Hal ini karena target dapat dibuat dalam beberapa konfigurasi dalam build yang sama. Misalnya, "cpu" konfigurasi exec cocok dengan nilai --host_cpu, bukan --cpu. Jadi, berbagai instance dari 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 mereferensikan flag yang dapat ditetapkan beberapa kali di command line (misalnya, bazel build --copt=foo --copt=bar --copt=baz ...), pencocokan akan terjadi jika salah satu setelan tersebut cocok.

filegroup

Melihat 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 memberikan nama yang mudah ke kumpulan target. Kemudian, aturan ini dapat dirujuk dari aturan lain.

Sebaiknya gunakan filegroup, bukan mereferensikan direktori secara langsung. Yang terakhir tidak valid karena sistem build tidak memiliki pengetahuan penuh tentang semua file di bawah direktori, sehingga mungkin tidak membangun ulang saat file ini berubah. Jika digabungkan dengan glob, filegroup dapat memastikan bahwa semua file diketahui secara eksplisit oleh sistem build.

Contoh

Untuk membuat filegroup yang terdiri dari dua file sumber, lakukan 

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

Atau, gunakan glob untuk menelusuri direktori testdata: 

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

Untuk menggunakan 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

Nama unik untuk target ini.
srcs

Daftar label; default-nya adalah []

Daftar target yang merupakan anggota grup file.

Hasil ekspresi glob biasa digunakan untuk nilai atribut srcs.

data

Daftar label; default-nya adalah []

Daftar file yang diperlukan oleh aturan ini saat runtime.

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

output_group

String; defaultnya adalah ""

Grup output tempat artefak dikumpulkan dari sumber. Jika atribut ini ditentukan, artefak dari grup output dependensi yang ditentukan akan diekspor, bukan grup output default.

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

{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 Blaze dan membuang hasilnya ke dalam file.

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

Satu-satunya perbedaan antara kueri yang diizinkan di sini dan command line adalah kueri yang berisi spesifikasi target karakter pengganti (misalnya, //pkg:* atau //pkg:all) tidak diizinkan di sini. Alasannya ada dua: pertama, karena genquery harus menentukan cakupan untuk mencegah target di luar penutupan transitif kueri memengaruhi outputnya; dan, kedua, karena file BUILD tidak mendukung dependensi karakter pengganti (misalnya, deps=["//a/..."] tidak diizinkan).

Output genquery diurutkan secara leksikografis untuk menerapkan output deterministik, kecuali --output=graph|minrank|maxrank atau saat somepath digunakan sebagai fungsi tingkat teratas.

Nama file output adalah nama aturan.

Contoh

Contoh ini menulis daftar label dalam penutupan transitif 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 jika output kueri diperkirakan berukuran besar. Bazel sudah mengompresi output kueri secara internal yang lebih besar dari 220 byte, terlepas dari nilai setelan ini, sehingga menyetelnya ke True mungkin tidak mengurangi heap yang dipertahankan. Namun, cara ini memungkinkan Bazel melewati dekompresi saat menulis file output, yang dapat menghabiskan banyak memori.
expression

String; wajib

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

Daftar string; default-nya adalah []

Opsi yang diteruskan ke mesin kueri. Hal ini sesuai dengan opsi command line 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 yang tidak ditentukan di sini akan memiliki nilai defaultnya seperti pada command line bazel query.
scope

Daftar label; wajib diisi

Cakupan kueri. Kueri tidak diizinkan untuk menyentuh target di luar penutupan transitif target ini.
strict

Boolean; default-nya adalah True

Jika benar, target yang kuerinya keluar dari penutupan transitif cakupannya akan gagal di-build. Jika salah, Bazel akan mencetak peringatan dan melewati jalur kueri apa pun yang mengarahkannya ke luar cakupan, sambil menyelesaikan kueri lainnya.

genrule

Melihat 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. Misalnya, Anda dapat menjalankan satu baris Bash. Namun, jika Anda perlu mengompilasi file C++, ikuti aturan cc_* yang ada, karena semua pekerjaan berat telah dilakukan untuk Anda.

Perhatikan bahwa genrule memerlukan shell untuk menafsirkan argumen perintah. Mereferensikan program arbitrer yang tersedia di PATH juga mudah, tetapi hal ini membuat perintah menjadi tidak hermetis dan mungkin tidak dapat direproduksi. Jika Anda hanya perlu menjalankan satu alat, sebaiknya gunakan run_binary sebagai gantinya.

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

Pertimbangan kompilasi silang

Lihat panduan pengguna untuk mengetahui info selengkapnya tentang kompilasi silang.

Saat genrules berjalan selama build, output-nya sering digunakan setelah build, untuk deployment atau pengujian. Pertimbangkan contoh kompilasi kode C untuk mikrokontroler: compiler menerima file sumber C dan menghasilkan kode yang berjalan pada mikrokontroler. Kode yang dihasilkan jelas tidak dapat berjalan di CPU yang digunakan untuk mem-build-nya, tetapi compiler C (jika dikompilasi dari sumber) itu sendiri harus.

Sistem build menggunakan konfigurasi exec untuk mendeskripsikan mesin tempat build berjalan dan konfigurasi target untuk mendeskripsikan mesin tempat output build seharusnya dijalankan. Alat ini menyediakan opsi untuk mengonfigurasi setiap opsi tersebut dan memisahkan file yang sesuai ke dalam direktori terpisah untuk menghindari konflik.

Untuk genrules, sistem build memastikan bahwa dependensi di-build dengan benar: srcs di-build (jika diperlukan) untuk konfigurasi target, tools di-build untuk konfigurasi exec, dan output dianggap untuk konfigurasi target. Alat ini juga menyediakan variabel "Make" yang dapat diteruskan perintah genrule ke alat yang sesuai.

Genrule sengaja tidak menentukan atribut deps: aturan bawaan lainnya menggunakan informasi meta dependen bahasa yang diteruskan di antara aturan untuk secara otomatis menentukan cara menangani aturan dependen, tetapi tingkat otomatisasi ini tidak dapat dilakukan untuk genrule. Genrules berfungsi sepenuhnya di tingkat file dan runfile.

Kasus Khusus

Kompilasi eksekusi-exec: dalam beberapa kasus, sistem build perlu menjalankan genrules sehingga output juga dapat dijalankan selama proses build. Misalnya, jika genrule mem-build beberapa compiler kustom yang kemudian digunakan oleh genrule lain, genrule pertama harus menghasilkan outputnya untuk konfigurasi exec, karena di sana compiler akan berjalan di genrule lain. Dalam hal ini, sistem build melakukan hal yang benar secara otomatis: sistem build membuat srcs dan outs dari genrule pertama untuk konfigurasi exec, bukan konfigurasi target. Lihat panduan pengguna untuk info selengkapnya.

JDK & Alat C++: untuk menggunakan alat dari JDK atau suite compiler C++, sistem build menyediakan serangkaian variabel yang akan digunakan. Lihat Variabel"Make" untuk mengetahui detailnya.

Lingkungan Genrule

Perintah genrule dijalankan oleh shell Bash yang dikonfigurasi untuk gagal saat perintah atau pipeline gagal, menggunakan set -e -o pipefail.

Alat build mengeksekusi perintah Bash di lingkungan proses yang dibersihkan yang hanya menentukan variabel inti seperti PATH, PWD, TMPDIR, dan beberapa lainnya. Untuk memastikan bahwa build dapat direproduksi, sebagian besar variabel yang ditentukan di lingkungan shell pengguna tidak diteruskan ke perintah genrule. Namun, Bazel (tetapi tidak Blaze) meneruskan nilai variabel lingkungan PATH pengguna. Setiap perubahan pada nilai PATH akan menyebabkan Bazel mengeksekusi ulang perintah pada build berikutnya.

Perintah genrule tidak boleh mengakses jaringan kecuali untuk menghubungkan proses yang merupakan turunan dari perintah itu sendiri, meskipun saat ini hal ini tidak diterapkan.

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

Saran Umum

  • Pastikan bahwa alat yang dijalankan dengan genrule bersifat determenistik dan hermetik. Fungsi ini tidak boleh menulis stempel waktu ke output, dan harus menggunakan pengurutan yang stabil untuk set dan peta, serta hanya menulis jalur file relatif ke output, tidak ada jalur absolut. Tidak mengikuti aturan ini akan menyebabkan perilaku build yang tidak terduga (Bazel tidak mem-build ulang genrule yang Anda harapkan) dan menurunkan performa cache.
  • Gunakan $(location) secara ekstensif, untuk output, alat, dan sumber. Karena pemisahan file output untuk konfigurasi yang berbeda, genrules tidak dapat mengandalkan jalur absolut dan/atau hard code.
  • Tulis makro Starlark umum jika genrule 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 serta kemudahan pengujian.
  • Pastikan bahwa kode keluar menunjukkan keberhasilan atau kegagalan genrule dengan benar.
  • Jangan menulis pesan informasi ke stdout atau stderr. Meskipun berguna untuk proses debug, hal ini dapat dengan mudah menjadi derau; genrule yang berhasil akan diam. Di sisi lain, genrule yang gagal akan menampilkan pesan error 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 struktur direktori/symlink yang dibuat oleh genrules dan pemeriksaan dependensi direktorinya tidak valid.
  • Saat mereferensikan genrule dalam aturan lain, Anda dapat menggunakan label genrule atau label setiap file output. Terkadang satu pendekatan lebih mudah dibaca, terkadang yang lain: mereferensikan output berdasarkan nama di srcs aturan yang menggunakan akan menghindari mengambil output genrule lainnya secara tidak sengaja, tetapi dapat merepotkan jika genrule menghasilkan banyak output.

Contoh

Contoh ini menghasilkan foo.h. Tidak ada sumber, karena perintah tidak mengambil input apa pun. "Biner" yang dijalankan oleh 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. Perhatikan bahwa menggunakan $(SRCS), bukan perintah $(location) eksplisit, juga akan berfungsi; contoh ini menggunakan perintah $(location) eksplisit 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 namanya di bagian srcs atau deps dari aturan BUILD lainnya. Jika aturan menghasilkan file sumber, Anda harus menggunakan atribut srcs.
srcs

Daftar label; default-nya adalah []

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

Atribut ini tidak cocok untuk mencantumkan alat yang dieksekusi oleh cmd; gunakan atribut tools untuk alat tersebut.

Sistem build memastikan prasyarat ini di-build sebelum menjalankan perintah genrule; prasyarat ini di-build menggunakan konfigurasi yang sama dengan permintaan build asli. Nama file prasyarat ini tersedia untuk perintah sebagai daftar yang dipisahkan spasi di $(SRCS); atau, jalur setiap srcs target //x:y dapat diperoleh menggunakan $(location //x:y), atau menggunakan $< asalkan itu adalah satu-satunya entri di srcs.

outs

Daftar nama file; tidak dapat dikonfigurasi; wajib

Daftar file yang dihasilkan 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 variabel "Make" khusus genrule ($@, $(OUTS), $(@D), atau $(RULEDIR)) atau menggunakan penggantian $(location).

cmd

String; defaultnya adalah ""

Perintah yang akan dijalankan. Tunduk pada substitusi $(location) dan variabel"Make".
  1. Penggantian $(location) pertama diterapkan, yang menggantikan semua kemunculan $(location label) dan $(locations label) (dan konstruksi serupa menggunakan variabel terkait execpath, execpaths, rootpath, dan rootpaths).
  2. Selanjutnya, variabel"Make" diperluas. Perhatikan bahwa variabel standar $(JAVA), $(JAVAC), dan $(JAVABASE) diperluas dalam konfigurasi exec, sehingga pemanggilan Java yang berjalan sebagai bagian dari langkah build dapat memuat library bersama dan dependensi lainnya dengan benar.
  3. Terakhir, perintah yang dihasilkan dieksekusi dengan menggunakan {i>shell Bash<i}. Jika exit code bukan nol, perintah tersebut dianggap gagal.
Ini adalah penggantian 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), genrule akan menulis perintah ke skrip dan mengeksekusi skrip tersebut untuk mengatasinya. Hal ini berlaku untuk semua atribut cmd (cmd, cmd_bash, cmd_ps, cmd_bat).

cmd_bash

String; defaultnya adalah ""

Perintah Bash untuk dijalankan.

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

cmd_bat

String; default-nya adalah ""

Perintah Batch yang akan dijalankan di Windows.

Atribut ini memiliki prioritas yang lebih tinggi daripada cmd dan cmd_bash. Perintah ini berjalan dengan cara yang mirip dengan atribut cmd, 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 dan mengeksekusi semua yang lain apa adanya.
    • /E:ON - mengaktifkan kumpulan perintah yang diperluas.
    • /V:ON - mengaktifkan perluasan variabel tertunda
    • /D - mengabaikan entri registry AutoRun.
  • Setelah penggantian $(location) dan variabel "Make", jalur akan diperluas ke jalur gaya Windows (dengan garis miring terbalik).
cmd_ps

String; default-nya adalah ""

Perintah Powershell yang akan dijalankan di Windows.

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

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

Agar Powershell lebih mudah digunakan dan tidak rentan terhadap error, kita menjalankan perintah berikut untuk menyiapkan lingkungan sebelum menjalankan perintah Powershell di genrule.

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - mengizinkan berjalannya skrip yang tidak ditandatangani.
  • $errorActionPreference='Stop' - Jika ada beberapa perintah yang dipisahkan oleh ;, tindakan ini akan langsung keluar jika Powershell CmdLet gagal, tetapi ini TIDAK berfungsi untuk perintah eksternal.
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8' - mengubah encoding default dari utf-16 menjadi utf-8.
executable

Boolean; tidak dapat dikonfigurasi; defaultnya adalah False

Mendeklarasikan output agar dapat dieksekusi.

Menetapkan tanda ini ke Benar (True) berarti output 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, apa pun 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 strategi "lokal", yang berarti tidak ada eksekusi jarak jauh, tidak ada sandbox, tidak ada pekerja persisten.

Hal ini setara dengan memberikan 'local' sebagai tag (tags=["local"]).

message

String; default-nya adalah ""

Pesan progres.

Pesan progres yang akan dicetak saat langkah build ini dijalankan. Secara default, pesannya adalah "Membuat output" (atau sesuatu yang sama-sama tidak menarik), tetapi Anda dapat memberikan pesan yang lebih spesifik. Gunakan atribut ini, bukan echo atau pernyataan cetak lainnya dalam perintah cmd Anda, karena hal ini memungkinkan alat build mengontrol apakah pesan progres tersebut dicetak atau tidak.

output_licenses

Jenis lisensi; defaultnya adalah ["none"]

Lihat common attributes
output_to_bindir

Boolean; tidak dapat dikonfigurasi; defaultnya adalah False

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

tools

Daftar label; default-nya adalah []

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

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

Setiap *_binary atau alat yang akan dieksekusi oleh cmd harus muncul dalam daftar ini, bukan di srcs, untuk memastikan alat tersebut di-build 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, fungsi (termasuk makro), aspek, dan penyedia yang ditentukan atau diekspor ulang dalam file .bzl atau .scl tertentu. Output aturan ini adalah proto biner ModuleInfo seperti yang ditentukan dalam stardoc_output.proto di hierarki sumber Bazel.

Target output implisit

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

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

Argumen

Atribut
name

Nama; wajib

Nama unik untuk target ini.
deps

Daftar label; default-nya adalah []

Daftar target yang menggabungkan file Starlark yang load()-ed oleh src. Target tersebut harus dalam penggunaan normal menjadi target bzl_library, tetapi aturan starlark_doc_extract tidak menerapkannya, dan menerima semua target yang menyediakan file Starlark dalam DefaultInfo-nya.

Perhatikan bahwa file Starlark yang digabungkan harus berupa file dalam hierarki sumber; Bazel tidak dapat file yang dihasilkan load().

src

Label; wajib diisi

File Starlark yang akan diekstrak dokumentasinya.

Perhatikan bahwa ini harus berupa file dalam hierarki sumber; Bazel tidak dapat membuat file load().

render_main_repo_name

Boolean; defaultnya adalah False

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

Nama yang akan digunakan untuk repositori utama diperoleh dari module(name = ...) dalam 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 dalam repositori yang sama, dan ke True saat membuat dokumentasi untuk file Starlark yang dimaksudkan untuk digunakan dari repositori lain.

symbol_names

Daftar string; default-nya adalah []

Daftar opsional nama yang memenuhi syarat dari fungsi, aturan, penyedia, atau aspek yang diekspor (atau struct tempat fungsi, aturan, penyedia, atau aspek tersebut disusun bertingkat) yang akan diekstrak dokumentasinya. Di sini, nama yang memenuhi syarat berarti nama tempat entitas disediakan untuk pengguna modul, termasuk struct tempat entitas disusun bertingkat untuk penataan nama.

starlark_doc_extract memunculkan dokumentasi untuk entity jika dan hanya jika

  1. setiap komponen nama yang memenuhi syarat entity bersifat publik (dengan kata lain, karakter pertama dari setiap komponen nama yang memenuhi syarat adalah alfabet, bukan "_"); dan
    1. baik daftar symbol_names kosong (yang merupakan kasus default), atau
    2. nama entity yang memenuhi syarat, atau nama struct tempat entity disusun bertingkat, tercantum 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 serangkaian pengujian yang dianggap "berguna" bagi manusia. Hal ini memungkinkan project menentukan kumpulan pengujian, seperti "pengujian yang harus Anda jalankan sebelum checkin", "pengujian stres project kami", atau "semua pengujian kecil". Perintah blaze test mengikuti jenis pengaturan ini: Untuk pemanggilan seperti blaze test //some/test:suite, Blaze pertama-tama menguraikan semua target pengujian yang disertakan secara transitif oleh target //some/test:suite (kita menyebutnya "ekspansi test_suite"), lalu Blaze mem-build dan menguji target tersebut.

Contoh

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

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

Rangkaian pengujian yang menjalankan serangkaian pengujian yang ditentukan:

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

Rangkaian pengujian untuk menjalankan semua pengujian dalam paket saat ini yang tidak bermasalah.

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

Argumen

Atribut
name

Nama; wajib diisi

Nama unik untuk target ini.
tags

Daftar string; tidak dapat dikonfigurasi; default-nya adalah []

Daftar tag teks seperti "small" atau "database" atau "-flaky". Tag dapat berupa string apa pun yang valid.

Tag yang dimulai dengan karakter "-" dianggap sebagai tag negatif. Karakter "-" sebelumnya tidak dianggap sebagai bagian dari tag, sehingga tag suite "-small" cocok dengan ukuran "small" pengujian. Semua tag lainnya dianggap sebagai tag positif.

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

Hanya aturan pengujian yang cocok dengan semua tag positif dan tidak ada tag negatif yang akan disertakan dalam rangkaian pengujian. Perhatikan bahwa hal ini tidak berarti bahwa pemeriksaan error untuk dependensi pada pengujian yang difilter akan dilewati; dependensi pada pengujian yang dilewati masih harus sah (misalnya, tidak diblokir oleh batasan visibilitas).

Kata kunci tag manual diperlakukan secara berbeda dari yang di atas oleh "ekspansi test_suite" yang dilakukan oleh perintah blaze test pada pemanggilan yang melibatkan pola target karakter pengganti. Di sana, target test_suite yang diberi tag "manual" akan difilter (sehingga tidak diperluas). Perilaku ini konsisten dengan cara blaze build dan blaze test menangani pola target karakter pengganti secara umum. Perhatikan bahwa ini secara eksplisit berbeda dengan perilaku blaze 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 sama-sama eksklusif (mis. semua pengujian kecil dan menengah), Anda harus membuat tiga aturan test_suite: satu untuk semua pengujian kecil, satu untuk semua pengujian sedang, dan satu yang menyertakan dua pengujian sebelumnya.

tests

Daftar label; tidak dapat dikonfigurasi; default-nya adalah []

Daftar suite pengujian dan target pengujian dari bahasa apa pun.

Semua *_test diterima di sini, terlepas dari bahasanya. Namun, tidak ada target *_binary yang diterima, meskipun target tersebut kebetulan menjalankan pengujian. Pemfilteran berdasarkan tags yang ditentukan hanya dilakukan untuk pengujian yang dicantumkan langsung dalam atribut ini. Jika atribut ini berisi test_suite, pengujian di dalamnya tidak akan difilter oleh test_suite ini (pengujian dianggap sudah difilter).

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