Aturan Repositori

Laporkan masalahopen_in_new Lihat sumberopen_in_new Per Malam · 7,4 kami. 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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-hermetik pada fase pemuatan dari Bazel. Setiap aturan repositori eksternal membuat ruang kerjanya sendiri, dengan file dan artefak BUILD-nya sendiri. Layanan ini dapat digunakan untuk bergantung pada ketersediaan pihak ketiga. library (seperti library terpaket Maven) tetapi juga untuk menghasilkan file BUILD khusus untuk {i>host<i} yang dijalankan 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. Ini memiliki atribut name wajib dan setiap target yang ada dalam file build-nya dapat disebut sebagai @<name>//package:target dengan <name> adalah nilai Atribut name.

Aturan dimuat ketika Anda secara eksplisit membangunnya, atau jika itu adalah dependensi dari build tersebut. Dalam hal ini, Bazel akan menjalankan fungsi implementation. Fungsi ini menjelaskan cara membuat repositori, kontennya, dan file BUILD.

Atribut

Atribut adalah argumen aturan yang diteruskan sebagai dict ke argumen aturan attrs. Atribut dan jenisnya didefinisikan tercantum saat Anda mendefinisikan 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 (sama 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 _, nama tersebut bersifat pribadi dan pengguna tidak dapat menetapkannya.

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. Misalnya, untuk aturan yang melacak repositori git, hal ini 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 dalam repositori atau mengunduh file dari internet). Lihat library untuk mengetahui informasi selengkapnya konteks tambahan. 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. Tindakan ini disebut "mengambil" repositori.

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

• Parameter yang diteruskan ke deklarasi repositori di File WORKSPACE.
• Kode Starlark yang terdiri dari implementasi repositori.
• Nilai variabel lingkungan apa pun yang dideklarasikan dengan environ atribut repository_rule. Nilai variabel lingkungan ini dapat di-hardwire di command line dengan flag --action_env (tetapi flag ini akan membatalkan setiap tindakan build).
• Konten dari file apa pun yang diteruskan ke read(), execute(), dan sejenisnya metode repository_ctx yang dirujuk oleh label (misalnya, //mypkg:label.txt, tetapi bukan mypkg/label.txt)
• Saat bazel sync dieksekusi.

Ada dua parameter repository_rule yang mengontrol kapan repositori diambil ulang:

• Jika flag configure ditetapkan, repositori hanya diambil ulang pada bazel sync saat parameter --configure diteruskan (jika 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, file WORKSPACE 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 diminta 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 ulang 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 secara otomatis: ia menggunakan aturan repositori untuk secara otomatis membuat file konfigurasi C++ untuk Bazel dengan mencari compiler C++ lokal, dan penanda yang didukung kompilator 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.