BazelCon 2022 akan hadir pada 16-17 November ke New York dan online.
Daftar sekarang.

Aturan Umum

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Aturan

alias

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

Aturan alias membuat nama lain yang dapat disebut sebagai aturan.

Alias hanya berfungsi untuk target "reguler" Secara khusus, package_group dan test_suite tidak dapat di-aliasi.

Aturan alias memiliki deklarasi visibilitas sendiri. Dalam semua hal lain, aturan ini berperilaku seperti aturan yang direferensikan (misalnya, hanya pengujian pada alias yang diabaikan; properti hanya-pengujian dari aturan yang direferensikan digunakan) dengan beberapa pengecualian kecil:

  • Pengujian tidak berjalan jika aliasnya disebutkan pada command line. Untuk menentukan alias yang menjalankan pengujian yang direferensikan, gunakan aturan test_suite dengan satu target dalam atribut tests-nya.
  • Saat menentukan grup lingkungan, alias ke aturan environment tidak didukung. Keduanya juga tidak didukung dalam opsi command line --target_environment.

Contoh

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

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

Argumen

Atribut
name

Name; required

Nama unik untuk target ini.

actual

Label; required

Target yang dirujuk alias ini. Format ini tidak harus berupa aturan, tetapi juga dapat berupa file input.

setelan_konfigurasi

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 pilih untuk mengetahui cara menggunakan aturan ini dan Atribut yang dapat dikonfigurasi untuk ringkasan fitur umum.

Contoh

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

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

Berikut adalah setiap build yang menargetkan ARM dan menerapkan FOO=bar yang ditentukan secara kustom (misalnya bazel build --cpu=arm --define FOO=bar ...):

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

Berikut ini cocok dengan semua build yang menetapkan tanda yang ditentukan pengguna --//custom_flags:foo=1 (baik secara eksplisit di command line atau secara implisit dari file .bazelrc):

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

Berikut ini cocok dengan semua build 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 nilai batasan tambahan selain keduanya.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  
Dalam semua kasus ini, kemungkinan konfigurasi dapat berubah dalam build, misalnya jika target perlu dibuat untuk platform yang berbeda dari dependensinya. Ini berarti bahwa meskipun config_setting tidak cocok dengan flag command line level teratas, mungkin tetap cocok dengan beberapa target build.

Catatan

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

    values = { "myflag": "a,b" } bekerja 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 di antara flag. 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 yang kedua). Namun, --ios_multi_cpus (untuk aturan Apple) memang: -ios_multi_cpus=a,b dan ios_multi_cpus=a --ios_multi_cpus=b sama-sama menghasilkan ["a", "b"]. Periksa 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 ini menawarkan dukungan yang lebih lemah dan tidak direkomendasikan. Lihat di sini untuk pembahasan lebih lanjut.
  • Hindari mengulangi definisi config_setting yang identik dalam paket yang berbeda. Sebagai gantinya, rujuk 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 satu harus ditetapkan untuk setiap config_setting tertentu.

Argumen

Atribut
name

Name; required

Nama unik untuk target ini.

constraint_values

List of labels; optional; nonconfigurable

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

Jika dua config_setting cocok dalam select yang sama, atribut ini tidak dipertimbangkan untuk tujuan penentuan apakah salah satu config_setting adalah spesialisasi yang lain. Dengan kata lain, satu config_setting tidak boleh lebih cocok dengan platform daripada yang lain.

define_values

Dictionary: String -> String; optional; nonconfigurable

Sama seperti values tetapi khusus untuk flag --define.

--define bersifat spesial 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 tetap dapat muncul di values dengan sintaksis flag normal, dan dapat digabungkan secara bebas dengan atribut ini selama kunci kamus tetap berbeda.

flag_values

Dictionary: label -> String; optional; nonconfigurable

Sama seperti values, tetapi untuk flag build buatan pengguna.

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

values

Dictionary: String -> String; optional; nonconfigurable

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

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

Demi kenyamanan, nilai konfigurasi ditentukan sebagai flag build (tanpa "--" sebelumnya). Namun, perlu diingat bahwa keduanya tidak sama. Hal ini karena target dapat dibuat di beberapa konfigurasi dalam build yang sama. Misalnya, konfigurasi host "cpu" cocok dengan nilai --host_cpu, bukan --cpu. Jadi, instance yang berbeda dari config_setting yang sama mungkin cocok dengan pemanggilan yang sama, tergantung 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 digunakan. Jika kunci mereferensikan flag yang dapat ditetapkan beberapa kali pada command line (misalnya bazel build --copt=foo --copt=bar --copt=baz ...), kecocokan terjadi jika salah satu setelan tersebut cocok.

grup file

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 koleksi target. Aturan ini kemudian dapat dirujuk dari aturan lain.

Sebaiknya gunakan filegroup, bukan mereferensikan direktori secara langsung. Metode yang terakhir tidak berfungsi karena sistem build tidak memiliki pengetahuan penuh tentang semua file di bawah direktori, sehingga sistem mungkin tidak mem-build ulang saat file ini berubah. Jika dikombinasikan dengan glob, filegroup dapat memastikan bahwa semua file secara eksplisit diketahui 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 mengelola direktori testdata:

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

Untuk memanfaatkan definisi ini, rujuk 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

Name; required

Nama unik untuk target ini.

srcs

List of labels; optional

Daftar target yang merupakan anggota grup file.

Sangat umum untuk menggunakan hasil ekspresi glob untuk nilai atribut srcs.

data

List of labels; optional

Daftar file yang diperlukan oleh aturan ini saat runtime.

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

output_group

String; optional

Grup output yang digunakan untuk mengumpulkan artefak 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.

kueri gen

genquery(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery() menjalankan kueri yang ditentukan dalam bahasa kueri Blaze dan membuang hasilnya ke dalam file.

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

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

Output genquery diurutkan menggunakan --order_output=full untuk memberlakukan output deterministik.

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

Name; required

Nama unik untuk target ini.

expression

String; required

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

List of strings; optional

Opsi yang diteruskan ke mesin kueri. Keduanya 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 default seperti halnya command line bazel query.
scope

List of labels; required

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

Boolean; optional; default is True

Jika benar, target yang kuerinya lolos dari penutupan transitif cakupannya akan gagal dibuat. Jika salah, Bazel akan mencetak peringatan dan melewati jalur kueri apa pun yang membuatnya berada di luar cakupan, sembari menyelesaikan sisa kueri.

Genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule menghasilkan satu atau beberapa file menggunakan perintah Bash yang ditentukan pengguna.

Aturan aturan adalah aturan build umum yang dapat Anda gunakan jika tidak ada aturan khusus untuk tugas. Misalnya, Anda dapat menjalankan one-liner Bash. Namun, jika Anda perlu mengompilasi file C++, tetap patuhi aturan cc_* yang ada, karena semua tugas berat telah dilakukan untuk Anda.

Jangan gunakan genrule untuk menjalankan pengujian. Ada dispensasi khusus untuk pengujian dan hasil pengujian, termasuk kebijakan caching dan variabel lingkungan. Biasanya pengujian harus dijalankan setelah build selesai dan pada arsitektur target, sedangkan genrules dieksekusi selama build dan arsitektur host (keduanya mungkin berbeda). Jika Anda memerlukan aturan pengujian dengan tujuan umum, gunakan sh_test.

Pertimbangan Lintas Kompilasi

Lihat panduan pengguna untuk mengetahui informasi selengkapnya tentang kompilasi silang.

Saat genrule berjalan selama proses build, outputnya sering digunakan setelah proses build, untuk deployment atau pengujian. Pertimbangkan contoh kompilasi kode C untuk pengontrol mikro: compiler menerima file sumber C dan menghasilkan kode yang berjalan pada pengontrol mikro. Kode yang dihasilkan jelas tidak dapat dijalankan pada CPU yang digunakan untuk membuatnya, tetapi compiler C (jika dikompilasi dari sumber) itu sendiri harus melakukannya.

Sistem build menggunakan konfigurasi host untuk mendeskripsikan mesin tempat build berjalan dan konfigurasi target untuk mendeskripsikan mesin tempat output build seharusnya berjalan. Ini memberikan opsi untuk mengonfigurasi setiap file dan memisahkan file yang sesuai ke dalam direktori terpisah untuk menghindari konflik.

Untuk genrules, sistem build memastikan bahwa dependensi dibuat dengan tepat: srcs dibuat (jika perlu) untuk konfigurasi target, tools dibuat untuk konfigurasi host, dan output dianggap untuk konfigurasi target. Ini juga menyediakan variabel ""Make" yang dapat diteruskan oleh perintah genrule ke alat yang sesuai.

Hal ini disengaja bahwa genrule tidak mendefinisikan 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 ini tidak mungkin dilakukan untuk genrules. Genrule berfungsi sepenuhnya pada tingkat file dan runfiles.

Kasus Khusus

Kompilasi host-host: dalam beberapa kasus, sistem build perlu menjalankan genrules sehingga output juga dapat dijalankan selama build. Jika misalnya, genrule mem-build beberapa compiler kustom yang selanjutnya digunakan oleh genrule lain, yang pertama harus menghasilkan outputnya untuk konfigurasi host, karena di situlah compiler akan berjalan di genrule lainnya. Dalam hal ini, sistem build otomatis melakukan hal yang benar: sistem membuat srcs dan outs genrule pertama untuk konfigurasi host, bukan konfigurasi target. Lihat panduan pengguna untuk mengetahui info selengkapnya.

JDK & C++ Tooling: untuk menggunakan alat dari JDK atau suite compiler C++, sistem build akan menyediakan sekumpulan variabel untuk digunakan. Lihat "Buat" variabel untuk 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 menjalankan perintah Bash dalam lingkungan proses bersih yang hanya menentukan variabel inti seperti PATH, PWD, TMPDIR, dan beberapa lainnya. Untuk memastikan build dapat direproduksi, sebagian besar variabel yang ditetapkan di lingkungan shell pengguna tidak diteruskan ke perintah genrule. Namun, Bazel (tetapi bukan Blaze) meneruskan nilai variabel lingkungan PATH pengguna. Setiap perubahan pada nilai PATH akan menyebabkan Bazel menjalankan kembali perintah pada build berikutnya.

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

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

Saran Umum

  • Pastikan bahwa alat yang dijalankan oleh genrule bersifat deterministik dan hermetic. Mereka tidak boleh menulis stempel waktu ke outputnya, dan harus menggunakan pengurutan yang stabil untuk set dan peta, serta menulis jalur file relatif saja ke output, bukan jalur absolut. Tidak mengikuti aturan ini akan menyebabkan perilaku build yang tidak terduga (Bazel tidak membuat kembali genrule yang Anda kira akan melakukannya) 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 hard code dan/atau absolut.
  • Tulis makro Starlark umum jika genrule yang sama atau sangat mirip digunakan di beberapa tempat. Jika genrule adalah rumit, pertimbangkan untuk menerapkannya dalam skrip atau sebagai aturan Starlark. Hal ini akan meningkatkan keterbacaan dan kemudahan untuk diuji.
  • Pastikan bahwa kode keluar menunjukkan dengan benar keberhasilan atau kegagalan genrule.
  • Jangan menulis pesan informasi untuk stdout atau stderr. Meskipun berguna untuk proses debug, hal ini mudah menjadi derau; genrule yang sukses harus diam. Di sisi lain, genrule yang gagal akan memunculkan 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 terdengar.
  • Saat mereferensikan genrule dalam aturan lain, Anda dapat menggunakan label genrule atau label file output individual. Terkadang, satu pendekatan lebih mudah dibaca, terkadang pendekatan yang lain: mereferensikan output berdasarkan nama dalam srcs aturan yang memakainya akan menghindari pengambilan output lain dari genrule 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 ini 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 penggunaan $(SRCS), bukan perintah $(location) eksplisit, juga akan berfungsi; contoh ini menggunakan perintah terakhir 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

Name; required

Nama unik untuk target ini.


Anda dapat merujuk pada aturan ini berdasarkan nama di bagian srcs atau deps pada aturan BUILD lainnya. Jika aturan menghasilkan file sumber, Anda harus menggunakan atribut srcs.
srcs

List of labels; optional

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

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

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

outs

List of filenames; required; nonconfigurable

Daftar file yang dihasilkan oleh aturan ini.

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

Jika flag executable ditetapkan, outs harus berisi satu label.

cmd

String; optional

Perintah untuk menjalankan. Tunduk pada substitusi $(location) dan "Make" variabel.
  1. Substitusi $(location) pertama diterapkan, menggantikan semua kemunculan $(location label) dan $(locations label).
  2. Perhatikan bahwa outs tidak disertakan dalam substitusi ini. File output selalu dihasilkan di lokasi yang dapat diprediksi (tersedia melalui $(@D), $@, $(OUTS), $(RULEDIR), atau $(location output_name); lihat di bawah).

  3. Selanjutnya, "Buat" variabel diperluas. Perlu diperhatikan bahwa variabel $(JAVA), $(JAVAC), dan $(JAVABASE) yang telah ditetapkan akan diperluas di bagian konfigurasi host, sehingga pemanggilan Java yang berjalan sebagai bagian dari langkah build dapat memuat library bersama dan dependensi lainnya dengan benar.
  4. Terakhir, perintah yang dihasilkan dijalankan menggunakan shell Bash. Jika kode keluarnya bukan nol, perintah dianggap gagal.

Perintah tersebut dapat merujuk ke target *_binary; dan harus menggunakan label untuk ini. Variabel berikut tersedia dalam subbahasa cmd:

  • "Buat" variabel
  • "Buat" variabel yang telah ditetapkan sebelumnya oleh alat build. Gunakan variabel ini, bukan nilai hardcode. Lihat Variabel &Make" standar dalam dokumen ini untuk daftar nilai yang didukung.

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 mengatasi masalah. Ini berlaku untuk semua atribut cmd (cmd, cmd_bash, cmd_ps, cmd_bat).

cmd_bash

String; optional

Perintah Bash untuk dijalankan.

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

cmd_bat

String; optional

Perintah Batch yang akan dijalankan di Windows.

Atribut ini memiliki prioritas yang lebih tinggi daripada cmd dan cmd_bash. Perintah tersebut berjalan dengan cara yang sama seperti 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, lalu mengeksekusi apa pun yang lainnya.
    • /E:ON - mengaktifkan set perintah yang diperluas.
    • /V:ON - aktifkan ekspansi variabel tertunda
    • /D - mengabaikan entri registry AutoRun.
  • Setelah substitusi $(location) dan "Make" variabel, jalur akan diperluas ke jalur gaya Windows (dengan garis miring terbalik).
cmd_ps

String; optional

Perintah Powershell untuk dijalankan di Windows.

Atribut ini memiliki prioritas yang lebih tinggi daripada cmd, cmd_bash, dan cmd_bat. Perintah tersebut berjalan dengan cara yang sama seperti 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 terlalu rentan error, kami menjalankan perintah berikut untuk menyiapkan lingkungan sebelum menjalankan perintah Powershell di genrule.

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

List of labels; optional

Daftar dependensi tool untuk aturan ini. Perilaku ini persis seperti atribut tools, hanya saja dependensi ini akan dikonfigurasi untuk platform eksekusi aturan, bukan konfigurasi host. Artinya, dependensi dalam exec_tools tidak tunduk pada batasan yang sama seperti dependensi dalam tools. Secara khusus, host tidak diwajibkan untuk menggunakan konfigurasi host untuk dependensi transitifnya sendiri. Lihat tools untuk mengetahui detail selengkapnya.

Tim Blaze memigrasikan semua penggunaan tools untuk menggunakan semantik exec_tools. Pengguna lebih memilih exec_tools daripada tools jika tidak ada masalah. Setelah migrasi fungsional selesai, kami dapat mengganti nama exec_tools menjadi tools. Anda akan menerima peringatan dan petunjuk migrasi sebelum penghentian ini dilakukan.

executable

Boolean; optional; nonconfigurable; default is False

Mendeklarasikan output agar dapat dijalankan.

Menetapkan tanda ini ke 1 berarti output file tersebut dapat dijalankan dan dapat dijalankan menggunakan perintah run. Dalam hal ini, genrule harus menghasilkan satu output. Jika atribut ini ditetapkan, run akan mencoba menjalankan file terlepas dari kontennya.

Mendeklarasikan dependensi data untuk file executable yang dihasilkan tidak didukung.

local

Boolean; optional; default is False

Jika disetel ke 1, opsi ini akan memaksa genrule berjalan menggunakan strategi "lokal" yang berarti tidak ada eksekusi jarak jauh, tidak ada sandboxing, tidak ada pekerja persisten.

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

message

String; optional

Pesan progres.

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

output_licenses

Licence type; optional

Lihat common attributes
output_to_bindir

Boolean; optional; nonconfigurable; default is False

Jika disetel ke 1, opsi ini akan menyebabkan file output ditulis ke dalam direktori bin, bukan direktori genfiles.

tools

List of labels; optional

Daftar dependensi tool untuk aturan ini. Lihat definisi dependensi untuk informasi lebih lanjut.

Sistem build memastikan prasyarat ini di-build sebelum menjalankan perintah genrule; di-build menggunakan konfigurasi host , karena alat ini dieksekusi sebagai bagian dari build. Jalur setiap target tools //x:y dapat diperoleh menggunakan $(location //x:y).

Semua *_binary atau alat yang akan dijalankan oleh cmd harus muncul dalam daftar ini, bukan dalam srcs, untuk memastikannya telah dibuat dalam konfigurasi yang benar.

suite_pengujian

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 untuk menentukan kumpulan pengujian, seperti "pengujian yang harus Anda jalankan sebelum checkin", "uji uji project kami" atau "semua pengujian kecil." Perintah blaze test mengikuti jenis organisasi ini: Untuk pemanggilan seperti blaze test //some/test:suite, Blaze pertama-tama akan menghitung semua target pengujian yang disertakan secara transitif oleh target //some/test:suite (kami menyebutnya "test_suite ekspansi"), lalu Blaze mem-build dan menguji target tersebut.

Contoh

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

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

Suite pengujian yang menjalankan serangkaian pengujian yang ditentukan:

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

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

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

Argumen

Atribut
name

Name; required

Nama unik untuk target ini.

tags

List of strings; optional; nonconfigurable

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

Tag yang diawali dengan karakter "-" dianggap sebagai tag negatif. Karakter "-" sebelumnya tidak dianggap sebagai bagian dari tag, sehingga tag suite berupa "-small" cocok dengan ukuran "kecil" 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. Hal ini hanya membuat perbedaan positif dan negatif lebih mudah dibaca.

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

Kata kunci tag manual diperlakukan secara berbeda dari yang di atas oleh perluasan "test_suite" dilakukan oleh perintah blaze test pada pemanggilan yang melibatkan pola target karakter pengganti. Di sana, test_suite target diberi tag "manual" 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.

Perlu diketahui bahwa size pengujian dianggap sebagai tag untuk tujuan pemfilteran.

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

tests

List of labels; optional; nonconfigurable

Daftar rangkaian pengujian dan target pengujian dalam bahasa apa pun.

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

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