Halaman ini membahas cara membuat aturan repositori dan memberikan contoh untuk secara lebih mendetail.
Repositori eksternal adalah aturan yang hanya dapat digunakan
dalam file WORKSPACE
dan memungkinkan operasi non-hermetik pada fase pemuatan
dari Bazel. Setiap aturan repositori eksternal membuat ruang kerjanya sendiri, dengan
file dan artefak BUILD
-nya sendiri. Layanan ini dapat digunakan untuk
bergantung pada ketersediaan pihak ketiga.
library (seperti library terpaket Maven) tetapi juga untuk menghasilkan file BUILD
khusus untuk {i>host<i} yang
dijalankan Bazel.
Pembuatan aturan repositori
Dalam file .bzl
, gunakan fungsi repository_rule untuk membuat aturan repositori baru dan menyimpannya dalam variabel global.
Aturan repositori kustom dapat digunakan seperti aturan repositori native. Ini
memiliki atribut name
wajib dan setiap target yang ada dalam file build-nya
dapat disebut sebagai @<name>//package:target
dengan <name>
adalah nilai
Atribut name
.
Aturan dimuat ketika Anda secara eksplisit membangunnya, atau jika itu adalah dependensi
dari build tersebut. Dalam hal ini, Bazel akan menjalankan fungsi implementation
. Fungsi
ini menjelaskan cara membuat repositori, kontennya, dan file BUILD
.
Atribut
Atribut adalah argumen aturan yang diteruskan sebagai dict ke argumen aturan attrs
.
Atribut dan jenisnya didefinisikan tercantum saat Anda mendefinisikan
aturan repositori. Contoh yang menentukan atribut url
dan sha256
sebagai
strings:
local_repository = repository_rule(
implementation=_impl,
local=True,
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 yang ditentukan secara implisit (seperti aturan
build). Dua atribut implisit adalah name
(sama seperti untuk aturan build) dan
repo_mapping
. Nama aturan repositori dapat diakses dengan
repository_ctx.name
. Arti repo_mapping
sama dengan untuk
aturan repositori native
local_repository
dan
new_local_repository
.
Jika nama atribut diawali dengan _
, nama tersebut bersifat pribadi dan pengguna tidak dapat menetapkannya.
Fungsi penerapan
Setiap aturan repositori memerlukan fungsi implementation
. File ini berisi
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 repositori yang sama. Misalnya,
untuk aturan yang melacak repositori git, hal ini berarti menampilkan
ID commit tertentu, bukan cabang mengambang yang awalnya
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 library untuk mengetahui informasi selengkapnya
konteks tambahan. Contoh:
def _impl(repository_ctx):
repository_ctx.symlink(repository_ctx.attr.path, "")
local_repository = repository_rule(
implementation=_impl,
...)
Kapan fungsi implementasi dieksekusi?
Fungsi implementasi repositori dijalankan saat Bazel memerlukan target dari repositori tersebut, misalnya saat target lain (di repositori lain) bergantung padanya atau jika disebutkan di command line. Fungsi implementasi kemudian diharapkan akan membuat repositori dalam sistem file. Tindakan ini disebut "mengambil" repositori.
Berbeda dengan target reguler, repositori tidak perlu diambil ulang saat terjadi perubahan yang akan menyebabkan repositori menjadi berbeda. Hal ini karena ada hal-hal yang tidak dapat dideteksi perubahannya oleh Bazel atau akan menyebabkan terlalu banyak overhead pada setiap build (misalnya, hal-hal yang diambil dari jaringan). Oleh karena itu, repositori hanya diambil ulang jika salah satu hal berikut berubah:
- Parameter yang diteruskan ke deklarasi repositori di
File
WORKSPACE
. - Kode Starlark yang terdiri dari implementasi repositori.
- Nilai variabel lingkungan apa pun yang dideklarasikan dengan
environ
atributrepository_rule
. Nilai variabel lingkungan ini dapat di-hardwire di command line dengan flag--action_env
(tetapi flag ini akan membatalkan setiap tindakan build). - 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 sync
dieksekusi.
Ada dua parameter repository_rule
yang mengontrol kapan repositori
diambil ulang:
- Jika flag
configure
ditetapkan, repositori hanya diambil ulang padabazel sync
saat parameter--configure
diteruskan (jika tidak ditetapkan, perintah ini tidak akan menyebabkan pengambilan ulang) Jika flag
local
ditetapkan, selain kasus di atas, repositori akan diambil ulang saat server Bazel dimulai ulang atau ketika file apa pun deklarasi repositori berubah (misalnya, fileWORKSPACE
atau file yang dimuat), terlepas dari apakah perubahan tersebut mengakibatkan perubahan pada deklarasi repositori atau kodenya.Repositori non-lokal tidak diambil ulang dalam kasus ini. Hal ini karena repositori ini diasumsikan berkomunikasi dengan jaringan atau harganya mahal.
Memulai ulang fungsi implementasi
Fungsi implementasi dapat dimulai ulang saat repositori sedang diambil jika dependensi yang diminta 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 me-resolve jalur dari string atau label yang dibuat hanya selama eksekusi fungsi mungkin masih menyebabkan mulai ulang.
Memaksa pengambilan ulang repositori eksternal
Terkadang, repositori eksternal dapat menjadi usang tanpa perubahan pada
definisi atau dependensinya. Misalnya, repositori yang mengambil sumber mungkin
mengikuti cabang tertentu dari repositori pihak ketiga, dan commit baru
tersedia di cabang tersebut. Dalam hal ini, Anda dapat meminta bazel untuk mengambil ulang semua
repositori eksternal tanpa syarat dengan memanggil bazel sync
.
Selain itu, beberapa aturan memeriksa komputer lokal dan mungkin menjadi
usang jika komputer lokal diupgrade. Di sini Anda dapat
meminta bazel untuk
hanya mengambil kembali repositori eksternal tersebut
repository_rule
definisi memiliki atribut configure
yang disetel, gunakan bazel sync --configure
.
Contoh
Toolchain C++ yang dikonfigurasi secara otomatis: ia menggunakan aturan repositori 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 yang disebut
@maven
secara default yang menghasilkan target build untuk setiap artefak Maven dalam hierarki dependensi transitif.