登錄概念

概述

vcpkg 提供選擇的函式庫，這些函式庫被封裝成 埠，在 https://github.com/Microsoft/vcpkg。 此連接埠集合稱為「精選註冊表」。 不過，vcpkg 不僅限於精選的倉庫。 用戶可以藉由建立自定義登錄來擴充埠選取範圍。

註冊表是一組以特定結構排列的端口和輔助檔案。 通過遵循註冊表結構，註冊表中包含的埠可以安裝與策劃註冊表中的埠相同的功能（版本設定、二進位快取）。

目前有三種登錄：

• 內建登錄、
• Git 目錄和
• 檔案系統註冊表。

您可以指示 vcpkg 使用 vcpkg-configuration.json 檔案，考慮自定義登錄中可用的埠。 如需如何在專案中使用自定義登錄的教學課程，請參閱 教學課程：從 Git 型登錄安裝相依性 一文。

登錄結構

若要讓 vcpkg 能夠與註冊掛接，它必須符合以下結構：

• 名為 ports 的目錄包含埠的集合，每個子目錄都包含符合子目錄名稱的特定埠。 例如，埠 foo 的檔案位於 ports/foo中。
• 名為 versions 的目錄包含組成 版本資料庫的檔案。

範例：登錄結構

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

版本資料庫

所有登錄檔在登錄檔的根目錄中都有一個 versions 目錄，其中包含 版本資料庫。

版本資料庫有兩個元件：

• 基準檔案
• 版本檔案

基準檔案是名為 baseline.json 的 JSON 檔案，位於 versions 目錄的根目錄。

版本檔案是 JSON 檔案，其名稱與可用的埠相同。 它們必須存在於 versions/<prefix>/<port name>.json，其中 <prefix> 是埠名稱的第一個字母，後面接著連字元。 例如，埠 foo 的版本檔案必須位於 versions/f-/foo.json。

版本檔案有兩個用途：

• 列出每個埠的所有可用版本
• 標示每個版本的獲取位置。

版本檔案的格式取決於登錄的類型。

基準檔案

不論種類為何，所有註冊表都必須包含名為 baseline.json 的檔案，該檔案位於 versions/baseline.json。

基準檔案的目的是描述登錄中所有埠視為最新版的版本集。 預期每次將新版本的埠新增至登錄時，都會更新此檔案。

檔案是由單一物件所組成的 JSON 檔案，其屬性為具名基準物件。 每個基準物件的屬性是埠名稱，其值為版本條目。 登錄參考 一文將更詳細地說明基準檔案的配置。

每個基準版本項目都是具有下列屬性的物件：

• baseline：值是符合其對應 vcpkg.json 檔案的埠版本。
• port-version：值是連接埠的 port-version 與其對應的 vcpkg.json 檔案相匹配。

範例基準檔案

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

請參閱參考文件：

• Git 資料庫的基準佈局
• 檔案系統登錄的基準檔案配置

版本檔案

登錄中的每個埠都有對應的版本檔案。 版本檔案會儲存在 versions/<prefix>/<port name>.json ，其中 <prefix> 是埠名稱的第一個字母，後面接著連字元。 例如，埠 foo 的版本檔案位於 versions/f-/foo.json。

版本檔案的用途是雙重的：

• 列出每個埠的所有可用版本
• 指示每個版本的擷取位置點

版本檔案的結構是一個包含 "versions" 陣列的物件，而該陣列中的每個項目都是版本物件。 版本物件必須包含下列屬性：

• version 屬性：屬性中的索引鍵和值必須與埠在其 vcpkg.json 檔案中使用的索引鍵和值匹配。 鍵值必須是 version、version-semver、version-date或 version-string之一;值必須是版本，如它出現在埠的清單檔中（vcpkg.json）。
• port-version：值是埠的 port-version，因為它出現在埠的 vcpkg.json 檔案中。
• git-tree：（僅適用於 Git 儲存庫）該值是對應至埠目錄的 git-tree SHA。 這是透過哈希計算港口目錄內容得出的 SHA；Git 可以使用這個 Git 樹狀結構 SHA 來擷取匹配提供的 git-tree 的港口內容。 這可讓 vcpkg 從登錄 Git 歷程記錄擷取舊版埠。 請參閱 git 登錄 一節，瞭解如何取得任何指定埠版本的此值。
• path（僅在文件系統登錄中）：值是包含特定版本port檔案的目錄的完整路徑。

檔系統登錄版本檔案的範例

{
  "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
    }
  ]
}

請參閱參考文件：

• Git 註冊表的版本檔案佈局
• 檔案系統登錄的版本檔案佈局

內建登錄

內建登錄是一種特殊的登錄。 這是 傳統模式中使用的預設登錄。 在 指令清單模式中，如果未指定 默認登錄，vcpkg 會隱含地使用內建登錄。

內建登錄是指當您從 https://github.com/Microsoft/vcpkggit clone vcpkg 資料庫時所建立之精選登錄的本地副本。 某些作業預期 VCPKG_ROOT 環境變數 指向內建登錄。

如果 vcpkg 是透過 「one liner」 或 Visual Studio 安裝程式取得，則內建登錄會變成相當於指向 https://github.com/Microsoft/vcpkg 存放庫的 Git 登錄。

Git 登錄

Git 登錄是遵循登錄結構的存放庫，並利用 Git 的功能來提供登錄中埠的版本控制。 https://github.com/Microsoft/vcpkg 精選註冊表是 Git 註冊表的一種實現。

Git 登錄可以裝載在任何 Git 存放庫提供者中，讓您能夠使用所選的 Git 主控服務來控制自定義登錄的存取，同時讓您的登錄更容易共用。

Git 登錄是實作自定義登錄的建議方法。 由於版本管理機制與策劃的註冊表相同，Git 註冊表可以使用 x-add-version 來管理版本資料庫的檔案。

如需 Git 登錄的實作詳細數據，請參閱 登錄參考。

將新版本新增至 Git 登錄

x-add-version 命令可用來將新的埠或新版本新增至登錄。 使用此命令新增版本時，請記住下列幾個事項：

重要

新增新版本時，請記得將埠的宣告版本更新為尚未發行的版本，以避免重寫版本歷程記錄。

當您變更埠時，第一個步驟應該是在 vcpkg.json 檔案中增加其版本。 如果您的變更包含套件 上游 版本的更新，請記得將 port-version 設定為 0;否則，請記得將 port-version 增加一個。

x-add-version 命令 要求您在更新版本資料庫之前，必須先將所有埠變更提交至版本庫。

範例：將新的埠版本新增至 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

重新導向選項 --x-builtin-ports-root 和 --x-builtin-registry-versions-dir 應該分別指向登錄的 ports 和 versions 目錄。

一旦成功執行 x-add-version 命令，請修改最後一次提交以包含版本文件的變更。

git commit --amend -m "Update foo to new version"

檔案系統登錄

檔系統登錄是位於文件系統上的登錄實作。 它們會遵循常見的登錄結構，但不會使用 Git 來提供版本控制功能。 反而，它們使用基本形式的版本控制，針對各版本的埠採用不同的路徑。

這類註冊表適合用於網路埠的測試環境，或者作為非 Git 的版本控制系統中註冊表的替代方案。 不建議針對大型端口集合使用檔案系統註冊表，且不提供任何工具來操作此類註冊表的版本資料庫檔案。

如需如何實作文件系統登錄的詳細資訊，請參閱 登錄參考。

使用登錄

若要在專案中取用自定義登錄，您必須在專案的 指令清單檔 （vcpkg.json）旁邊建立 組態檔 （vcpkg-configuration.json）。

默認登錄

在解析埠名稱時，如果埠的名稱不符合registries陣列中其他登錄所宣告的任何套件模式，則默認登錄將作為後援。

為了方便未與自定義登錄互動的使用者，vcpkg 會隱含地將 內建登錄新增為默認登錄。 若要變更此行為，可以將默認註冊表設定為任何註冊表，或完全停用。 default-registry 屬性。

範例：將自定義登錄設定為預設值

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

範例：停用默認登錄

vcpkg-configuration.json

{
  "default-registry": null
}

註冊表陣列

若要擴充可使用 vcpkg 安裝的埠選擇，您可以使用 registries 陣列來指定其他登錄。

範例：將自定義登錄新增至組態

注意

視登錄種類而定，您可能需要在 registries 陣列中提供不同的資訊。 請參閱 vcpkg-configurtion.json 參考，以瞭解每種登錄類型所需的屬性。

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" ]
    }
  ]
}

註冊的建議做法

不要重寫版本歷程記錄

發佈版本至版本文件後，請勿在 git 儲存庫或檔案系統目錄中變更其相關聯的 git-tree。

vcpkg 的設計原則之一是，安裝相依性的版本不會在沒有使用者介入的情況下變更。 藉由變更 git-tree 項目來改寫版本檔案歷程記錄違反了此原則。

如果現有的版本有問題，偏好建立新的 port-version。

請勿刪除版本檔案

注意

本節僅適用於 Git 儲存庫

當您從登錄中移除埠時，請從埠目錄中移除其內容，以及從基準檔案中刪除其條目。 但 不會 移除其相關聯的版本檔案。

即使登錄中已不存在埠，只要版本檔案仍然存在，埠的用戶還是可以使用 版本 overrides來安裝舊版。

下一步

以下是接下來要嘗試的一些工作：

• 建立您自己的 Git 型登錄
• 從自定義登錄安裝套件
• 閱讀登錄參考檔