Eden 依赖安装完全指南:编译器、CMake 3.31 与 CPMUtil 包管理的实战拆解

原创2026-11-01 12:10:241,673 阅读

Eden 依赖安装完全指南:编译器、CMake 3.31 与 CPMUtil 包管理的实战拆解

本文以仓库中的 docs/Deps.md 为骨架,系统梳理 Eden(本仓库文档中的项目名,CMake 工程仍沿用历史名 yuzu)在 Linux、Windows、macOS 以及各类 BSD/Solaris 系系统上的依赖安装全流程。读完你将掌握:如何选对编译器与 Vulkan/Qt 工具链、各发行版的一键安装命令、仓库中 cpmfile.json 与 CPMUtil 的依赖装配机制,以及当配置失败时如何用 CPMUTIL_FORCE_SYSTEM、<pkg>_FORCE_BUNDLED、<pkg>_CUSTOM_DIR 精准排障。

一、先建立依赖全景:两条并行的装配路径

docs/Deps.md 隐含了一个非常重要的结论:Eden 的依赖并非"全部由系统提供",也并非"全部由构建系统下载",而是分成两类:

  1. 必须由你(或系统包管理器)提供的部分:C++ 编译器、CMake、Git、Python3、Qt 6、Vulkan SDK(Windows),以及 Vulkan 头文件/工具链相关包。
  2. 由 Eden 的 externals/ 与 CPM 自动处理的部分:FFmpeg、SDL3、Boost、fmt、lz4、nlohmann_json、OpenSSL、ZLIB、zstd、enet、Opus,以及一批"即便系统有包也优先使用捆绑版本"的库(SimpleIni、DiscordRPC、cubeb、libusb、VulkanMemoryAllocator、sirit、httplib、cpp-jwt)。

这条分界线在源码里有明确的落点:根 CMakeLists.txt 第一行就要求 cmake_minimum_required(VERSION 3.31),随后 include(CPMUtil) 引入自研的 CPM 包装层;第三方库的实际拉取则集中在 externals/CMakeLists.txt 与 cpmfile.json 中。

理解这条分界线的意义在于:排错时你要先判断失败的是"系统包"还是"CPM 下载/编译",二者的修复手段完全不同。

二、编译器与基础工具链要求

2.1 C++ 编译器

docs/Deps.md 的开篇结论很直接:编译 Eden 必须有 C++ 编译器,并且各平台的最低版本如下:

平台 编译器 最低版本 / 说明
Linux GCC 11+
Linux Clang 14+(GCC 12 场景同时需要 Clang 14+)
Windows MSVC 默认方案,强烈建议 Visual Studio 2022 Community
Windows clang-cl 需要安装 "C++ Clang tools for Windows"
Windows MSYS2 MinGW64 环境(ARM 上用 CLANGARM64)
macOS Apple Clang 通过 xcode-select --install 安装

这里的版本要求并非文档随口一提:根 CMakeLists.txt 将语言标准固定为 CMAKE_CXX_STANDARD 20 且 STANDARD_REQUIRED ON。工程中大量使用 C++20 特性,配置阶段还在非 Linux 的 UNIX 系统上补充了 -fexperimental-library 或 -D_LIBCPP_ENABLE_EXPERIMENTAL=1(见 CMakeLists.txt),因为 std::jthread、std::stop_token 等特性在较旧的 libc++ 中仍是实验状态。这也是为什么在 OpenBSD/NetBSD 一类系统上,"系统默认编译器太老"几乎是首要故障原因。

MSVC 用户还有一个额外的硬性限制:根 CMakeLists.txt 会在 MSVC AND ARCHITECTURE_x86 时直接 FATAL_ERROR,并提示你从开始菜单打开 Developer Command Prompt 是错误用法,应当直接运行 vcvars64.bat。换言之,32 位 x86 构建环境不受支持。

2.2 必须额外安装的工具

工具 版本要求 用途
CMake 3.31+ 配置与生成构建系统(Android SDK 已自带)
Git 无特定版本 版本控制;Windows 可用 gitforwindows 安装包
Python3 3.10+ 下载外部仓库(CPM 相关脚本)
Vulkan SDK — 仅 Windows 必须,用于着色器编译等工具
Qt 6 — 桌面端使用 Qt 前端时必须安装
Qt Creator 可选 文档称之为推荐的 IDE

Windows 上的 Vulkan SDK 安装,仓库提供了两个便利脚本(文档中已给出路径):

  • tools/windows/install-vulkan-sdk.ps1(PowerShell 5+)
  • tools/windows/install-vulkan-sdk.sh(Git Bash 等)

这两个脚本在仓库中真实存在。以 tools/windows/install-vulkan-sdk.sh 为例,它默认下载 VULKAN_SDK_VER=1.4.341.1 的 Windows SDK,自动识别 ARM64 与 X64 架构,并调用安装器以 --accept-licenses --default-answer --confirm-command install 静默安装;若脚本在 GitHub Actions 环境运行,还会把 VULKAN_SDK 与 bin 目录写入环境变量与 PATH。这意味着 CI 与本地可以复用同一套流程。

2.3 Qt 6 的获取方式

文档对 Qt 的区别对待值得记住,因为这是"包管理器 vs 官方安装器"的典型分叉:

  • Linux / BSD / macOS:可以用包管理器安装 Qt 6;如果还想用 Qt Creator,在下面给出的安装命令里追加 qtcreator 或 qt-creator。
  • Windows 上的 MSVC/clang-cl:必须使用 Qt 官方在线安装器。
  • Linux / macOS:也可以选择官方安装器。
  • MSYS2:可以用包管理器安装 Qt 6。

此外文档还给出一条便捷说明:./install.sh -h qtcreator 可用于 Qt Creator 的配置帮助。需要提醒的是,在当前仓库根目录中并未找到 install.sh 这个脚本(ls 结果中只有 shell.nix、CMakeLists.txt、cpmfile.json 等),如遇该命令不存在,请直接使用系统包管理器或 Qt 官方安装器完成 Qt Creator 的安装,并按 docs/Build.md 的 "Option A: Qt Creator" 流程打开项目。

2.4 clang-cl 与 Visual Studio 版本切换(文档中的"反直觉"段落)

docs/Deps.md 中有一段容易看错的说明:如果你想在 Windows 上用 clang-cl,同时保留 MSVC 环境,可以:

  1. 在 Visual Studio 安装器中勾选 "C++ clang compiler for Windows",在 "C++ desktop development tools" 中取消勾选 "x64/x86 build tool for MSVC",并把 Visual Studio 从 2022 换成 2026;
  2. 在 Qt Creator 的 generator 选项里把 Visual Studio 17 2022 改成 2026;
  3. 最终使用 clang-cl 配置:
cmake -S . -B build -G "Visual Studio 17 2026" -T ClangCL

如果使用 MSVC 或 clang-cl 在 Windows 上构建,文档明确说明:可以直接回到构建主指南继续,无需再读后面的平台命令。

三、由 Eden 的 externals/ 处理的依赖

文档列出了两个"由 Eden 的 externals 处理"的依赖,并附带了关键选项:

依赖 版本 相关选项 / 说明
FFmpeg — 应使用 -DYUZU_USE_EXTERNAL_FFMPEG=ON
SDL3 3.2.10+ 使用 -DYUZU_USE_BUNDLED_SDL2=ON 可缩短编译时间

这里有两点需要结合源码校正,属于"文档与实现之间的历史遗留":

(1)SDL3 的选项名。 根 CMakeLists.txt 定义的是 option(YUZU_USE_BUNDLED_SDL3 "Download bundled SDL3 build" ${EXT_DEFAULT}),externals/CMakeLists.txt 也依据 YUZU_USE_BUNDLED_SDL3 在 sdl3 与 sdl3-ci 两个 CPM 包之间切换。YUZU_USE_BUNDLED_SDL2 在仓库中已无对应实现,因此实际应使用 -DYUZU_USE_BUNDLED_SDL3=ON。docs/Options.md 中的选项表同样写作 YUZU_USE_BUNDLED_SDL3。

(2)FFmpeg 的三条路径。 CMakeLists.txt 中同时存在:

  • YUZU_USE_BUNDLED_FFMPEG(下载预编译包 ffmpeg-ci)
  • YUZU_USE_EXTERNAL_FFMPEG(从源码构建,Solaris 默认 ON)
  • 两者都不开时,走系统 find_package(FFmpeg ...)(见 CMakeLists.txt)

并且 Eden 只需要 FFmpeg 的四个组件,定义在 CMakeLists.txt:

set(FFmpeg_COMPONENTS
    avcodec
    avfilter
    avutil
    swscale)

这与 CMakeModules/find/FindFFmpeg.cmake 中"按组件查找 + 建立 FFmpeg::<component> 导入目标"的实现一一对应。系统包若缺少 avfilter 或 swscale 的开发包,配置阶段就会以组件缺失失败——这也是 Debian 系要安装 libavfilter-dev、libavcodec-dev、libswscale-dev 的原因。

从源码构建 FFmpeg(YUZU_USE_EXTERNAL_FFMPEG)时,externals/ffmpeg/CMakeLists.txt 会用一组精简的 configure 参数裁剪功能(--disable-everything、--disable-network、仅启用 h264/vp8/vp9 解码与 yadif,scale 滤镜),并额外探测 VA-API、VDPAU、ffnvcodec/CUDA 等硬件加速能力。这也解释了 Linux 发行版命令里为何反复出现 libva-dev、libvdpau-dev、nasm、autoconf:x86_64 上 FFmpeg 汇编需要 nasm/yasm,从源码 configure 需要 autoconf,configure 脚本由 bash 执行。

四、由 CPM 管理的通用依赖(含最低版本)

docs/Deps.md 说明:其余依赖在 YUZU_USE_CPM 开启时会由 CPM 下载并构建,但在类 UNIX 系统上始终优先使用系统依赖(如果可用)。

不过这句描述同样带有历史痕迹:docs/Options.md 已说明 YUZU_USE_CPM 被"退休"——所有构建现在都使用 CPMUtil 管理依赖;若你想强制使用系统包,应改用 -DCPMUTIL_FORCE_SYSTEM=ON。

4.1 可能被系统包满足的库

依赖 最低版本 备注
Boost 1.57.0+ 通过 CPM 时会启用 algorithm/icl/pool/container/heap/asio/headers/process/filesystem/crc/variant 等组件
Catch2 3.0.1 仅当 YUZU_TESTS 或 DYNARMIC_TESTS 开启
fmt 8.0.1+ —
lz4 — —
nlohmann_json 3.8+ 系统包名可能为 nlohmann-json、json-c++ 等
OpenSSL 3+ —
ZLIB 1.2+ —
zstd 1.5+ —
enet 1.3+ 联机相关
Opus 1.3+ 音频解码

Boost 的这组组件并非随意罗列,可在 CMakeLists.txt 中找到对应实现:

set(BOOST_INCLUDE_LIBRARIES algorithm icl pool container heap asio headers process filesystem crc variant)
AddJsonPackage(boost)

并且当 Boost 由 CPM 提供时会额外定义 YUZU_BOOST_v1,并为 boost_heap、boost_icl、boost_asio 抑制特定告警。Binding 这一层细节的价值在于:如果你在系统上装了残缺的 Boost(缺 context/fiber),就会出现"配置通过但链接失败",此时最直接的解法就是回到捆绑包。

Opus 的查找走 pkg-config,见 CMakeModules/find/FindOpus.cmake:它通过 pkg_search_module(OPUS QUIET IMPORTED_TARGET opus) 建立 PkgConfig::OPUS 目标,再别名为 Opus::opus;在 MSYS2 上还会调用 FixMsysPath 修正路径。这就是 MSYS2 与交叉编译环境必须安装 pkg-config/pkgconf 的原因。

4.2 Vulkan 相关(1.3.274+)

文档给出的 Vulkan 门槛为 1.3.274+,并列出四个组件:

  • VulkanUtilityLibraries
  • VulkanHeaders
  • SPIRV-Tools
  • SPIRV-Headers

仓库中的真实约束比文档更严格:cpmfile.json 里 vulkan-headers 的 min_version 为 1.4.317、捆绑版本为 v1.4.345;vulkan-utility-libraries 的捆绑版本同为 v1.4.345。以仓库为准时,建议直接安装满足 1.4.317+ 的头文件,或在系统包过旧时让 CPM 接管。

更关键的是版本一致性:externals/CMakeLists.txt 使用了:

AddDependentPackages(vulkan-headers vulkan-utility-libraries)

这个命令要求两个包要么都用系统版本,要么都捆绑。其失败提示的实现位于 CMakeModules/CPMUtil.cmake:一旦检测到"部分系统、部分捆绑",会直接 FATAL_ERROR,并给出两条修复建议——补齐缺失的系统包,或把已安装的那一个设为 _FORCE_BUNDLED。这正是 B 系列 BSD 上"vulkan-headers 装了但 utility libraries 没装"导致配置中断的根因。

4.3 无论如何都由 CPM 拉取的库

文档明确指出:以下依赖"系统包可以使用,但很多发行版没有打包,或者系统版本存在问题",因此实际以捆绑为主:

依赖 触发条件 / 说明
SimpleIni 配置文件解析
DiscordRPC 需 USE_DISCORD_PRESENCE
cubeb 需 ENABLE_CUBEB;文档源码注释称"大多数 Linux 发行版不打包 cubeb"
libusb 需 ENABLE_LIBUSB
VulkanMemoryAllocator 显存分配
sirit SPIR-V 汇编;MSVC/Android 默认捆绑
httplib 需 ENABLE_UPDATE_CHECKER 或 ENABLE_WEB_SERVICE;AUR 上该包已知损坏
cpp-jwt 需 ENABLE_WEB_SERVICE,要求 1.4+

cubeb 的处理逻辑很能说明"为什么推荐捆绑":externals/CMakeLists.txt 直接注释 "Most linux distros don't package cubeb, so enable regardless of cpm settings",并对捆绑 cubeb 关闭了一批告警。类似的"系统包不可靠"判断也出现在 httplib 上,cpmfile.json 为其配置了 HTTPLIB_REQUIRE_OPENSSL ON 与 mingw 补丁。

五、架构相关依赖

指令集模拟与 JIT 后端随宿主架构不同而不同,文档给出三组:

架构 / 条件 依赖 版本要求
amd64 xbyak 建议 7.22 或更早
aarch64 或 DYNARMIC_TESTS oaknut 2.0.1+
riscv64 biscuit 0.9.1+

源码中的选择逻辑位于 externals/CMakeLists.txt:

if (ARCHITECTURE_x86 OR ARCHITECTURE_x86_64)
    AddJsonPackage(xbyak)
endif()
...
if (ARCHITECTURE_arm64 OR DYNARMIC_TESTS)
    AddJsonPackage(oaknut)
endif()
if (ARCHITECTURE_riscv64)
    AddJsonPackage(biscuit)
endif()
if (ARCHITECTURE_loongarch64)
    AddJsonPackage(lagoon)
endif()

注意这里还多出一个文档表格未列出的 loongarch64 → lagoon,可在 cpmfile.json 中查到 lagoon 的定义(loongson-community/lagoon,版本 1.0.0)。

关于 xbyak 的版本口径:文档写"推荐 7.22 或更早",而 cpmfile.json 中捆绑版本为 v7.40.1。两者并不矛盾——文档给的是系统包/兼容性建议,捆绑版本则由项目自行 pin。若你在极新的 xbyak 上遇到 JIT 相关问题,可以显式安装旧版系统包并配合 -Dxbyak_FORCE_SYSTEM=ON 验证。

六、Linux / BSD / macOS 一键安装命令

文档强调:以下命令安装"全部必要依赖",执行前请先看清楚自己在跑什么。另外一个写作约定值得转述:这些命令假设系统是全新安装但已更新过,因此除 Arch 这类滚动发行版外,不包含 update && upgrade 步骤。

6.1 Gentoo Linux

需要先启用 GURU 仓库:

sudo emerge -a app-eselect/eselect-repository
sudo eselect repository enable guru
sudo emaint sync -r guru

再安装依赖:

sudo emerge -a \
    app-arch/lz4 app-arch/zstd app-arch/unzip \
    dev-libs/libfmt dev-libs/libusb dev-libs/mcl dev-libs/sirit \
    dev-libs/boost dev-libs/openssl dev-libs/discord-rpc \
    dev-util/spirv-tools dev-util/spirv-headers dev-util/vulkan-headers \
    dev-util/vulkan-utility-libraries dev-util/glslang \
    media-gfx/renderdoc media-libs/libva media-libs/opus media-video/ffmpeg \
    media-libs/VulkanMemoryAllocator media-libs/libsdl3 media-libs/cubeb \
    net-libs/enet \
    sys-libs/zlib \
    dev-cpp/nlohmann_json dev-cpp/simpleini dev-cpp/cpp-httplib dev-cpp/cpp-jwt \
    games-util/gamemode \
    net-wireless/wireless-tools \
    dev-qt/qtbase:6 dev-libs/quazip \
    virtual/pkgconfig

架构补充与可选包:

  • amd64 追加 dev-libs/xbyak
  • riscv64 追加 dev-libs/biscuit(当前不可用)
  • aarch64 追加 dev-libs/oaknut
  • 启用测试时追加 dev-libs/oaknut 与 dev-cpp/catch

必须的 USE 标志:

  • dev-qt/qtbase network concurrent dbus gui widgets
  • dev-libs/quazip qt6
  • media-libs/libsdl3 haptic joystick sound video
    • 建议(非必须)追加 X vulkan udev opengl
  • dev-cpp/cpp-httplib ssl

其他注意事项见 Gentoo Linux 注意事项。

6.2 Arch Linux

sudo pacman -Syu --needed base-devel boost catch2 cmake enet ffmpeg fmt git glslang libzip lz4 ninja nlohmann-json openssl opus qt6-base qt6-multimedia qt6-charts sdl3 zlib zstd zip unzip vulkan-headers vulkan-utility-libraries libusb spirv-tools spirv-headers
  • 使用 Qt Web Engine 需额外安装 qt6-webengine
  • 完整的 Wayland 支持需 qt6-wayland
  • 需要 GCC 11 或更高版本

6.3 Ubuntu / Debian / Mint Linux

sudo apt-get install autoconf cmake g++ gcc git glslang-tools libglu1-mesa-dev libhidapi-dev libpulse-dev libtool libudev-dev libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-xinerama0 libxcb-xkb1 libxext-dev libxkbcommon-x11-0 mesa-common-dev nasm ninja-build qt6-base-private-dev catch2 libfmt-dev liblz4-dev nlohmann-json3-dev libzstd-dev libssl-dev libavfilter-dev libavcodec-dev libswscale-dev pkg-config zlib1g-dev libva-dev libvdpau-dev qt6-tools-dev qt6-charts-dev libvulkan-dev spirv-tools spirv-headers libusb-1.0-0-dev libxbyak-dev libboost-dev libboost-fiber-dev libboost-context-dev libsdl3-dev libopus-dev libasound2t64 vulkan-utility-libraries-dev
  • 要求 Ubuntu 26.04、Linux Mint 22.3 或 Debian 13 及以后版本
  • 要启用 Qt Web Engine,配置时追加 -DYUZU_USE_QT_WEB_ENGINE=ON

这条命令里的 libboost-fiber-dev、libboost-context-dev 与前面 Boost 组件列表中的 context/fiber 严格对应;libavfilter-dev、libavcodec-dev、libswscale-dev 则对应 Eden 需要的 FFmpeg 四组件中的三个(avutil 随 libavcodec-dev 一并提供)。

6.4 AlmaLinux / Fedora / Red Hat Linux

Fedora:

sudo dnf install autoconf cmake fmt-devel gcc{,-c++} glslang hidapi-devel json-devel libtool libusb1-devel libzstd-devel lz4-devel nasm ninja-build openssl-devel pulseaudio-libs-devel qt6-linguist qt6-qtbase{-private,}-devel qt6-qtwebengine-devel qt6-qtmultimedia-devel qt6-charts-devel speexdsp-devel wayland-devel zlib-devel ffmpeg-devel libXext-devel boost jq

AlmaLinux(需 YUZU_USE_CPM=ON):

# vvv - Only if RPMfusion is not installed or EPEL isn't either
sudo dnf install epel-release dnf-utils
# (run rpmfusion installation afterwards)
# vvv - This will work for most systems
sudo dnf install autoconf cmake libtool libudev cmake gcc gcc-c++ qt6-qtbase-devel zlib-devel openssl-devel boost SDL3 ffmpeg-devel libdrm glslang jq patch
# Qt6 private GUI must be taken from CRB repos
sudo dnf config-manager --enable crb
sudo dnf install qt6-qtbase-private-devel
  • OpenEuler 及其衍生版还需:SDL3-devel pkg-config fmt-dev nlohmann-json-dev
  • ffmpeg-devel 依赖 RPM Fusion 仓库
  • 需要 Fedora 32 或更高版本
  • Fedora 36+ 配 GCC 12 的用户需要 Clang,并应以如下方式配置:cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -B build

其中 AlmaLinux 段落的 YUZU_USE_CPM=ON 是文档的旧口径,按 docs/Options.md 与 CMakeModules/CPMUtil.cmake 的现状,正确写法是让 CPMUtil 接管(默认行为)或显式 -DCPMUTIL_FORCE_SYSTEM=ON。

6.5 Alpine Linux

先启用 community 仓库:

# Enable the community repository
setup-apkrepos -c
# Install
apk add g++ git cmake make mesa-dev qt6-qtbase-dev qt6-qtbase-private-dev libquazip1-qt6 ffmpeg-dev qt6-charts-dev libusb-dev libtool boost-dev sdl3-dev zstd-dev vulkan-utility-libraries spirv-tools-dev openssl-dev nlohmann-json lz4-dev opus-dev jq patch

6.6 Void Linux

xbps-install -Su git make cmake clang pkg-config patch SPIRV-Tools-devel SPIRV-Headers lz4 liblz4-devel boost-devel ffmpeg6-devel catch2 Vulkan-Utility-Libraries Vulkan-Headers glslang openssl-devel SDL3-devel quazip-qt6-devel qt6-base-devel qt6-qt5compat-devel qt6-charts-devel fmt-devel json-c++ libenet-devel libusb-devel

文档顺带吐槽了一句:Void 里 nlohmann-json 的包名就叫 json-c++。这类命名差异正是"跨发行版依赖表"必须逐个维护的原因。

6.7 NixOS

仓库根目录提供了便利脚本 shell.nix,直接运行 nix-shell 即可。该文件使用 nixos-24.05 的 nixpkgs,通过 pkgs.mkShellNoCC 声明了 cmake clang gnumake patch jq pkg-config、openssl boost fmt nlohmann_json lz4 zlib zstd、enet libopus vulkan-headers vulkan-utility-libraries、spirv-tools spirv-headers vulkan-loader、glslang python3 httplib cpp-jwt ffmpeg-headless、libusb1 cubeb,以及 Qt 6、SDL3、discord-rpc、gamemode 等。

如果要做"纯离线/无下载依赖"的构建,文档给出的组合是:

-DYUZU_USE_CPM=ON -DCPMUTIL_FORCE_SYSTEM=ON

按照当前实现,真正起作用的是后半段 -DCPMUTIL_FORCE_SYSTEM=ON。它的语义在 docs/CPMUtil.md 中定义得很清楚:要求所有 CPM 依赖都使用系统包;任何缺失的依赖都会被当作配置错误,而不会静默下载——这正是 Nix 沙箱需要的确定性行为。

6.8 macOS

从 Homebrew 安装:

brew install autoconf automake boost ffmpeg fmt glslang hidapi libtool libusb lz4 ninja nlohmann-json openssl pkg-config qt@6 sdl3 speexdsp zlib zstd cmake Catch2 molten-vk vulkan-loader spirv-tools
  • 在 Intel Mac 或使用 Rosetta Homebrew 时,必须把命令中所有 /opt/homebrew 替换为 /usr/local
  • 要用 MoltenVK 运行,需额外安装:
brew install molten-vk

注意事项见 macOS 注意事项。文档对 macOS 的态度比较坦率:整体"largely untested",可能出现崩溃与明显的 Vulkan 问题。此外根 CMakeLists.txt 把 CMAKE_OSX_DEPLOYMENT_TARGET 默认设为 15.0,这意味着构建产物的最低系统版本门槛不低。

6.9 FreeBSD

以 root 运行:

pkg install devel/cmake devel/sdl3 devel/boost-libs devel/catch2 devel/libfmt devel/nlohmann-json devel/ninja devel/nasm devel/autoconf devel/pkgconf devel/qt6-base x11-toolkits/qt6-charts devel/simpleini net/enet multimedia/ffnvcodec-headers multimedia/ffmpeg audio/opus archivers/liblz4 lang/gcc12 graphics/glslang graphics/vulkan-utility-libraries graphics/spirv-tools www/cpp-httplib graphics/vulkan-utility-libraries graphics/vulkan-headers graphics/spirv-headers quazip-qt6

FreeBSD 段的实用补充(来自 Caveats):系统 OpenSSL 端口版本偏旧,建议加 -DYUZU_USE_BUNDLED_OPENSSL=ON;在 FreeBSD 15.0 上手柄可能因 SDL 与新的 usbhid(2) 驱动配合不良而失效,可在 /boot/loader.conf 中加入:

hw.usb.usbhid.enable="0"

6.10 NetBSD

面向 NetBSD 10.1:

pkgin install git cmake boost fmtlib SDL3 catch2 libjwt spirv-headers spirv-tools ffmpeg7 libva nlohmann-json jq libopus qt6-qtbase qt6-qtcharts qt6-qtmultimedia qt6-qttools cpp-httplib lz4 vulkan-headers nasm autoconf enet pkg-config libusb1 libcxx frozen

注意事项见 NetBSD 注意事项。其中最关键的一条是:截至 2026-02-07,vulkan-headers 不应安装系统包,因为 pkgsrc 里的版本低于要求;系统默认的 g++-10 也不足以支撑当前代码库,需要 clang-19 或 gcc14/15。

6.11 OpenBSD

pkg_add -u
pkg_add cmake nasm git boost unzip--iconv autoconf-2.72p0 bash ffmpeg glslang gmake qt6 jq fmt nlohmann-json enet boost vulkan-utility-libraries vulkan-headers spirv-headers spirv-tools catch2 sdl3 libusb1-1.0.29 quazip-qt6

注意事项见 OpenBSD 注意事项。两个高频坑:系统 Boost 缺少 context(需 -DBoost_FORCE_BUNDLED=ON),以及 -lc++-experimental 不存在导致链接失败。

6.12 DragonFlyBSD

pkg install gcc14 git cmake unzip nasm autoconf bash pkgconf ffmpeg glslang gmake jq nlohmann-json enet spirv-tools sdl3 vulkan-utility-libraries vulkan-headers catch2 libfmt openssl liblz4 boost-libs cpp-httplib qt6-base qt6-charts quazip-qt6 libva-vdpau-driver libva-utils libva-intel-driver

注意事项见 DragonFlyBSD 注意事项。同样有 vulkan-headers/vulkan-utility-libraries 版本过旧(1.3.289)的问题,需等二进制包更新或自行从源码构建。

6.13 OpenIndiana

sudo pkg install git cmake qt6 boost glslang libzip library/lz4 libusb-1 nlohmann-json openssl opus sdl3 zlib compress/zstd unzip pkg-config nasm autoconf mesa library/libdrm header-drm developer/fmt

注意事项见 OpenIndiana 注意事项。该平台有两条硬约束:clang 20 是坏的,应装 developer/clang-19;Qt Widgets 目前不可用,需要 -DENABLE_QT=OFF,同时系统 OpenSSL 通常不可用,建议 -DYUZU_USE_BUNDLED_OPENSSL=ON。

6.14 OmniOS

sudo pkgin install git cmake autoconf build-essential libusb-1 nasm gcc13

注意事项见 OmniOS 注意事项。OmniOS 依赖缺口较大,文档建议直接使用 -DCPMUTIL_FORCE_BUNDLED=ON 与 -DYUZU_USE_BUNDLED_OPENSSL=OFF;同时 glslang 必须自行构建,且不要在构建时用 -t glslang 目标,否则安装会失败。

6.15 MSYS2

先打开 MSYS2 MinGW 64-bit shell(mingw64.exe),再下载安装全部依赖:

BASE="git make autoconf libtool automake-wrapper jq patch"
MINGW="qt6-base qt6-charts qt6-tools qt6-translations qt6-svg cmake toolchain clang python-pip openssl vulkan-memory-allocator vulkan-devel glslang boost fmt lz4 nlohmann-json zlib zstd enet opus libusb openssl SDL3"
# Either x86_64 or clang-aarch64 (Windows on ARM)
packages="$BASE"
for pkg in $MINGW; do
    packages="$packages mingw-w64-x86_64-$pkg"
    #packages="$packages mingw-w64-clang-aarch64-$pkg"
done
pacman -Syuu --needed --noconfirm $packages

要点:

  • 使用 qt6-static 也可以,但需以 -DYUZU_STATIC_BUILD=ON 构建
  • 其他环境未经验证,理论上只要装齐依赖即可工作
  • MinGW 环境下 GCC 表现更好;ARM 上只有 CLANGARM64 提供 Clang,因此先用它
  • 想装 Qt Creator,把 qt-creator 加入 MINGW 变量,然后可用如下 PowerShell 创建开始菜单快捷方式:
powershell "\$s=(New-Object -COM WScript.Shell).CreateShortcut('C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Qt Creator.lnk');\$s.TargetPath='C:\\msys64\\mingw64\\bin\\qtcreator.exe';\$s.Save()"
  • 若 MinGW 二进制不在 PATH,补充:
echo 'PATH=/mingw64/bin:$PATH' >> ~/.bashrc
# 或
echo 'PATH=/mingw64/bin:$PATH' >> ~/.zshrc

注意事项见 MSYS2 注意事项。该节还给出了非完全静态打包时的递归 DLL 收集脚本,对做发行包的用户很有参考价值。

6.16 HaikuOS

pkgman install git cmake patch libfmt_devel nlohmann_json lz4_devel opus_devel boost1.90_devel vulkan_devel qt6_base_devel qt6_declarative_devel libsdl3_devel ffmpeg7_devel libx11_devel enet_devel catch2_devel quazip1_qt5_devel qt6_5compat_devel glslang qt6_devel qt6_charts_devel cubeb_devel simpleini quazip_qt6_devel

注意事项见 HaikuOS 注意事项。建议先执行 pkgman full-sync;GPU 支持普遍较弱,推荐只装 mesa_lavapipe;glslangValidator 在该平台会崩溃,需要自行构建 glslang 并应用 .patch/glslang/0001-haikuos-fix.patch(根本原因是 ShFinalize() 释放了已销毁的内存,"修复"思路是允许泄漏)。

6.17 RedoxOS

sudo pkg update
sudo pkg install git cmake ffmpeg6 zlib llvm18

文档直言:RedoxOS 目前不支持 SDL3,需要自己编译。注意事项见 RedoxOS 注意事项。

七、依赖声明的真实来源:cpmfile.json 与 CPMUtil

理解依赖安装不止于"把包装上"。当你执行 cmake -S . -B build 时,实际的决策链是:

  1. 根 CMakeLists.txt 引入 CPMUtil;
  2. externals/CMakeLists.txt 按平台/架构/开关调用 AddJsonPackage(<key>);
  3. AddJsonPackage 读取 cpmfile.json 中同名键,得到 repo、version、hash、min_version、patches、options 等字段;
  4. 优先尝试 find_package(<package> <min_version> ...),命中即使用系统包;
  5. 未命中则从缓存目录 .cache/cpm/<lowercase-package>/<version> 取用或下载(SHA512 校验),应用补丁,再 add_subdirectory 接入构建。

从 cpmfile.json 可以读出大量"文档未展开"的事实,例如:

JSON 键 实际捆绑版本 说明
boost 1.92.0 走 eden-emulator/ext-boost 的预打包产物
fmt 12.1.0 min_version 为 8
sdl3 release-3.4.8 min_version 为 3.2.10,与文档一致
sdl3-ci 3.4.14-... 预编译 CI 包(ci: true)
openssl openssl-3.6.2 附带 0001-add-bundled-cert.patch
ffmpeg 提交 c7b5f1537d 从源码构建时使用
ffmpeg-ci 9.0.2-... 使用 YUZU_USE_BUNDLED_FFMPEG 时使用
opus a3f0ec02b3 启用 OPUS_PRESUME_NEON ON
cubeb fa02160712 BUNDLE_SPEEX ON,关闭测试与工具
sirit / sirit-ci v1.0.5 / v1.0.7 前者从源码构建,后者为 CI 预编译
httplib v0.46.0 HTTPLIB_REQUIRE_OPENSSL ON + 0001-mingw.patch
vulkan-headers v1.4.345 min_version 为 1.4.317
xbyak v7.40.1 仅 x86/x86_64
oaknut v2.0.3 min_version 为 2.0.1
biscuit v0.19.0 min_version 为 0.9.1

7.1 系统包 / 捆绑包的优先级

docs/Deps.md 只说了"优先系统包",而 CMakeModules/CPMUtil.cmake 给出了完整的优先级顺序(从高到低):

  1. AddJsonPackage(... FORCE_BUNDLED_PACKAGE ON)(调用方强覆盖)
  2. <package>_FORCE_SYSTEM / <package>_FORCE_BUNDLED(单包用户选项)
  3. CPMUTIL_FORCE_SYSTEM / CPMUTIL_FORCE_BUNDLED(全局选项)
  4. JSON 中的 bundled 默认值
  5. 默认允许使用系统包

这解释了文档里那些"看起来矛盾"的建议:某些系统必须 -DCPMUTIL_FORCE_BUNDLED=ON(OmniOS),某些必须对单包开 _FORCE_BUNDLED(OpenBSD 的 Boost),本质是在这条优先级链上选择了不同层级。

7.2 常用排障开关速查

目标 参数
全部用系统包,缺失即报错 -DCPMUTIL_FORCE_SYSTEM=ON
全部用捆绑包 -DCPMUTIL_FORCE_BUNDLED=ON
仅强制捆绑某包 -D<package>_FORCE_BUNDLED=ON(如 -DBoost_FORCE_BUNDLED=ON)
仅强制系统某包 -D<package>_FORCE_SYSTEM=ON
指向本地已解压的包 -D<package>_CUSTOM_DIR=/path/to/dir
指定 CPM 缓存位置 -DCPM_SOURCE_CACHE=/path/to/cache
指定补丁目录 -DCPMUTIL_PATCH_DIR=/path/to/.patch
使用捆绑 OpenSSL -DYUZU_USE_BUNDLED_OPENSSL=ON
使用捆绑 SDL3 -DYUZU_USE_BUNDLED_SDL3=ON
从源码构建 FFmpeg -DYUZU_USE_EXTERNAL_FFMPEG=ON
使用预编译 FFmpeg -DYUZU_USE_BUNDLED_FFMPEG=ON
关闭 Qt 前端 -DENABLE_QT=OFF
关闭 cubeb -DENABLE_CUBEB=OFF

其中 <package>_CUSTOM_DIR 对沙箱环境尤其重要:docs/CPMUtil.md 明确建议,如果某个包无论如何都无法用系统包替代,就单独下载并指到本地目录。

7.3 缓存、校验与工具脚本

依赖默认落在 .cache/cpm(由 CMakeModules/CPMUtil.cmake 设置,根 CMakeLists.txt 也做了同样的赋值)。缓存失效的触发条件在 CPMUtil.cmake 中:补丁文件集合的 SHA512 "patch key" 变化,或缓存目录缺失,都会导致重新下载。

仓库提供了命令行工具 tools/cpmutil.sh 管理这些包:

tools/cpmutil.sh package dir  <JSON key>   # 查看某个包的本地目录
tools/cpmutil.sh package hash <JSON key>   # 校验并更新哈希
tools/cpmutil.sh package fetch -a          # 预取全部包
tools/cpmutil.sh package reset <JSON key>  # 复位到原始状态
tools/cpmutil.sh package patch <JSON key>  # 基于本地修改生成补丁

此外 tools/cpm-fetch-all.sh 就是 tools/cpmutil.sh package fetch -a 的封装,用于 CI 预取。生成结果的依赖清单最终会进入 src/dep_hashes.h.in 与 CMakeModules/GenerateDepHashes.cmake,用于"关于/依赖"对话框展示——这也是为什么 AddJsonPackage 内部会往 CPM_PACKAGE_NAMES / CPM_PACKAGE_URLS / CPM_PACKAGE_SHAS 三个全局属性里追加记录。

八、装完依赖之后:确认与下一步

按 docs/Deps.md 的收尾,安装完成后应返回根构建指南。如果你已经具备完整的开发环境,那份指南给出的最简命令是:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -G Ninja
cmake --build build

配置失败时的推荐处理顺序(同样来自 docs/Build.md):

  1. 仔细重读这份依赖指南(大多数失败确实是缺包);
  2. 清理 CPM 缓存 .cache/cpm 与 CMake 缓存 <build directory>/CMakeCache.txt;
  3. 分析报错信息,找出对应选项;
  4. 查阅 CPMUtil 文档,判断是否需要强制捆绑某个包。

需要修改的构建选项可以在 docs/Options.md 中查全,或直接读根 CMakeLists.txt。默认配置通常已经是最佳体验,不建议无理由改动。

最后再提醒三点高频误区,均可在本仓库源码中得到印证:

  • YUZU_USE_CPM 已退休:需要"只用系统包"时请用 CPMUTIL_FORCE_SYSTEM。
  • SDL 的选项是 YUZU_USE_BUNDLED_SDL3:不是文档历史遗留的 YUZU_USE_BUNDLED_SDL2。
  • Vulkan 头文件与工具库必须版本一致:AddDependentPackages(vulkan-headers vulkan-utility-libraries) 会直接拒绝"一半系统一半捆绑"的混合状态。

依赖装齐后,编译器、CMake 3.31、Qt 6 与一套版本相互匹配的 Vulkan/FFmpeg/SDL3 就构成了 Eden 构建的基础环境;剩下的工作交给 CPMUtil:它会在 cpmfile.json 声明的版本与 SHA512 校验之下,把其余几十个库稳定地复现出来。

登录后查看全文
Eglantine