Halaman ini membahas cara menentukan aturan repositori dan memberikan contoh untuk detail lebih lanjut.
Repositori eksternal adalah hierarki direktori,
yang berisi file sumber yang dapat digunakan dalam build Bazel, yang dihasilkan sesuai permintaan dengan
menjalankan aturan repo yang sesuai. Repo dapat ditentukan dalam banyak cara, tetapi pada akhirnya, setiap repo ditentukan dengan memanggil aturan repo, sama seperti target build ditentukan dengan memanggil aturan build. Library ini dapat digunakan untuk bergantung pada
library pihak ketiga (seperti library paket Maven), tetapi juga untuk menghasilkan
file BUILD
khusus untuk host yang dijalankan Bazel.
Definisi aturan repositori
Dalam file .bzl
, gunakan fungsi repository_rule untuk menentukan aturan repo baru dan menyimpannya dalam variabel global. Setelah ditentukan, aturan repo dapat dipanggil sebagai fungsi untuk menentukan repo. Pemanggilan ini biasanya dilakukan dari dalam fungsi implementasi ekstensi modul.
Dua komponen utama dari definisi aturan repo adalah skema atribut dan fungsi implementasinya. Skema atribut menentukan nama dan jenis atribut yang diteruskan ke pemanggilan aturan repo, dan fungsi implementasi dijalankan saat repo perlu diambil.
Atribut
Atribut adalah argumen yang diteruskan ke pemanggilan aturan repo. Skema atribut yang diterima oleh aturan repo ditentukan menggunakan argumen attrs
saat aturan repo ditentukan dengan panggilan ke repository_rule
. Contoh yang menentukan
atribut url
dan sha256
sebagai string:
http_archive = repository_rule(
implementation=_impl,
attrs={
"url": attr.string(mandatory=True)
"sha256": attr.string(mandatory=True)
}
)
Untuk mengakses atribut dalam fungsi implementasi, gunakan
repository_ctx.attr.<attribute_name>
:
def _impl(repository_ctx):
url = repository_ctx.attr.url
checksum = repository_ctx.attr.sha256
Semua repository_rule
memiliki atribut name
yang ditetapkan secara implisit. Ini adalah
atribut string yang berperilaku cukup ajaib: saat ditetapkan sebagai input ke
pemanggilan aturan repo, nama repo yang jelas akan ditampilkan; tetapi saat dibaca dari
fungsi implementasi aturan repo menggunakan repository_ctx.attr.name
, nama repo kanonis akan ditampilkan.
Fungsi penerapan
Setiap aturan repo memerlukan fungsi implementation
. Fungsi ini berisi
logika aturan yang sebenarnya dan dieksekusi secara ketat dalam Fase Pemuatan.
Fungsi ini memiliki tepat satu parameter input, repository_ctx
. Fungsi ini
menampilkan None
untuk menunjukkan bahwa aturan dapat direproduksi dengan
parameter yang ditentukan, atau dikte dengan kumpulan parameter untuk aturan tersebut yang
akan mengubah aturan tersebut menjadi aturan yang dapat direproduksi dan menghasilkan repo yang sama. Misalnya, untuk aturan yang melacak repositori git yang berarti menampilkan ID commit tertentu, bukan cabang mengambang yang awalnya ditentukan.
Parameter input repository_ctx
dapat digunakan untuk mengakses nilai atribut, dan fungsi non-hermetic (menemukan biner, mengeksekusi biner, membuat file di repositori, atau mendownload file dari Internet). Lihat dokumen API untuk mengetahui konteks selengkapnya. Contoh:
def _impl(repository_ctx):
repository_ctx.symlink(repository_ctx.attr.path, "")
local_repository = repository_rule(
implementation=_impl,
...)
Kapan fungsi implementasi dieksekusi?
Fungsi implementasi aturan repo dijalankan saat Bazel memerlukan target dari repositori tersebut, misalnya saat target lain (dalam repo lain) bergantung padanya atau jika disebutkan dalam command line. Fungsi implementasi selanjutnya diharapkan untuk membuat repo dalam sistem file. Tindakan ini disebut "mengambil" repo.
Berbeda dengan target reguler, repo belum tentu diambil ulang ketika sesuatu berubah yang akan menyebabkan repo menjadi berbeda. Hal ini karena ada hal-hal yang perubahannya tidak dapat dideteksi oleh Bazel atau akan menyebabkan terlalu banyak overhead pada setiap build (misalnya, hal-hal yang diambil dari jaringan). Oleh karena itu, repo hanya diambil ulang jika salah satu dari hal berikut berubah:
- Atribut yang diteruskan ke pemanggilan aturan repo.
- Kode Starlark yang berisi penerapan aturan repo.
- Nilai variabel lingkungan apa pun yang diteruskan ke metode
getenv()
repository_ctx
atau dideklarasikan dengan atributenviron
repository_rule
. Nilai variabel lingkungan ini dapat terhubung ke command line dengan flag--repo_env
. - Konten dari setiap file yang diteruskan ke
read()
,execute()
, dan metode serupa darirepository_ctx
yang dirujuk dengan label (misalnya,//mypkg:label.txt
, tetapi bukanmypkg/label.txt
) - Saat
bazel fetch --force
dieksekusi.
Ada dua parameter repository_rule
yang mengontrol kapan repositori
diambil ulang:
- Jika tanda
configure
ditetapkan, repositori hanya diambil ulang padabazel fetch
saat parameter--configure
diteruskan ke properti tersebut (jika atribut tidak disetel, perintah ini tidak akan menyebabkan pengambilan ulang) - Jika flag
local
ditetapkan, selain kasus di atas, repo juga akan diambil ulang saat server Bazel dimulai ulang.
Memulai ulang fungsi implementasi
Fungsi penerapan dapat dimulai ulang saat repo sedang diambil jika dependensi yang dimintanya tidak ada. Dalam hal ini, eksekusi fungsi implementasi akan berhenti, dependensi yang hilang akan diselesaikan, dan fungsi akan dieksekusi kembali setelah dependensi diselesaikan. Untuk menghindari mulai ulang yang tidak perlu (yang mahal, karena akses jaringan mungkin harus diulang), argumen label akan diambil data terlebih dahulu, asalkan semua argumen label dapat di-resolve ke file yang ada. Perhatikan bahwa penyelesaian jalur dari string atau label yang dibuat hanya selama eksekusi fungsi masih dapat menyebabkan mulai ulang.
Memaksa pengambilan ulang repositori eksternal
Terkadang, repo eksternal dapat usang tanpa ada perubahan pada
definisi atau dependensinya. Misalnya, sumber pengambilan repo mungkin
mengikuti cabang tertentu dari repositori pihak ketiga, dan commit baru tersedia
di cabang tersebut. Dalam hal ini, Anda dapat meminta bazel untuk mengambil kembali semua repositori eksternal tanpa syarat dengan memanggil bazel fetch --force --all
.
Selain itu, beberapa aturan repo memeriksa mesin lokal dan mungkin menjadi usang jika mesin lokal diupgrade. Di sini, Anda dapat meminta Bazel untuk
hanya mengambil kembali repositori eksternal tersebut dengan definisi
repository_rule
memiliki kumpulan atribut configure
, gunakan
bazel fetch --all --configure
.
Contoh
Toolchain yang dikonfigurasi secara otomatis C++: alat ini menggunakan aturan repo untuk membuat file konfigurasi C++ secara otomatis untuk Bazel dengan mencari compiler C++ lokal, lingkungan, dan tanda yang didukung compiler C++.
Repositori Go menggunakan beberapa
repository_rule
untuk menentukan daftar dependensi yang diperlukan untuk menggunakan aturan Go.rules_jvm_external membuat repositori eksternal yang disebut
@maven
secara default, yang menghasilkan target build untuk setiap artefak Maven dalam hierarki dependensi transitif.