Peraturan Umum

Aturan

• alias
• config_setting
• grup file
• genquery
• genrule
• 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 menjadi rujukan aturan.

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

Aturan alias memiliki deklarasi visibilitas sendiri. Dalam semua hal lainnya, kode ini berperilaku seperti aturan yang direferensikannya (misalnya, hanya pengujian pada alias diabaikan; nilai khusus pengujian dari aturan yang dirujuk yang digunakan) dengan beberapa pengecualian kecil:

• Pengujian tidak akan dijalankan 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 untuk aturan environment tidak didukung. Metode tersebut juga tidak didukung dalam 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 flag build atau batasan platform) untuk tujuan memicu atribut yang dapat dikonfigurasi. Lihat bagian select untuk mengetahui cara menggunakan aturan ini dan Atribut yang dapat dikonfigurasi untuk mengetahui ringkasan fitur umum.

Contoh

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

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

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

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

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

Yang berikut ini 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 keduanya.

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

Catatan

• Lihat bagian select 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 formulir.
• Jika flag mengambil beberapa nilai (seperti --copt=-Da --copt=-Db atau flag Starlark yang berjenis daftar), values = { "flag": "a" } cocok jika "a" ada di mana pun 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-flag. Misalnya, --copt tidak mendukung banyak nilai dalam instance yang sama: --copt=a,b menghasilkan ["a,b"], sedangkan --copt=a --copt=b menghasilkan ["a", "b"] (jadi values = { "copt": "a,b" } cocok dengan nilai sebelumnya, tetapi tidak dengan yang kedua). Namun, --ios_multi_cpus (untuk aturan Apple) memang: -ios_multi_cpus=a,b dan ios_multi_cpus=a --ios_multi_cpus=b 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 cara ini menawarkan dukungan yang lebih lemah dan tidak direkomendasikan. Lihat di sini untuk diskusi selengkapnya.
• Hindari pengulangan definisi config_setting yang identik dalam paket 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

            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",
                })
          

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 bagi kumpulan target. Aturan ini kemudian bisa dirujuk dari aturan lain.

Sebaiknya gunakan filegroup daripada mereferensikan direktori secara langsung. Situasi ini tidaklah baik karena sistem build tidak memiliki pengetahuan penuh tentang semua file di bawah direktori, sehingga sistem mungkin tidak akan 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 menjelajahi 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

kueri

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 memasukkan hasilnya ke dalam file.

Agar build tetap konsisten, 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 true (jika strict bernilai salah, target di luar cakupan 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 karakter pengganti (misalnya //pkg:* atau //pkg:all) tidak diizinkan di sini. Alasannya ada dua kemungkinan: pertama, karena genquery harus menentukan cakupan untuk mencegah target di luar penutupan transitif kueri untuk memengaruhi output-nya; dan, kedua, karena file BUILD tidak mendukung dependensi karakter pengganti (misalnya, deps=["//a/..."] tidak diizinkan).

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

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

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.

Genrules adalah aturan build generik yang bisa Anda gunakan jika tidak ada aturan spesifik untuk tugas tersebut. Misalnya, Anda dapat menjalankan Bash satu baris. Namun, jika Anda perlu mengompilasi file C++, tetap ikuti 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. Pengujian umumnya harus dijalankan setelah build selesai dan berada pada arsitektur target, sedangkan genrules dijalankan selama build dan pada arsitektur host (keduanya mungkin berbeda). Jika Anda memerlukan aturan pengujian tujuan umum, gunakan sh_test.

Pertimbangan Lintas Kompilasi

Lihat panduan pengguna untuk mengetahui info selengkapnya tentang kompilasi silang.

Meskipun 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 dijalankan pada CPU yang digunakan untuk mem-build-nya, tetapi compiler C (jika dikompilasi dari sumber) sendiri harus melakukannya.

Sistem build menggunakan konfigurasi host untuk mendeskripsikan mesin tempat build berjalan, dan konfigurasi target untuk mendeskripsikan mesin tempat output build seharusnya dijalankan. API ini menyediakan opsi untuk mengonfigurasi setiap hal tersebut dan memisahkan file terkait 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. Class ini juga menyediakan variabel "Make" yang dapat diteruskan oleh perintah genrule ke alat terkait.

genrule dimaksudkan untuk tidak menentukan atribut deps: aturan bawaan lainnya menggunakan informasi meta yang bergantung pada bahasa yang diteruskan di antara aturan untuk otomatis menentukan cara menangani aturan dependen, tetapi tingkat otomatisasi ini tidak memungkinkan untuk genrules. Genrules hanya berfungsi di level file dan runfile.

Kasus Khusus

Kompilasi host-host: 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, yang pertama harus menghasilkan output-nya untuk konfigurasi host, karena di situlah compiler akan berjalan dalam genrule lainnya. Dalam hal ini, sistem build melakukan hal yang benar secara otomatis: sistem mem-build srcs dan outs dari genrule pertama untuk konfigurasi host, bukan konfigurasi target. Lihat panduan pengguna untuk info selengkapnya.

Tooling JDK & C++: untuk menggunakan alat dari JDK atau compiler C++, sistem build menyediakan satu set variabel untuk digunakan. Lihat variabel"Membuat" untuk mengetahui detailnya.

Lingkungan Genrule

Perintah genrule dijalankan oleh shell Bash yang dikonfigurasi agar gagal jika perintah atau pipeline gagal menggunakan set -e -o pipefail.

Alat build menjalankan perintah Bash di lingkungan proses yang bersih yang hanya menentukan variabel inti seperti PATH, PWD, TMPDIR, dan beberapa variabel lainnya. Untuk memastikan bahwa build dapat direproduksi, sebagian besar variabel yang ditentukan dalam lingkungan shell pengguna tidak diteruskan ke perintah genrule. Namun, Bazel (tetapi tidak Blaze) akan 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 dari perintah itu sendiri, meskipun hal ini saat ini tidak diberlakukan.

Sistem build akan otomatis menghapus file output yang ada, tetapi membuat direktori induk yang diperlukan sebelum menjalankan genrule. Juga menghapus file {i>output<i} jika terjadi kegagalan.

Saran Umum

• Pastikan bahwa alat yang dijalankan oleh genrule bersifat deterministik dan hermetis. Anotasi 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, tanpa jalur absolut. Tidak mengikuti aturan ini akan menyebabkan perilaku build yang tidak terduga (Bazel tidak mem-build kembali genrule yang Anda kira akan) 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 genrules yang sama atau sangat mirip digunakan di beberapa tempat. Jika genrule-nya rumit, 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, genrule yang berhasil harus disenyapkan dengan mudah. Di sisi lain, genaturan 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 dependensinya terhadap direktori tidak berjalan lancar.
• Saat mereferensikan genrule di aturan lain, Anda dapat menggunakan label genrule atau label setiap file output. Terkadang pendekatan yang satu lebih mudah dibaca, terkadang pendekatan yang lain: mereferensikan output berdasarkan nama dalam srcs aturan yang menggunakan akan mencegah 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 ini 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 lain. Perhatikan 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

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 rangkaian pengujian, seperti "pengujian yang harus Anda jalankan sebelum checkin", "pengujian stress project kami", atau "semua pengujian kecil". Perintah blaze test mengikuti organisasi semacam ini: Untuk pemanggilan seperti blaze test //some/test:suite, Blaze akan terlebih dahulu menghitung semua target pengujian yang disertakan secara transitif yang disertakan oleh target //some/test:suite (kami menyebut ini "test_suite development"), lalu Blaze mem-build dan menguji target tersebut.

Contoh

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

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

Test suite yang menjalankan serangkaian pengujian tertentu:

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

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

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

Argumen