Eden 依赖安装完全指南:编译器、CMake 3.31 与 CPMUtil 包管理的实战拆解
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 的依赖并非"全部由系统提供",也并非"全部由构建系统下载",而是分成两类:
- 必须由你(或系统包管理器)提供的部分:C++ 编译器、CMake、Git、Python3、Qt 6、Vulkan SDK(Windows),以及 Vulkan 头文件/工具链相关包。
- 由 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 环境,可以:
- 在 Visual Studio 安装器中勾选 "C++ clang compiler for Windows",在 "C++ desktop development tools" 中取消勾选 "x64/x86 build tool for MSVC",并把 Visual Studio 从 2022 换成 2026;
- 在 Qt Creator 的 generator 选项里把
Visual Studio 17 2022改成2026; - 最终使用 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 widgetsdev-libs/quazip qt6media-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 12 或更早版本请改用
devel/pkg-config - 注意事项见 FreeBSD 注意事项
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 时,实际的决策链是:
- 根 CMakeLists.txt 引入
CPMUtil; - externals/CMakeLists.txt 按平台/架构/开关调用
AddJsonPackage(<key>); AddJsonPackage读取 cpmfile.json 中同名键,得到repo、version、hash、min_version、patches、options等字段;- 优先尝试
find_package(<package> <min_version> ...),命中即使用系统包; - 未命中则从缓存目录
.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 给出了完整的优先级顺序(从高到低):
AddJsonPackage(... FORCE_BUNDLED_PACKAGE ON)(调用方强覆盖)<package>_FORCE_SYSTEM/<package>_FORCE_BUNDLED(单包用户选项)CPMUTIL_FORCE_SYSTEM/CPMUTIL_FORCE_BUNDLED(全局选项)- JSON 中的
bundled默认值 - 默认允许使用系统包
这解释了文档里那些"看起来矛盾"的建议:某些系统必须 -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):
- 仔细重读这份依赖指南(大多数失败确实是缺包);
- 清理 CPM 缓存
.cache/cpm与 CMake 缓存<build directory>/CMakeCache.txt; - 分析报错信息,找出对应选项;
- 查阅 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 校验之下,把其余几十个库稳定地复现出来。