背景

在我们私有项目中，经常会遇到由于自定义功能而必须修改依赖库的代码然后使用修改代码后生成的库，或一些私有的依赖库未被加入vcpkg中的场景。这时无法通过vcpkg集成功能满足上述的需求只能手动配置这些依赖项的构建流程。overlay ports则是为了满足这些自定义需求而产生的。

使用场景

  1. 实际项目中所需依赖库的版本高于或低于vcpkg当前提供的版本。

  2. 需要修改vcpkg提供的库，才可以满足具体的使用情况，例如修改编译流程，或使用私人fork的repo。

  3. 需要使用未被添加进vcpkg的第三方库。

 

以下提供2种模式下的使用方法以及示例。

经典模式

使用方法

vcpkg现在对于install、update、upgrade、export与depend-info命令提供了选项 --overlay-ports，您可以将该选项添加这些命令之后来指定库覆盖安装的其他路径。可使用如下命令：

vcpkg install port_name  --overlay-ports=<port_dir>

其中port_dir可以是相对路径，也可以是绝对路径。同时还可以通过多个--overlay-ports选项来支持多个路径。

目前主要有以下几种使用方法：

  1. custom-ports目录下只存在一个库，例如sqlite3（使用绝对路径）

vcpkg install sqlite3 --overlay-ports="F:\custom-ports\sqlite3"

  2. custom-ports目录下包含多个库 （使用相对路径，custom-ports与vcpkg根目录处于同一级）

vcpkg install sqlite3 --overlay-ports=custom-ports

备注：这里的相对路径主要是针对vcpkg根目录来说的。

使用示例

假设覆盖安装库所在的目录结构为：（其中team-ports, my-ports与vcpkg根目录同级）

team-ports/
|-- sqlite3/
|---- vcpkg.json
|-----portfile.cmake
|-----这里省略sqlite3所需要的其他文件，如CMakeLists.txx, fix-arm-uwp.patch, sqlite3-config.in.cmake
|-- rapidjson/
|---- vcpkg.json
|-----portfile.cmake
|-- curl/
|---- vcpkg.json
|-----portfile.cmake

my-ports/
|-- sqlite3/
|---- vcpkg.json
|-----portfile.cmake
|-- rapidjson/
|---- vcpkg.json
|-----portfile.cmake

vcpkg
|-- ports/
|-- my-ports
|-- team-ports
|-- vcpkg.exe

需要注意的是，覆盖安装库中所包含的文件应该与所需要的具体的版本匹配，应该是一个可以独立安装成功的库，所以至少需要包含vcpkg.json(或CONTROL)和portfile.cmake文件。

1. 假设我们在多个路径下创建了同一个库的不同版本，同时传入了多个--overlay-ports， 这个时候，只会安装第一个--overlay-ports所指定路径下的覆盖库版本。

 ./vcpkg.exe install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports

 运行命令，输出如下：

	PS F:\new\vcpkg> ./vcpkg.exe install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports
	Computing installation plan...
	The following packages will be built and installed:
	    sqlite3[core]:x86-windows -> 3.32.3 -- F:\new\vcpkg\my-ports\sqlite3
	Detecting compiler hash for triplet x86-windows...
	Could not locate cached archive: C:\Users\usr\AppData\Local\vcpkg\archives\8e\8e0a5a364a7e4860280d89c600b9012fc5fc2d86e190dd417d43c76bc171586f.zip
	Starting package 1/1: sqlite3:x86-windows
	Building package sqlite3[core]:x86-windows...
	-- Installing port from location: F:\new\vcpkg\my-ports\sqlite3
	-- Using F:/new/vcpkg/downloads/sqlite-amalgamation-3320300.zip
	-- Cleaning sources at F:/new/vcpkg/buildtrees/sqlite3/src/3320300-5126d0ce85.clean. Use --editable to skip cleaning for the packages you specify.
	-- Extracting source F:/new/vcpkg/downloads/sqlite-amalgamation-3320300.zip
	-- Applying patch fix-arm-uwp.patch
	-- Using source at F:/new/vcpkg/buildtrees/sqlite3/src/3320300-5126d0ce85.clean
	-- Found external ninja('1.10.2').
	-- Configuring x86-windows
	-- Building x86-windows-dbg
	-- Building x86-windows-rel
	-- Performing post-build validation
	-- Performing post-build validation done
	Stored binary cache: C:\Users\usr\AppData\Local\vcpkg\archives\8e\8e0a5a364a7e4860280d89c600b9012fc5fc2d86e190dd417d43c76bc171586f.zip
	Building package sqlite3[core]:x86-windows... done
	Installing package sqlite3[core]:x86-windows...
	Installing package sqlite3[core]:x86-windows... done
	Elapsed time for package sqlite3:x86-windows: 24.04 s
	
	Total elapsed time: 28.65 s
	
	The package sqlite3:x86-windows provides CMake targets:
	
	    find_package(sqlite3 CONFIG REQUIRED)
	    target_link_libraries(main PRIVATE sqlite3)

Output

我们可以从上述的输出信息中看到，安装的确实是第一个参数指定的位置所包含的库。

sqlite3[core]:x86-windows -> 3.32.3 -- F:\new\vcpkg\my-ports\sqlite3

注意：如果team-ports, my-ports与vcpkg在同一级目录，则应该使用如下命令：

./vcpkg.exe install sqlite3 --overlay-ports=../my-ports --overlay-ports=../team-ports

 

2. 假设我们想安装不同路径下的多个库，例如team-ports/sqlite3，my-ports/rapidjson和vcpkg/ports/curl, 可以使用如下命令：

./vcpkg.exe install sqlite3 rapidjson curl --overlay-ports=my-ports/rapidjson --overlay-ports=ports/curl --overlay-ports=team-ports

运行命令，输出如下：

	PS F:\new\vcpkg> ./vcpkg.exe install sqlite3 rapidjson curl --overlay-ports=my-ports/rapidjson --overlay-ports=ports/curl --overlay-ports=team-ports
	Computing installation plan...
	The following packages will be built and installed:
	    curl[core,non-http,schannel,ssl,sspi,winssl]:x86-windows -> 7.74.0#8
	    rapidjson[core]:x86-windows -> 2020-09-14#2 -- F:\new\vcpkg\my-ports/rapidjson
	    sqlite3[core]:x86-windows -> 3.35.4#1 -- F:\new\vcpkg\team-ports\sqlite3
	Detecting compiler hash for triplet x86-windows...
	Could not locate cached archive: C:\Users\usr\AppData\Local\vcpkg\archives\96\9642ba57d6754383ffd191a2d7a3297487bfdbd6153b74016a59851cb6974681.zip
	Could not locate cached archive: C:\Users\usr\AppData\Local\vcpkg\archives\f3\f35d8628bc1565a710d1970eaafd35ecdd739fca748e979aee279e1058a5e445.zip
	Could not locate cached archive: C:\Users\usr\AppData\Local\vcpkg\archives\38\3827392c379f31dc5c383e0d973656cb0d243826700a41d48623c0d26a15f398.zip
	Starting package 1/3: curl:x86-windows
	Building package curl[core,non-http,schannel,ssl,sspi,winssl]:x86-windows...
	-- Downloading https://github.com/curl/curl/archive/e052859759b34d0e05ce0f17244873e5cd7b457b.tar.gz -> curl-curl-e052859759b34d0e05ce0f17244873e5cd7b457b.tar.gz...
	-- Extracting source F:/new/vcpkg/downloads/curl-curl-e052859759b34d0e05ce0f17244873e5cd7b457b.tar.gz
	-- Applying patch 0002_fix_uwp.patch
	-- Applying patch 0004_nghttp2_staticlib.patch
	-- Applying patch 0005_remove_imp_suffix.patch
	-- Applying patch 0006_fix_tool_depends.patch
	-- Applying patch 0007_disable_tool_export_curl_target.patch
	-- Applying patch 0010_fix_othertests_cmake.patch
	-- Applying patch 0011_fix_static_build.patch
	-- Applying patch 0012-fix-dependency-idn2.patch
	-- Applying patch 0020-fix-pc-file.patch
	-- Using source at F:/new/vcpkg/buildtrees/curl/src/e5cd7b457b-e7993911b1.clean
	-- Found external ninja('1.10.2').
	-- Configuring x86-windows
	-- Building x86-windows-dbg
	-- Building x86-windows-rel
	-- Using msys root at F:/new/vcpkg/downloads/tools/msys2/aa5af7b2aa7e90e8
	-- Fixing pkgconfig file: F:/new/vcpkg/packages/curl_x86-windows/lib/pkgconfig/libcurl.pc
	-- Fixing pkgconfig file: F:/new/vcpkg/packages/curl_x86-windows/debug/lib/pkgconfig/libcurl.pc
	-- Installing: F:/new/vcpkg/packages/curl_x86-windows/share/curl/vcpkg-cmake-wrapper.cmake
	-- Installing: F:/new/vcpkg/packages/curl_x86-windows/share/curl/copyright
	-- Performing post-build validation
	-- Performing post-build validation done
	Stored binary cache: C:\Users\usr\AppData\Local\vcpkg\archives\96\9642ba57d6754383ffd191a2d7a3297487bfdbd6153b74016a59851cb6974681.zip
	Building package curl[core,non-http,schannel,ssl,sspi,winssl]:x86-windows... done
	Installing package curl[core,non-http,schannel,ssl,sspi,winssl]:x86-windows...
	Installing package curl[core,non-http,schannel,ssl,sspi,winssl]:x86-windows... done
	Elapsed time for package curl:x86-windows: 4.282 min
	Starting package 2/3: rapidjson:x86-windows
	Building package rapidjson[core]:x86-windows...
	-- Installing port from location: F:\new\vcpkg\my-ports/rapidjson
	-- Downloading https://github.com/Tencent/rapidjson/archive/ce81bc9edfe773667a7a4454ba81dac72ed4364c.tar.gz -> Tencent-rapidjson-ce81bc9edfe773667a7a4454ba81dac72ed4364c.tar.gz...
	-- Extracting source F:/new/vcpkg/downloads/Tencent-rapidjson-ce81bc9edfe773667a7a4454ba81dac72ed4364c.tar.gz
	-- Using source at F:/new/vcpkg/buildtrees/rapidjson/src/c72ed4364c-35829b36f2.clean
	-- Found external ninja('1.10.2').
	-- Configuring x86-windows
	-- Building x86-windows-dbg
	-- Building x86-windows-rel
	-- Installing: F:/new/vcpkg/packages/rapidjson_x86-windows/share/rapidjson/copyright
	-- Performing post-build validation
	-- Performing post-build validation done
	Stored binary cache: C:\Users\usr\AppData\Local\vcpkg\archives\f3\f35d8628bc1565a710d1970eaafd35ecdd739fca748e979aee279e1058a5e445.zip
	Building package rapidjson[core]:x86-windows... done
	Installing package rapidjson[core]:x86-windows...
	Installing package rapidjson[core]:x86-windows... done
	Elapsed time for package rapidjson:x86-windows: 7.319 s
	Starting package 3/3: sqlite3:x86-windows
	Building package sqlite3[core]:x86-windows...
	-- Installing port from location: F:\new\vcpkg\team-ports\sqlite3
	-- Using F:/new/vcpkg/downloads/sqlite-amalgamation-3350400.zip
	-- Cleaning sources at F:/new/vcpkg/buildtrees/sqlite3/src/3350400-e6b299d337.clean. Use --editable to skip cleaning for the packages you specify.
	-- Extracting source F:/new/vcpkg/downloads/sqlite-amalgamation-3350400.zip
	-- Applying patch fix-arm-uwp.patch
	-- Using source at F:/new/vcpkg/buildtrees/sqlite3/src/3350400-e6b299d337.clean
	-- Found external ninja('1.10.2').
	-- Configuring x86-windows
	-- Building x86-windows-dbg
	-- Building x86-windows-rel
	-- Performing post-build validation
	-- Performing post-build validation done
	Stored binary cache: C:\Users\usr\AppData\Local\vcpkg\archives\38\3827392c379f31dc5c383e0d973656cb0d243826700a41d48623c0d26a15f398.zip
	Building package sqlite3[core]:x86-windows... done
	Installing package sqlite3[core]:x86-windows...
	Installing package sqlite3[core]:x86-windows... done
	Elapsed time for package sqlite3:x86-windows: 24.09 s
	
	Total elapsed time: 4.894 min
	
	The package curl:x86-windows provides CMake targets:
	
	    find_package(CURL CONFIG REQUIRED)
	    target_link_libraries(main PRIVATE CURL::libcurl)
	
	The package rapidjson:x86-windows provides CMake targets:
	
	    find_package(RapidJSON CONFIG REQUIRED)
	    target_link_libraries(main PRIVATE rapidjson)
	
	The package sqlite3:x86-windows provides CMake targets:
	
	    find_package(unofficial-sqlite3 CONFIG REQUIRED)
	    target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)

Output

 

manifest模式

使用方法

1. cmake工程集成：

在cmake命令行中添加参数VCPKG_OVERLAY_PORTS，其值必须为绝对路径。例如：

cmake.exe -G "Ninja" … --DCMAKE_TOOLCHAIN_FILE=<vcpkg_toolchain_path> -DVCPKG_OVERLAY_PORTS="<overlay_abs_path>"

2. msbuild工程集成：

在项目——属性（"Properties"）——配置属性（"Configuration Properties"）——vcpkg——Additional Options中添加以下参数，其值必须为绝对路径：

--overlay-ports=<overlay_abs_path>

可参考如下进行设置：

 

使用示例

manifest模式请先参照Manifest设置。首先创建overlay ports的路径并编写对应文件，假设为：

my-ports/
|-- sqlite3/
|---- vcpkg.json
|-----portfile.cmake

1. 示例 —CMake工程

创建并编写以下代码：

CMakeLists.txt：

cmake_minimum_required (VERSION 3.8)
project(test)
# Add source to this project's executable.
add_executable (test "test.cpp")
find_package(unofficial-sqlite3 CONFIG REQUIRED)
target_link_libraries(test PRIVATE unofficial::sqlite3::sqlite3)

vcpkg.json：

{
  "name": "test",
  "version-string": "0.0.1",
  "dependencies": [
    "sqlite3"
  ]
}

test.cpp：

#include <iostream>

int main()
{
    return 0;
}

执行以下命令：

"cmake.exe"  -G "Visual Studio 16 2019" -A x64  -DCMAKE_CONFIGURATION_TYPES:STRING="Debug" -DCMAKE_INSTALL_PREFIX:PATH="x64-Debug" -DCMAKE_TOOLCHAIN_FILE:STRING="VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake" -DVCPKG_OVERLAY_PORTS="<overlay_abs_prefix>/my-ports" "CMAKELISTS_PATH"

输出：

1> CMake generation started for configuration: 'x64-Debug'.
1> Command line: "cmd.exe" /c "%SYSTEMROOT%\System32\chcp.com 65001 >NUL && "C:\PROGRAM FILES (X86)\MICROSOFT VISUAL STUDIO\2019\COMMUNITY\COMMON7\IDE\COMMONEXTENSIONS\MICROSOFT\CMAKE\CMake\bin\cmake.exe"  -G "Visual Studio 16 2019" -A x64  -DCMAKE_CONFIGURATION_TYPES:STRING="Debug" -DCMAKE_INSTALL_PREFIX:PATH="C:\Users\usr\source\repos\ManifestTest\out\install\x64-Debug" -DCMAKE_TOOLCHAIN_FILE:STRING="F:\vcpkg\scripts\buildsystems\vcpkg.cmake" -DVCPKG_OVERLAY_PORTS:STRING="F:\vcpkg\my-ports"  "C:\Users\usr\source\repos\ManifestTest" 2>&1"
1> Working directory: C:\Users\usr\source\repos\ManifestTest\out\build\x64-Debug
1> [CMake] -- Running vcpkg install
1> [CMake] Detecting compiler hash for triplet x64-windows...
1> [CMake] The following packages will be removed:
1> [CMake]     jsoncpp:x64-windows
1> [CMake] The following packages will be built and installed:
1> [CMake]     sqlite3[core]:x64-windows -> 3.35.5 -- F:\vcpkg\my-ports\sqlite3
1> [CMake] Starting package 1/2: jsoncpp:x64-windows
1> [CMake] Removing package jsoncpp:x64-windows...
1> [CMake] Removing package jsoncpp:x64-windows... done
1> [CMake] Elapsed time for package jsoncpp:x64-windows: 36.88 ms
1> [CMake] Could not locate cached archive: C:\Users\usr\AppData\Local\vcpkg\archives\d3\d3f2d1afac1b9ed6984b8fee5642d83169e6251f20de57d88f3454f6965e59a0.zip
1> [CMake] Starting package 2/2: sqlite3:x64-windows
1> [CMake] Building package sqlite3[core]:x64-windows...
1> [CMake] -- Installing port from location: F:\vcpkg\my-ports\sqlite3
1> [CMake] -- Downloading https://sqlite.org/2021/sqlite-amalgamation-3350500.zip -> sqlite-amalgamation-3350500.zip...
1> [CMake] -- Extracting source F:/vcpkg/downloads/sqlite-amalgamation-3350500.zip
1> [CMake] -- Applying patch fix-arm-uwp.patch
1> [CMake] -- Using source at F:/vcpkg/buildtrees/sqlite3/src/3350500-adf155e1e1.clean
1> [CMake] -- Found external ninja('1.10.2').
1> [CMake] -- Configuring x64-windows
1> [CMake] -- Building x64-windows-dbg
1> [CMake] -- Building x64-windows-rel
1> [CMake] -- Performing post-build validation
1> [CMake] -- Performing post-build validation done
1> [CMake] Stored binary cache: C:\Users\usr\AppData\Local\vcpkg\archives\d3\d3f2d1afac1b9ed6984b8fee5642d83169e6251f20de57d88f3454f6965e59a0.zip
1> [CMake] Building package sqlite3[core]:x64-windows... done
1> [CMake] Installing package sqlite3[core]:x64-windows...
1> [CMake] Installing package sqlite3[core]:x64-windows... done
1> [CMake] Elapsed time for package sqlite3:x64-windows: 36.95 s
1> [CMake] 
1> [CMake] Total elapsed time: 36.99 s
1> [CMake] 
1> [CMake] -- Running vcpkg install - done
1> [CMake] -- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.19043.
1> [CMake] -- The C compiler identification is MSVC 19.28.29916.0
1> [CMake] -- The CXX compiler identification is MSVC 19.28.29916.0
1> [CMake] -- Detecting C compiler ABI info
1> [CMake] -- Detecting C compiler ABI info - done
1> [CMake] -- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.28.29910/bin/Hostx64/x64/cl.exe - skipped
1> [CMake] -- Detecting C compile features
1> [CMake] -- Detecting C compile features - done
1> [CMake] -- Detecting CXX compiler ABI info
1> [CMake] -- Detecting CXX compiler ABI info - done
1> [CMake] -- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.28.29910/bin/Hostx64/x64/cl.exe - skipped
1> [CMake] -- Detecting CXX compile features
1> [CMake] -- Detecting CXX compile features - done
1> [CMake] -- Configuring done
1> [CMake] -- Generating done
1> [CMake] -- Build files have been written to: C:/Users/usr/source/repos/manifesttest/out/build/x64-Debug
1> Extracted CMake variables.
1> Extracted source files and headers.
1> Extracted code model.
1> Extracted includes paths.
1> CMake generation finished.

Output

请注意以下日志：

1> [CMake] -- Installing port from location: F:\vcpkg\my-ports\sqlite3

此时您使用的sqlite3使用自定义的构建配置，路径为F:\vcpkg\my-ports\sqlite3。

 2. 示例 — MSBuild工程

创建一个控制台程序，名称为test。

在sln同级目录下创建清单文件vcpkg.json，并填入以下代码：

{
  "name": "test",
  "version-string": "0.0.1",
  "dependencies": [
    "jsoncpp"
  ]
}

在项目——属性——vcpkg 中将 User Vcpkg 设为 true，将--overlay-ports="<overlay_abs_prefix>\\my-ports"添加进Additional Options中。

编译项目，输出为：

Build started...
1>------ Build started: Project: test, Configuration: Debug Win32 ------
1>Installing vcpkg dependencies to C:\Users\usr\source\repos\test\vcpkg_installed\
1>"F:\vcpkg\scripts\buildsystems\msbuild\..\..\..\vcpkg.exe" install  --x-wait-for-lock --triplet "x86-windows" --vcpkg-root "F:\vcpkg\scripts\buildsystems\msbuild\..\..\..\\" "--x-manifest-root=C:\Users\usr\source\repos\test\\" "--x-install-root=C:\Users\usr\source\repos\test\vcpkg_installed\\" --overlay-ports="F:\\vcpkg\\my-ports"
1>Detecting compiler hash for triplet x86-windows...
1>The following packages will be removed:
1>    jsoncpp:x86-windows
1>The following packages will be built and installed:
1>    sqlite3[core]:x86-windows -> 3.35.5 -- F:\\vcpkg\\my-ports\sqlite3
1>Starting package 1/2: jsoncpp:x86-windows
1>Removing package jsoncpp:x86-windows...
1>Removing package jsoncpp:x86-windows... done
1>Elapsed time for package jsoncpp:x86-windows: 376.7 ms
1>Could not locate cached archive: C:\Users\usr\AppData\Local\vcpkg\archives\a0\a0e8ce62fd26180dadd7a9378b6bf457335d1a3a2759c3b0dbca077e26538096.zip
1>Starting package 2/2: sqlite3:x86-windows
1>Building package sqlite3[core]:x86-windows...
1>-- Installing port from location: F:\\vcpkg\\my-ports\sqlite3
1>-- Using F:/vcpkg/downloads/sqlite-amalgamation-3350500.zip
1>-- Cleaning sources at F:/vcpkg/buildtrees/sqlite3/src/3350500-adf155e1e1.clean. Use --editable to skip cleaning for the packages you specify.
1>-- Extracting source F:/vcpkg/downloads/sqlite-amalgamation-3350500.zip
1>-- Applying patch fix-arm-uwp.patch
1>-- Using source at F:/vcpkg/buildtrees/sqlite3/src/3350500-adf155e1e1.clean
1>-- Found external ninja('1.10.2').
1>-- Configuring x86-windows
1>-- Building x86-windows-dbg
1>-- Building x86-windows-rel
1>-- Performing post-build validation
1>-- Performing post-build validation done
1>Stored binary cache: C:\Users\usr\AppData\Local\vcpkg\archives\a0\a0e8ce62fd26180dadd7a9378b6bf457335d1a3a2759c3b0dbca077e26538096.zip
1>Building package sqlite3[core]:x86-windows... done
1>Installing package sqlite3[core]:x86-windows...
1>Installing package sqlite3[core]:x86-windows... done
1>Elapsed time for package sqlite3:x86-windows: 24.02 s
1>
1>Total elapsed time: 24.39 s
1>
1>test.cpp
1>test.vcxproj -> C:\Users\usr\source\repos\test\Debug\test.exe
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Output

请注意以下日志：

1>-- Installing port from location: F:\\vcpkg\\my-ports\sqlite3

此时您使用的sqlite3使用自定义的构建配置，路径为F:\vcpkg\my-ports\sqlite3。

 

参考：https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md