Aturan Umum

Aturan

• alias
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• test_suite

alias

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

Aturan alias membuat nama lain yang dapat digunakan untuk merujuk ke suatu aturan.

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

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

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

• Pengujian tidak 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 ini juga tidak didukung di opsi command line --target_environment.

Contoh

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

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

Argumen

config_setting

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

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

Contoh

Berikut adalah build yang cocok dengan build apa pun yang menyetel --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 definisi kustom FOO=bar (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 atau secara implisit dari file .bazelrc):

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

Berikut cocok dengan build apa pun yang menargetkan platform dengan arsitektur x86_64 dan glibc versi 2.25, dengan asumsi adanya constraint_value dengan label //example:glibc_2_25. Perhatikan bahwa platform tetap cocok jika menentukan nilai batasan tambahan di luar kedua nilai ini.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

Catatan

• Lihat select untuk mengetahui apa yang terjadi saat beberapa config_setting cocok dengan status konfigurasi saat ini.
• Untuk tanda yang mendukung bentuk singkat (misalnya, --compilation_mode vs. -c), definisi values harus menggunakan bentuk lengkap. Ini secara otomatis mencocokkan pemanggilan menggunakan salah satu bentuk.
• Jika tanda memiliki beberapa nilai (seperti --copt=-Da --copt=-Db atau tanda Starlark berjenis daftar), values = { "flag": "a" } 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 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 dengan yang terakhir). Namun, --ios_multi_cpus (untuk aturan Apple) melakukannya: -ios_multi_cpus=a,b dan ios_multi_cpus=a --ios_multi_cpus=b menghasilkan ["a", "b"]. Periksa definisi tanda 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 dukungan yang ditawarkan lebih lemah dan tidak direkomendasikan. Lihat di sini untuk diskusi selengkapnya.
• Hindari pengulangan 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 di config_setting yang sama, tetapi setidaknya satu harus ditetapkan untuk config_setting tertentu.

Argumen

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

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

filegroup

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

Gunakan filegroup untuk memberi nama yang mudah diingat pada kumpulan target. Kemudian, hal ini dapat dirujuk dari aturan lain.

Sebaiknya gunakan filegroup, bukan mereferensikan direktori secara langsung. Yang terakhir tidak valid karena sistem build tidak memiliki pengetahuan lengkap 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 mencari direktori testdata:

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

Untuk menggunakan definisi ini, lihat filegroup dengan label dari aturan apa pun:

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

Argumen

genquery

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

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

Untuk menjaga konsistensi build, kueri hanya diizinkan untuk mengunjungi 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 termudah 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 di command line adalah kueri yang berisi spesifikasi target wildcard (misalnya, //pkg:* atau //pkg:all) tidak diizinkan di sini. Ada dua alasan untuk hal ini: 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 memastikan output yang 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 dari target yang ditentukan ke file.

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

Argumen

genrule

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

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

Genrule adalah aturan build generik yang dapat Anda gunakan jika tidak ada aturan khusus untuk tugas tersebut. Misalnya, Anda dapat menjalankan perintah Bash satu baris. Namun, jika Anda perlu mengompilasi file C++, tetaplah menggunakan aturan cc_* yang ada, karena semua pekerjaan berat telah dilakukan untuk Anda.

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

Jangan gunakan genrule untuk menjalankan pengujian. Ada dispensasi khusus untuk pengujian dan hasil pengujian, termasuk kebijakan caching 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 untuk tujuan umum, gunakan sh_test.

Pertimbangan Kompilasi Silang

Lihat panduan pengguna untuk mengetahui info selengkapnya tentang kompilasi silang.

Meskipun genrule berjalan selama build, outputnya sering digunakan setelah build, untuk deployment atau pengujian. Pertimbangkan contoh mengompilasi kode C untuk pengontrol mikro: compiler menerima file sumber C dan menghasilkan kode yang berjalan di pengontrol mikro. Kode yang dihasilkan jelas tidak dapat berjalan di CPU yang digunakan untuk membangunnya, tetapi compiler C (jika dikompilasi dari sumber) itu sendiri harus dapat berjalan.

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

Untuk genrule, sistem build memastikan bahwa dependensi dibangun dengan tepat: srcs dibangun (jika perlu) untuk konfigurasi target, tools dibangun untuk konfigurasi exec, dan output dianggap untuk konfigurasi target. Selain itu, alat ini menyediakan variabel "Make" yang dapat diteruskan perintah genrule ke alat yang sesuai.

Genrule sengaja tidak menentukan atribut deps: aturan bawaan lainnya menggunakan informasi meta yang bergantung pada bahasa yang diteruskan antar-aturan untuk otomatis menentukan cara menangani aturan dependen, tetapi tingkat otomatisasi ini tidak mungkin dilakukan untuk genrule. Genrules bekerja murni di tingkat file dan runfiles.

Kasus Khusus

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

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

Lingkungan Genrule

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

Alat build menjalankan perintah Bash di lingkungan proses yang telah dibersihkan yang hanya menentukan variabel inti seperti PATH, PWD, TMPDIR, dan beberapa variabel lainnya. Untuk memastikan bahwa build dapat direproduksi, sebagian besar variabel yang ditentukan 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 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 tidak diterapkan.

Sistem build akan otomatis menghapus 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 alat yang dijalankan oleh genrule bersifat deterministik dan hermetik. Mereka tidak boleh menulis stempel waktu ke output, dan mereka harus menggunakan pengurutan yang stabil untuk set dan peta, serta menulis hanya jalur file relatif ke output, bukan jalur absolut. Tidak mengikuti aturan ini akan menyebabkan perilaku build yang tidak terduga (Bazel tidak membangun ulang genrule yang Anda kira akan dibangun ulang) 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 yang dikodekan secara permanen dan/atau absolut.
• Tulis makro Starlark umum jika genrule yang sama atau sangat mirip digunakan di beberapa tempat. Jika genrule kompleks, pertimbangkan untuk menerapkannya dalam skrip atau sebagai aturan Starlark. Hal ini meningkatkan keterbacaan serta kemudahan pengujian.
• Pastikan 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 gangguan; genrule yang berhasil tidak akan menampilkan output. Di sisi lain, genrule yang gagal harus 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/link simbolis yang dibuat oleh genrules dan pemeriksaan dependensi direktorinya tidak valid.
• Saat mereferensikan genrule dalam aturan lain, Anda dapat menggunakan label genrule atau label file output individual. Terkadang satu pendekatan lebih mudah dibaca, terkadang pendekatan lainnya: mereferensikan output berdasarkan nama dalam srcs aturan yang menggunakan akan menghindari output genrule lain yang tidak disengaja, tetapi bisa membosankan jika genrule menghasilkan banyak output.

Contoh

Contoh ini menghasilkan foo.h. Tidak ada sumber, karena perintah tidak menerima 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 penggunaan $(SRCS), bukan direktif $(location) eksplisit juga akan berfungsi; contoh ini menggunakan direktif $(location) untuk tujuan 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

starlark_doc_extract

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() 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): A ModuleInfo binary proto.
• name.textproto (hanya dibuat jika diminta secara eksplisit): versi proto teks name.binaryproto.

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

Argumen

test_suite

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 serangkaian pengujian, seperti "pengujian yang harus Anda jalankan sebelum check-in", "pengujian beban project kami", atau "semua pengujian kecil". Perintah blaze test mematuhi organisasi semacam ini: Untuk pemanggilan seperti blaze test //some/test:suite, Blaze terlebih dahulu menghitung semua target pengujian yang disertakan secara transitif oleh target //some/test:suite (kami menyebutnya "perluasan test_suite"), lalu Blaze membangun dan menguji target tersebut.

Contoh

Test suite untuk menjalankan semua pengujian kecil dalam paket saat ini.

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

Rangkaian pengujian yang menjalankan serangkaian pengujian tertentu:

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

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

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

Argumen