Daftar isi
paket
package(default_deprecation, default_testonly, default_visibility, features)
Fungsi ini mendeklarasikan metadata yang berlaku untuk setiap aturan berikutnya dalam paket. Kode ini digunakan maksimal sekali di dalam paket (file BUILD).
Fungsi package() harus dipanggil tepat setelah semua pernyataan load() di bagian atas file, sebelum aturan.
Argumen
Atribut | Deskripsi |
---|---|
default_visibility |
Visibilitas default aturan dalam paket ini. Setiap aturan dalam paket ini memiliki visibilitas yang ditentukan dalam atribut ini, kecuali ditentukan lain dalam atribut |
default_deprecation |
Menetapkan pesan
|
default_testonly |
Menetapkan properti
Dalam paket di bawah |
features |
Menetapkan berbagai flag yang memengaruhi semantik file BUILD ini. Fitur ini terutama digunakan oleh orang-orang yang mengerjakan sistem build untuk memberi tag pada paket yang memerlukan semacam penanganan khusus. Jangan gunakan ini kecuali jika diminta secara eksplisit oleh seseorang yang mengerjakan sistem build. |
Contoh
Deklarasi di bawah mendeklarasikan bahwa aturan dalam paket ini hanya dapat dilihat oleh anggota grup paket//foo:target
. Deklarasi visibilitas individual pada aturan, jika ada, menggantikan spesifikasi ini.
package(default_visibility = ["//foo:target"])
paket_grup
package_group(name, packages, includes)
Fungsi ini menentukan kumpulan paket dan menetapkan label ke
grup. Label dapat dirujuk di atribut visibility
.
Grup paket digunakan untuk kontrol visibilitas. Anda dapat memberikan akses ke aturan ke satu atau beberapa grup paket, setiap aturan di seluruh hierarki sumber, atau hanya ke aturan yang dideklarasikan dalam paket yang sama. Untuk deskripsi sistem visibilitas yang lebih mendetail, lihat atribut visibilitas.
Argumen
Atribut | Deskripsi |
---|---|
name |
Nama unik untuk target ini. |
packages |
Enumerasi lengkap paket dalam grup ini. Paket harus dirujuk menggunakan nama lengkapnya, dimulai dengan garis miring ganda. Misalnya, Anda juga dapat menentukan karakter pengganti: spesifikasi
Spesifikasi paket dapat diawali dengan Jika atribut ini tidak ada, grup paket itu sendiri tidak akan berisi paket (tetapi masih dapat menyertakan grup paket lainnya). |
includes |
Grup paket lainnya yang disertakan dalam grup paket ini. Label dalam atribut ini harus merujuk ke grup paket
lain. Paket dalam grup paket yang direferensikan dianggap sebagai bagian dari grup paket ini. Ini bersifat transitif, yaitu jika grup paket |
Contoh
Deklarasi package_group
berikut menentukan
grup paket yang disebut "tropical" 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"], )
export_files
exports_files([label, ...], visibility, licenses)
exports_files()
menentukan daftar file yang termasuk dalam
paket ini yang diekspor ke paket lain.
File BUILD untuk sebuah paket hanya dapat merujuk langsung ke file sumber milik
paket lain jika file tersebut diekspor secara eksplisit dengan
pernyataan exports_files()
. Baca selengkapnya tentang visibilitas file.
Sebagai perilaku lama, file yang juga disebut sebagai input ke aturan diekspor
dengan visibilitas default hingga flag
--incompatible_no_implicit_file_export
dibalik. Namun, perilaku ini tidak boleh diandalkan dan secara aktif
bermigrasi.
Argumen
Argumennya adalah daftar nama file dalam paket saat ini. Deklarasi 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
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 pengujian
data
.
# 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 yang baru, dapat berubah, dan diurutkan. Glob hanya menelusuri file dalam paketnya sendiri, dan hanya mencari file sumber (bukan file yang dihasilkan atau target lain).
Label file sumber disertakan dalam hasil jika jalur relatif paket file
cocok dengan 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 *
: ini cocok dengan substring apa pun di segmen jalur (bahkan substring kosong), tidak termasuk 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 karakter pengganti tersebut 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
(kecualifoo/
merupakan subpaket)foo/a*.htm*
mencocokkan setiap file di 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
cocok dengan 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 nol segmen) 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 (ditetapkan ke 1), file direktori jenis akan dihilangkan dari hasil (default 1).
Jika argumen allow_empty
disetel ke False
, fungsi
glob
akan mengalami error jika hasilnya adalah
daftar kosong.
Ada beberapa batasan dan peringatan penting:
-
Karena
glob()
berjalan selama evaluasi file BUILD,glob()
hanya mencocokkan file dalam hierarki sumber, bukan file yang dihasilkan. Jika Anda membuat target yang memerlukan file sumber dan yang dihasilkan, Anda harus menambahkan daftar eksplisit file yang dihasilkan ke glob. Lihat contoh di bawah dengan:mylib
dan:gen_java_srcs
. -
Jika nama aturan sama dengan file sumber yang cocok, aturan tersebut akan "bayangan" file tersebut.
Untuk memahami hal ini, ingat bahwa
glob()
menampilkan daftar jalur, jadi menggunakanglob()
dalam atribut aturan lainnya' (mis.srcs = glob(["*.cc"])
) memiliki efek yang sama dengan mencantumkan jalur yang cocok secara eksplisit. Jika misalnyaglob()
menghasilkan["Foo.java", "bar/Baz.java"]
, tetapi ada juga aturan dalam paket bernama "Foo.java" (yang diizinkan, meskipun Bazel memperingatkan tentang hal ini), maka konsumenglob()
akan menggunakan aturan "Foo.java" (output-nya) bukan file "Foo.java" Lihat Masalah GitHub #10395 untuk detail selengkapnya. - Globs mungkin cocok dengan file di subdirektori. Dan nama subdirektori mungkin memiliki karakter pengganti. Namun...
-
Label tidak diizinkan melewati batas paket dan glob tidak cocok dengan file dalam sub-paket.
Misalnya, ekspresi glob
**/*.cc
dalam paketx
tidak menyertakanx/y/z.cc
jikax/y
ada sebagai paket (sebagaix/y/BUILD
, atau berada di tempat lain pada jalur paket). Artinya, 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 flag --deleted_packages. - Batasan di atas berlaku untuk semua ekspresi glob, apa pun karakter pengganti yang mereka gunakan.
-
File tersembunyi dengan nama file yang dimulai dengan
.
sepenuhnya cocok dengan karakter pengganti**
dan*
. Jika ingin mencocokkan file tersembunyi dengan pola gabungan, 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 globb yang tidak diperlukan serta konsumsi memori. Untuk mengecualikan direktori tersembunyi, tambahkan direktori tersebut ke argumen "exclude" list. -
Karakter pengganti "**" memiliki satu kasus pojok: pola
"**"
tidak cocok dengan jalur direktori paket. Artinya,glob(["**"], exclude_directories = 0)
cocok dengan semua file dan direktori secara transitif secara ketat di bawah 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) daripada menggunakan pola kosong '*' Nama yang lebih eksplisit menunjukkan dokumentasi mandiri dan memastikan bahwa Anda tidak mencocokkan file cadangan secara tidak sengaja, atau menyimpan file secara otomatis atau emacs/vi/....
Saat menulis aturan build, Anda dapat menghitung elemen glob. Hal ini memungkinkan pembuatan aturan individual untuk setiap input, misalnya. Lihat bagian contoh glob diperluas di bawah ini.
Contoh Glob
Buat library Java yang dibuat dari semua file java dalam 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 dalam data pengujian direktori, kecuali eksperimental.txt. Perhatikan bahwa file dalam subdirektori data pengujian 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
Membuat pengujian bergantung pada semua file txt dalam direktori testdata dan subdirektorinya (serta 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 dalam direktori ini dan semua subdirektori kecuali yang jalurnya menyertakan direktori bernama pengujian. Pola ini harus 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 dalam direktori saat ini yang menghitung jumlah baris di 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 ada dalam paket //foo dan paketnya berisi tiga file yang cocok, a_test.cc, b_test.cc, dan c_test.cc, lalu menjalankan bazel query '//foo:all'
akan mencantumkan semua aturan yang dibuat:
$ 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.
Fungsi ini dapat menggantikan sisi kanan
hampir
penetapan atribut apa pun sehingga nilainya bergantung pada tanda Bazel command line.
Anda dapat menggunakan ini, misalnya, untuk menentukan dependensi khusus platform atau untuk menyematkan resource yang berbeda bergantung pada apakah suatu 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"] }) )
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 "cocok dengan" 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 pemanggilan apa pun.
- Jika beberapa kondisi cocok dan salah satunya adalah spesialisasi dari yang lainnya, spesialisasi tersebut akan diprioritaskan. Kondisi B dianggap sebagai spesialisasi untuk kondisi A jika B memiliki semua tanda dan nilai batasan yang sama seperti A ditambah beberapa tanda atau nilai batasan tambahan. Hal ini juga berarti bahwa resolusi spesialisasi tidak dirancang untuk membuat pengurutan seperti yang ditunjukkan pada Contoh 2 di bawah.
- Jika beberapa kondisi cocok dan salah satunya bukan spesialisasi dari semua kondisi lainnya, Bazel akan gagal dengan error.
- Label semu khusus
//conditions:default
dianggap cocok jika tidak ada kondisi lain yang cocok. Jika kondisi ini terlewat, beberapa aturan lainnya 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.subpaket
subpackages(include, exclude=[], allow_empty=True)
subpackages()
adalah fungsi bantuan, mirip denganglob()
yang mencantumkan sub-paket, bukan file dan direktori. Contoh ini menggunakan pola jalur yang sama denganglob()
dan dapat cocok dengan subpaket apa pun yang merupakan turunan langsung dari file BUILD yang saat ini dimuat. Lihat glob untuk penjelasan mendetail dan contoh pola sertakan dan kecualikan.Daftar sub-paket yang dihasilkan ditampilkan dalam urutan yang diurutkan dan berisi jalur relatif terhadap paket pemuatan saat ini yang cocok dengan pola tertentu dalam
include
dan bukan yang dalamexclude
.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, daripada memanggil fungsi ini secara langsung, sebaiknya gunakan modul 'subpackages'skylib.