Aturan Repositori

Tiap hari · 9.2 · 9.1 · 9.0 · 8.7 · 8.6

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

Repositori eksternal adalah struktur direktori, yang berisi file sumber yang dapat digunakan dalam build Bazel, yang dibuat sesuai permintaan dengan menjalankan aturan repo yang sesuai. Repositori dapat ditentukan dalam berbagai cara, tetapi pada akhirnya, setiap repositori ditentukan dengan memanggil aturan repositori, sama seperti target build ditentukan dengan memanggil aturan build. File 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.

Definisi aturan repositori

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

Dua komponen utama definisi aturan repositori adalah skema atribut dan fungsi implementasinya. Skema atribut menentukan nama dan jenis atribut yang diteruskan ke pemanggilan aturan repositori, dan fungsi implementasi dijalankan saat repositori perlu diambil.

Atribut

Atribut adalah argumen yang diteruskan ke pemanggilan aturan repositori. Skema atribut yang diterima oleh aturan repositori ditentukan menggunakan argumen attrs saat aturan repositori 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 repositori, atribut ini mengambil nama repositori yang jelas; tetapi saat dibaca dari fungsi penerapan aturan repositori menggunakan repository_ctx.attr.name, atribut ini akan menampilkan nama repositori kanonis.

Fungsi penerapan

Setiap aturan repositori memerlukan fungsi implementation. Bagian ini berisi logika sebenarnya dari aturan dan dijalankan secara ketat dalam Fase Pemuatan.

Fungsi ini memiliki tepat satu parameter input, repository_ctx. Fungsi menampilkan None untuk menandakan bahwa aturan dapat direproduksi dengan 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, hal itu 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 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 repositori dijalankan 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 membuat repositori dalam sistem file. Tindakan ini disebut "mengambil" repositori.

Berbeda dengan target reguler, repositori tidak perlu diambil ulang saat sesuatu berubah yang akan menyebabkan repositori menjadi berbeda. Hal ini karena ada hal-hal yang perubahannya tidak dapat dideteksi oleh Bazel atau akan menyebabkan terlalu banyak overhead pada setiap build (misalnya, hal-hal yang diambil dari jaringan). Oleh karena itu, repositori diambil ulang hanya jika salah satu hal berikut berubah:

  • Atribut yang diteruskan ke pemanggilan aturan repositori.
  • Kode Starlark yang terdiri dari penerapan aturan repositori.
  • Nilai variabel lingkungan apa pun yang diteruskan ke metode getenv() repository_ctx atau dideklarasikan dengan atribut environ dari repository_rule. Nilai variabel lingkungan ini dapat ditetapkan secara permanen di command line dengan tanda --repo_env.
  • Keberadaan, konten, dan jenis jalur apa pun yang watched dalam fungsi penerapan aturan repositori.
    • Metode repository_ctx lainnya dengan parameter watch tertentu, 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 tanda configure ditetapkan, repositori akan diambil ulang pada bazel fetch --force --configure (repositori non-configure tidak diambil ulang).
  • Jika tanda local disetel, selain kasus di atas, repositori juga akan diambil ulang saat server Bazel dimulai ulang.

Memaksa pengambilan ulang repo eksternal

Terkadang, repositori eksternal dapat menjadi tidak berlaku tanpa ada 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 repo eksternal tanpa syarat dengan memanggil bazel fetch --force --all.

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

Contoh

  • Toolchain yang dikonfigurasi otomatis C++: menggunakan aturan repositori untuk membuat file konfigurasi C++ secara otomatis 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 bernama @maven secara default yang menghasilkan target build untuk setiap artefak Maven dalam hierarki dependensi transitif.