Ringkasan dependensi eksternal

Laporkan masalah Lihat sumber Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bazel mendukung dependensi eksternal, file sumber (teks dan biner) yang digunakan dalam build Anda yang bukan dari ruang kerja Anda. Misalnya, file tersebut dapat berupa kumpulan aturan yang dihosting di repositori GitHub, artefak Maven, atau direktori di komputer lokal Anda di luar ruang kerja saat ini.

Mulai Bazel 6.0, ada dua cara untuk mengelola dependensi eksternal dengan Bazel: sistem WORKSPACE tradisional yang berfokus pada repositori, dan sistem MODULE.bazel yang lebih baru dan berfokus pada modul (bernama kode Bzlmod, dan diaktifkan dengan tanda --enable_bzlmod). Kedua sistem dapat digunakan bersama, tetapi Bzlmod akan menggantikan sistem WORKSPACE dalam rilis Bazel mendatang. Lihat panduan migrasi Bzlmod untuk mengetahui cara bermigrasi.

Dokumen ini menjelaskan konsep seputar pengelolaan dependensi eksternal di Bazel, sebelum membahas lebih detail kedua sistem secara berurutan.

Konsep

Repositori

Direktori dengan file WORKSPACE atau WORKSPACE.bazel, yang berisi file sumber yang akan digunakan dalam build Bazel. Sering disingkat menjadi repo.

Repositori utama

Repositori tempat perintah Bazel saat ini dijalankan.

Ruang kerja

Lingkungan yang digunakan oleh semua perintah Bazel berjalan di repositori utama yang sama.

Perhatikan bahwa secara historis, konsep "repositori" dan "ruang kerja" telah disamakan; istilah "ruang kerja" sering digunakan untuk merujuk ke repositori utama, dan terkadang bahkan digunakan sebagai sinonim dari "repositori".

Nama repositori kanonis

Nama kanonis yang dapat digunakan untuk mengakses repositori. Dalam konteks ruang kerja, setiap repositori memiliki satu nama kanonis. Target di dalam repo yang nama kanonisnya adalah canonical_name dapat diakses dengan label @@canonical_name//pac/kage:target (perhatikan @ ganda).

Repositori utama selalu memiliki string kosong sebagai nama kanonis.

Nama repositori yang terlihat

Nama repositori yang dapat diakses dalam konteks repositori lain tertentu. Ini dapat dianggap sebagai "nama panggilan" repo: Repo dengan nama kanonis michael mungkin memiliki nama yang terlihat mike dalam konteks repo alice, tetapi mungkin memiliki nama yang terlihat mickey dalam konteks repo bob. Dalam hal ini, target di dalam michael dapat diatasi dengan label @mike//pac/kage:target dalam konteks alice (perhatikan @ tunggal).

Sebaliknya, ini dapat dipahami sebagai pemetaan repositori: setiap repositori mempertahankan pemetaan dari "nama repositori yang terlihat" ke "nama repositori kanonis".

Aturan repositori

Skema untuk definisi repositori yang memberi tahu Bazel cara mewujudkan repositori. Misalnya, "download arsip zip dari URL tertentu dan ekstrak", atau "ambil artefak Maven tertentu dan sediakan sebagai target java_import", atau cukup "buat symlink direktori lokal". Setiap repo ditentukan dengan memanggil aturan repo dengan jumlah argumen yang sesuai.

Lihat Aturan repositori untuk mengetahui informasi selengkapnya tentang cara menulis aturan repositori Anda sendiri.

Aturan repo yang paling umum adalah http_archive, yang mendownload arsip dari URL dan mengekstraknya, serta local_repository, yang membuat symlink direktori lokal yang sudah menjadi repositori Bazel.

Mengambil repositori

Tindakan membuat repo tersedia di disk lokal dengan menjalankan aturan repo terkaitnya. Repositori yang ditentukan di ruang kerja tidak tersedia di disk lokal sebelum diambil.

Biasanya, Bazel hanya mengambil repo saat memerlukan sesuatu dari repo, dan repo belum diambil. Jika repo sudah diambil sebelumnya, Bazel hanya mengambilnya kembali jika definisinya telah berubah.

Tata letak direktori

Setelah diambil, repo dapat ditemukan di subdirektori external di output base, dengan nama kanonisnya.

Anda dapat menjalankan perintah berikut untuk melihat konten repositori dengan nama kanonis canonical_name:

ls $(bazel info output_base)/external/ canonical_name

Mengelola dependensi eksternal dengan Bzlmod

Bzlmod, subsistem dependensi eksternal baru, tidak berfungsi langsung dengan definisi repo. Sebagai gantinya, alat ini membuat grafik dependensi dari modul, menjalankan ekstensi di atas grafik, dan menentukan repositori yang sesuai.

Modul Bazel adalah project Bazel yang dapat memiliki beberapa versi, yang masing-masing memublikasikan metadata tentang modul lain yang menjadi dependensinya. Modul harus memiliki file MODULE.bazel di root repositorinya, di samping file WORKSPACE. File ini adalah manifes modul, yang menyatakan nama, versi, daftar dependensi, dan informasi lainnya. Berikut adalah contoh dasar:

module(name = "my-module", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

Modul hanya boleh mencantumkan dependensi langsungnya, yang dicari Bzlmod di registry Bazel — secara default, Bazel Central Registry. Registry menyediakan file MODULE.bazel dependensi, yang memungkinkan Bazel menemukan seluruh grafik dependensi transitif sebelum melakukan penyelesaian versi.

Setelah penyelesaian versi, yang memilih satu versi untuk setiap modul, Bazel akan berkonsultasi dengan registry lagi untuk mempelajari cara menentukan repo untuk setiap modul (dalam sebagian besar kasus, menggunakan http_archive).

Modul juga dapat menentukan potongan data yang disesuaikan yang disebut tag, yang digunakan oleh ekstensi modul setelah penyelesaian modul untuk menentukan repositori tambahan. Ekstensi ini memiliki kemampuan yang mirip dengan aturan repo, sehingga memungkinkan mereka melakukan tindakan seperti I/O file dan mengirim permintaan jaringan. Selain itu, mereka memungkinkan Bazel berinteraksi dengan sistem pengelolaan paket lain sekaligus mematuhi grafik dependensi yang dibuat dari modul Bazel.

Menentukan repositori dengan WORKSPACE

Secara historis, Anda dapat mengelola dependensi eksternal dengan menentukan repositori dalam file WORKSPACE (atau WORKSPACE.bazel). File ini memiliki sintaksis yang mirip dengan file BUILD, menggunakan aturan repo, bukan aturan build.

Cuplikan berikut adalah contoh penggunaan aturan repo http_archive dalam file WORKSPACE:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "foo",
    urls = ["https://example.com/foo.zip"],
    sha256 = "c9526390a7cd420fdcec2988b4f3626fe9c5b51e2959f685e8f4d170d1a9bd96",
)

Cuplikan menentukan repo yang nama kanonisnya adalah foo. Di sistem WORKSPACE, secara default, nama kanonis repo juga merupakan nama yang terlihat oleh semua repo lainnya.

Lihat daftar lengkap fungsi yang tersedia dalam file WORKSPACE.

Kekurangan sistem WORKSPACE

Sejak sistem WORKSPACE diperkenalkan, pengguna telah melaporkan banyak poin masalah, termasuk:

  • Bazel tidak mengevaluasi file WORKSPACE dari dependensi apa pun, sehingga semua dependensi transitif harus ditentukan dalam file WORKSPACE repositori utama, selain dependensi langsung.
  • Untuk mengatasi hal ini, project telah mengadopsi pola "deps.bzl", yang di dalamnya project menentukan makro yang pada gilirannya menentukan beberapa repo, dan meminta pengguna untuk memanggil makro ini dalam file WORKSPACE mereka.
    • Hal ini menimbulkan masalah tersendiri: makro tidak dapat load file .bzl lain, sehingga project ini harus menentukan dependensi transitifnya dalam makro "deps" ini, atau mengatasi masalah ini dengan meminta pengguna memanggil beberapa makro "deps" berlapis.
    • Bazel mengevaluasi file WORKSPACE secara berurutan. Selain itu, dependensi ditentukan menggunakan http_archive dengan URL, tanpa informasi versi apa pun. Artinya, tidak ada cara yang andal untuk melakukan penyelesaian versi dalam kasus dependensi berlian (A bergantung pada B dan C; B dan C bergantung pada versi D yang berbeda).

Karena kekurangan WORKSPACE, Bzlmod akan menggantikan sistem WORKSPACE lama dalam rilis Bazel mendatang. Baca panduan migrasi Bzlmod tentang cara bermigrasi ke Bzlmod.