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 untuk foo port terletak di ports/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 file vcpkg.json yang sesuai.
• port-version: nilainya adalah port-version port yang sesuai dengan file vcpkg.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 dari version, version-semver, version-date, atau version-string; nilai harus berupa versi seperti yang muncul dalam file manifes port (vcpkg.json).
• port-version: nilai port-version dari port sebagaimana tercantum dalam berkas vcpkg.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:

• Tata letak file versi untuk registri Git
• Tata letak file versi untuk registri sistem berkas

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:

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

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-versionbaru.

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:

• Membuat registri berbasis Git Anda sendiri
• Menginstal paket dari registri kustom
• Membaca dokumentasi referensi registri