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 paling banyak sekali dalam sebuah paket (BUILD file).
Untuk pasangan yang mendeklarasikan metadata yang diterapkan ke setiap aturan di seluruh repositori, gunakan fungsi repo()
dalam file REPO.bazel
di root repo Anda.
Fungsi repo()
mengambil 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. Objek ini biasanya 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 bawah |
features |
String daftar; default-nya adalah Menetapkan berbagai tanda yang memengaruhi semantik file BUILD ini. Fitur ini terutama digunakan oleh orang-orang yang mengerjakan sistem build untuk memberi tag pada paket yang memerlukan penanganan khusus. Jangan gunakan ini kecuali jika diminta secara eksplisit oleh seseorang yang bekerja di sistem build. |
Contoh
Deklarasi di bawah mendeklarasikan bahwa aturan dalam paket ini hanya dapat dilihat oleh anggota grup paket//foo:target
. Deklarasi visibilitas
individu pada aturan, jika ada, akan menggantikan spesifikasi ini.
package(default_visibility = ["//foo:target"])
package_group
package_group(name, packages, includes)
Fungsi ini menentukan kumpulan paket
dan mengaitkan label dengan kumpulan tersebut. Label dapat dirujuk dalam
atribut visibility
.
Grup paket terutama digunakan untuk kontrol visibilitas. Target yang terlihat secara publik dapat direferensikan dari setiap paket di hierarki sumber. Target yang terlihat secara pribadi hanya dapat direferensikan dalam paketnya sendiri (bukan sub-paket). 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 detail tentang sistem visibilitas, lihat atribut visibilitas.
Paket tertentu dianggap berada dalam grup jika cocok dengan
atribut packages
, atau sudah dimuat dalam salah satu grup
paket lain yang disebutkan dalam atribut includes
.
Grup paket secara teknis adalah target, tetapi tidak dibuat oleh aturan, dan tidak memiliki perlindungan visibilitas apa pun.
Argumen
Atribut | Deskripsi |
---|---|
name |
Nama; wajib diisi Nama unik untuk target ini. |
packages |
Daftar string; default-nya adalah Daftar nol atau beberapa spesifikasi paket. 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 yang cocok dengan setidaknya salah satu
spesifikasi positifnya dan tidak satu pun spesifikasi negatifnya
Misalnya, nilai Selain visibilitas publik, tidak ada cara untuk secara langsung menentukan paket di luar repositori saat ini. Jika atribut ini tidak ada, sama dengan menyetelnya ke
daftar kosong, yang juga sama dengan menyetelnya ke daftar yang
hanya berisi Catatan: Sebelum Bazel 6.0, spesifikasi Catatan: Sebelum Bazel 6.0, jika atribut ini diserialisasi sebagai
bagian dari |
includes |
Daftar label; default-nya adalah Grup paket lain yang disertakan dalam paket ini. Label dalam atribut ini harus merujuk ke grup paket lainnya.
Paket dalam grup paket yang direferensikan dianggap menjadi bagian dari
grup paket ini. Ini bersifat transitif — jika grup paket
Saat digunakan bersama dengan spesifikasi paket negasi, perhatikan bahwa kumpulan paket untuk setiap grup akan dihitung secara independen terlebih dahulu, lalu hasilnya digabungkan. Ini berarti bahwa spesifikasi yang diabaikan dalam satu grup tidak memengaruhi spesifikasi di grup lainnya. |
Contoh
Deklarasi package_group
berikut menentukan
grup paket yang disebut "tropis" yang berisi buah 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 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 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 dari lokasi.
Argumen
Argumennya adalah daftar nama file dalam paket saat ini. Deklarasi
visibilitas juga dapat ditentukan; dalam hal ini, file akan
terlihat oleh target yang telah 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 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 relatif paket file
cocok dengan pola include
mana pun dan tidak dengan
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 dalam pola dicocokkan dengan segmen jalur. 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 ini (kecualifoo/
adalah sub-paket)foo/*.txt
cocok dengan setiap file dalam direktorifoo/
jika file diakhiri dengan.txt
(kecualifoo/
adalah sub-paket)foo/a*.htm*
cocok dengan setiap file dalam direktorifoo/
yang dimulai dengana
, kemudian memiliki string arbitrer (bisa kosong), kemudian memiliki.htm
, dan diakhiri dengan string arbitrer lainnya (kecualifoo/
adalah sub-paket); sepertifoo/axx.htm
danfoo/a.html
ataufoo/axxx.html
foo/*
cocok dengan setiap file dalam direktorifoo/
, (kecualifoo/
adalah sub-paket); tidak cocok dengan direktorifoo
itu sendiri meskipunexclude_directories
ditetapkan ke 0foo/**
cocok dengan setiap file di setiap subdirektori non-subpaket dalam subdirektori tingkat pertama paketfoo/
; jikaexclude_directories
ditetapkan ke 0, direktorifoo
itu sendiri juga cocok dengan pola; dalam hal ini,**
dianggap cocok dengan segmen jalur nol**/a.txt
cocok dengan filea.txt
dalam direktori paket ini serta subdirektori non-sub-paket.**/bar/**/*.txt
cocok dengan setiap file.txt
di setiap subdirektori non-subpaket dari paket ini, jika setidaknya satu direktori di jalur yang dihasilkan dipanggilbar
, 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 non-sub-paket dari paket inifoo**/a.txt
adalah pola yang tidak valid, karena**
harus berdiri sendiri sebagai segmenfoo/
adalah pola yang tidak valid karena segmen kedua yang ditentukan setelah/
adalah string kosong
Jika argumen exclude_directories
diaktifkan (ditetapkan 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 mencocokkan file dalam hierarki sumber Anda, bukan pernah menghasilkan file. Jika akan membuat target yang memerlukan file 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 akan "membayangi" file tersebut.
Untuk memahami hal ini, ingat bahwa
glob()
menampilkan daftar jalur, sehingga menggunakanglob()
di atribut aturan lain (misalnyasrcs = 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 yang disebut "Foo.java" (yang diizinkan, meskipun Bazel memperingatkan tentang hal itu), konsumenglob()
akan menggunakan aturan "Foo.java" (output-nya) bukan file "Foo.java". Lihat masalah GitHub #10395 untuk detail selengkapnya. - Globs bisa cocok dengan file yang ada di subdirektori. Selain itu, nama subdirektori mungkin menggunakan karakter pengganti. Namun...
-
Label tidak diizinkan untuk 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 sebuah paket (baik sebagaix/y/BUILD
, atau di tempat lain pada package-path). Artinya, hasil ekspresi glob sebenarnya bergantung pada keberadaan file BUILD — yaitu, ekspresi glob yang sama akan menyertakanx/y/z.cc
jika tidak ada paket yang disebutx/y
atau ditandai sebagai dihapus menggunakan flag --deleted_packages. - Pembatasan di atas berlaku untuk semua ekspresi glob, apa pun karakter pengganti yang digunakan.
-
File tersembunyi dengan nama file yang dimulai dengan
.
sepenuhnya dicocokkan dengan karakter pengganti**
dan*
. Jika Anda ingin mencocokkan file tersembunyi dengan pola gabungan, pola Anda harus diawali dengan.
. Misalnya,*
dan.*.txt
akan cocok dengan.foo.txt
, tetapi*.txt
tidak. Direktori tersembunyi juga dicocokkan dengan cara yang sama. Direktori tersembunyi dapat mencakup file yang tidak diperlukan sebagai input, dan dapat meningkatkan jumlah file glob yang tidak perlu serta konsumsi memori. Untuk mengecualikan direktori tersembunyi, tambahkan direktori tersebut ke argumen daftar "exclude". -
Karakter pengganti "**" memiliki satu kasus sudut: pola
"**"
tidak cocok dengan jalur direktori paket. Dengan kata lain,glob(["**"], exclude_directories = 0)
cocok dengan semua file dan direktori secara transitif secara ketat 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 menyediakan ekstensi yang sesuai (misalnya *.html), bukan menggunakan '*' sederhana untuk pola glob. Nama yang lebih eksplisit mendokumentasikan diri sendiri dan memastikan bahwa Anda tidak mencocokkan file cadangan secara tidak sengaja, atau file disimpan otomatis 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 yang diperluas di bawah.
Contoh Glob
Buat library Java yang dibangun 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 direktori data pengujian, kecuali experiment.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
Buat pengujian bergantung pada semua file txt dalam direktori data pengujian serta subdirektorinya (beserta subdirektorinya, dan sebagainya). Subdirektori yang berisi file BUILD akan diabaikan. (Lihat batasan dan peringatan di atas.)
sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob(["testdata/**/*.txt"]), )
Buat library yang di-build 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 dan juga 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 tersebut berisi tiga file
yang cocok, a_test.cc, b_test.cc, dan c_test.cc, 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 helper yang membuat atribut aturan
dapat dikonfigurasi.
Atribut ini dapat menggantikan sisi kanan
hampir
penetapan atribut sehingga nilainya bergantung pada flag Bazel command line.
Anda dapat menggunakannya, misalnya, untuk menentukan dependensi khusus platform atau
menyematkan resource yang berbeda, bergantung pada apakah aturan dibuat dalam mode "developer"
vs. "rilis".
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 "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 diutamakan. Kondisi B dianggap sebagai spesialisasi kondisi A jika B memiliki semua tanda dan nilai batasan yang sama dengan A, ditambah beberapa tanda atau nilai batasan tambahan. Ini juga berarti bahwa penyelesaian spesialisasi tidak dirancang untuk membuat pengurutan seperti yang ditunjukkan pada Contoh 2 di bawah.
- Jika beberapa kondisi cocok dan salah satunya bukan merupakan spesialisasi dari kondisi lainnya, Bazel akan gagal dengan menampilkan error, kecuali jika semua kondisi diselesaikan dengan nilai yang sama.
- Label-pseudo khusus
//conditions:default
dianggap cocok jika tidak ada kondisi lain yang cocok. Jika kondisi ini diabaikan, 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 atribut, tetapi tidak semua. Atribut yang tidak kompatibel ditandai sebagainonconfigurable
dalam dokumentasinya.sub-paket
subpackages(include, exclude=[], allow_empty=True)
subpackages()
adalah fungsi bantuan, mirip denganglob()
yang mencantumkan sub-paket, bukan file dan direktori. Class ini menggunakan pola jalur yang sama denganglob()
dan dapat cocok dengan subpaket apa pun yang merupakan turunan langsung dari file BUILD yang sedang dimuat. Lihat glob untuk mengetahui penjelasan mendetail dan contoh pola sertakan dan pengecualian.Daftar subpaket yang dihasilkan ditampilkan dalam urutan yang diurutkan dan berisi jalur yang relatif terhadap paket pemuatan saat ini yang cocok dengan pola yang diberikan di
include
dan bukan yang ada diexclude
.Contoh
Contoh berikut mencantumkan semua subpaket langsung untuk paket
foo/BUILD
# The following BUILD files exist: # foo/BUILD # foo/bar/baz/BUILD # foo/bar/but/bad/BUILD # foo/sub/BUILD # foo/sub/deeper/BUILD # # In foo/BUILD a call to subs1 = subpackages(include = ["**"]) # results in subs1 == ["sub", "bar/baz", "bar/but/bad"] # # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of # 'foo' subs2 = subpackages(include = ["bar/*"]) # results in subs2 = ["bar/baz"] # # Since 'bar' is not a subpackage itself, this looks for any subpackages under # all first level subdirectories of 'bar'. subs3 = subpackages(include = ["bar/**"]) # results in subs3 = ["bar/baz", "bar/but/bad"] # # Since bar is not a subpackage itself, this looks for any subpackages which are # (1) under all subdirectories of 'bar' which can be at any level, (2) not a # subpackage of another subpackages. subs4 = subpackages(include = ["sub"]) subs5 = subpackages(include = ["sub/*"]) subs6 = subpackages(include = ["sub/**"]) # results in subs4 and subs6 being ["sub"] # results in subs5 = []. # # In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a # subpackage of 'foo'). # In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since # 'foo/sub' is already a subpackage itself, the subdirectories will not be # traversed anymore. # In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it # is returned. But the subdirectories of 'foo/sub' will not be traversed # anymore.
Secara umum, lebih baik pengguna menggunakan modul 'sub-paket' skylib daripada memanggil fungsi ini secara langsung.