游戏客户端架构 / 系统课时

管理第三方依赖

管理第三方依赖

本课使用 vcpkg 清单模式统一接入窗口、数学、音频和 JSON 解析库,并通过 CMake 将依赖限制在需要它们的构建目标中。完成后,项目可以在新环境中自动恢复依赖,而不必手工复制头文件和动态库。

学习目标

  • 使用 vcpkg.json 声明项目所需的第三方库
  • 在 CMake 中查找并链接不同类型的依赖
  • 验证依赖能否被正确编译、链接和运行

依赖管理要解决什么问题

直接把第三方源码或二进制文件复制进工程,短期内看似简单,但容易产生版本不一致、平台文件混杂和许可证来源不清等问题。更稳定的做法是把依赖名称和版本约束写入清单,由包管理器负责下载、构建和缓存。

本课选择四类常见依赖:GLFW 负责窗口和图形上下文,GLM 提供向量与矩阵运算,miniaudio 提供音频能力,nlohmann-json 负责读取配置数据。

游戏引擎第三方依赖关系

声明项目依赖

在项目根目录创建 vcpkg.json。清单中的名称使用 vcpkg 端口名,提交到版本库后,其他开发者可以恢复同一组依赖。

json
{
  "name": "engine-dependency-demo",
  "version-string": "0.1.0",
  "dependencies": [
    "glfw3",
    "glm",
    "miniaudio",
    "nlohmann-json"
  ]
}

该配置生效时,vcpkg 会在 CMake 配置阶段检查并安装缺失依赖。正式项目还应提交 vcpkg-configuration.json 或基线信息,以便固定端口仓库版本,避免不同时间安装到行为不同的库版本。

在 CMake 中链接依赖

下面的 CMakeLists.txt 创建一个可执行程序,并通过导入目标传播头文件路径和链接参数。不要手工填写包安装目录,因为导入目标已经包含当前平台所需的信息。

cmake
cmake_minimum_required(VERSION 3.24)
project(engine_dependency_demo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(glfw3 CONFIG REQUIRED)
find_package(glm CONFIG REQUIRED)
find_package(miniaudio CONFIG REQUIRED)
find_package(nlohmann_json CONFIG REQUIRED)

add_executable(dependency_demo src/main.cpp)

target_link_libraries(dependency_demo PRIVATE
    glfw
    glm::glm
    miniaudio::miniaudio
    nlohmann_json::nlohmann_json
)

PRIVATE 表示这些依赖只服务于当前可执行目标,不需要继续传递给其他目标。以后创建公共引擎库时,只有出现在公共头文件中的依赖才应考虑使用 PUBLIC。

编写最小验证程序

创建 src/main.cpp。程序依次初始化窗口系统和音频引擎,同时使用 GLM 保存窗口尺寸,并通过 JSON 对象读取程序标题。

cpp
#include <GLFW/glfw3.h>
#include <glm/vec2.hpp>
#include <miniaudio.h>
#include <nlohmann/json.hpp>
#include <iostream>
#include <string>

int main() {
    if (glfwInit() != GLFW_TRUE) {
        std::cerr << "GLFW initialization failed\n";
        return 1;
    }

    glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);
    GLFWwindow* window = glfwCreateWindow(1280, 720, "Dependency Demo", nullptr, nullptr);
    if (window == nullptr) {
        glfwTerminate();
        std::cerr << "Window creation failed\n";
        return 1;
    }

    ma_engine audioEngine;
    if (ma_engine_init(nullptr, &audioEngine) != MA_SUCCESS) {
        glfwDestroyWindow(window);
        glfwTerminate();
        std::cerr << "Audio initialization failed\n";
        return 1;
    }

    const glm::ivec2 windowSize{1280, 720};
    const nlohmann::json config{{"title", "Dependency Demo"}};
    std::cout << config.at("title").get<std::string>() << " "
              << windowSize.x << "x" << windowSize.y << "\n";

    ma_engine_uninit(&audioEngine);
    glfwDestroyWindow(window);
    glfwTerminate();
    return 0;
}

该验证程序不播放声音,也不显示可见窗口,但会真实调用四个依赖。运行环境仍需具备可用的桌面窗口系统和音频后端。

配置、构建与验证

将 <VCPKG_ROOT> 替换为本机 vcpkg 根目录。首次配置可能需要下载和编译依赖,因此耗时会明显长于后续构建。

bash
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=<VCPKG_ROOT>/scripts/buildsystems/vcpkg.cmake
cmake --build build
./build/dependency_demo

预期输出

text
Dependency Demo 1280x720

Windows 多配置生成器的程序通常位于 build/Debug 或 build/Release,实际路径可能不同。如果 CMake 报告找不到包,优先检查工具链文件路径、清单中的端口名以及配置阶段是否成功完成依赖安装。

本课总结

  • 依赖清单记录项目需要什么,CMake 导入目标负责如何编译和链接
  • 第三方库应按构建目标精确链接,避免把所有依赖设置成全局可见
  • 最小验证程序必须真实引用依赖,才能同时检查头文件、链接库和运行环境

下一课预告

下一课将把单一可执行程序拆分为引擎库、游戏程序和工具程序,使不同产物能够独立构建并复用同一套核心代码。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理第三方依赖

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通