Peraturan 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 disebut sebagai nama aturan.

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

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

Aturan alias memiliki deklarasi visibilitasnya sendiri. Dalam hal lain, 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 direferensikan, gunakan test_suite aturan dengan satu target di tests .
• Saat menentukan grup lingkungan, alias 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

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 dengan 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

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

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

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

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

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

Berikut ini cocok dengan build apa pun yang menargetkan platform dengan arsitektur x86_64 dan glibc versi 2.25, dengan asumsi adanya 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",
      ]
  )
  

Catatan

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

  values = { "myflag": "a,b" } berfungsi dengan cara yang sama: 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 antara penanda. Misalnya, --copt tidak mendukung beberapa nilai dalam satu instance: --copt=a,b menghasilkan ["a,b"] sedangkan --copt=a --copt=b menghasilkan ["a", "b"] (jadi values = { "copt": "a,b" } cocok dengan yang pertama, tetapi tidak dengan yang kedua). Namun, --ios_multi_cpus (untuk aturan Apple) memilikinya: -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 cara ini menawarkan dukungan teknis IT dan tidak direkomendasikan. Lihat di sini untuk diskusi lebih lanjut.
• Hindari pengulangan definisi config_setting yang identik dalam paket yang berbeda. Sebagai gantinya, referensikan config_setting umum yang ditentukan dalam paket kanonis.
• values, define_values, dan constraint_values dapat digunakan dalam kombinasi apa pun dalam config_setting yang sama tetapi setidaknya salah satunya harus ditetapkan untuk config_setting tertentu.

Argumen

            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 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. Bila digabungkan dengan glob, filegroup dapat memastikan bahwa semua file secara eksplisit dikenal oleh sistem build.

Contoh

Untuk membuat filegroup yang terdiri dari dua file sumber, lakukan

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

Atau, gunakan glob untuk menelusuri direktori testdata:

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

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

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

Argumen

{i>genquery<i}

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 scope . Kueri yang melanggar aturan ini akan gagal selama eksekusi jika strict tidak ditentukan atau benar (jika strict salah, target di luar cakupan akan dilewati begitu saja dengan peringatan). Tujuan cara termudah untuk memastikan hal ini tidak terjadi adalah dengan menyebutkan label yang sama ke dalam cakupan seperti di ekspresi kueri.

Satu-satunya perbedaan antara kueri yang diizinkan di sini dan di 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 memiliki untuk menentukan cakupan guna mencegah target di luar penutupan transitif {i>query <i}untuk mempengaruhi {i>outputnya<i}; dan kedua, karena file BUILD tidak mendukung dependensi karakter pengganti (misalnya, deps=["//a/..."] tidak diizinkan).

Output genquery diurutkan secara leksikografis untuk 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

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 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.

Perlu diperhatikan 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 sesuai pada arsitektur target, sedangkan genrules dijalankan selama arsitektur build dan exec (keduanya mungkin berbeda). Jika Anda memerlukan aturan pengujian tujuan umum, gunakan sh_test.

Pertimbangan Kompilasi Silang

Lihat panduan pengguna untuk info selengkapnya tentang kompilasi silang.

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

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

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

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

Kasus Khusus

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

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

Lingkungan Genrule

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

Alat 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 (tapi 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 file output yang ada, tetapi membuat direktori induk yang diperlukan sebelum menjalankan genrule. Alat ini juga menghapus file output jika terjadi kegagalan.

Saran Umum

• Pastikan alat yang dijalankan oleh genrule bersifat deterministik dan hermetis. Mereka tidak boleh menulis stempel waktu ke outputnya, dan harus menggunakan pengurutan yang stabil untuk set dan peta, serta hanya menulis jalur file relatif ke {i>output<i}, tanpa jalur absolut. Jika aturan ini tidak diikuti, menyebabkan perilaku build yang tidak terduga (Bazel tidak membangun ulang genrule yang Anda kira) 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 {i>stdout<i} atau {i>stderr<i}. Meskipun berguna untuk proses debug, hal ini dapat dengan mudah menjadi derau; genrule yang berhasil akan diam. Di sisi lain, genrule yang gagal akan memunculkan pesan {i>error<i} yang baik.
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x).
• Hindari membuat symlink dan direktori. Bazel tidak menyalin direktori/symlink struktur yang dibuat oleh genrules dan pemeriksaan dependensinya terhadap direktori tidak terdengar.
• Saat mereferensikan genrule di aturan lain, Anda bisa menggunakan label genrule atau label dari setiap file {i>output<i}. Terkadang satu pendekatan lebih mudah dibaca, terkadang pendekatan lainnya: mereferensikan output berdasarkan nama di srcs aturan yang menggunakan akan menghindari pengambilan 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 dengan perintah adalah skrip perl dalam paket yang sama dengan genrule.

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

Contoh berikut menunjukkan cara menggunakan filegroup dan output genrule lainnya. 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

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

Target output implisit

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

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

Argumen

test_suite

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

test_suite menentukan kumpulan pengujian yang dianggap "berguna" manusia. 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 pengurutan ini organisasi: 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 sebut ini "perluasan test_suite"), lalu Blaze membangun 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