Konsep registri
Ikhtisar
vcpkg menghosting kumpulan pustaka yang dikemas menjadi port di https://github.com/Microsoft/vcpkg. Kumpulan port ini disebut registri terkurasi. Namun, vcpkg tidak terbatas pada registri yang diatur. Pengguna dapat memperluas pemilihan port dengan membuat registri kustom.
Registri adalah kumpulan port dan file pembantu yang diatur dalam struktur tertentu. Dengan mengikuti struktur registri, port yang terdapat dalam registri dapat diinstal dengan fitur yang sama (pengelolaan versi, cache biner) yang ditawarkan ke port di registri yang telah dikurasi.
Saat ini ada tiga jenis registri:
- Registri bawaan ,
- pustaka Git, dan
- pencatatan sistem berkas.
vcpkg dapat diinstruksikan untuk mempertimbangkan port yang tersedia di registri kustom dengan menggunakan file vcpkg-configuration.json
. Lihat artikel Tutorial: Instalasi dependensi dari registri berbasis Git untuk panduan tentang cara menggunakan registri kustom di proyek Anda.
Struktur registri
Agar vcpkg dapat berinteraksi dengan registri, vcpkg harus sesuai dengan struktur berikut:
- Direktori bernama
ports
berisi kumpulan port, dengan setiap subdirektori yang berisi port tertentu yang cocok dengan nama subdirektori. Misalnya, file untukfoo
port terletak diports/foo
. - Direktori bernama
versions
berisi file yang terdiri dari database versi .
Contoh: struktur registri
ports/
foo/
portfile.cmake
vcpkg.json
versions/
f-/
foo.json
baseline.json
Database versi-versi
Semua registri berisi direktori versions
di akar registri yang berisi database versi .
Ada dua komponen untuk database versi:
- File dasar
- File versi
File garis besar adalah file JSON bernama baseline.json
terletak di akar direktori versions
.
File versi adalah file JSON dengan nama yang sama dengan port yang tersedia.
Mereka harus ada di versions/<prefix>/<port name>.json
, di mana <prefix>
adalah huruf pertama dari nama port diikuti dengan tanda hubung. Misalnya, file versi untuk port foo
harus berada di versions/f-/foo.json
.
Tujuan file versi adalah dua tujuan utama:
- Mencantumkan semua versi yang tersedia dari setiap port
- Arahkan ke tempat pengunduhan setiap versi.
Format file versi tergantung pada jenis registri.
File dasar acuan
Semua registri, terlepas dari jenisnya, harus berisi file bernama baseline.json
yang terletak di versions/baseline.json
.
Tujuan file garis besar adalah untuk menjelaskan kumpulan versi yang dianggap terbaru untuk semua port dalam registri. Diharapkan file ini diperbarui setiap kali versi port baru ditambahkan ke registri.
File adalah file JSON yang terdiri dari satu objek yang propertinya diberi nama objek garis besar. Setiap properti objek garis besar adalah nama port, yang nilainya adalah entri versi. Artikel yang merujuk pada registri menjelaskan tata letak file standar secara lebih rinci.
Setiap entri versi garis besar adalah objek dengan properti berikut:
-
baseline
: nilainya adalah versi port yang cocok dengan filevcpkg.json
yang sesuai. -
port-version
: nilainya adalahport-version
port yang sesuai dengan filevcpkg.json
yang bersangkutan.
Contoh file garis besar
{
"default": {
"foo": { "baseline": "1.0.0", "port-version": 0 },
"bar": { "baseline": "2024-08-01", "port-version": 1 },
"baz": { "baseline": "vista-xp", "port-version": 0 }
}
}
Lihat dokumentasi referensi untuk:
- Tata letak file garis besar untuk registri Git
- Tata letak file garis besar untuk registri sistem file
File versi
Setiap port dalam registri memiliki file versi yang sesuai.
File versi disimpan di versions/<prefix>/<port name>.json
, di mana <prefix>
adalah huruf pertama dari nama port diikuti dengan tanda hubung. Misalnya, file versi untuk port foo
berada di versions/f-/foo.json
.
Tujuan file versi adalah dua tujuan:
- Mencantumkan semua versi yang tersedia dari setiap port
- Tunjukkan lokasi penyimpanan untuk masing-masing versi ini
Tata letak file versi adalah objek yang berisi array "versions"
, dengan setiap entri dalam array tersebut menjadi objek versi. Objek versi harus berisi properti berikut:
- Properti versi: Kunci dan nilai properti harus cocok dengan yang digunakan oleh port dalam file
vcpkg.json
. Kuncinya harus salah satu dariversion
,version-semver
,version-date
, atauversion-string
; nilai harus berupa versi seperti yang muncul dalam file manifes port (vcpkg.json
). -
port-version
: nilaiport-version
dari port sebagaimana tercantum dalam berkasvcpkg.json
port. -
git-tree
: (hanya pada registri Git) nilainya adalah SHA git-tree yang sesuai dengan direktori port. Ini adalah SHA yang dihitung dengan hash konten direktori port; GIT-tree SHA ini dapat digunakan oleh Git untuk mengambil konten port yang cocok dengan git-tree yang disediakan. Hal ini memungkinkan vcpkg mengambil versi port lama dari riwayat Git registri. Baca bagian registri git untuk mempelajari cara mendapatkan nilai ini untuk versi port tertentu. -
path
: (hanya pada registri sistem file) nilainya adalah jalur lengkap ke direktori yang berisi file port untuk versi tertentu.
Contoh file versi sistem berkas dari registri
{
"versions": [
{
"path": "$/ports/foo/1.2.0",
"version": "1.2.0",
"port-version": 0
},
{
"path": "$/ports/foo/1.1.0",
"version": "1.1.0",
"port-version": 0
},
{
"path": "$/ports/foo/1.0.0",
"version": "1.0.0",
"port-version": 0
}
]
}
Lihat dokumentasi referensi untuk:
Registri bawaan
Registri bawaan adalah jenis registri khusus. Ini adalah registri default yang digunakan dalam mode klasik . Dalam mode manifes , ketika registri default tidak ditentukan, vcpkg secara implisit menggunakan registri bawaan.
Registri bawaan merujuk pada salinan lokal dari registri yang telah dikurasi, yang dibuat ketika Anda git clone
repositori vcpkg dari https://github.com/Microsoft/vcpkg. Beberapa operasi mengharapkan bahwa variabel lingkungan VCPKG_ROOT
menunjuk ke registri bawaan.
Jika vcpkg diperoleh melalui "satu liner" atau alat penginstal Visual Studio, registri bawaan menjadi setara dengan registri Git menunjuk ke repositori https://github.com/Microsoft/vcpkg.
Registri Git
Registri Git adalah repositori yang mengikuti struktur registri dan memanfaatkan kemampuan Git untuk menyediakan penerapan versi untuk port di registri. Registri yang disusun di https://github.com/Microsoft/vcpkg adalah implementasi dari registri Git.
Registri Git dapat dihosting di penyedia repositori Git mana pun, memungkinkan Anda menggunakan layanan hosting Git pilihan Anda untuk mengontrol akses ke registri kustom Anda sekaligus membuat registri Anda mudah dibagikan.
Registri Git adalah metode yang direkomendasikan untuk menerapkan registri kustom.
Karena mekanisme penerapan versi sama dengan yang digunakan oleh registri yang dikumpulkan, registri Git dapat menggunakan x-add-version
untuk mengelola file database versi Anda.
Lihat referensi registri untuk detail implementasi registri Git.
Menambahkan versi baru ke registri Git
Perintah x-add-version
dapat digunakan untuk menambahkan port baru atau versi baru ke registri. Saat menambahkan versi menggunakan perintah ini ada beberapa hal yang perlu diingat:
Penting
Saat menambahkan versi baru, selalu ingatlah untuk memperbarui versi port yang dideklarasikan ke versi yang belum diterbitkan, untuk menghindari penulisan ulang riwayat versi.
Saat Anda membuat perubahan pada port, langkah pertama harus meningkatkan versinya dalam file vcpkg.json
. Jika perubahan Anda menyertakan pembaruan ke versi upstream paket, ingatlah untuk mengatur port-version
ke 0
; jika tidak, ingatlah untuk meningkatkan port-version
satu per satu.
Perintah x-add-version
mengharuskan semua perubahan port Anda diterapkan ke repositori sebelum memperbarui database versi.
Contoh: menambahkan versi port baru ke registri Git
git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json
Opsi pengalihan --x-builtin-ports-root
dan --x-builtin-registry-versions-dir
harus menunjuk ke direktori ports
dan versions
registri Anda.
Segera setelah perintah x-add-version
berhasil dijalankan, perbarui commit terakhir untuk menyertakan perubahan dalam file versi tersebut.
git commit --amend -m "Update foo to new version"
Registri sistem file
Registri sistem file adalah implementasi registri yang hidup di sistem file. Mereka mengikuti struktur registri umum tetapi tidak menggunakan Git untuk menawarkan kemampuan penerapan versi. Sebaliknya, mereka menggunakan bentuk primitif kontrol versi menggunakan jalur yang berbeda untuk setiap versi port-nya.
Registri semacam ini cocok untuk menjadi tempat pengujian untuk port Anda atau untuk memberikan alternatif untuk registri dalam sistem kontrol versi non-Git. Registri sistem file tidak disarankan untuk kumpulan port yang besar dan tidak ada alat yang disediakan untuk memanipulasi file database versi untuk registri semacam ini.
Lihat referensi registri di untuk informasi detail tentang implementasi registri sistem berkas.
Mengonsumsi registri
Untuk menggunakan registri kustom dalam proyek Anda, Anda perlu membuat file konfigurasi (vcpkg-configuration.json
) di samping file manifes proyek Anda (vcpkg.json
).
Registri bawaan
Ketika menyelesaikan nama port, registri default berfungsi sebagai fallback ketika nama port tidak cocok dengan salah satu pola paket dideklarasikan oleh registri lain dalam array registries
.
Sebagai kenyamanan bagi pengguna yang tidak terlibat dengan registri kustom, vcpkg secara implisit menambahkan registri bawaan sebagai registri default. Untuk mengubah perilaku ini, registri default dapat diatur ke registri apa pun atau dinonaktifkan sepenuhnya menggunakan
default-registry
properti.
Contoh: Mengatur registri kustom sebagai default
vcpkg-configuration.json
{
"default-registry": {
"kind": "git",
"repository": "https://github.com/Microsoft/vcpkg",
"baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
}
}
Contoh: Menonaktifkan registri default
vcpkg-configuration.json
{
"default-registry": null
}
Array registri
Untuk memperluas pilihan port yang tersedia untuk diinstal dengan vcpkg, Anda dapat menentukan registri tambahan menggunakan array registries
.
Contoh: Menambahkan registri kustom ke konfigurasi
Nota
Tergantung pada jenis registri, Anda mungkin perlu memberikan informasi yang berbeda dalam array registries
. Lihat referensi vcpkg-configurtion.json
untuk mempelajari properti mana yang diperlukan untuk setiap jenis registri.
vcpkg-configuration.json
{
"default-registry": {
"kind": "git",
"repository": "https://github.com/Microsoft/vcpkg",
"baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
},
"registries": [
{
"kind": "git",
"repository": "https://my.privateregistry.git",
"baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
"packages": [ "foo" ]
},
{
"kind": "filesystem",
"path": "C:/path/to/registry",
"baseline": "baseline1",
"packages": [ "bar" ]
}
]
}
Praktik yang direkomendasikan untuk registri
Jangan menulis ulang riwayat versi
Setelah versi diterbitkan ke file versi, jangan ubah git-tree
terkait dalam registri git atau direktori dalam registri sistem file.
Salah satu prinsip desain vcpkg adalah bahwa versi dependensi yang diinstal tidak berubah tanpa intervensi pengguna. Menulis ulang riwayat file versi dengan mengubah entri git-tree
melanggar prinsip ini.
Jika versi yang ada memiliki masalah, sebaiknya membuat port-version
baru.
Jangan hapus file versi
Saat menghapus port dari registri Anda, hapus kontennya dari direktori port dan entrinya dalam file garis besar. Tetapi tidak menghapus file versi terkait.
Bahkan jika port tidak lagi ada di registri, selama file versi tetap ada, pengguna port dapat menginstal versi lama dengan menggunakan versi overrides
.
Langkah berikutnya
Berikut adalah beberapa tugas untuk dicoba berikutnya: