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-hermetis pada fase pemuatan
Bazel. Setiap aturan repositori eksternal membuat ruang kerjanya sendiri, dengan
file dan artefak BUILD
-nya sendiri. Library ini dapat digunakan untuk bergantung pada library
pihak ketiga (seperti library yang dikemas Maven), tetapi juga untuk membuat file BUILD
khusus untuk host tempat Bazel berjalan.
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. Atribut ini
memiliki atribut name
wajib dan setiap target yang ada dalam file buildnya
dapat dirujuk sebagai @<name>//package:target
dengan <name>
adalah nilai
atribut name
.
Aturan dimuat saat Anda mem-build-nya secara eksplisit, atau jika merupakan dependensi
build. Dalam hal ini, Bazel akan menjalankan fungsi implementation
-nya. Ini
fungsi yang menjelaskan cara membuat repositori, kontennya, dan file BUILD
.
Atribut
Atribut adalah argumen aturan yang diteruskan sebagai dict ke argumen aturan attrs
.
Atribut dan jenisnya ditentukan dan dicantumkan saat Anda menentukan
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
(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 _
, atribut tersebut bersifat pribadi dan pengguna tidak dapat menyetelnya.
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. 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-hermetis (menemukan biner,
menjalankan biner, membuat file di repositori, atau mendownload file
dari Internet). Lihat library untuk 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 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. Hal ini disebut "pengambilan" repositori.
Berbeda dengan target reguler, repositori tidak harus diambil ulang saat sesuatu yang berubah yang akan menyebabkan repositori menjadi berbeda. Ini adalah karena ada hal-hal yang tidak dapat dideteksi perubahannya atau yang akan menyebabkan terlalu banyak overhead pada setiap build (misalnya, item yang diambil dari jaringan). Oleh karena itu, repositori hanya diambil ulang jika salah satu hal berikut berubah:
- Parameter yang diteruskan ke deklarasi repositori dalam
file
WORKSPACE
. - Kode Starlark yang terdiri dari implementasi repositori.
- Nilai variabel lingkungan apa pun yang diteruskan ke metode
getenv()
repository_ctx
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 sync
dieksekusi.
Ada dua parameter repository_rule
yang mengontrol kapan repositori
diambil ulang:
- Jika tanda
configure
ditetapkan, repositori hanya diambil ulang dibazel sync
saat parameter--configure
diteruskan ke repositori tersebut (jika atribut 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 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 me-resolve jalur dari string atau label yang dibuat hanya selama eksekusi fungsi mungkin masih menyebabkan mulai ulang.
Memaksa pengambilan kembali 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 otomatis: menggunakan aturan repositori untuk membuat file konfigurasi C++ secara otomatis untuk Bazel dengan mencari compiler C++ lokal, lingkungan, dan flag 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 bernama
@maven
secara default yang menghasilkan target build untuk setiap artefak Maven dalam hierarki dependensi transitif.