Daftar Isi
paket
package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)
Fungsi ini mendeklarasikan metadata yang berlaku untuk setiap aturan dalam paket. Ini digunakan maksimal sekali dalam paket (file BUILD).
Untuk pasangan yang mendeklarasikan metadata yang berlaku untuk setiap aturan di seluruh repositori, gunakan fungsi repo()
di file REPO.bazel
di root repo Anda.
Fungsi repo()
menggunakan argumen yang sama persis dengan package()
.
Fungsi package() harus dipanggil tepat setelah semua pernyataan load() di bagian atas file, sebelum aturan apa pun.
Argumen
Atribut | Deskripsi |
---|---|
default_applicable_licenses |
Alias untuk |
default_visibility |
Daftar label; default-nya adalah Visibilitas default aturan dalam paket ini. Setiap aturan dalam paket ini memiliki visibilitas yang ditentukan dalam atribut
ini, kecuali jika ditentukan lain dalam atribut |
default_deprecation |
String; defaultnya adalah Menetapkan pesan
|
default_package_metadata |
Daftar label; default-nya adalah Menetapkan daftar default target metadata yang berlaku untuk semua target lain dalam paket. Ini biasanya adalah target yang terkait dengan paket OSS dan deklarasi lisensi. Lihat rules_license untuk mengetahui contohnya. |
default_testonly |
Boolean; defaultnya adalah Menetapkan properti
Dalam paket di bagian |
features |
Mencantumkan string; default-nya adalah Menetapkan berbagai tanda yang memengaruhi semantik file BUILD ini. Fitur ini terutama digunakan oleh orang-orang yang bekerja pada sistem build untuk memberi tag pada paket yang memerlukan semacam penanganan khusus. Jangan gunakan ini kecuali diminta secara eksplisit oleh seseorang yang mengerjakan sistem build. |
Contoh
Deklarasi di bawah menyatakan bahwa aturan dalam paket ini hanya terlihat oleh anggota grup paket//foo:target
. Deklarasi visibilitas individual
pada aturan, jika ada, ganti spesifikasi ini.
package(default_visibility = ["//foo:target"])
package_group
package_group(name, packages, includes)
Fungsi ini menentukan sekumpulan paket
dan mengaitkan label dengan kumpulan tersebut. Label dapat direferensikan dalam
atribut visibility
.
Grup paket terutama digunakan untuk kontrol visibilitas. Target yang terlihat secara publik dapat direferensikan dari setiap paket dalam hierarki sumber. Target yang terlihat secara pribadi hanya dapat direferensikan dalam paketnya sendiri (bukan subpaket). Di antara kedua ekstrem ini, target dapat mengizinkan akses ke paketnya sendiri serta salah satu paket yang dijelaskan oleh satu atau beberapa grup paket. Untuk penjelasan yang lebih mendetail tentang sistem visibilitas, lihat atribut visibilitas.
Paket tertentu dianggap berada dalam grup jika cocok dengan
atribut packages
, atau sudah ada dalam salah satu
grup paket lain yang disebutkan dalam atribut includes
.
Grup paket secara teknis merupakan target, tetapi tidak dibuat oleh aturan, dan tidak memiliki perlindungan visibilitas.
Argumen
Atribut | Deskripsi |
---|---|
name |
Nama; wajib Nama unik untuk target ini. |
packages |
Daftar string; default-nya adalah Daftar tanpa spesifikasi paket atau lebih. Setiap string spesifikasi paket dapat memiliki salah satu bentuk berikut:
Selain itu, dua jenis spesifikasi paket pertama juga dapat
diawali dengan Grup paket berisi paket apa pun yang cocok dengan setidaknya salah satu
spesifikasi positifnya dan tidak ada spesifikasi negatifnya
Misalnya, nilai Selain visibilitas publik, tidak ada cara untuk menentukan paket secara langsung di luar repositori saat ini. Jika atribut ini tidak ada, hal ini sama dengan menetapkannya ke
daftar kosong, yang juga sama dengan menetapkannya ke daftar yang hanya berisi
Catatan: Sebelum Bazel 6.0, spesifikasi Catatan: Sebelum Bazel 6.0, saat atribut ini diserialisasi sebagai
bagian dari |
includes |
Daftar label; defaultnya adalah Grup paket lain yang termasuk dalam paket ini. Label dalam atribut ini harus merujuk ke grup paket lain.
Paket dalam grup paket yang dirujuk dianggap sebagai bagian dari
grup paket ini. Ini bersifat transitif — jika grup paket
Jika digunakan bersama dengan spesifikasi paket negatif, perlu diperhatikan bahwa kumpulan paket untuk setiap grup akan dikomputasi secara independen terlebih dahulu dan hasilnya kemudian digabungkan. Ini berarti bahwa spesifikasi yang dinegasikan di satu grup tidak berpengaruh pada spesifikasi di grup lain. |
Contoh
Deklarasi package_group
berikut menentukan
grup paket yang disebut "tropis" yang berisi buah-buahan tropis.
package_group( name = "tropical", packages = [ "//fruits/mango", "//fruits/orange", "//fruits/papaya/...", ], )
Deklarasi berikut menentukan grup paket aplikasi fiktif:
package_group( name = "fooapp", includes = [ ":controller", ":model", ":view", ], ) package_group( name = "model", packages = ["//fooapp/database"], ) package_group( name = "view", packages = [ "//fooapp/swingui", "//fooapp/webui", ], ) package_group( name = "controller", packages = ["//fooapp/algorithm"], )
exports_files
exports_files([label, ...], visibility, licenses)
exports_files()
menentukan daftar file milik
paket ini yang diekspor ke paket lain.
File BUILD untuk paket hanya dapat merujuk langsung ke file sumber yang merupakan milik
paket lain jika diekspor secara eksplisit dengan
pernyataan exports_files()
. Baca selengkapnya tentang visibilitas file.
Sebagai perilaku lama, file yang disebutkan sebagai input ke aturan juga diekspor dengan visibilitas default hingga tanda --incompatible_no_implicit_file_export
dibalik. Namun, perilaku ini tidak boleh diandalkan dan secara aktif
dimigrasikan.
Argumen
Argumennya adalah daftar nama file dalam paket saat ini. Pernyataan visibilitas juga dapat ditentukan; dalam hal ini, file akan terlihat oleh target yang ditentukan. Jika tidak ada visibilitas yang ditentukan, file
akan terlihat oleh setiap paket, meskipun visibilitas default paket telah
ditentukan dalam fungsi package
. Lisensi juga dapat ditentukan.
Contoh
Contoh berikut mengekspor golden.txt
, file teks dari paket test_data
, sehingga paket lain dapat menggunakannya, misalnya, dalam atribut data
pengujian.
# from //test_data/BUILD exports_files(["golden.txt"])
glob
glob(include, exclude=[], exclude_directories=1, allow_empty=True)
Glob adalah fungsi bantuan yang menemukan semua file yang cocok dengan pola jalur tertentu, dan menampilkan daftar jalur baru yang dapat diubah dan diurutkan. Glob hanya menelusuri file dalam paketnya sendiri, dan hanya mencari file sumber (bukan file yang dihasilkan atau target lainnya).
Label file sumber disertakan dalam hasil jika jalur
paket relatif file cocok dengan salah satu pola include
dan tidak ada
pola exclude
.
Daftar include
dan exclude
berisi pola jalur
yang relatif terhadap paket saat ini. Setiap pola dapat terdiri dari satu atau
beberapa segmen jalur. Seperti biasa dengan jalur Unix, segmen ini dipisahkan oleh
/
. Segmen dapat berisi karakter pengganti *
: karakter pengganti ini cocok
dengan substring apa pun di segmen jalur (bahkan substring kosong), kecuali
pemisah direktori /
. Karakter pengganti ini dapat digunakan beberapa kali
dalam satu segmen jalur. Selain itu, karakter pengganti **
dapat cocok dengan
nol atau beberapa segmen jalur lengkap, tetapi harus dideklarasikan sebagai segmen
jalur mandiri.
foo/bar.txt
sama persis dengan filefoo/bar.txt
dalam paket inifoo/*.txt
cocok dengan setiap file dalam direktorifoo/
jika file diakhiri dengan.txt
(kecuali jikafoo/
adalah subpaket)foo/a*.htm*
cocok dengan setiap file dalam direktorifoo/
yang dimulai dengana
, lalu memiliki string arbitrer (bisa kosong), lalu memiliki.htm
, dan diakhiri dengan string arbitrer lainnya; sepertifoo/axx.htm
danfoo/a.html
ataufoo/axxx.html
**/a.txt
mencocokkan setiap filea.txt
di setiap subdirektori paket ini**/bar/**/*.txt
cocok dengan setiap file.txt
di setiap subdirektori paket ini, jika setidaknya satu direktori di jalur yang dihasilkan disebutbar
, sepertixxx/bar/yyy/zzz/a.txt
ataubar/a.txt
(ingat bahwa**
juga cocok dengan segmen nol) ataubar/zzz/a.txt
**
cocok dengan setiap file di setiap subdirektori paket inifoo**/a.txt
adalah pola yang tidak valid, karena**
harus berdiri sendiri sebagai segmen
Jika argumen exclude_directories
diaktifkan (disetel ke 1), file direktori jenis akan dihilangkan dari hasil (default 1).
Jika argumen allow_empty
ditetapkan ke False
, fungsi glob
akan mengalami error jika hasilnya berupa daftar kosong.
Ada beberapa batasan dan peringatan penting:
-
Karena
glob()
berjalan selama evaluasi file BUILD,glob()
hanya cocok dengan file dalam hierarki sumber, dan tidak pernah menghasilkan file. Jika Anda mem-build target yang memerlukan sumber dan file yang dihasilkan, Anda harus menambahkan daftar eksplisit file yang dihasilkan ke glob. Lihat contoh di bawah dengan:mylib
dan:gen_java_srcs
. -
Jika aturan memiliki nama yang sama dengan file sumber yang cocok, aturan tersebut akan "mengbayangi" file.
Untuk memahami hal ini, ingat bahwa
glob()
menampilkan daftar jalur, sehingga menggunakanglob()
dalam atribut aturan lain (misalnya,srcs = glob(["*.cc"])
) memiliki efek yang sama dengan mencantumkan jalur yang cocok secara eksplisit. Misalnya, jikaglob()
menghasilkan["Foo.java", "bar/Baz.java"]
tetapi ada juga aturan dalam paket bernama "Foo.java" (yang diizinkan, meskipun Bazel memperingatkan tentang hal tersebut), konsumenglob()
akan menggunakan aturan "Foo.java" (outputnya) bukan file "Foo.java". Lihat GitHub masalah #10395 untuk detail selengkapnya. - Glob dapat mencocokkan file di subdirektori. Selain itu, nama subdirektori dapat diberi karakter pengganti. Namun...
-
Label tidak diizinkan untuk melintasi batas paket dan glob tidak cocok dengan file dalam subpaket.
Misalnya, ekspresi glob
**/*.cc
dalam paketx
tidak menyertakanx/y/z.cc
jikax/y
ada sebagai paket (baik sebagaix/y/BUILD
, atau di tempat lain pada jalur paket). Ini berarti hasil ekspresi glob sebenarnya bergantung pada keberadaan file BUILD — yaitu, ekspresi glob yang sama akan menyertakanx/y/z.cc
jika tidak ada paket bernamax/y
atau ditandai sebagai dihapus menggunakan tanda --deleted_packages. - Batasan di atas berlaku untuk semua ekspresi glob, terlepas dari karakter pengganti yang digunakan.
-
File tersembunyi dengan nama file yang diawali dengan
.
sepenuhnya cocok dengan karakter pengganti**
dan*
. Jika Anda ingin mencocokkan file tersembunyi dengan pola majemuk, pola Anda harus dimulai dengan.
. Misalnya,*
dan.*.txt
akan cocok dengan.foo.txt
, tetapi*.txt
tidak akan cocok. Direktori tersembunyi juga dicocokkan dengan cara yang sama. Direktori tersembunyi dapat menyertakan file yang tidak diperlukan sebagai input, dan dapat meningkatkan jumlah file yang tidak perlu di-glob dan konsumsi memori. Untuk mengecualikan direktori tersembunyi, tambahkan direktori tersebut ke argumen daftar "exclude". -
Karakter pengganti "**" memiliki satu huruf besar/kecil: pola
"**"
tidak cocok dengan jalur direktori paket. Artinya,glob(["**"], exclude_directories = 0)
cocok dengan semua file dan direktori secara transitif secara transitif hanya dalam direktori paket saat ini (tetapi tentu saja tidak masuk ke direktori sub-paket - lihat catatan sebelumnya tentang hal tersebut).
Secara umum, Anda harus mencoba memberikan ekstensi yang sesuai (misalnya, *.html) bukan menggunakan '*' kosong untuk pola glob. Nama yang lebih eksplisit mendokumentasikan dirinya sendiri dan memastikan bahwa Anda tidak mencocokkan file cadangan secara tidak sengaja, atau emacs/vi/... file yang disimpan otomatis.
Saat menulis aturan build, Anda dapat menghitung elemen glob. Hal ini memungkinkan pembuatan aturan individual untuk setiap input, misalnya. Lihat bagian contoh glob yang diperluas di bawah.
Contoh Glob
Buat library Java yang dibuat dari semua file java di direktori ini,
dan semua file yang dihasilkan oleh aturan :gen_java_srcs
.
java_library( name = "mylib", srcs = glob(["*.java"]) + [":gen_java_srcs"], deps = "...", ) genrule( name = "gen_java_srcs", outs = [ "Foo.java", "Bar.java", ], ... )
Sertakan semua file txt di direktori testdata kecuali experimental.txt. Perhatikan bahwa file dalam subdirektori testdata tidak akan disertakan. Jika Anda ingin file tersebut disertakan, gunakan glob rekursif (**).
sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob( ["testdata/*.txt"], exclude = ["testdata/experimental.txt"], ), )
Contoh Glob Rekursif
Buat pengujian bergantung pada semua file txt di direktori testdata dan semua subdirektorinya (dan subdirektorinya, dan seterusnya). Subdirektori yang berisi file BUILD diabaikan. (Lihat batasan dan peringatan di atas.)
sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob(["testdata/**/*.txt"]), )
Buat library yang dibuat dari semua file java di direktori ini dan semua subdirektori kecuali yang jalurnya menyertakan direktori bernama pengujian. Pola ini sebaiknya dihindari jika memungkinkan karena dapat mengurangi inkrementalitas build sehingga meningkatkan waktu build.
java_library( name = "mylib", srcs = glob( ["**/*.java"], exclude = ["**/testing/**"], ), )
Contoh Glob yang Diperluas
Buat genrule individual untuk *_test.cc di direktori saat ini yang menghitung jumlah baris dalam file.
# Conveniently, the build language supports list comprehensions. [genrule( name = "count_lines_" + f[:-3], # strip ".cc" srcs = [f], outs = ["%s-linecount.txt" % f[:-3]], cmd = "wc -l $< >$@", ) for f in glob(["*_test.cc"])]
Jika file BUILD di atas berada dalam paket //foo dan paket berisi tiga
file yang cocok, a_test.cc, b_test.cc, dan c_test.cc, maka menjalankan
bazel query '//foo:all'
akan mencantumkan semua aturan yang dihasilkan:
$ bazel query '//foo:all' | sort //foo:count_lines_a_test //foo:count_lines_b_test //foo:count_lines_c_test
pilih
select( {conditionA: valuesA, conditionB: valuesB, ...}, no_match_error = "custom message" )
select()
adalah fungsi bantuan yang membuat atribut aturan
dapat dikonfigurasi.
Flag ini dapat menggantikan sisi kanan
hampir
penetapan atribut apa pun sehingga nilainya bergantung pada flag Bazel command line.
Anda dapat menggunakannya, misalnya, untuk menentukan dependensi khusus platform atau untuk
menyematkan resource yang berbeda, bergantung pada apakah aturan dibuat dalam mode "developer"
vs. "release".
Penggunaan dasarnya adalah sebagai berikut:
sh_binary( name = "mytarget", srcs = select({ ":conditionA": ["mytarget_a.sh"], ":conditionB": ["mytarget_b.sh"], "//conditions:default": ["mytarget_default.sh"] }) )
Hal ini membuat atribut srcs
dari sh_binary
dapat dikonfigurasi dengan mengganti penetapan daftar label normalnya dengan panggilan select
yang memetakan kondisi konfigurasi ke nilai yang cocok. Setiap kondisi adalah referensi label ke config_setting
atau constraint_value
, yang akan "cocok" jika konfigurasi target cocok dengan kumpulan nilai yang diharapkan. Nilai mytarget#srcs
kemudian menjadi daftar label mana pun yang cocok dengan pemanggilan saat ini.
Catatan:
- Hanya satu kondisi yang dipilih pada setiap pemanggilan.
- Jika beberapa kondisi cocok dan salah satunya merupakan spesialisasi dari kondisi lainnya, spesialisasi akan lebih diutamakan. Kondisi B dianggap sebagai spesialisasi kondisi A jika B memiliki semua flag dan nilai batasan yang sama dengan A ditambah beberapa flag atau nilai batasan tambahan. Hal ini juga berarti bahwa resolusi spesialisasi tidak dirancang untuk membuat pengurutan seperti yang ditunjukkan dalam Contoh 2 di bawah.
- Jika beberapa kondisi cocok dan salah satunya bukan spesialisasi dari semua kondisi lainnya, Bazel akan gagal dengan error, kecuali jika semua kondisi di-resolve ke nilai yang sama.
- Label semu khusus
//conditions:default
dianggap cocok jika tidak ada kondisi lain yang cocok. Jika kondisi ini tidak disertakan, beberapa aturan lain harus cocok untuk menghindari error. select
dapat disematkan di dalam penetapan atribut yang lebih besar. Jadi,srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...})
dansrcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]})
adalah ekspresi yang valid.select
berfungsi dengan sebagian besar, tetapi tidak semua, atribut. Atribut yang tidak kompatibel ditandai sebagainonconfigurable
dalam dokumentasinya.sub-paket
subpackages(include, exclude=[], allow_empty=True)
subpackages()
adalah fungsi bantuan, mirip denganglob()
yang mencantumkan subpaket, bukan file dan direktori. Class ini menggunakan pola jalur yang sama denganglob()
dan dapat mencocokkan subpaket apa pun yang merupakan turunan langsung dari file BUILD yang sedang dimuat. Lihat glob untuk mengetahui penjelasan mendetail dan contoh pola sertakan dan kecualikan.Daftar sub-paket yang dihasilkan yang ditampilkan dalam urutan yang diurutkan dan berisi jalur yang relatif terhadap paket pemuatan saat ini yang cocok dengan pola yang diberikan dalam
include
dan bukan yang ada diexclude
.Contoh
Contoh berikut mencantumkan semua sub-paket langsung untuk paket
foo/BUILD
# The following BUILD files exist: # foo/BUILD # foo/bar/baz/BUILD # foo/sub/BUILD # foo/sub/deeper/BUILD # # In foo/BUILD a call to subs = subpackages(include = ["**"]) # results in subs == ["sub", "bar/baz"] # # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of # 'foo'
Secara umum, sebaiknya pengguna menggunakan modul 'subpackages' dari skylib, bukan memanggil fungsi ini secara langsung.