手把手制作一个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/vcpkg
d:\git> cd vcpkg
d:\git\vcpkg> .\bootstrap-vcpkg.bat
d:\git\vcpkg> .\vcpkg integrate install
3. 使用vcpkg获取C/C++库
使用vcpkg --help命令查看联席帮助文档：
D:\git\vcpkg>.\vcpkg --help
Commands:
vcpkg search [pat] Search for packages available to be built
vcpkg install ... Install a package
vcpkg remove ... 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 [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 ... [opt]... Exports a package
vcpkg edit Open up a port for editing (uses %EDITOR%, default 'code')
vcpkg import Import a pre-built library
vcpkg create
[archivename] Create a new package
vcpkg owns Search for files in installed packages
vcpkg cache List cached compiled packages
vcpkg version Display version information
vcpkg contact Display contact information to send feedback
Options:
--triplet Specify the target architecture triplet.
(default: %VCPKG_DEFAULT_TRIPLET%, see 'vcpkg help triplet')
--vcpkg-root Specify the vcpkg root directory
(default: %VCPKG_ROOT%)
For more help (including examples) see the accompanying README.md.
这里我们可以看到，很多有用的命令
- vcpkg search [pattern]
- 搜索一个C/C++库
- vcpkg install [pkg]
- 安装一个C/C++库
- vcpkg remove [pkg]
- 卸载(删除)一个C/C++库
下面举例，安装curl这个常用的C语言写的网络库。
D:\git\vcpkg>.\vcpkg install curl
The following packages will be built and installed:
curl:x86-windows
* libssh2:x86-windows
Additional 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 done
Building package libssh2:x86-windows... done
Installing package libssh2:x86-windows...
Installing package libssh2:x86-windows... done
Building 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 done
Building package curl:x86-windows... done
Installing package curl:x86-windows...
Installing package curl:x86-windows... done
可以看到，安装curl所需的依赖安装包libssh2也被自动安装处理好了。这类似与Linux系统下面的yum工具，自动处理rpm包的依赖关系，非常棒。
安装x64版本时，只需要在包名后面追加:x64-windows即可，例如 curl:x64-windows
D:\git\vcpkg>.\vcpkg install curl:x64-windows
The following packages will be built and installed:
curl:x64-windows
* libssh2:x64-windows
Additional packages (*) will be installed to complete this operation.
Building package zlib:x64-windows...
...
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
我们可以看到，在D:\git\vcpkg\ports\目录下多出一个vcpkgdemo目录，并且目录下有两个文件portfile.cmake和CONTROL。
c) 定制CONTROL文件
CONTROL文件原始内容如下：
Source: vcpkgdemo
Version:
Description:
我们修改为下面内容：
Source: vcpkgdemo
Version: 1.0
Description: A demo to show how to create a vcpkg package
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 =
# 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)
我们将其修改为下面内容：
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 files
file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)
# remove not used cmake files
file(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 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)
message(STATUS "Installing done")
e) 测试
D:\git\vcpkg>.\vcpkg install vcpkgdemo
The following packages will be built and installed:
vcpkgdemo:x86-windows
Building 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 done
Building package vcpkgdemo:x86-windows... done
Installing package vcpkgdemo:x86-windows...
Installing package vcpkgdemo:x86-windows... done
如果不顺利，有错误发生的话，可以根据错误提示去 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
我们可以看到，在D:\git\vcpkg\ports\目录下多出一个evpp目录，并且目录下有两个文件portfile.cmake和CONTROL。
第2步：定制CONTROL文件
CONTROL文件原始内容如下：
Source: evpp
Version:
Description:
我们修改为下面内容：
Source: evpp
Version: 0.5.0
Description: A modern C++ network library based on libevent for developing high performance network services in TCP/UDP/HTTP protocols.
Build-Depends: glog, libevent
注意上面的依赖库写法，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 =
# 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)
我们将其修改为下面内容：
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 files
file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)
# remove not used cmake files
file(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 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)
message(STATUS "Installing done")
第4步：测试
D:\git\vcpkg>.\vcpkg install evpp
The following packages will be built and installed:
evpp:x86-windows
Building 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 done
Building package evpp:x86-windows... done
Installing package evpp:x86-windows...
Installing package evpp:x86-windows... done
第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