手把手制作一个vcpkg的安装包及port file相关说明

0. 前言

Windows平台的程序包的依赖管理一直以来都是个大难题。之前有NuGet，现在有vcpkg。 
本文的重点是先介绍一下vcpkg的特性，然后以一个实际例子说明，说明如何创建一个vcpkg安装包。

1. vcpkg简介

vcpkg是为了在windows平台能够方便获取一个C或者C++库。当前还处于预览版状态。不过已经有很多常见的库了，例如：

• openssl
• boost
• zlib
• glog
• libevent
• curl

等等，很多知名的C/C++库都已经提供vcpkg安装包。

2. vcpkg安装

首先，我们的windows系统必须安装有下列软件

• Visual Studio 2015 Update 3 or
• Visual Studio 2017
• CMake 3.8.0 or higher (note: downloaded automatically if not found)
• git.exe available in your path

然后，我们在windows命令行终端上运行：

d:\git> git clone https://github.com/Microsoft/vcpkgd:\git> cd vcpkgd:\git\vcpkg> .\bootstrap-vcpkg.batd:\git\vcpkg> .\vcpkg integrate install
1
2
3
4
5

3. 使用vcpkg获取C/C++库

使用vcpkg --help命令查看联席帮助文档：

D:\git\vcpkg>.\vcpkg --helpCommands:  vcpkg search [pat]              Search for packages available to be built  vcpkg install <pkg>...          Install a package  vcpkg remove <pkg>...           Uninstall a package  vcpkg remove --outdated         Uninstall all out-of-date packages  vcpkg list                      List installed packages  vcpkg update                    Display list of packages for updating  vcpkg hash <file> [alg]         Hash a file by specific algorithm, default SHA512  vcpkg integrate install         Make installed packages available user-wide. Requires admin privileges on first use  vcpkg integrate remove          Remove user-wide integration  vcpkg integrate project         Generate a referencing nuget package for individual VS project use  vcpkg export <pkg>... [opt]...  Exports a package  vcpkg edit <pkg>                Open up a port for editing (uses %EDITOR%, default 'code')  vcpkg import <pkg>              Import a pre-built library  vcpkg create <pkg> <url>             [archivename]        Create a new package  vcpkg owns <pat>                Search for files in installed packages  vcpkg cache                     List cached compiled packages  vcpkg version                   Display version information  vcpkg contact                   Display contact information to send feedbackOptions:  --triplet <t>                   Specify the target architecture triplet.                                  (default: %VCPKG_DEFAULT_TRIPLET%, see 'vcpkg help triplet')  --vcpkg-root <path>             Specify the vcpkg root directory                                  (default: %VCPKG_ROOT%)For more help (including examples) see the accompanying README.md.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

这里我们可以看到，很多有用的命令

• vcpkg search [pattern] 
  
  • 搜索一个C/C++库
• vcpkg install [pkg] 
  
  • 安装一个C/C++库
• vcpkg remove [pkg] 
  
  • 卸载(删除)一个C/C++库

下面举例，安装curl这个常用的C语言写的网络库。

D:\git\vcpkg>.\vcpkg install curlThe following packages will be built and installed:    curl:x86-windows  * libssh2:x86-windowsAdditional packages (*) will be installed to complete this operation.Building package libssh2:x86-windows...-- CURRENT_INSTALLED_DIR=D:/git/vcpkg/installed/x86-windows-- DOWNLOADS=D:/git/vcpkg/downloads-- CURRENT_PACKAGES_DIR=D:/git/vcpkg/packages/libssh2_x86-windows-- CURRENT_BUILDTREES_DIR=D:/git/vcpkg/buildtrees/libssh2-- CURRENT_PORT_DIR=D:/git/vcpkg/ports/libssh2/.-- Downloading https://www.libssh2.org/download/libssh2-1.8.0.tar.gz...-- Downloading https://www.libssh2.org/download/libssh2-1.8.0.tar.gz... OK-- Testing integrity of downloaded file...-- Testing integrity of downloaded file... OK-- Extracting source D:/git/vcpkg/downloads/libssh2-1.8.0.tar.gz-- Extracting done-- Applying patch D:/git/vcpkg/ports/libssh2/0001-Fix-UWP.patch-- Applying patch D:/git/vcpkg/ports/libssh2/0001-Fix-UWP.patch done-- Configuring x86-windows-rel-- Configuring x86-windows-rel done-- Configuring x86-windows-dbg-- Configuring x86-windows-dbg done-- Package x86-windows-rel-- Package x86-windows-rel done-- Package x86-windows-dbg-- Package x86-windows-dbg done-- Installing: D:/git/vcpkg/packages/libssh2_x86-windows/share/libssh2/copyright-- Performing post-build validation-- Performing post-build validation doneBuilding package libssh2:x86-windows... doneInstalling package libssh2:x86-windows...Installing package libssh2:x86-windows... doneBuilding package curl:x86-windows...-- CURRENT_INSTALLED_DIR=D:/git/vcpkg/installed/x86-windows-- DOWNLOADS=D:/git/vcpkg/downloads-- CURRENT_PACKAGES_DIR=D:/git/vcpkg/packages/curl_x86-windows-- CURRENT_BUILDTREES_DIR=D:/git/vcpkg/buildtrees/curl-- CURRENT_PORT_DIR=D:/git/vcpkg/ports/curl/.-- Downloading https://github.com/curl/curl/archive/curl-7_51_0.tar.gz...-- Downloading https://github.com/curl/curl/archive/curl-7_51_0.tar.gz... OK-- Testing integrity of downloaded file...-- Testing integrity of downloaded file... OK-- Extracting source D:/git/vcpkg/downloads/curl-7.51.0.tar.gz-- Extracting done-- Applying patch D:/git/vcpkg/ports/curl/0001_cmake.patch-- Applying patch D:/git/vcpkg/ports/curl/0001_cmake.patch done-- Applying patch D:/git/vcpkg/ports/curl/0002_fix_uwp.patch-- Applying patch D:/git/vcpkg/ports/curl/0002_fix_uwp.patch done-- Configuring x86-windows-rel-- Configuring x86-windows-rel done-- Configuring x86-windows-dbg-- Configuring x86-windows-dbg done-- Package x86-windows-rel-- Package x86-windows-rel done-- Package x86-windows-dbg-- Package x86-windows-dbg done-- Installing: D:/git/vcpkg/packages/curl_x86-windows/share/curl/copyright-- Performing post-build validation-- Performing post-build validation doneBuilding package curl:x86-windows... doneInstalling package curl:x86-windows...Installing package curl:x86-windows... done
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

可以看到，安装curl所需的依赖安装包libssh2也被自动安装处理好了。这类似与Linux系统下面的yum工具，自动处理rpm包的依赖关系，非常棒。

安装x64版本时，只需要在包名后面追加:x64-windows即可，例如 curl:x64-windows

D:\git\vcpkg>.\vcpkg install curl:x64-windowsThe following packages will be built and installed:    curl:x64-windows  * libssh2:x64-windowsAdditional packages (*) will be installed to complete this operation.Building package zlib:x64-windows......
1
2
3
4
5
6
7
8

4. Step by step 手把手教你如何制作一个vcpkg安装包

a) 创建一个C库项目

这里我们直接创建项目 https://github.com/zieckey/vcpkgdemo

然后提交了一些简单的代码及 CMakeLists.txt。并打了一个tag 1.0。从而我们得到一个该项目源码的现在的地址https://github.com/zieckey/vcpkgdemo/archive/1.0.zip

b) 从源头开始创建一个vcpkg安装包项目：Bootstrap with create

D:\git\vcpkg>.\vcpkg create vcpkgdemo https://github.com/zieckey/vcpkgdemo/archive/1.0.zip vcpkgdemo-1.0.zip-- Generated portfile: D:\git\vcpkg\ports\vcpkgdemo\portfile.cmake-- Generated CONTROL: D:\git\vcpkg\ports\vcpkgdemo\CONTROL-- To launch an editor for these new files, run--     .\vcpkg edit vcpkgdemo
1
2
3
4
5
6

我们可以看到，在D:\git\vcpkg\ports\目录下多出一个vcpkgdemo目录，并且目录下有两个文件portfile.cmake和CONTROL。

c) 定制CONTROL文件

CONTROL文件原始内容如下：

Source: vcpkgdemoVersion:Description:
1
2
3
4

我们修改为下面内容：

Source: vcpkgdemoVersion: 1.0Description: A demo to show how to create a vcpkg package
1
2
3
4

d) 定制portfile.cmake文件

portfile.cmake文件原始内容如下：

# Common Ambient Variables:#   CURRENT_BUILDTREES_DIR    = ${VCPKG_ROOT_DIR}\buildtrees\${PORT}#   CURRENT_PACKAGES_DIR      = ${VCPKG_ROOT_DIR}\packages\${PORT}_${TARGET_TRIPLET}#   CURRENT_PORT DIR          = ${VCPKG_ROOT_DIR}\ports\${PORT}#   PORT                      = current port name (zlib, etc)#   TARGET_TRIPLET            = current triplet (x86-windows, x64-windows-static, etc)#   VCPKG_CRT_LINKAGE         = C runtime linkage type (static, dynamic)#   VCPKG_LIBRARY_LINKAGE     = target library linkage type (static, dynamic)#   VCPKG_ROOT_DIR            = <C:\path\to\current\vcpkg>#   VCPKG_TARGET_ARCHITECTURE = target architecture (x64, x86, arm)#include(vcpkg_common_functions)set(SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/vcpkgdemo-1.0)vcpkg_download_distfile(ARCHIVE    URLS "https://github.com/zieckey/vcpkgdemo/archive/1.0.zip"    FILENAME "vcpkgdemo-1.0.zip"    SHA512 8805850856abdd39afdafa78dbd3a9e1d57d1a19a97579facf4571a0980799483574163e5f9a877a1fa38d541b7a0820c8ae7db61ae896803a8f89c5c22e386a)vcpkg_extract_source_archive(${ARCHIVE})vcpkg_configure_cmake(    SOURCE_PATH ${SOURCE_PATH}    PREFER_NINJA # Disable this option if project cannot be built with Ninja    # OPTIONS -DUSE_THIS_IN_ALL_BUILDS=1 -DUSE_THIS_TOO=2    # OPTIONS_RELEASE -DOPTIMIZE=1    # OPTIONS_DEBUG -DDEBUGGABLE=1)vcpkg_install_cmake()# Handle copyright#file(COPY ${SOURCE_PATH}/LICENSE DESTINATION ${CURRENT_PACKAGES_DIR}/share/vcpkgdemo)#file(RENAME ${CURRENT_PACKAGES_DIR}/share/vcpkgdemo/LICENSE ${CURRENT_PACKAGES_DIR}/share/vcpkgdemo/copyright)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

我们将其修改为下面内容：

include(vcpkg_common_functions)set(SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/vcpkgdemo-1.0)vcpkg_download_distfile(ARCHIVE    URLS "https://github.com/zieckey/vcpkgdemo/archive/1.0.zip"    FILENAME "vcpkgdemo-1.0.zip"    SHA512 5b526b848c05d9b30eac8aede6c6c19591baf45e601c54ed6a0aa40ae3f11545d9648f332fb991f9540e44cfc3fc3ea6dd6db3b6c9d8e076b74af08e9ac69740)message(STATUS "Begin to extract files ...")vcpkg_extract_source_archive(${ARCHIVE})message(STATUS "Building vcpkgdemo project ...")vcpkg_configure_cmake(    SOURCE_PATH ${SOURCE_PATH}    OPTIONS -DCMAKE_TOOLCHAIN_FILE=D:/git/vcpkg/scripts/buildsystems/vcpkg.cmake -DEVPP_VCPKG_BUILD=ON)vcpkg_install_cmake()file(MAKE_DIRECTORY ${CURRENT_PACKAGES_DIR}/share)file(MAKE_DIRECTORY ${CURRENT_PACKAGES_DIR}/share/vcpkgdemo)#remove duplicated filesfile(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)# remove not used cmake filesfile(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share )file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/lib/cmake )file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/lib/cmake )# Handle copyrightfile(COPY ${SOURCE_PATH}/LICENSE DESTINATION ${CURRENT_PACKAGES_DIR}/share/vcpkgdemo)file(RENAME ${CURRENT_PACKAGES_DIR}/share/vcpkgdemo/LICENSE ${CURRENT_PACKAGES_DIR}/share/vcpkgdemo/copyright)message(STATUS "Installing done")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

e) 测试

D:\git\vcpkg>.\vcpkg install vcpkgdemoThe following packages will be built and installed:    vcpkgdemo:x86-windowsBuilding package vcpkgdemo:x86-windows...-- CURRENT_INSTALLED_DIR=D:/git/vcpkg/installed/x86-windows-- DOWNLOADS=D:/git/vcpkg/downloads-- CURRENT_PACKAGES_DIR=D:/git/vcpkg/packages/vcpkgdemo_x86-windows-- CURRENT_BUILDTREES_DIR=D:/git/vcpkg/buildtrees/vcpkgdemo-- CURRENT_PORT_DIR=D:/git/vcpkg/ports/vcpkgdemo/.-- Using cached D:/git/vcpkg/downloads/vcpkgdemo-1.0.zip-- Testing integrity of cached file...-- Testing integrity of cached file... OK-- Begin to extract files ...-- Extracting source D:/git/vcpkg/downloads/vcpkgdemo-1.0.zip-- Extracting done-- Building vcpkgdemo project ...-- Configuring x86-windows-rel-- Configuring x86-windows-rel done-- Configuring x86-windows-dbg-- Configuring x86-windows-dbg done-- Package x86-windows-rel-- Package x86-windows-rel done-- Package x86-windows-dbg-- Package x86-windows-dbg done-- Installing done-- Performing post-build validation-- Performing post-build validation doneBuilding package vcpkgdemo:x86-windows... doneInstalling package vcpkgdemo:x86-windows...Installing package vcpkgdemo:x86-windows... done
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

如果不顺利，有错误发生的话，可以根据错误提示去 D:/git/vcpkg/buildtrees/vcpkgdemo 找错误日志，并解决。

f) 将D:\git\vcpkg\ports\vcpkgdemo整个目录提交到https://github.com/Microsoft/vcpkg

为了让这个vcpkg包能够被其世界上任何他人使用，我们必须将port file提交到https://github.com/Microsoft/vcpkg项目中。

也就是我们需要发起一个Pull Request到vcpkg的官方github地址 https://github.com/Microsoft/vcpkg

这里不再累述。

5. Step by step 手把手教你如何制作一个vcpkg安装包：实际案例

这里我们以evpp项目为例。evpp是一个基于libevent开发的现代化C++11高性能网络服务器，自带TCP/UDP/HTTP等协议的异步非阻塞式的服务器和客户端库。

第1步：从源头开始创建一个项目：Bootstrap with create

首先，我们需要有一个网络上可供下载的安装包地址，在这里我们选择https://github.com/Qihoo360/evpp/archive/v0.5.0.zip 
然后，我们需要为项目取一个好记的名字，最好是小写字母，这里我们选择 evpp 
最后，使用vcpkg create创建一个项目模板

D:\git\vcpkg>.\vcpkg create evpp https://github.com/Qihoo360/evpp/archive/v0.5.0.zip evpp-0.5.0.zip-- Generated portfile: D:\git\vcpkg\ports\evpp\portfile.cmake-- Generated CONTROL: D:\git\vcpkg\ports\evpp\CONTROL-- To launch an editor for these new files, run--     .\vcpkg edit evpp
1
2
3
4
5
6

我们可以看到，在D:\git\vcpkg\ports\目录下多出一个evpp目录，并且目录下有两个文件portfile.cmake和CONTROL。

第2步：定制CONTROL文件

CONTROL文件原始内容如下：

Source: evppVersion:Description:
1
2
3
4

我们修改为下面内容：

Source: evppVersion: 0.5.0Description: A modern C++ network library based on libevent for developing high performance network services in TCP/UDP/HTTP protocols.Build-Depends: glog, libevent
1
2
3
4
5

注意上面的依赖库写法，evpp依赖两个项目 glog 和 libevent，所以写法是 Build-Depends: glog, libevent

第3步：定制portfile.cmake文件

portfile.cmake文件原始内容如下：

# Common Ambient Variables:#   CURRENT_BUILDTREES_DIR    = ${VCPKG_ROOT_DIR}\buildtrees\${PORT}#   CURRENT_PACKAGES_DIR      = ${VCPKG_ROOT_DIR}\packages\${PORT}_${TARGET_TRIPLET}#   CURRENT_PORT DIR          = ${VCPKG_ROOT_DIR}\ports\${PORT}#   PORT                      = current port name (zlib, etc)#   TARGET_TRIPLET            = current triplet (x86-windows, x64-windows-static, etc)#   VCPKG_CRT_LINKAGE         = C runtime linkage type (static, dynamic)#   VCPKG_LIBRARY_LINKAGE     = target library linkage type (static, dynamic)#   VCPKG_ROOT_DIR            = <C:\path\to\current\vcpkg>#   VCPKG_TARGET_ARCHITECTURE = target architecture (x64, x86, arm)#include(vcpkg_common_functions)set(SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/evpp-0.5.0)vcpkg_download_distfile(ARCHIVE    URLS "https://github.com/Qihoo360/evpp/archive/v0.5.0.zip"    FILENAME "evpp-0.5.0.zip"    SHA512 fce8ebfec8b22b137f827a886f9ef658d70e060cef3950600ac42136d87cdd9357d78897348ed1d1c112c5e04350626fb218b02cba190a2c2a6fb81136eb2d7d)vcpkg_extract_source_archive(${ARCHIVE})vcpkg_configure_cmake(    SOURCE_PATH ${SOURCE_PATH}    PREFER_NINJA # Disable this option if project cannot be built with Ninja    # OPTIONS -DUSE_THIS_IN_ALL_BUILDS=1 -DUSE_THIS_TOO=2    # OPTIONS_RELEASE -DOPTIMIZE=1    # OPTIONS_DEBUG -DDEBUGGABLE=1)vcpkg_install_cmake()# Handle copyright#file(COPY ${SOURCE_PATH}/LICENSE DESTINATION ${CURRENT_PACKAGES_DIR}/share/evpp)#file(RENAME ${CURRENT_PACKAGES_DIR}/share/evpp/LICENSE ${CURRENT_PACKAGES_DIR}/share/evpp/copyright)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

我们将其修改为下面内容：

include(vcpkg_common_functions)set(EVPP_VERSION 0.5.0)set(EVPP_HASH fce8ebfec8b22b137f827a886f9ef658d70e060cef3950600ac42136d87cdd9357d78897348ed1d1c112c5e04350626fb218b02cba190a2c2a6fb81136eb2d7d)set(SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/evpp-${EVPP_VERSION})vcpkg_download_distfile(ARCHIVE    URLS "https://github.com/Qihoo360/evpp/archive/v${EVPP_VERSION}.zip"    FILENAME "evpp-${EVPP_VERSION}.zip"    SHA512 ${EVPP_HASH})message(STATUS "Begin to extract files ...")vcpkg_extract_source_archive(${ARCHIVE})message(STATUS "Building evpp project ...")vcpkg_configure_cmake(    SOURCE_PATH ${SOURCE_PATH}    OPTIONS -DCMAKE_TOOLCHAIN_FILE=D:/git/vcpkg/scripts/buildsystems/vcpkg.cmake -DEVPP_VCPKG_BUILD=ON)vcpkg_install_cmake()file(MAKE_DIRECTORY ${CURRENT_PACKAGES_DIR}/share)file(MAKE_DIRECTORY ${CURRENT_PACKAGES_DIR}/share/evpp)#remove duplicated filesfile(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)# remove not used cmake filesfile(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share )file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/lib/cmake )file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/lib/cmake )# Handle copyrightfile(COPY ${SOURCE_PATH}/LICENSE DESTINATION ${CURRENT_PACKAGES_DIR}/share/evpp)file(RENAME ${CURRENT_PACKAGES_DIR}/share/evpp/LICENSE ${CURRENT_PACKAGES_DIR}/share/evpp/copyright)message(STATUS "Installing done")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

第4步：测试

D:\git\vcpkg>.\vcpkg install evppThe following packages will be built and installed:    evpp:x86-windowsBuilding package evpp:x86-windows...-- CURRENT_INSTALLED_DIR=D:/git/vcpkg/installed/x86-windows-- DOWNLOADS=D:/git/vcpkg/downloads-- CURRENT_PACKAGES_DIR=D:/git/vcpkg/packages/evpp_x86-windows-- CURRENT_BUILDTREES_DIR=D:/git/vcpkg/buildtrees/evpp-- CURRENT_PORT_DIR=D:/git/vcpkg/ports/evpp/.-- Using cached D:/git/vcpkg/downloads/evpp-0.5.0.zip-- Testing integrity of cached file...-- Testing integrity of cached file... OK-- Begin to extract files ...-- Extracting done-- Building evpp project ...-- Configuring x86-windows-rel-- Configuring x86-windows-rel done-- Configuring x86-windows-dbg-- Configuring x86-windows-dbg done-- Package x86-windows-rel-- Package x86-windows-rel done-- Package x86-windows-dbg-- Package x86-windows-dbg done-- Installing done-- Performing post-build validation-- Performing post-build validation doneBuilding package evpp:x86-windows... doneInstalling package evpp:x86-windows...Installing package evpp:x86-windows... done
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

第5步：将D:\git\vcpkg\ports\evpp整个目录提交到https://github.com/Microsoft/vcpkg

也就是我们需要发起一个Pull Request到vcpkg的官方github地址 https://github.com/Microsoft/vcpkg

这里不再累述。

6. 最后

evpp项目官网地址为：https://github.com/Qihoo360/evpp

为vcpkg制作的安装包，已经提交Pull Request ：https://github.com/Microsoft/vcpkg/pull/1177

vcpkgdemo的原始代码请见 https://github.com/zieckey/vcpkgdemo