版本控制參考

發行項
02/06/2025

版本控制可讓您從指令清單檔內確定性地控制專案所使用的相依性精確修訂。版本控制僅適用於使用者指令清單模式。

如需 vcpkg 版本設定演算法和高階概念的詳細資訊，請參閱版本控制概念。

如需內容範例，請參閱我們的指南，以開始使用版本設定。

版本配置

vcpkg 中的埠應該嘗試遵循套件作者所使用的版本設定慣例。因此，在宣告套件版本時，應該使用適當的配置。

每個版本控制配置都會針對什麼是有效的版本字串定義自己的規則，更重要的是如何使用相同配置來排序版本的規則。

vcpkg 所瞭解的版本設定配置如下：

Manifest 屬性	版本控制配置
`version`	針對點分隔的數值版本
`version-semver`	針對符合 SemVer 規範的版本
`version-date`	針對格式為 `YYYY-MM-DD` 的日期
`version-string`	針對任意字串

指令清單必須只包含一個版本宣告。

注意

根據設計，vcpkg 不會比較使用不同配置的版本。例如，具有 version-string: 7.1.3 的套件無法使用 version: 7.1.4來與相同的套件進行比較，即使轉換似乎很明顯。

`version`

接受遵循寬鬆、以點分隔、類似 semver 的配置的版本字串。

版本會以邏輯方式由點分隔（.）數值區段所組成。每個區段都必須包含沒有前置零的整數正數。

此版本設定配置的 regex 模式為：(0|[1-9]\d*)(\.(0|[1-9]\d*))*

排序行為：比較兩個版本時，每個區段會從左到右依其數值進行比較，直到找到第一個差異為止。具有最社區段集的版本優先於另一組具有較大區段的版本，因為上述各節的比較相同。

例：

0 < 0.1 < 0.1.0 < 1 < 1.0.0 < 1.0.1 < 1.1< 2.0.0

`version-semver`

接受遵循語意版本設定慣例的版本字串，如語意版本設定規格中所述，。

排序行為：字串會依照語意版本設定規格中所述的規則進行排序。

例：

1.0.0-1 < 1.0.0-alpha < 1.0.0-beta < 1.0.0 < 1.0.1 < 1.1.0

`version-date`

接受可剖析為 ISO-8601 格式 YYYY-MM-DD日期的版本字串。以無前置零的點分隔、正數、整數等形式允許區分標識碼。

這是未建立發行版本的「在 HEAD 上即時」連結庫的建議版本設定配置。

此版本設定配置的 regex 模式為：\d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*

排序行為：字串會先依日期部分排序，然後依其釐清標識符的數值比較來排序。釐清標識元遵循寬鬆（version）配置的規則。

範例：2021-01-01<2021-01-01.1<2021-02-01.1.2<2021-02-01.1.3<2021-02-01

`version-string`

對於使用不符合任何其他配置之版本字串的套件，它接受大部分的任意字串。不允許用來表示埠版本的 #。

排序行為：版本字串本身不會嘗試排序。不過，如果字串完全相符，則可以比較和排序其埠版本。

例子：

apple <> orange <> orange.2 <> orange2
watermelon#0< watermelon#1

`port-version`

埠版本會追蹤封裝檔案中的變更（vcpkg.json、portfile.cmake等），而不需要對上游連結庫版本進行任何變更。

埠版本是非負整數值。

連接埠版本的規則如下：

從 0 開始，以取得埠的原始版本，
每次對未增加套件版本的埠進行 vcpkg 特定變更時，增加 1。
和會在每次更新套件版本時重設為 0。

注意

vcpkg 遵循文字格式 <version>#<port version>。例如，1.2.0#2 表示版本 1.2.0 埠版本 2。如果埠版本 0 省略 #0 後綴（例如，1.2.0 表示 1.2.0 埠版本 0）。

排序行為：如果兩個版本相等比較，則會將其埠版本與其數值進行比較，較低的埠版本優先。

例子：

1.2.0 < 1.2.0#1 < 1.2.0#2 < 1.2.0#10
2021-01-01#20 < 2021-01-01.1
windows#7 < windows#8

版本條件約束

基線

基準會針對要考慮的版本定義全域版本底板（除非在其他地方指定，否則將使用與該基準相關聯的版本）。這可讓最上層指令清單保留相依性的完整圖表 up-to日期，而不需要個別指定直接 "version>=" 條件約束。

每個設定的登錄都有相關聯的基準。對於未設定任何登錄的指令清單，["builtin-baseline"] 字段會定義內建登錄的基準。如果指令清單未設定任何登錄，而且沒有 "builtin-baseline"，則安裝會根據傳統模式演算法運作，並忽略所有版本設定資訊。

基準與其他登錄設定一樣，會忽略作為相依性取用的埠。如果在轉移版本解析期間需要最低版本，埠應該使用 "version>="。

例

{
  "name": "project",
  "version": "1.0.0",
  "dependencies": ["zlib", "fmt"],
  "builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
}

若要新增初始 "builtin-baseline"，請使用 vcpkg x-update-baseline --add-initial-baseline。若要更新指令清單中的基準，請使用 vcpkg x-update-baseline。

`version>=`

表示最低版本需求，version>= 宣告會將下限放在可用來滿足相依性的版本上。

注意

vcpkg 會選取符合所有條件約束的最低版本，因此不需要小於條件約束。

例：

{
  "name": "project",
  "version-semver": "1.0.0",
  "dependencies": [
    { "name": "zlib", "version>=": "1.2.11#9" },
    { "name": "fmt", "version>=": "7.1.3#1" }
  ],
  "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc"
}

作為版本條件約束宣告的一部分，您可以在上一個範例中新增後綴 #<port-version>來指定埠版本，1.2.11#9 是指版本 1.2.11 埠版本 9。

`overrides`

宣告覆寫會強制 vcpkg 忽略所有其他版本條件約束，並使用覆寫中指定的版本。這適用於釘選確切的版本，以及解決版本衝突。

覆寫會宣告為套件版本宣告的數位。

若要讓覆寫生效，覆寫的套件必須構成相依性圖形的一部分。這表示必須由最上層指令清單宣告相依性，或成為可轉移相依性的一部分。

指定名稱只能宣告一個覆寫。

{
  "name": "project",
  "version-semver": "1.0.0",
  "dependencies": [
    "curl",
    { "name": "zlib", "version>=": "1.2.11#9" },
    "fmt"
  ],
  "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc",
  "overrides": [
    { "name": "fmt", "version": "6.0.0" },
    { "name": "openssl", "version": "1.1.1h#3" }
  ]
}

共用方式為