Vcpkg新增头文件库示例

概述

针对仅仅是头文件的包，新增包配置相对来讲比较简单，基本上只有2个步骤：

1. 获取源代码
2. 复制头文件

源码包(WebSocket++)

WebSocket++是一个高性能、标准兼容、开源的C++ WebSocket客户端和服务端库。
在其github主页上可以找到对应的releases:

Github上的releases

其最新relase是0.7.0版本,并附有相应的压缩包下载。

首先在vcpkg的ports下建立websocketpp路径,CONTROL和portfile.cmake模板位于vcpkg\scripts\templates。

修改CONTROL文件内容为:

Source: websocketpp
Version: 0.7.0
Description: C++ websocket client/server library 
```
然后是调整`portfile.cmake`内容：
### 指定其为仅包含头文件的库
```
##header-only library
```
### 导入vcpkg方法
```
include(vcpkg_common_functions)
```
### 指定源代码路径
```
SET(SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/websocketpp-0.7.0)
```
其中`${CURRENT_BUILDTREES_DIR}`为vcpkg的build路径加上库名,此处对应位置为 ` vcpkg\buildtrees\websocketpp `。

### 下载源代码包
```
vcpkg_download_distfile(ARCHIVE
    URLS "https://github.com/zaphoyd/websocketpp/archive/0.7.0.tar.gz"
    FILENAME "websocketpp-0.7.0.tar.gz"
    SHA512 91a86d4f5120db3f474169bb146f865f82167b1e9eedabec8793b31005e4ce3d22083283bc1b9f9e37fa0da835addcb2b68260a27c753852c06b3b1bb2f3c12e
)
```
- `ARCHIVE`为cmake变量，该变量即为下载到的源码包路径；
- `FILENAME`为下载完成后的文件名,注意尽量不要和其它库冲突；
- `SHA512`为文件特征码,随便写一个,然后下载后校验会提示正确的特征码；
- 文件会被下载到vcpkg的downloads路径,此处对应的路径及源代码包为`vcpkg\downloads\websocketpp-0.7.0.tar.gz`。

### 解压源代码包
```
vcpkg_extract_source_archive(${ARCHIVE})
```
经过该操作后,会被解压到之前的`SOURCE_PATH`,解压完成后的结果如图:

![解压结果](http://upload-images.jianshu.io/upload_images/4066292-cf3d92169b1978df.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

### 处理licence文件
vcpkg必须要将授权文件放在包路径下,并且名称为copyright：
```
file(COPY ${SOURCE_PATH}/COPYING DESTINATION ${CURRENT_PACKAGES_DIR}/share/websocketpp)
file(RENAME ${CURRENT_PACKAGES_DIR}/share/websocketpp/COPYING ${CURRENT_PACKAGES_DIR}/share/websocketpp/copyright)
```
- `SOURCE_PATH`是源代码路径;
- `${CURRENT_PACKAGES_DIR}`为`vcpkg\packages`加上包名`websocketpp`和对应的triplets，当用户安装`x86-windows`库时,该路径为`\vcpkg\packages\websocketpp_x86-windows`；
- 一般为两步操作,复制和重命名

### 复制头文件
```
file(INSTALL ${SOURCE_PATH}/websocketpp DESTINATION ${CURRENT_PACKAGES_DIR}/include)
```
此处注意,`${SOURCE_PATH}/websocketpp`和`${SOURCE_PATH}/websocketpp/`,前者是复制`websocketpp`下文件，附带上了websocketpp路径；后者复制出来的路径不包含websocketpp路径,效果如图:

![带websocketpp路径](http://upload-images.jianshu.io/upload_images/4066292-2601a986c925abdd.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)


![不带websocketpp路径](http://upload-images.jianshu.io/upload_images/4066292-8298052e8e3cf68c.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

针对使用时的影响就是,前者引用头文件为`#include `;后者引用头文件为`#include `。

另外,添加文件过滤的写法为
```
file(INSTALL ${SOURCE_PATH}/websocketpp DESTINATION ${CURRENT_PACKAGES_DIR}/include  FILES_MATCHING PATTERN "*.hpp")
```
### 结果
经过上述操作之后,安装指令会在`vcpkg\installed`下对应的triplets路径中存放头文件等信息；移除包的时候也只会从该路径移除对应的信息。

## 源代码(cxx-prettyprint)
[cxx-prettyprint](http://louisdx.github.io/cxx-prettyprint/)是一个用来打印C++容器内容的头文件库。
在其[github主页](https://github.com/louisdx/cxx-prettyprint)上并没有对应的releases,因而需要使用git获取源代码。

其`CONTROL`文件内容为:
```
Source: cxx-prettyprint
Version: 0.1.0
Description: A header-only library for C++(0x) that allows automagic pretty-printing of any container. 
```
对应的`portfile.cmake`编写要点:
### 请求git
```
find_program(GIT git)
```
该指令会获取git.exe,供获取代码使用。

### 指定源代码服务器路径和分支
```
set(GIT_URL "https://github.com/louisdx/cxx-prettyprint.git")
set(GIT_REF "9ab26d2")
```
### clone源代码库
```
if(NOT EXISTS "${DOWNLOADS}/cxx-prettyprint.git")
    message(STATUS "Cloning")
    vcpkg_execute_required_process(
        COMMAND ${GIT} clone --bare ${GIT-URL} ${DOWNLOADS}/cxx-prettyprint.git
        WORKING_DIRECTORY ${DOWNLOADS}
        LOGNAME clone
    )
endif(NOT EXISTS "${DOWNLOADS}/cxx-prettyprint.git")
message(STATUS "Cloning done")
```
- `${DOWNLOADS}/`即为vcpkg的下载路径；

### 获取分支代码到源代码路径
```
if(NOT EXISTS "${CURRENT_BUILDTREES_DIR}/src/.git")
    message(STATUS "Adding worktree")
    file(MAKE_DIRECTORY ${CURRENT_BUILDTREES_DIR})
    vcpkg_execute_required_process(
        COMMAND ${GIT} worktree add -f --detach ${CURRENT_BUILDTREES_DIR}/src ${GIT_REF}
        WORKING_DIRECTORY ${DOWNLOADS}/cxx-prettyprint.git
        LOGNAME worktree
    )
endif(NOT EXISTS "${CURRENT_BUILDTREES_DIR}/src/.git")
message(STATUS "Adding worktree done")
```
经过该操作后就可以在`vcpkg\buildtrees\cxx-prettyprint\src`下找到源代码仓库内容了,结构如下:

![源代码目录结构](http://upload-images.jianshu.io/upload_images/4066292-5862345993b2d8c5.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

### 处理license文件
```
set(SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src)

file(COPY ${SOURCE_PATH}/LICENSE_1_0.txt DESTINATION ${CURRENT_PACKAGES_DIR}/share/cxx-prettyprint)
file(RENAME ${CURRENT_PACKAGES_DIR}/share/cxx-prettyprint/LICENSE_1_0.txt ${CURRENT_PACKAGES_DIR}/share/cxx-prettyprint/copyright)
```

### 复制头文件
```
file(INSTALL ${CURRENT_BUILDTREES_DIR}/src/ DESTINATION ${CURRENT_PACKAGES_DIR}/include FILES_MATCHING PATTERN "*.hpp")
```
只需要将两个`hpp`文件复制到包路径即可。

## 调试方法
- 源代码下载
源代码下载路径在`vcpkg/downloads`,可以手动下载或者clone源代码仓库到该位置
- 构建/解压缩
构建/解压缩等过程，中间信息存放在`vcpkg/buildtrees`下,如果出现问题，可以去相关路径下查看对应日志
- 安装
安装出来的包结果存放在`vcpkg/packages`下,如果信息不正确可以去对应路径查看
- 使用
安装的结果供使用时存放在`vcpkg/installed`下,如果使用过程出现问题，可以去对应路径查看是否有内容缺失或者错误，进而调整包配置。