Halaman ini membahas cara menentukan aturan repositori dan memberikan contoh untuk secara lebih mendetail.
Repositori eksternal adalah hierarki direktori,
yang berisi file sumber yang dapat digunakan dalam {i>build<i} Bazel, yang dibuat sesuai permintaan oleh
menjalankan aturan repositori yang sesuai. Repositori dapat didefinisikan dalam banyak
tetapi pada akhirnya, setiap repo ditentukan dengan memanggil aturan repo,
target build ditentukan dengan memanggil aturan build. Mereka dapat digunakan
untuk bergantung pada
library pihak ketiga (seperti library paket Maven) tetapi juga untuk menghasilkan
File BUILD
khusus untuk host yang menjalankan Bazel.
Definisi aturan repositori
Dalam file .bzl
, gunakan
fungsi repository_rule untuk menentukan
aturan repo baru dan menyimpannya
dalam variabel global. Setelah aturan repo ditentukan,
dapat dipanggil sebagai fungsi untuk menentukan repo. Pemanggilan ini biasanya
dilakukan dari dalam implementasi ekstensi modul
.
Dua komponen utama dari definisi aturan repo adalah skema atributnya dan implementasi. Skema atribut menentukan nama dan jenis yang diteruskan ke pemanggilan aturan repo, dan fungsi implementasinya dijalankan saat repo perlu diambil.
Atribut
Atribut adalah argumen yang diteruskan ke pemanggilan aturan repo. Skema dari
atribut yang diterima oleh aturan repo ditentukan menggunakan argumen attrs
saat
aturan repo ditentukan dengan panggilan ke repository_rule
. Contoh yang mendefinisikan
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 penerapan, 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 ditentukan secara implisit. Ini adalah
atribut string yang berperilaku aneh: jika ditetapkan sebagai input
pemanggilan aturan repo, diperlukan nama repo yang jelas; tapi ketika dibaca dari
fungsi penerapan aturan repo menggunakan repository_ctx.attr.name
, fungsi ini akan menampilkan
nama repo kanonis.
Fungsi penerapan
Setiap aturan repo memerlukan fungsi implementation
. Isinya adalah
logika aturan yang sebenarnya dan
dijalankan secara ketat pada Fase Pemuatan.
Fungsi ini memiliki tepat satu parameter input, repository_ctx
. {i>Function<i}
menampilkan None
untuk menunjukkan bahwa aturan tersebut dapat direproduksi mengingat
parameter tertentu, atau dict dengan set parameter untuk aturan tersebut
akan mengubah aturan itu menjadi aturan
yang dapat direproduksi yang menghasilkan repo yang sama. Sebagai
misalnya, untuk aturan yang melacak repositori git yang berarti menampilkan
ID commit spesifik, dan bukan cabang mengambang yang awalnya
yang ditentukan.
Parameter input repository_ctx
dapat digunakan untuk
mengakses nilai atribut, dan fungsi
non-hermetik (menemukan biner,
mengeksekusi biner, membuat file dalam repositori atau mengunduh file
dari internet). Lihat dokumen API untuk
konteks yang lebih lengkap. 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 dieksekusi ketika Bazel membutuhkan dari repositori tersebut, misalnya saat target lain (di repo) tergantung padanya atau jika disebutkan pada command line. Tujuan maka fungsi implementasi akan membuat repo dalam file sistem file. Hal ini disebut "pengambilan" repo tersebut.
Berbeda dengan target biasa, repositori tidak harus diambil kembali saat perubahan yang akan menyebabkan repo berbeda. Ini adalah karena ada hal-hal yang tidak bisa dideteksi perubahannya atau yang akan menyebabkan terlalu banyak overhead pada setiap build (misalnya, item yang diambil dari jaringan). Oleh karena itu, repositori diambil ulang hanya jika salah satu hal-hal berikut akan berubah:
- Atribut yang diteruskan ke pemanggilan aturan repo.
- Kode Starlark yang terdiri dari implementasi aturan repo.
- Nilai variabel lingkungan apa pun yang diteruskan ke
repository_ctx
metodegetenv()
atau dideklarasikan dengan atributenviron
darirepository_rule
. Nilai-nilai dari variabel lingkungan ini dapat dihubungkan dengan baris perintah dengan Flag--repo_env
. - Konten dari file apa pun yang diteruskan ke
read()
,execute()
, dan sejenisnya metoderepository_ctx
yang dirujuk oleh 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 flag
configure
ditetapkan, repositori hanya diambil ulang padabazel fetch
saat parameter--configure
diteruskan (jika tidak ditetapkan, perintah ini tidak akan menyebabkan pengambilan ulang) - Jika flag
local
ditetapkan, selain kasus di atas, repo akan diambil kembali saat server Bazel dimulai ulang.
Memulai ulang fungsi implementasi
Fungsi implementasi dapat dimulai ulang saat repo sedang dijalankan 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. Kepada menghindari mulai ulang yang tidak perlu (yang mahal, karena akses jaringan mungkin harus diulang), argumen label di-pengambilan data, asalkan semua argumen label dapat di-resolve menjadi file yang sudah ada. Perhatikan bahwa menyelesaikan jalur dari {i>string<i} atau label yang dibuat hanya selama eksekusi fungsi tersebut masih dapat menyebabkan {i>restart<i}.
Memaksa pengambilan kembali repositori eksternal
Terkadang, repo eksternal bisa menjadi usang tanpa perubahan apa pun pada repositorinya
definisi atau dependensi. Misalnya, sumber pengambilan repo mungkin
mengikuti cabang tertentu dari repositori pihak ketiga, dan commit baru
yang tersedia di cabang itu. 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 komputer lokal dan mungkin menjadi
usang jika komputer lokal di-upgrade. Di sini Anda dapat
meminta Bazel untuk
hanya mengambil kembali repositori eksternal tersebut
repository_rule
definisi memiliki atribut configure
yang disetel, gunakan
bazel fetch --all --configure
.
Contoh
Toolchain C++ yang dikonfigurasi secara otomatis: ia menggunakan aturan repo untuk secara otomatis membuat file konfigurasi C++ untuk Bazel dengan mencari compiler C++ lokal, dan penanda yang didukung kompilator C++.
Repositori Go menggunakan beberapa
repository_rule
untuk menentukan daftar dependensi yang diperlukan untuk menggunakan aturan Go.rules_jvm_external membuat repositori eksternal bernama
@maven
secara default yang menghasilkan target build untuk setiap artefak Maven dalam hierarki dependensi transitif.