在Visual Studio/Qt Creator 中使用CMake安装和使用vcpkg包

0. vcpkg简介和安装

0.1 vcpkg简介

vcpkg 是 Microsoft 和 C++ 社区维护的免费开放源代码 C/C++ 包管理器。 它于 2016 年推出，可帮助开发人员将项目迁移到较新版本的 Visual Studio。 vcpkg 已演变成 Windows、macOS 和 Linux 上开发人员使用的跨平台工具。 vcpkg 拥有大量开放源代码库注册表和企业就绪功能，旨在通过支持任何构建和项目系统来促进开发过程。 vcpkg 是核心的 C++ 工具，使用 CMake 中的脚本以 C++ 语言编写。 它从头开始设计，以解决 C/C++ 开发人员体验的独特难点。

0.2 vcpkg安装

0.2.1 如何在Visual Studio 2022以及以上版本中安装vcpkg

从 Visual Studio 2022 开始，vcpkg 已经被包含在 Visual Studio Installer 中，你可以直接在安装或修改 Visual Studio 时选择安装 vcpkg。具体步骤如下：

1. 打开 Visual Studio 安装器，选择安装或修改 Visual Studio 2022。
2. 在安装页面中，选择你需要的工具选项，例如“C++桌面开发”。
3. 在组件页面中，勾选 “vcpkg - C++库管理器”。
4. 点击修改或安装，等待安装完成。
5. 安装完成后，你就可以使用 vcpkg 了。
   

0.2.2 在其他VS版本或Qt Creator等平台上中安装vcpkg

1. 从github上克隆存储库
   创建文件夹如C:\dev，将vcpkg从github中克隆到当前文件夹中

git clone https://github.com/microsoft/vcpkg.git

2. 运行启动脚本
   启动脚本执行先决条件检查并下载 vcpkg 可执行文件。

cn vcpkg && bootstrap-vcpkg.bat

运行成功，会给出如下提示

3. 设置环境变量
   打开环境变量设置窗口：我的电脑【右键】-> 属性 -> 高级系统设置 -> 环境变量，选择Path，点击“编辑”，将C:\dev\vcpkg添加后确定。

1. 在Visual Studio 中使用CMake安装和使用vcpkg包

1.1 创建Visual Studio项目

1. 使用“CMake项目”模版创建项目
   
2. 项目命名为HelloWorldVS，并选中“将解决方案和项目放在同一目录中”的复选框，点击“创建”
   
3. 生成清单文件并添加依赖项

• 打开VS中的【开发人员命令提示】
  
• 运行以下命令来创建vcpkg清单文件(vcpkg.json)

vcpkg new --application

运行成功后，可以看到项目目录中多了一个vcpkg.json文件和一个vcpkg-configuration.json文件

• 添加fmt包作为依赖项：

vcpkg add port fmt

运行成功后，可在vcpkg.json文件中看到：

{
  "dependencies": [
    "fmt"
  ]
}

1.2 设置项目文件

a. 配置CMakePresets.json文件：

• 将CMakePresets.json文件重命名为CMakeUserPresets.json
• 如下所示更新其内容，将 <VCPKG_ROOT> 替换为至 vcpkg 目录的路径。

{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "<VCPKG_ROOT>/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

b. 编辑CMakeList.txt文件

在vs自动创建项目时自动生成的CMakeList.txt中添加一下两行代码，并重新"生成CMake缓存"

find_package(fmt CONFIG REQUIRED)
target_link_libraries(HelloWorldVS PRIVATE fmt::fmt)

c. 修改HelloWorldVS.cpp文件

#include "HelloWorldVS.h"
#include <fmt/core.h>

using namespace std;
int main()
{
	cout << "Hello CMake." << endl;
	fmt::print("Hello World.");
	return 0;
}

1.3 生成并运行该项目

a. 生成项目
按下 Ctrl+Shift+B 以在 Visual Studio 中生成项目。
b. 运行应用程序
选择并运行可执行文件

可以看到输出：

示例代码下载：HelloWorldVS.zip

2. 在Qt Creator中使用CMake安装和使用vcpkg包

2.1 启用vcpkg插件及设置

1. 启用vcpkg插件
   
2. 设置vcpkg参数

• 选择“工具”->“Preferences ”，打开设置界面，选择CMake，
  
• 设置vcpkg路径（如C:\dev\vcpkg）
  

2.2 创建Qt项目

1. 按照QtCreator引导创建新的项目HelloWorldQt，在‘构建系统’页面选择Build system为CMake。
   
2. 创建清单文件(vcpkg.json)
   a. 文件-> New File -> vcpkg -> vcpkg.json Manifest File -> 选择…
   

b. 在弹出的Location对话框中，可以输入文件名(默认为vcpkg.json)和路径(默认为当前项目路径)；可以编辑清单内容（默认添加了fmt库）
c. 完成后，项目中会自动生成一个vcpkg.json文件，同时并将该文件添加到了CMakeList.txt中

2.3 编辑vcpkg清单文件

1. 添加vcpkg包，如fmt
   
2. 生成CMake配置文件代码
   
   将以上复制的内容，添加到CMakeList.txt文件中，注意需要将target_link_libraries中的目标改为当前项目的可执行文件名（如将main改为HelloWorld）
   
3. 配置vcpkg的路径
   a. 项目->Initial Configuration->添加 string
   秘钥：CMAKE_TOOLCHAIN_FILE
   值：vcpkg的安装路径下的vcpkg.cmake的完整路径，注意路径是斜线/
   b. 点击Re-configure with Initial Parameters
   
4. 修改main.cpp，并构建运行
   

示例代码下载：HelloWorldQT

3. 碰到的一些问题

1. 报错: could not find a package configuration file provided by "fmt" with any of ...
   
   解决方法：
   a. 检查CMAKE_TOOLCHAIN_FILE变量值路径是否设置正确；
   b. 如设置正确，若在vs中重新生成一下cmake的缓存，若在qt Creator中则点击Re-configure with Initial Parameters重新生成一下cmake的配置；

2. 报错：The plain signature for target_link_libraries has already been used with ...
   
   解决方法：
   在使用target_link_libraries过程中，要么为所有元素指定PUBLIC// PRIVATE，要么不指定。
   在本例中，我们只需要删除target_link_libraries中的PRIVATE，再来执行CMake即可。
   

附 参考文献

4. vcpkg 概述 https://learn.microsoft.com/zh-cn/vcpkg/get_started/overview
5. 在 Visual Studio 中使用 CMake 安装和使用包https://learn.microsoft.com/zh-cn/vcpkg/get_started/get-started-vs?pivots=shell-cmd
6. vcpkg Package Managerhttps://doc.qt.io/qtcreator/creator-vcpkg.html
7. Create vcpkg manifest fileshttps://doc.qt.io/qtcreator/creator-how-to-create-vcpkg-manifest-files.html
8. Edit vcpkg manifest fileshttps://doc.qt.io/qtcreator/creator-how-to-edit-vcpkg-manifest-files.html