vcpkg 特性 - Binarycaching

背景

在多个合作开发过程或使用自动化构建或自动化测试时，我们的私有项目每次构建通常需要使用多个依赖库，而这些依赖库在每次构建应当是统一的版本。

这样会遇到以下两个问题：

1. 通过vcpkg管理依赖项时，需要在每次构建私有项目时重新构建依赖项。

2. 多人开发时，需要从vcpkg中将依赖项导出并分发给其他合作开发者。

这两个问题导致了我们既花费额外的时间又不能保证依赖项的稳定性，binarycaching正是为了解决该问题而出现的。它将第一次安装的依赖项文件打包并默认存储，如果将来要求 vcpkg 安装具有相同构建配置的相同库，它只会从缓存中复制构建的二进制文件并在几秒钟内完成操作，并可使用已存储的缓存向其他合作开发者分发来导入他们的vcpkg中。简而言之，binarycaching做到了一次构建，多次使用。

binarycaching也可将缓存托管至本地计算机上的文件夹或网络文件共享，云服务（例如 GitHub、Azure 或许多其他服务），NuGet 源（例如 GitHub 或 Azure DevOps Artifacts）、Azure Blob Storage* 或 Google Cloud Storage* 中来解决跨异地构建问题。如果您的 CI /CD 提供了本机“缓存”功能，我们建议同时使用 vcpkg binarycaching和本机方法以获得最高性能的结果。您可通过命令 vcpkg help binarycaching 获得帮助信息。

使用

Binarycaching通过默认值、环境变量VCPKG_BINARY_SOURCES（设置为<source>;<source>;...）和命令行选项的组合进行配置--binarysource=<source>。使用binarycaching的源按照环境变量、默认值及命令行的顺序进行设置。binarysource参数可传递多次以实现优先级功能，若使用环境变量VCPKG_BINARY_SOURCES，请使用英文分号";"分隔多个缓存源。通过--binarysource=clear作为最后一个命令行选项传递，可以完全禁用二进制缓存。

注意： vcpkg默认开启此特性。

默认情况下，基于 zip 的存档将缓存在以下第一个有效位置：

I. Windows

1. %VCPKG_DEFAULT_BINARY_CACHE%

2. %LOCALAPPDATA%\vcpkg\archives

3. %APPDATA%\vcpkg\archives

II. 非Windows

1. $VCPKG_DEFAULT_BINARY_CACHE

2. $XDG_CACHE_HOME/vcpkg/archives

3. $HOME/.cache/vcpkg/archives

有效的源字符串 ( <source>)

形式	描述
clear	删除该命令前所有binarysource的设置与默认的binarysource设置(包括read,write以及readwrite)
default[,<operator>]	添加默认的基于文件的位置
files,<absolute path>[,<operator>]	添加基于文件的自定义位置
nuget,<uri>[,<operator>]	添加基于 NuGet 的源；相当于-SourceNuGet CLI的参数
nugetconfig,<path>[,<operator>]	添加基于 NuGet-config-file 的源；相当于-ConfigNuGet CLI的参数。此配置应指定defaultPushSource上传
nugettimeout,<seconds>	指定 NuGet 网络操作的超时时间；相当于-TimeoutNuGet CLI的参数
x-azblob,<baseuri>,<sas>[,<operator>]	实验性：将在没有警告的情况下更改或删除 添加 Azure Blob 存储源。使用共享访问签名验证。URL 应包含容器路径
interactive	为 NuGet 启用交互式凭据管理（用于调试；需要--debug在命令行上）

其中<operator>分为read, write与readwrite三种操作,是针对于读写权限的可选参数，可使用该参数控制是否使用二进制文件 ( read)（默认），是否存储二进制文件 ( write)，或两者均可（readwrite）。

注意：vcpkg始终使用默认的binarysource设置，若不希望使用它，请在其他binarysource参数前添加"--binarysource=clear"。

例如:

PS D:\vcpkg> .\vcpkg.exe install zlib --binarysource="files,d:\\cache,read"
Computing installation plan...
The following packages will be built and installed:
    zlib[core]:x86-windows -> 1.2.11#11
Detecting compiler hash for triplet x86-windows...
Using cached binary package: C:\Users\usr\AppData\Local\vcpkg\archives\1a\1a7e5c25146ede7fcdbe872ab506e974d5e07618f81312340a74bc8fb17b32dc.zip
Starting package 1/1: zlib:x86-windows
Building package zlib[core]:x86-windows...
Building package zlib[core]:x86-windows... done
Installing package zlib[core]:x86-windows...
Installing package zlib[core]:x86-windows... done
Elapsed time for package zlib:x86-windows: 111.2 ms

Total elapsed time: 3.134 s

The package zlib is compatible with built-in CMake targets:

    find_package(ZLIB REQUIRED)
    target_link_libraries(main PRIVATE ZLIB::ZLIB)

在此例中只添加了一个binarysource参数，vcpkg将首先检查并使用默认的binarysource设置的路径中的缓存，若不存在再查找并使用d:\\cache中的缓存。若均不存在，则会将缓存放入默认路径下。

PS D:\vcpkg> .\vcpkg.exe install zlib --binarysource=clear --binarysource="files,d:\\cache,readwrite"
Computing installation plan...
The following packages will be built and installed:
    zlib[core]:x86-windows -> 1.2.11#11

Detecting compiler hash for triplet x86-windows...
Using cached binary package: d:\\cache\1a\1a7e5c25146ede7fcdbe872ab506e974d5e07618f81312340a74bc8fb17b32dc.zip
Starting package 1/1: zlib:x86-windows
Building package zlib[core]:x86-windows...
Building package zlib[core]:x86-windows... done
Installing package zlib[core]:x86-windows...
Installing package zlib[core]:x86-windows... done
Elapsed time for package zlib:x86-windows: 99.93 ms

Total elapsed time: 3.335 s

The package zlib is compatible with built-in CMake targets:

    find_package(ZLIB REQUIRED)
    target_link_libraries(main PRIVATE ZLIB::ZLIB)

在此例中，由于clear命令在首位，所以vcpkg仅使用d:\\cache作为缓存路径，而不会使用默认的binarysource设置。

PS D:\vcpkg> .\vcpkg.exe install zlib --binarysource="files,d:\\cache,read"  --binarysource=clear
Computing installation plan...
The following packages will be built and installed:
    zlib[core]:x86-windows -> 1.2.11#11
Detecting compiler hash for triplet x86-windows...
Starting package 1/1: zlib:x86-windows
Building package zlib[core]:x86-windows...
-- Downloading http://www.zlib.net/zlib-1.2.11.tar.gz;https://downloads.sourceforge.net/project/libpng/zlib/1.2.11/zlib-1.2.11.tar.gz -> zlib1211.tar.gz...
-- Cleaning sources at D:/vcpkg/buildtrees/zlib/src/1.2.11-e9a093319e.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source D:/vcpkg/downloads/zlib1211.tar.gz
-- Applying patch cmake_dont_build_more_than_needed.patch
-- Applying patch 0001-Prevent-invalid-inclusions-when-HAVE_-is-set-to-0.patch
-- Applying patch add_debug_postfix_on_mingw.patch
-- Applying patch 0002-android-build-mingw.patch
-- Using source at D:/vcpkg/buildtrees/zlib/src/1.2.11-e9a093319e.clean
-- Configuring x86-windows
…
-- Installing: D:/vcpkg/packages/zlib_x86-windows/share/zlib/copyright
-- Performing post-build validation
-- Performing post-build validation done
Building package zlib[core]:x86-windows... done
Installing package zlib[core]:x86-windows...
Installing package zlib[core]:x86-windows... done
Elapsed time for package zlib:x86-windows: 10.74 s

Total elapsed time: 13.64 s

The package zlib is compatible with built-in CMake targets:

    find_package(ZLIB REQUIRED)
    target_link_libraries(main PRIVATE ZLIB::ZLIB)

在此例中，由于clear命令在所有binarysource命令之后，vcpkg会通过清除所有binarycaching设置而禁用binarycaching功能。

本地文件夹或网络文件夹

在install命令后添加以下参数来缓存并且使用缓存文件：

存储缓存文件命令：

--binarysource="files,<absolute_folder_path>,write"

使用binarycaching命令：

--binarysource="files,<absolute_folder_path>,read"

在manifest模式下，将以上参数加入VCPKG_INSTALL_OPTIONS（cmake项目）中或Additional Options（msbuild项目）中以使用binarycaching。详情请参阅https://blog.csdn.net/xiyangmo/article/details/119650687?spm=1001.2014.3001.5501。

 NuGet本地/网络源

在install命令后添加以下参数来缓存并且使用缓存文件：

存储缓存文件命令：

--binarysource=clear --binarysource="nuget,<absolute_folder_path>,write"

使用binarycaching命令：

--binarysource=clear --binarysource="nuget,<absolute_folder_path>,read"

注意：首先使用clear参数以避免使用本地缓存。

在manifest模式下，将以上参数加入VCPKG_INSTALL_OPTIONS（cmake项目）中或Additional Options（msbuild项目）中以使用binarycaching。

注意： 使用export命令导出的nuget包不能直接在binarycaching中使用。

VCPKG 默认开启binarycaching，当安装新的库时，vcpkg根据库的ABI判断该库的缓存是否与当前vcpkg中的库相同，如果不同，则会生成新的缓存文件，如果相同，则会用缓存的库。在实际项目共享缓存文件时，同样要注意库的ABI信息。

影响ABI的因素有：

1. ports/<port_name>中文件内容

2. toolchain文件内容

3. triplet文件内容

4. 依赖的二进制文件内容

5. cmake及其他构建使用工具版本

6. 编译器，目前binarychaching会影响abi值，在vcpkg下一个版本中，会有一个新的环境变量VCPKG_DISABLE_COMPILER_TRACKING 来控制是否将编译器作为一个检查项。由于vcpkg目前没有跟踪构建使用的编译器及Linux中的CRT版本，请在其他需要使用binarycaching的机器上安装统一的编译器及Linux中的CRT版本以避免编译器导致的使用问题。

参考：

https://github.com/microsoft/vcpkg/blob/master/docs/users/binarycaching.md

https://github.com/microsoft/vcpkg/blob/master/docs/specifications/binarycaching.md

首次发布于https://www.cnblogs.com/vcpkg/p/15167661.html