建立登錄

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

概觀

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

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

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

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

登錄的基本結構為:

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

Git 登錄

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

Northwind Traders: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";不過,我們不建議在新登錄中使用 CONTROL 檔案。

警告

登錄的其中一個重要部分是不應該變更版本。 更新至較新的 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
    }
  }
}

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

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

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

但是,具有 CONTROL 檔案之埠的版本字段為 "version-string";不過,我們不建議在新登錄中使用 CONTROL 檔案。

一般而言,您放置埠目錄的位置並不重要。 不過,vcpkg 中的語意是與內建 vcpkg 登錄的功能相近:您的 kittenx.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
    }
  }
}

你完成了!