Aturan Repositori

Halaman ini membahas cara menentukan aturan repositori dan memberikan contoh untuk mengetahui detail selengkapnya.

Repositori eksternal adalah pohon direktori, yang berisi file sumber yang dapat digunakan dalam build Bazel, yang dibuat sesuai permintaan dengan menjalankan aturan repo yang sesuai. Repos dapat ditentukan dengan berbagai cara, tetapi pada akhirnya, setiap repo ditentukan dengan memanggil aturan repo, sama seperti target build yang ditentukan dengan memanggil aturan build. Repos dapat digunakan untuk bergantung pada library pihak ketiga (seperti library yang dikemas Maven), tetapi juga untuk membuat file BUILD yang khusus untuk host tempat Bazel berjalan.

Definisi aturan repositori

Dalam file .bzl, gunakan fungsi repository_rule untuk menentukan aturan repo baru dan menyimpannya dalam variabel global. Setelah aturan repo ditentukan, aturan tersebut dapat dipanggil sebagai fungsi untuk menentukan repo. Pemanggilan ini biasanya dilakukan dari dalam fungsi penerapan ekstensi modul.

Dua komponen utama definisi aturan repo adalah skema atribut dan fungsi penerapan. Skema atribut menentukan nama dan jenis atribut yang diteruskan ke pemanggilan aturan repo, dan fungsi penerapan 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 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 agak ajaib: saat ditentukan sebagai input ke pemanggilan aturan repo, atribut ini mengambil nama repo yang jelas; tetapi saat dibaca dari fungsi penerapan aturan repo menggunakan repository_ctx.attr.name, atribut ini menampilkan nama repo kanonis.

Fungsi penerapan

Setiap aturan repo memerlukan fungsi implementation. Fungsi ini berisi logika sebenarnya dari aturan dan dieksekusi secara ketat dalam Fase Pemuatan.

Fungsi ini memiliki tepat satu parameter input, repository_ctx. Fungsi ini menampilkan None untuk menandakan bahwa aturan dapat direproduksi dengan parameter yang ditentukan, atau dict dengan kumpulan parameter untuk aturan yang akan mengubah aturan tersebut menjadi aturan yang dapat direproduksi yang menghasilkan repo yang sama. Misalnya, untuk aturan yang melacak repositori Git, hal ini berarti menampilkan ID commit tertentu, bukan cabang floating yang awalnya ditentukan.

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 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 penerapan dieksekusi?

Fungsi penerapan aturan repo dieksekusi saat Bazel memerlukan target dari repositori tersebut, misalnya saat target lain (di repo lain) bergantung padanya atau jika disebutkan di command line. Fungsi penerapan kemudian diharapkan untuk membuat repo dalam sistem file. Hal ini disebut "mengambil" repo.

Berbeda dengan target reguler, repo tidak selalu diambil ulang saat ada perubahan yang akan menyebabkan repo menjadi berbeda. Hal ini karena ada hal-hal yang Bazel tidak dapat mendeteksi perubahannya 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 hal berikut berubah:

• Atribut yang diteruskan ke pemanggilan aturan repo.
• Kode Starlark yang terdiri dari penerapan aturan repo.
• Nilai variabel lingkungan apa pun yang diteruskan ke repository_ctx's getenv() metode atau dideklarasikan dengan atribut environ dari repository_rule. Nilai variabel lingkungan ini dapat dikodekan secara permanen di command line dengan --repo_env flag.
• Keberadaan, konten, dan jenis jalur apa pun yang di- watched dalam implementasi fungsi aturan repo.
  • Metode repository_ctx lainnya dengan parameter watch, seperti read(), execute(), dan extract(), juga dapat menyebabkan jalur dipantau.
  • Demikian pula, repository_ctx.watch_tree dan path.readdir dapat menyebabkan jalur dipantau dengan cara lain.
• Saat bazel fetch --force dieksekusi.

Ada dua parameter repository_rule yang mengontrol kapan repositori diambil ulang:

• Jika flag configure ditetapkan, repositori akan diambil ulang di bazel fetch --force --configure (repositori non-configure tidak diambil ulang).
• Jika flag local ditetapkan, selain kasus di atas, repo juga diambil ulang saat server Bazel dimulai ulang.

Memaksa pengambilan ulang repo eksternal

Terkadang, repo eksternal dapat menjadi tidak berlaku tanpa ada perubahan pada definisi atau dependensinya. Misalnya, repo 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 repo eksternal tanpa syarat dengan memanggil bazel fetch --force --all.

Selain itu, beberapa aturan repo memeriksa mesin lokal dan mungkin menjadi tidak berlaku jika mesin lokal diupgrade. Di sini, Anda dapat meminta Bazel untuk hanya mengambil ulang repo eksternal yang definisi repository_rule memiliki atribut configure yang ditetapkan, gunakan bazel fetch --force --configure.

Contoh

• Rantai alat yang dikonfigurasi otomatis C++: menggunakan aturan repo untuk otomatis membuat file konfigurasi C++ 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 yang disebut @maven secara default yang menghasilkan target build untuk setiap artefak Maven di pohon dependensi transitif.