C++包管理工具vcpkg

Vcpkg

• 1. 说明
• 2. 安装
• 3. 基础操作
  • 3.1. 安装包
  • 3.2. 查看支持的平台
  • 3.3. 安装过程解析
  • 3.4. vcpkg的各个目录
• 4. 其他操作
  • 4.1. 安装到项目目录
  • 4.2. 查询是否包含某包
  • 4.3. 列出已经安装的开源库
  • 4.4. 更新已经安装的开源库：
  • 4.5. 导出已安装的开源库
  • 4.6. 导入备份的开源库(已失效)
  • 4.7. 使用导出的开源库
  • 4.8. 设置VS项目的编译平台
    • 4.8.1. 方式1-编辑工程文件
    • 4.8.2. 方式2-设置项目属性
  • 4.9. 自定义编译平台
  • 4.10. 自定义安装路径
• 5. 疑难
  • 5.1. 警告：English language pack is unavailable
  • 5.2. 疑难-无法解析的外部符号
  • 5.3. 疑难-“RuntimeLibrary”不匹配
    • 5.3.1. 问题描述：
    • 5.3.2. 解决方法1
    • 5.3.3. 解决方案2
  • 5.4. 疑难-安装失败

1. 说明

vcpkg是开源的，C++包管理工具。支持跨平台。此文档是针对windows的。其他操作系统上请参考官方文档

参考：

• Visual Studio开源库集成器Vcpkg全教程–利用Vcpkg轻松集成开源第三方库
• 官方文档：vcpkg docs
• github仓库地址

2. 安装

第一步，安装vcpkg.使用下面命令

# 下载或克隆,建议放在C:\dev\vcpkg
git clone https://github.com/microsoft/vcpkg
# 执行下面命令,来下载vcpkg.exe到根目录
.\vcpkg\bootstrap-vcpkg.bat

• 然后将它的文件夹路径添加到环境变量path中即可。

第二步，安装CMAKE

• 该版本的vcpkg依赖CMAKE3.20。打开命令行工具，输入cmake，即可检查cmake是否已安装。
• 可以在cmake的github官网地址下载。然后解压出来，新建环境变量CMAKE_ROOT,值为它的根目录。然后将%CMAKE_ROOT%\bin添加到环境变量path中。

3. 基础操作

3.1. 安装包

使用命令vcpkg install 包名即安装完成，如果失败了，就再试一次该命令。很多时候，第二次执行该安装命令才能安装成功.

• 集成到全局(Visual Studio开发环境和msbuild命令行),命令如下。如果集成到了全局，在Visual Studio中，就可以直接使用该包了，就像C++自带的库一样。不需要添加到库目录、引用目录、编译链接等

  vcpkg integrate install
  

• 如果不想全局集成，就使用下面命令

  vcpkg integrate remove
  

要注意的是，在windows平台下，默认安装的是x86-windows。那么使用x64平台时，就需要安装x64-windows.使用命令

vcpkg install 包名:x64-windows

或者

vcpkg install 包名  --triplet=x64-windows

3.2. 查看支持的平台

输入下面命令，就可以看到vcpkg支持的平台

vcpkg help triplet

它会列出下面这些平台

• x64-uwp
• x64-windows-static
• x64-windows
• x86-uwp
• x86-windows-static
• x86-windows
• arm-uwp
• arm-windows
• arm64-uwp
• arm64-windows

但其实安装目录下triplets文件夹里的都可以。triplets的子文件夹community里的cmake文件也都可以。同理，可以仿造

3.3. 安装过程解析

如果执行vcpkg

• 先下载到vcpkg根目录下的downloads文件夹,如果发现它下载很慢。可以先退出安装，然后通过浏览器、迅雷等下载下来后放到downloads文件夹
• 然后，安装到vcpkg根目录下的installed文件夹

如果再VisualStudio中利用vcpkg.json来安装

• 它就会安装到与工程文件同级的vcpkg_installed文件夹中

3.4. vcpkg的各个目录

使用vcpkg install命令时，可以看到一些输出信息(可以用>将输出信息输出到文件中，如使用命令vcpkg install boost-filesystem > log.txt)。前面的输出信息中可以看到下面内容。

[DEBUG] Using vcpkg-root: C:\GreenSoftware\vcpkg
[DEBUG] Using installed-root: C:\GreenSoftware\vcpkg\installed
[DEBUG] BuiltinRegistry initialized with: “”
[DEBUG] Using buildtrees-root: C:\GreenSoftware\vcpkg\buildtrees
[DEBUG] Using downloads-root: C:\GreenSoftware\vcpkg\downloads
[DEBUG] Using packages-root: C:\GreenSoftware\vcpkg\packages
[DEBUG] Using scripts-root: C:\GreenSoftware\vcpkg\scripts
[DEBUG] Using ports-root: C:\GreenSoftware\vcpkg\ports
[DEBUG] Using versions-root: C:\GreenSoftware\vcpkg\versions
[DEBUG] Default binary cache path is: C:\Users\tanzi_WTG\AppData\Local\vcpkg\archives

4. 其他操作

4.1. 安装到项目目录

对于visual Studio,执行vcpkg integrate install后，VS的C++工程属性中就会多出一个vcpkg

点进去。有一个选项USe Vcpkg Manifest,默认为No。设置为Yes.

这时候必须在项目中添加vcpkg.json文件，否则就会报错

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg/master/scripts/vcpkg.schema.json",
  "name": "my-application",
  "version": "0.1.1",
  "dependencies": [
    "glog",
    "boost-filesystem",
  ]
}

关于vcpkg.json的使用，见manifest-files

4.2. 查询是否包含某包

• 方式1：进入 vcpkg的官网查询
• 方式2：使用命令vcpkg search 包名

4.3. 列出已经安装的开源库

命令vcpkg list

4.4. 更新已经安装的开源库：

• 命令vcpkg update, 会列出可以升级的开源库
• 命令vcpkg upgrade, 会升级所有可以升级的开源库

4.5. 导出已安装的开源库

• 有的时候，一个项目组中有很多人，不需要每个人都参与编译。一个人编译好所有开源库后到处给别人即可。
• 有的时候也是出于备份的目的，也会导出已经安装的开源库。

例如，我要导出jsoncpp库，那么执行命令：vcpkg.exe export jsoncpp --7zip

注意，导出时必须指定导出的包格式。vcpkg支持5种导出包格式，有

参数	格式
–raw	以不打包的目录格式导出
–nuget	以nuget包形式导出
–ifw	我也不知道这是啥格式
–zip	以zip压缩包形式导出
–7zip	以7z压缩包形式导出

默认情况下只会导出x86-windows的包

• 我们可以自己指定平台，vcpkg export 包名 包名:x64-windows --7zip
• 也可以指定多个平台，vcpkg export 包名:x86-windows 包名:x64-windows --7zip

导出nuget包的demo如下。但是感觉还要手动在工程属性中设置lib,include目录,麻烦。

# 导出多个x64-windows的nuget包,并设置包名
vcpkg export glog boost-filesystem inih stb glew glad glfw3 --triplet=x64-windows --nuget --output=dependencies.holo_engine.x64

4.6. 导入备份的开源库(已失效)

导入比较简单，执行import指令即可。例如：

vcpkg import xxx.7z

4.7. 使用导出的开源库

导出时，直接导出7zip或zip即可。如

vcpkg export glog boost-filesystem inih stb glew glad glfw3 --triplet=x64-windows --7zip --output=Dependency.OpticalTweezers

使用时，将它解压出来。

• 对于VisualStudio,使用scripts\buildsystems\msbuild\vcpkg.targets
  • 使用方法，以文本方式打开工程文件.vcxproj。然后添加下面语句到<project></Project>一级子节点(我已经将解压目录设置成了环境变量CpplibPath)。可以在该文件中搜索Microsoft.Cpp.targets,它就是这么用的。win10,vs2019下亲测有效。

    <Import Project="$(CpplibPath)\scripts\buildsystems\msbuild\vcpkg.targets" />
    

• 对于CMake,使用scripts\buildsystems\vcpkg.cmake
  • 使用方法，使用cmake命令时，申明 CMAKE_TOOLCHAIN_FILE变量。

    cmake .. "-DCMAKE_TOOLCHAIN_FILE=C:\dev\CppLib\scripts\buildsystems\vcpkg.cmake"
    

参考链接：As there is no import command, why does the export command exist?

4.8. 设置VS项目的编译平台

4.8.1. 方式1-编辑工程文件

改用static平台。首先要保证vcpkg安装了static平台的包。然后用文本工具打开vcxproj文件，搜索global,将下面代码中的VcpkgTriplet设置添加进去

<PropertyGroup Label="Globals">
  <!-- .... -->
  <VcpkgTriplet Condition="'$(Platform)'=='Win32'">x86-windows-static</VcpkgTriplet>
  <VcpkgTriplet Condition="'$(Platform)'=='x64'">x64-windows-static</VcpkgTriplet>
</PropertyGroup>

4.8.2. 方式2-设置项目属性

方式一的设置，和项目属性-vcpkg-Triplet是同一个设置(如下图)。也可以在这里改。

如果只是修改static,只用将Use Static Libraries改一下即可。

VS Platform	Use Static Libraries	Triplet	使用的triplet库
x64	否	空	x64-windows
x64	是	空	x64-windows-static
x86	否	空	x86-windows
x86	是	空	x86-windows-static

4.9. 自定义编译平台

编译平台的设置都在vcpkg根目录下的triplets文件夹中。如下图，有很多.cmake文件，community文件中也有，每一个都代表一个编译平台。

我们可以用文本编辑工具编辑它们，也可以自己模仿着写一个。如，我模仿x86-windows-v120.cmake添加一个x86-windows-v142.cmake。内容如下。然后使用时，就使用命令vcpkg install 包名:x86-windows-v142。结果就是多了一个vcpkg根目录\installed\x86-windows-v142文件夹

set(VCPKG_TARGET_ARCHITECTURE x86)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)
set(VCPKG_PLATFORM_TOOLSET "v142")
set(VCPKG_DEP_INFO_OVERRIDE_VARS "v142")

4.10. 自定义安装路径

使用命令vcpkg install --help可以看到，还有下面几个参数

• --x-install-root可以用来指明安装路径。相当于自定义vcpkg-root/installed路径
• --x-packages-root可以用来指明包的路径。

例如，下面命令会让它在x64-windows-static文件夹内,创建一个vcpkg目录，再创建一个x64-windows目录，安装进去。如果不适用绝对路径，就会自动使用cmd的当前路径

vcpkg install enet:x64-windows --x-install-root="C:\GreenSoftware\vcpkg\installed\x64-windows-static"

而下面命令，会让它在x64-windows-static文件夹内,创建一个vcpkg目录，再创建两个目录detect_compiler_x64-windows和enet_x64-windows，然后将enet安装到第二个文件夹中。

vcpkg install enet:x64-windows --x-packages-root="C:\GreenSoftware\vcpkg\installed\x64-windows-static"

5. 疑难

5.1. 警告：English language pack is unavailable

问题描述

Warning: The following VS instances are excluded because the English language pack is unavailable.
C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools

解决方案1
也可以在.cmake文件中，指明VS的路径。添加如下语句

set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Enterprise")

解决方案2
给visual studio安装英文语言包呗。步骤如下，启动vs_installer.exe,然后找到Visual studio生成工具

如果找不到Visual studio生成工具，就去下面位置下载安装

5.2. 疑难-无法解析的外部符号

这是在GPGPU例程helloGPGPU_GLSL-1.0.2中碰到过的问题

通常来说，这是因为找不到.lib文件，或者lib文件内容不全

解决方案：

改一下VS项目的tripplet。参考设置vs项目的编译平台一节。有的库要使用static库，有的不能使用static库，有的都可以。

5.3. 疑难-“RuntimeLibrary”不匹配

这里也有问题描述：Boost RuntimeLibrary missmatch，但是我按照该教程，并不能解决

5.3.1. 问题描述：

这个问题出现在，glog的使用中，VS2019创建的C++控制台项目。出现下面报错

LNK2038 检测到“RuntimeLibrary”的不匹配项: 值“MTd_StaticDebug”不匹配值“MDd_DynamicDebug”(glog_Test.obj 中) glog_Test F:\3D_Graphic\OpensourceTest\glog_Test\boost_filesystem-vc140-mt-gd.lib(directory.obj)

上面报错，说明使用的库是MTD_StaticDebug的，而我们的工程是MDd_DynamicDebug的，不匹配导致出错。

5.3.2. 解决方法1

项目属性 -> 配置属性 -> C/C++ -> 代码生成 -> 运行库。将MDd改为MTD即可

5.3.3. 解决方案2

让vcpkg编译出MD版本的库，在这里例子中就是要使用下面命令

vcpkg install boost-filesystem:x86-windows-static-md

之所以能使用x86-windows-static-md这个triplet，是因为vcpkg_root\triplets\community目录中有x86-windows-static-md.cmake

但是，对于boost-filesytem，它的输出并不是\installed\x86-windows-static\xxx-md.lib。而是和vcpkg install boost-filesystem:x86-windows-static命令相同的输出文件，只是输出目录改到了\installed\x86-windows-static-md\，并不能用啊。这个问题，我在它的github的issue版块提出来了：Boost RuntimeLibrary missmatch #18255

另外，How to switch the visual studio version? ，因为我用的是vs2019(vc142),而它的输出是vc140。这是由vcpkg_root\ports\boost-modular-build-helper\boost-modular-build.cmake决定的(第38行)

5.4. 疑难-安装失败

问题描述：

• SSL 错误

解决方案

• 这是网络问题。在大陆地区，下载github上的资源经常出错，正常。要使用vpn。也可以使用其他途径，把这个下载失败的东西给下载下来，然后复制到vcpkg安装目录\downloads里。然后再执行一次安装命令