Halaman ini membahas cara membuat aturan repositori dan memberikan contoh untuk detail selengkapnya.
Repositori eksternal adalah aturan yang hanya dapat digunakan
dalam file WORKSPACE
dan mengaktifkan operasi non-hermetic pada fase pemuatan
Bazel. Setiap aturan repositori eksternal membuat ruang kerja sendiri, dengan
file dan artefak BUILD
miliknya sendiri. 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 oleh 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. Atribut ini
memiliki atribut name
wajib dan setiap target yang ada dalam file build-nya
dapat disebut sebagai @<name>//package:target
dengan <name>
sebagai nilai dari atribut
name
.
Aturan ini dimuat saat Anda secara eksplisit mem-build-nya, atau jika aturan tersebut adalah dependensi
build. Dalam hal ini, Bazel akan menjalankan fungsi implementation
-nya. Fungsi
ini menjelaskan cara membuat repositori, kontennya, dan file BUILD
.
Atribut
Atribut adalah argumen aturan, seperti url
atau sha256
. Anda harus mencantumkan
atribut dan jenisnya saat menetapkan aturan repositori.
local_repository = repository_rule(
implementation=_impl,
local=True,
attrs={"path": attr.string(mandatory=True)})
Untuk mengakses atribut, gunakan repository_ctx.attr.<attribute_name>
.
Semua repository_rule
memiliki atribut yang ditentukan secara implisit (seperti aturan
build). Dua atribut implisitnya adalah name
(sama seperti aturan build) dan
repo_mapping
. Nama aturan repositori dapat diakses dengan
repository_ctx.name
. Arti repo_mapping
sama dengan
aturan repositori native
local_repository
dan
new_local_repository
.
Jika nama atribut dimulai dengan _
, nama atribut tersebut akan bersifat pribadi dan pengguna tidak dapat menyetelnya.
Fungsi implementasi
Setiap aturan repositori memerlukan fungsi implementation
. Project ini berisi logika sebenarnya dari aturan dan dijalankan secara ketat dalam fase Pemuatan.
Fungsi ini memiliki tepat satu parameter input, repository_ctx
. Fungsi ini menampilkan None
untuk menandakan bahwa aturan tersebut dapat direproduksi mengingat parameter yang ditentukan, atau dict dengan serangkaian parameter untuk aturan tersebut yang akan mengubah aturan tersebut menjadi aturan yang dapat direproduksi yang menghasilkan repositori yang sama. Misalnya, untuk aturan yang melacak repositori git, yang berarti menampilkan ID commit tertentu, bukan cabang mengambang yang awalnya ditetapkan.
Parameter input repository_ctx
dapat digunakan untuk
mengakses nilai atribut, dan fungsi non-hermetik (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 dieksekusi saat Bazel memerlukan target dari repositori tersebut, misalnya saat target lain (di repositori lain) bergantung pada repositori atau jika disebutkan dalam baris perintah. Selanjutnya, fungsi implementasi diharapkan untuk membuat repositori dalam sistem file. Ini disebut "mengambil" repositori.
Tidak seperti target reguler, repositori tidak selalu diambil ulang ketika ada sesuatu yang menyebabkan repositori berbeda. Hal ini karena ada hal-hal yang tidak dapat dideteksi oleh Bazel atau akan menyebabkan terlalu banyak overhead pada setiap build (misalnya, hal 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 dideklarasikan dengan atribut
environ
repository_rule
. Nilai variabel lingkungan ini dapat dikaitkan melalui command line dengan flag--action_env
(tetapi flag ini akan membatalkan setiap tindakan build). - Konten file apa pun yang diteruskan ke
read()
,execute()
, dan metode serupa darirepository_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 sana (jika atribut tidak ditetapkan, perintah ini tidak akan menyebabkan pengambilan ulang) Jika flag
local
ditetapkan, selain kasus di atas, repositori juga diambil ulang saat server Bazel dimulai ulang atau saat file apa pun yang memengaruhi deklarasi repositori berubah (misalnya, fileWORKSPACE
atau file yang dimuat), terlepas dari apakah perubahan menghasilkan perubahan pada deklarasi repositori atau kodenya atau tidak.Repositori non-lokal tidak diambil ulang dalam kasus ini. Hal ini dikarenakan repositori ini dianggap dapat terhubung ke jaringan atau memerlukan biaya yang tinggi.
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 diselesaikan, dan fungsi akan dijalankan ulang setelah dependensi diselesaikan. Untuk menghindari mulai ulang yang tidak perlu (yang mahal, karena akses jaringan mungkin harus diulang), argumen label di-prefetch, asalkan semua argumen label dapat diselesaikan ke file yang ada. Perhatikan bahwa menyelesaikan jalur dari string atau label yang dibuat hanya selama eksekusi fungsi masih dapat menyebabkan mulai ulang.
Memaksa pengambilan ulang repositori eksternal
Terkadang, repositori eksternal dapat menjadi usang tanpa perubahan definisi
atau dependensinya. Misalnya, repositori pengambilan repositori 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 mesin lokal dan mungkin menjadi usang jika komputer lokal diupgrade. Di sini, Anda dapat meminta bazel untuk
hanya mengambil ulang repositori eksternal tersebut tempat
definisi repository_rule
telah menetapkan atribut configure
, gunakan bazel sync --configure
.
Contoh
Toolchain yang dikonfigurasi secara otomatis C++: menggunakan aturan repositori untuk otomatis membuat file konfigurasi C++ untuk Bazel dengan mencari compiler C++ lokal, lingkungan, dan flag yang didukung oleh 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.