Aturan Repositori

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

Repositori eksternal adalah aturan yang hanya dapat digunakan dalam file WORKSPACE dan memungkinkan operasi non-hermetik pada fase pemuatan Bazel. Setiap aturan repositori eksternal membuat ruang kerjanya sendiri, dengan file dan artefak BUILD miliknya sendiri. Aturan ini 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.

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 bawaan. Aturan ini memiliki atribut name wajib dan setiap target yang ada dalam file build-nya dapat dirujuk sebagai @<name>//package:target dengan <name> adalah nilai atribut name.

Aturan dimuat saat Anda mem-build-nya secara eksplisit, atau jika aturan tersebut adalah dependensi build. Dalam hal ini, Bazel akan menjalankan fungsi implementation. 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 menentukan 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 implisit adalah name (seperti untuk aturan build) dan repo_mapping. Nama aturan repositori dapat diakses dengan repository_ctx.name. Arti repo_mapping sama dengan aturan repositori bawaan local_repository dan new_local_repository.

Jika nama atribut dimulai dengan _, atribut tersebut bersifat pribadi dan pengguna tidak dapat menetapkannya.

Fungsi penerapan

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

Fungsi ini memiliki tepat satu parameter input, repository_ctx. Fungsi ini menampilkan None untuk menunjukkan 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 repositori 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 library 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 dijalankan?

Jika repositori dideklarasikan sebagai local, perubahan dalam dependensi di grafik dependensi (termasuk file WORKSPACE itu sendiri) akan menyebabkan eksekusi fungsi penerapan.

Fungsi penerapan dapat dimulai ulang jika dependensi yang dimintanya tidak ada. Awal fungsi penerapan akan dieksekusi ulang setelah dependensi diselesaikan. Untuk menghindari memulai ulang yang tidak perlu (yang mahal, karena akses jaringan mungkin harus diulang), argumen label diambil terlebih dahulu, asalkan semua argumen label dapat diselesaikan ke file yang ada. Perhatikan bahwa menyelesaikan jalur dari string atau label yang dibuat hanya selama eksekusi fungsi mungkin masih menyebabkan memulai ulang.

Terakhir, untuk repositori non-local, hanya perubahan pada dependensi berikut yang dapat menyebabkan memulai ulang:

• File .bzl yang diperlukan untuk menentukan aturan repositori.
• Deklarasi aturan repositori dalam file WORKSPACE.
• Nilai variabel lingkungan apa pun yang dideklarasikan dengan environ atribut dari repository_rule fungsi. Nilai variabel lingkungan tersebut dapat diterapkan dari command line dengan --action_env flag (tetapi flag ini akan membatalkan setiap tindakan build).
• Konten file apa pun yang digunakan dan dirujuk oleh label (misalnya, //mypkg:label.txt, bukan mypkg/label.txt).

Memaksa pengambilan ulang repositori 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 repositori eksternal tanpa syarat dengan memanggil bazel sync.

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

Contoh

• Rantai alat 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 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.