背景
在我們私有項目中，經常會遇到由於自定義功能而必須修改依賴庫的代碼然后使用修改代碼后生成的庫，或一些私有的依賴庫未被加入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)
我們可以從上述的輸出信息中看到，安裝的確實是第一個參數指定的位置所包含的庫。
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)
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.
請注意以下日志：
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 ==========
請注意以下日志：
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