版本控制参考

项目
03/01/2024

版本控制让你可以确切地从清单文件控制项目使用的依赖项的精确修订。仅清单模式用户可以使用版本控制。

有关 vcpkg 版本控制算法和高级概念的详细信息，请参阅版本控制概念。

有关上下文的示例，请参阅我们的指南，了解入门版本控制。

版本方案

vcpkg 中的端口应尝试遵循包的作者使用的版本控制约定。因此，在声明包的版本时，应使用适当的方案。

每个版本控制方案定义其自己的规则，即什么是有效的版本字符串，以及更重要的，如何使用相同方案对版本进行排序的规则。

vcpkg 理解的版本控制方案包括：

清单属性	版本控制方案
`version`	对于以句点分隔的数字版本
`version-semver`	对于符合 SemVer 的版本
`version-date`	对于采用格式 `YYYY-MM-DD` 的日期
`version-string`	对于任意字符串

清单必须仅包含一个版本声明。

注意

vcpkg 有意不比较使用不同方案的版本。例如，不能将具有 version-string: 7.1.3 的包与使用 version: 7.1.4 的同一个包进行比较，即使转换似乎很明显。

`version`

接受遵循宽松的句点分隔的类似 semver 的方案的版本字符串。

版本在逻辑上由句点分隔的 (.) 数字部分组成。每个部分都必须包含一个正整数，不得有前导零。

此版本控制方案的正则表达式模式为：(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 的日期的版本字符串。允许消除歧义标识符采用句点分隔、无前导零的正整数形式。

建议未建立发布版本的“Live at HEAD”库使用此版本控制方案。

此版本控制方案的正则表达式模式为：\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

版本约束

基线

基线定义将考虑哪些版本的全局版本下限。这使顶级清单能够使整个依赖项关系图保持最新状态，而无需单独指定直接 "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" }
  ]
}

通过