教程:通过 CMake 安装和使用包

本教程介绍如何通过 CMake 和 vcpkg 创建使用 fmt 库的 C++ "Hello World" 程序。 你将安装依赖项、配置、生成和运行简单的应用程序。

先决条件

注意

对于 Windows 用户,Visual Studio 的 MSVC(Microsoft Visual C++ 编译器)是 C++ 开发所需的编译器。

1 - 设置 vcpkg

  1. 克隆存储库

    第一步是从 GitHub 克隆 vcpkg 存储库。 存储库包含用于获取 vcpkg 可执行文件的脚本,以及由 vcpkg 社区维护的特选开放源代码库的注册表。 要执行此操作,请运行:

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

    vcpkg 特选注册表是一组数量超过 2000 个的开源库。 这些库已通过 vcpkg 的持续集成管道进行验证,可以协同工作。 虽然 vcpkg 存储库不包含这些库的源代码,但它保存方案和元数据,以便在系统中生成和安装它们。

  2. 运行启动脚本

    现在,你已经克隆了 vcpkg 存储库,请导航到 vcpkg 目录并执行启动脚本:

    cd vcpkg && bootstrap-vcpkg.bat
    
    cd vcpkg; .\bootstrap-vcpkg.bat
    
    cd vcpkg && ./bootstrap-vcpkg.sh
    

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

    就这么简单! vcpkg 已安装并可供使用。

2 - 设置项目

  1. 配置 VCPKG_ROOT 环境变量。

    export VCPKG_ROOT=/path/to/vcpkg
    export PATH=$VCPKG_ROOT:$PATH
    

    注意

    使用 export 命令设置环境变量只会影响当前 shell 会话。 要使此更改在整个会话中永久存在,需要将 export 命令添加到 shell 的配置文件脚本(例如,~/.bashrc~/.zshrc)。

    set "VCPKG_ROOT=C:\path\to\vcpkg"
    set PATH=%VCPKG_ROOT%;%PATH%
    

    注意

    以这种方式设置环境变量只会影响当前终端会话。 若要使这些更改在所有会话中永久存在,请通过“Windows 系统环境变量”面板进行设置。

    $env:VCPKG_ROOT = "C:\path\to\vcpkg"
    $env:PATH = "$env:VCPKG_ROOT;$env:PATH"
    

    注意

    以这种方式设置环境变量只会影响当前终端会话。 若要使这些更改在所有会话中永久存在,请通过“Windows 系统环境变量”面板进行设置。

    设置 VCPKG_ROOT 将告知 vcpkg vcpkg 实例所在的位置。 将它添加到 PATH 确保可以直接从 shell 运行 vcpkg 命令。

  2. 创建项目目录。

    mkdir helloworld && cd helloworld
    

3 - 添加依赖项和项目文件

  1. 创建清单文件并添加 fmt 依赖项。

    首先,通过从 vcpkg.json 目录中运行 vcpkg new 命令,在项目的目录中创建清单文件 (helloworld):

    vcpkg new --application
    

    接下来,添加 fmt 依赖项:

    vcpkg add port fmt
    

    vcpkg.json 现在应如下所示:

    {
        "dependencies": [
            "fmt"
        ]
    }
    

    这是清单文件。 vcpkg 读取清单文件,以了解要安装和与 CMake 集成的依赖项,从而提供项目所需的依赖项。

    默认 vcpkg-configuration.json 文件引入了基线约束,指定项目应使用的依赖项的最低版本。 修改此文件超出了本教程的范围,但这在定义项目依赖项的版本约束方面起着重要作用。 因此,尽管这对于本教程来说并不是必要的,但建议将 vcpkg-configuration.json 添加到源代码管理,以确保不同开发环境中的版本一致性。

  2. 创建项目文件。

    创建包含以下内容的 CMakeLists.txt 文件:

    cmake_minimum_required(VERSION 3.10)
    
    project(HelloWorld)
    
    find_package(fmt CONFIG REQUIRED)
    
    add_executable(HelloWorld helloworld.cpp)
    
    target_link_libraries(HelloWorld PRIVATE fmt::fmt)
    

    现在,让我们逐一了解 CMakeLists.txt 文件中每一行的作用:

    • cmake_minimum_required(VERSION 3.10):指定生成项目所需的 CMake 最低版本为 3.10。 如果系统上安装的 CMake 版本低于此版本,则将生成错误。
    • project(HelloWorld):将项目的名称设置为 "HelloWorld."。
    • find_package(fmt CONFIG REQUIRED):使用 fmt 库的 CMake 配置文件查找该库。 REQUIRED 关键字确保在找不到包时生成错误。
    • add_executable(HelloWorld helloworld.cpp):添加从源文件 helloworld.cpp 生成的名为 "HelloWorld," 的可执行目标。
    • target_link_libraries(HelloWorld PRIVATE fmt::fmt):指定 HelloWorld 可执行文件应链接到 fmt 库。 PRIVATE 关键字表明 fmt 仅在生成 HelloWorld 时需要,不应传播到其他依赖项目。

    创建包含以下内容的 helloworld.cpp 文件:

    #include <fmt/core.h>
    
    int main()
    {
        fmt::print("Hello World!\n");
        return 0;
    }
    

    在此 helloworld.cpp 文件中,包含用于使用 <fmt/core.h> 库的 fmt 标头。 然后,main() 函数调用 fmt::print() 将 "Hello World!" 消息输出到控制台。

4 - 生成并运行该项目

  1. 运行 CMake 配置

    当将 CMAKE_TOOLCHAIN_FILE 设置为使用 vcpkg 的自定义工具链时,CMake 可以自动链接 vcpkg 安装的库。 这可以使用 CMake 预设文件来完成。

    helloworld 目录内创建以下文件:

    CMakePresets.json

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

    CMakeUserPresets.json

    {
        "version": 2,
        "configurePresets": [
          {
            "name": "default",
            "inherits": "vcpkg",
            "environment": {
              "VCPKG_ROOT": "<path to vcpkg>"
            }
          }
        ]
      }
    

    CMakePresets.json 文件包含一个名为“vcpkg”的预设,用于设置 CMAKE_TOOLCHAIN_FILE 变量。 CMakeUserPresets.json 文件会将 VCPKG_ROOT 环境变量设置为指向包含 vcpkg 本地安装的绝对路径。 建议不要将 CMakeUserPresets.json 签入版本控制系统。

    最后,使用 CMake 配置生成:

    cmake --preset=default
    
  2. 生成项目

    运行:

    cmake --build build
    
  3. 运行应用程序

    最后,运行可执行文件以查看应用程序的操作过程:

    ./build/HelloWorld
    
    Hello World!
    
    .\build\HelloWorld.exe
    
    Hello World!
    

后续步骤