建立登錄

發行項
06/20/2024

如需取用登錄的資訊，請參閱使用登錄。

概觀

登錄是埠及其版本的集合。如果您想要建立自己的登錄，有兩個主要的登錄實作選擇：git 登錄和文件系統登錄。

Git 登錄是簡單的 Git 存放庫，可透過 Git 存放庫的一般機制公開或私下共用。例如，vcpkg 存放庫是 git 登錄。

檔系統登錄設計為更多測試場。假設它們實際上存在於文件系統上，共享它們的唯一方式是透過共享目錄。不過，文件系統登錄可用來代表非 Git 版本控制系統中保留的登錄，假設有某種方法可將登錄放入磁碟上。

我們預期一組登錄類型會隨著時間成長;如果您想要支援以您慣用的公用版本控制系統建置的登錄，請毫不猶豫地開啟 PR。

登錄的基本結構為：

歷程記錄中特定時間視為「最新」的版本集合，稱為「基準」。
所有埠的所有版本集合，以及在登錄中尋找每個埠的位置。

Git 登錄

隨著您遵循此檔，有一個可參考的工作範例可能會很有説明。我們已經寫了一個，並把它放在這裡：

Microsoft/vcpkg-docs：vcpkg 登錄。

所有 Git 登錄都必須有檔案 versions/baseline.json 。此檔案包含特定認可時的一組「最新版本」。它會配置為只 "default" 包含欄位的最上層物件。此欄位應該包含物件對應埠名稱至目前為最新版本的版本。

以下是有效的baseline.json範例：

{
  "default": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

目錄 versions 包含登錄中包含哪些套件版本以及儲存這些版本的所有資訊。其餘的登錄只是作為備份存儲區，就 vcpkg 而言：只有目錄內 versions 的內容會用來指示 vcpkg 如何看到您的登錄。

登錄中的每個埠都應該存在於版本目錄中， <first letter of port>-/<name of port>.json換句話說，埠的相關信息 kitten 會位於 versions/k-/kitten.json。這應該是只有單一欄位的最上層物件： "versions"。此欄位應包含版本物件的陣列：

有問題的埠版本;應該與 vcpkg.json 檔案完全相同，包括版本欄位和 "port-version"。
欄位 "git-tree" ，也就是 Git 樹狀結構;換句話說，您在撰寫 git rev-parse COMMIT-ID:path/to/port時會得到的內容。

具有已 CONTROL 取代檔案之埠的版本欄位為 "version-string"。

警告

登錄的其中一個重要部分是不應該變更版本。更新至較新的 ref 絕不應移除或變更現有的版本。更新登錄必須一律安全。

以下是一個版本之 kitten 埠的有效版本資料庫範例：

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

一般而言，您放置埠目錄的位置並不重要。不過，vcpkg 中的成語是遵循內建 vcpkg 登錄的用途：您的 kitten 埠應該放在 ports/kitten中。

警告

另一個要記住的事項是，當您更新登錄時，也應該存取所有舊版。由於您的使用者會將基準設定為認可標識符，因此該認可標識碼必須一律存在，而且可從您的HEAD認可存取，也就是實際擷取的內容。這表示您的 HEAD 認可應該是所有先前 HEAD 認可的子系。

內建登錄

內建登錄會被視為特殊的 Git 登錄。內建登錄不會從遠端 URL 擷取，而是參考 $VCPKG_ROOT/.git vcpkg 複製的目錄。他們會使用目前取出 $VCPKG_ROOT/versions 的目錄作為版本設定資訊的來源。

新增新版本

建立新版本的埠涉及一些 Git 技巧。第一件事是進行一些變更、視需要更新 "port-version" 和一般版本欄位，然後使用進行測試 overlay-ports：

vcpkg install kitten --overlay-ports=ports/kitten.

完成測試之後，您必須確定目錄位於 git 的 purview 之下。您將藉由建立暫存認可來執行此動作：

> git add ports/kitten
> git commit -m 'temporary commit'

然後，取得目錄的 Git 樹狀目錄識別碼：

> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07

然後，您可以將這個版本新增至版本資料庫。在頂端 versions/k-/kitten.json，您可以新增（假設您正在新增版本 2.6.3#0）：

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

然後，您也會想要使用新版本來修改 versions/baseline.json ：

{
  "default": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

並修改您目前的認可：

> git commit --amend

然後分享！

檔案系統登錄

隨著您遵循此檔，有一個可參考的工作範例可能會很有説明。我們已經寫了一個，並把它放在這裡：

範例檔系統登錄。

所有檔案系統登錄都必須有檔案 versions/baseline.json 。此檔案包含特定登錄版本的「最新版本」集合。它會配置為最上層物件，其中包含從版本名稱到「基準物件」的對應，該對應埠名稱對應至該版本登錄的「最新」版本。

檔系統登錄必須決定版本設定配置。與具有 refs 隱含版本設定設定的 git 登錄不同，文件系統登錄在此無法依賴版本控制系統。其中一個可能的選項是執行每日發行，並將您的「版本」設為日期。

警告

發佈之後，不得修改基準。如果您想要變更或更新版本，您必須在檔案中 baseline.json 建立新的基準。

以下是有效 baseline.json的範例，適用於已決定其版本日期的登錄：

{
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

有問題的埠版本;應該與 vcpkg.json 檔案完全相同，包括版本欄位和 "port-version"。
欄位 "path" ：位於登錄基底的相對目錄（換句話說，位於的 versions 目錄）到埠目錄。它看起來應該像 "$/path/to/port/dir”

具有已 CONTROL 取代檔案之埠的版本欄位為 "version-string"。

一般而言，您放置埠目錄的位置並不重要。不過，vcpkg 中的語意是與內建 vcpkg 登錄的功能相近：您的 kitten 埠 x.y.z 版本應該放在 ports/kitten/x.y.z中，並附加埠版本，因為您認為適合（雖然因為 # 不是用於檔名的好字元，或許使用 _）。

警告

登錄的其中一個重要部分是不應該變更版本。一個不應該移除或變更現有的版本。您對登錄所做的變更不應該變更下游用戶的行為。

以下是一個版本之 kitten 埠的有效版本資料庫範例：

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

加入新版本

與 git 登錄不同，將新版本新增至文件系統登錄大多牽涉到大量複製。首先，若要將最新版本的埠複製到新版本目錄、視需要更新版本和 "port-version" 欄位，然後使用進行測試 overlay-ports：

vcpkg install kitten --overlay-ports=ports/kitten/new-version.

完成測試之後，您可以將這個新版本新增至頂 versions/k-/kitten.json端：

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.3_0"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

然後，您也會想要使用新版本來修改您的 versions/baseline.json （請記得不要修改現有的基準）：

{
  "2021-04-17": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

你就完功！

共用方式為