vcpkg manifest 的使用

最近项目上要使用 CMakeLists 管理，由于 Windows 版本有依赖到 vcpkg 提供的库，所以需要使用 vcpkg manifest 来统一设置库的版本，方便后续维护

推荐一个文章，介绍的可以说是非常全面了

• VCPKG 特性 - Versioning

不过里面也有一些过时的特性，我在后面会补充一下

为了防止上面文章的链接失效，故列出一些常用的命令

这是一个完整的 vcpkg.json

{
    "name": "versions-test",
    "version": "1.0.0",
    "dependencies": [
    {
      "name": "fmt",
      "version>=": "7.1.3"
     },
     "zlib"
    ],
    "builtin-baseline": "6a349fe1fbea1e5fcda2e0775f555d829a5e82df"，
    "overrides": [
    {
       "name": "fmt",
       "version": "6.0.0"
     }
    ]
}

原文中说使用 git rev-parse HEAD 获取 builtin-baseline 其实是不准确的

git rev-parse HEAD

git rev-parse HEAD 是获取 .git 中当前分支的最新 commit_id，这与库是没什么关系的，如下

// 在 cmd 中输入
C:\Users\xxx\vcpkg>git rev-parse HEAD
6a349fe1fbea1e5fcda2e0775f555d829a5e82df
C:\Users\xxx\vcpkg>git show 6a349fe1fbea1e5fcda2e0775f555d829a5e82df
commit 6a349fe1fbea1e5fcda2e0775f555d829a5e82df (HEAD -> master, origin/master, origin/HEAD, ffmpeg_test)
Author: Billy O'Neal <bion@microsoft.com>
Date:   Mon Sep 18 16:34:12 2023 -0700

    Update vcpkg-tool to 2023-09-15 (#33804)

    https://github.com/microsoft/vcpkg-tool/releases/tag/2023-09-15

diff --git a/scripts/vcpkg-tool-metadata.txt b/scripts/vcpkg-tool-metadata.txt
index eb6591bf4..c8387661b 100644
--- a/scripts/vcpkg-tool-metadata.txt
+++ b/scripts/vcpkg-tool-metadata.txt
@@ -1,5 +1,5 @@
-VCPKG_TOOL_RELEASE_TAG=2023-08-09
-VCPKG_MACOS_SHA=b46eaabbcc586b40c21f15ae8da671ce67da9022cd7acef4651bf8de81587f06074e7eb4066f521086270c01f9fa557374972159756412e852426a3ff04759d4
-VCPKG_MUSLC_SHA=114de7c643386ca2b8319bacfd83979e109abe490d4f25a23a0918fc0020f918131fb260cdb8abbbbaae7c170952e0327cf77c26cfa9135c6a1bfd7e6c0d8fca
-VCPKG_GLIBC_SHA=4aa9b734b13526385c0d034452a52edd393e9a1d11274634cd4dacf52f16a3579782a9a6069746e15c2b82257046f3be951bf7c7a03846236fb6247211308044
-VCPKG_TOOL_SOURCE_SHA=bcf05ca1f52bd5cd8274fd6e1678bd1d4f9673aecead127fe4a4d7e40c583829f60bc568cdfa9ce36f13a6cbf21d95322dd7088b011024461682813c8ab1ecb3
+VCPKG_TOOL_RELEASE_TAG=2023-09-15
+VCPKG_MACOS_SHA=3c822003ec4e5eb3ea15d8ccf1a156f1d58e742b9d375a79693af9ad5b454796d4a42e05091bafefdf8359b56aee27ff8b07ff9bcb99f549a5bc81cb7ed47cc7
+VCPKG_MUSLC_SHA=125c77acbc6a2271eb882767e44da3fb0acd0719a35f2460e65eafcccae47967a5c370206d7af06b1d5a10d4ea53d04e620ca8df4bface8cd972b27eb89cf04e
+VCPKG_GLIBC_SHA=08d27596961819573a66163ca5373e8f20137856d78d58154cc9ad0ba4864a1d22698d25c08c5ebcb3601f2952a476b0f1d12bed25c42cdbe6dab520870fabf3

　　

// 在 git bash 中输入 git log 查看历史提交
xxx@DESKTOP-MS9D4O9 MINGW64 ~/vcpkg (master)
$ git log
commit 6a349fe1fbea1e5fcda2e0775f555d829a5e82df (HEAD -> master, origin/master, origin/HEAD, ffmpeg_test)
Author: Billy O'Neal <bion@microsoft.com>
Date:   Mon Sep 18 16:34:12 2023 -0700

    Update vcpkg-tool to 2023-09-15 (#33804)

    https://github.com/microsoft/vcpkg-tool/releases/tag/2023-09-15

commit 0a50c9623b797eb393ca852099bc3b776c34b532
Author: Fabien Péan <fabien@pean.pro>
Date:   Mon Sep 18 19:12:53 2023 +0200

    [yomm2] Update to v1.4.0 (#33509)

...

所以说用上述方法查看 builtin-baseline 是不准确的，包括后面说的使用 x-history 命令也是过时的

新方法是使用 git blame -l 方法

git blame -l versions/<port-first-char>-/<portname>.json

相关文档：How do I get history versions of a port now

实际使用：

C:\Users\xxx\vcpkg>git blame -l versions/c-/curl.json
2f6537fa2b8928d2329e827f862692112793435d port_versions/c-/curl.json (Victor Romero              2021-01-14 16:08:36 -0800   1) {
2f6537fa2b8928d2329e827f862692112793435d port_versions/c-/curl.json (Victor Romero              2021-01-14 16:08:36 -0800   2)   "versions": [
679df196c1d43210c4dfd079a47fa4bcefe44f00 versions/c-/curl.json      (Lily Wang                  2023-08-02 08:59:01 -0700   3)     {
679df196c1d43210c4dfd079a47fa4bcefe44f00 versions/c-/curl.json      (Lily Wang                  2023-08-02 08:59:01 -0700   4)       "git-tree": "1e4df4c9590fb15d2d73014c66dbbc151b624b9b",
679df196c1d43210c4dfd079a47fa4bcefe44f00 versions/c-/curl.json      (Lily Wang                  2023-08-02 08:59:01 -0700   5)       "version": "8.2.1",
679df196c1d43210c4dfd079a47fa4bcefe44f00 versions/c-/curl.json      (Lily Wang                  2023-08-02 08:59:01 -0700   6)       "port-version": 0
679df196c1d43210c4dfd079a47fa4bcefe44f00 versions/c-/curl.json      (Lily Wang                  2023-08-02 08:59:01 -0700   7)     },
864c70b8369e59c72fb71b50f2a233a91398d591 versions/c-/curl.json      (JonLiu1993                 2023-07-21 08:46:53 -0700   8)     {
864c70b8369e59c72fb71b50f2a233a91398d591 versions/c-/curl.json      (JonLiu1993                 2023-07-21 08:46:53 -0700   9)       "git-tree": "c82d0a822ec7d4044a58c18f2e198df681822cf6",
864c70b8369e59c72fb71b50f2a233a91398d591 versions/c-/curl.json      (JonLiu1993                 2023-07-21 08:46:53 -0700  10)       "version": "8.2.0",
864c70b8369e59c72fb71b50f2a233a91398d591 versions/c-/curl.json      (JonLiu1993                 2023-07-21 08:46:53 -0700  11)       "port-version": 0
864c70b8369e59c72fb71b50f2a233a91398d591 versions/c-/curl.json      (JonLiu1993                 2023-07-21 08:46:53 -0700  12)

　　

c- 就是 versions 文件夹的子文件夹

curl.json 是 c- 文件夹下的 json 文件

那 versions 与 builtin-baseline 是如何配合使用呢？

借助一开始文章链接，我贴出主要部分，

builtin-baseline 具体作用过程：

1. 从给定的 builtin-baseline（commit id）版本中查找是否含有 baseline.json 文件，如果有，就从这个文件中查找该库的版本。

2. 如果没有 baseline.json，就会报错。

3. 如果有 baseline.json，但是它不包含库的历史版本，也会报错。

version>=

以上示例中，zlib 的版本号 1.2.11#9 是由 version 和 port-version 两部分组成，version（1.2.11） 是 zlib 的实际的版本号，port-version(9) 是这个版本在 vcpkg 中的补丁版本。两者组合可以获取该库在 vcpkg 中的具体版本。

当 version 版本更新时，port-version 重置为 0 ，每次改动都加 1。

在 vcpkg 中，版本是如何比较大小呢？实际是比较版本的新旧，例如：

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

注意：

1. Version>= 主要用于表示需要使用的最低版本，只有作为 "dependencies"的一部分时才是被允许的。

2. 如果使用 Version>=， vcpkg会从所有满足条件的版本中选用最低版本，这种做法的好处是更新 vcpkg 时，避免依赖升级出现异常的问题。可以总结为：

如果使用 overrides，那么会使用 overrides 提供的版本，例如 fmt 6.0.0。如果没有，会选择 version>= 和 builtin-baseline 中最高的版本，例如：

version>= 7.1.3 + builtin-baseline(7.1.4) ， 会安装 fmt 7.1.4；

version>= 7.1.3 + builtin-baseline(7.1.2) ， 会安装 fmt 7.1.3。

3. Vcpkg允许升级版本，例如： 如果 zlib 依赖fmt，而且声明依赖 fmt 的 7.1.4 版本，那么 vcpkg 就会安装 7.1.4 版本，而不是 7.1.3。

4. 在您的项目中，如果想升级依赖库的版本，只需把最低版本改掉，或者是把 builtin-baseline 改为更新的版本。

5. Vcpkg 不会比较version类型不同的版本，例如：同一个库的2 个版本 ‘version-string: 7.1.3’ 与 `version: 7.1.4`，version 类型不同，所以不能比较。

以上大概都是能用到的知识

---

下面是我在项目中遇到的一些问题包括尝试的解决方案：

第一个问题：

因为 manifest 无法识别 "triplet" 字段，故无法在 vcpkg,json 中指定该字段，只能在外部创建本地的 vcpkg 三方库

D:\my_project\build>vcpkg install --triplet x86-windows-static
Detecting compiler hash for triplet x86-windows-static...
-- Using HTTP(S)_PROXY in environment variables.
Detecting compiler hash for triplet x64-windows...
The following packages will be built and installed:
....

最后会在项目的 build 文件下生成相关库

第二个问题：

我们随便打开一个自动生成的 vcpkg.json 会发现多了一些字段，比如 “port-version”

{
  "name": "libfabric",
  "version-semver": "1.13.2",
  "port-version": 2,
  "description": "The OpenFabrics Interfaces Working Group (OFIWG) and the Libfabr...
  "homepage": "https://github.com/ofiwg/libfabric",
  "supports": "windows & !uwp & x64 & !static",
  "dependencies": [
    {
      "name": "networkdirect-sdk",
      "platform": "windows"
    },
    {
      "name": "vcpkg-msbuild",
      "host": true,
      "platform": "windows"
    }
  ]
}

“port-version” 其实就是补丁，上面有提到，那么如何获取呢？

我们拿 curl 来举例，git show xxx(git show 命令后跟着一个特定的文件路径参数可以用于查看 Git 仓库中特定文件在指定提交（17fc556532840f436f67f8d08c943d1ff97ea2f9）的版本)

C:\Users\xxx\vcpkg>git show 17fc556532840f436f67f8d08c943d1ff97ea2f9 versions/c-/curl.json
commit 17fc556532840f436f67f8d08c943d1ff97ea2f9
Author: Theodore Tsirpanis <theodore.tsirpanis@tiledb.com>
Date:   Thu Jul 13 21:24:11 2023 +0300

    [curl] Add zstd feature. (#32533)

diff --git a/versions/c-/curl.json b/versions/c-/curl.json
index ba17a0c9f..9c4f96d98 100644
--- a/versions/c-/curl.json
+++ b/versions/c-/curl.json
@@ -1,5 +1,10 @@
 {
   "versions": [
+    {
+      "git-tree": "c2681b59ec41e4ec760fe10a60385202ee4763bb",
+      "version": "8.1.2",
+      "port-version": 2
+    },
     {
       "git-tree": "7d8ee40552d5b1c103d52b2b28d9577cb45e2593",
       "version": "8.1.2",

可以看到 port_version 是 2，git-tree 是 commit-id，跟 builtin-baseline 不同，我们一般用不到它

顺便补充下图：

最下面的图显示的绿颜色字符都是新增的，说明当前分支新增了一个 8.2.1  的版本