UnleashedRecomp Flatpak 构建指南在 Linux 上从源码打包 Sonic Unleashed 静态重编译移植版【免费下载链接】UnleashedRecompAn unofficial PC port of the Xbox 360 version of Sonic Unleashed created through the process of static recompilation.项目地址: https://gitcode.com/GitHub_Trending/un/UnleashedRecomp导读UnleashedRecomp 是通过静态重编译技术制作的《索尼克释放》Sonic UnleashedXbox 360 版本非官方 PC 移植版。为了在 Linux 桌面与 Steam Deck 上提供开箱即用的安装体验项目在 flatpak 目录中提供了完整的 Flatpak 打包定义从flatpak-builder编译构建到flatpak build-bundle生成可分发的单文件 bundle。本文以 flatpak/README.md 的两条核心命令为主线逐项拆解其背后的 Manifest 配置、CMake 适配逻辑与桌面集成文件读完你将能够独立完成该移植版的 Flatpak 打包、分发与安装排错。一、flatpak 目录的文件布局与各自职责仓库根目录下的 flatpak 目录共包含四个文件构成一次完整 Flatpak 打包的全部输入文件作用README.md打包与打包分发的两条核心命令说明io.github.hedge_dev.unleashedrecomp.jsonFlatpak Manifest描述运行时、权限与构建步骤io.github.hedge_dev.unleashedrecomp.desktop桌面入口文件.desktop用于应用菜单集成io.github.hedge_dev.unleashedrecomp.metainfo.xmlAppStream 元数据供软件中心展示应用信息其中 Manifest 是构建的蓝图README 中的命令则是调用flatpak-builder与flatpak build-bundle的标准姿势。二、打包前置条件在动手之前需要确认以下条件满足安装 Flatpak 工具链需要flatpak与flatpak-builder两个命令。Debian/Ubuntu 系可用sudo apt install flatpak flatpak-builder安装Arch 系可用sudo pacman -S flatpak flatpak-builder。注册 Flathub 远程仓库构建时--install-deps-fromflathub会从 Flathub 拉取运行时依赖org.freedesktop.Platform等需要先执行flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo。完整的游戏文件Flatpak 打包只编译移植版本体游戏资源default.xex、default.xexp、shader.ar需要在安装时由用户自行提供。获取与校验方法详见 docs/BUILDING.md 与 README.md 的安装章节这些文件必须来自你合法拥有的美版或欧版日版不支持。构建期网络访问Manifest 中为构建步骤单独授予了--sharenetwork见下文 build-options因为 CMake 配置阶段需要下载 vcpkg 依赖。磁盘与内存vcpkg 依赖、中间产物与最终 builddir 合计占用数 GB 空间请预留充足磁盘。三、构建命令逐项解析flatpak/README.md 给出的构建命令为flatpak-builder --force-clean --user --install-deps-fromflathub --reporepo --install builddir io.github.hedge_dev.unleashedrecomp.json各参数含义如下参数含义--force-clean构建前清空builddir保证每次都是干净构建避免脏状态导致的偶发失败--user以用户级安装方式安装应用安装到~/.local/share/flatpak无需 root 权限--install-deps-fromflathub自动从名为flathub的远程仓库安装 Manifest 声明的运行时与 SDK 依赖--reporepo将构建产物导出到当前目录下名为repo的 OSTree 仓库该仓库是下一步build-bundle的输入--install构建完成后直接将应用安装到系统配合--user即用户级安装可立即在应用菜单或命令行中启动builddir构建过程中的临时工作目录由--force-clean管理io.github.hedge_dev.unleashedrecomp.json本次构建使用的 Manifest 文件命令执行完毕后builddir中是中间产物repo/目录中则是可被flatpak客户端直接使用的本地 OSTree 仓库。若只想构建而不安装可去掉--install之后通过flatpak install --user repo io.github.hedge_dev.unleashedrecomp手动安装。从 CMakePresets.json 可知Linux 平台可用 preset 包括linux-debug、linux-relwithdebinfo与linux-releaseFlatpak 打包固定使用 release 配置以保证性能与体积。四、Manifest 深入解析运行时、权限与构建步骤io.github.hedge_dev.unleashedrecomp.json 是整条打包链的核心下面逐段解读。4.1 应用 ID 与运行时id: io.github.hedge_dev.unleashedrecomp, runtime: org.freedesktop.Platform, runtime-version: 24.08, sdk: org.freedesktop.Sdk, sdk-extensions: [ org.freedesktop.Sdk.Extension.llvm18 ]应用 ID 使用反向域名形式与 .desktop 和 metainfo.xml 中的 ID 保持一致这是 Flatpak 应用标识与集成文件匹配的前提。运行时基于freedesktop 平台 24.08这是 Flatpak 生态常用的通用 Linux 桌面运行时。SDK 扩展llvm18提供了 LLVM/Clang 18 工具链。从 Manifest 的build-options可见构建时通过append-path与prepend-ld-library-path将/usr/lib/sdk/llvm18/bin和/usr/lib/sdk/llvm18/lib注入构建环境确保 CMake 使用仓库期望的 Clang 工具链完成编译。4.2 运行时权限finish-argsfinish-args: [ --sharenetwork, --socketwayland, --socketfallback-x11, --socketpulseaudio, --deviceall, --filesystemhost, --filesystem/media, --filesystem/run/media, --filesystem/mnt ]这些参数决定应用在 Flatpak 沙箱内的能力参数授予的能力必要性分析--sharenetwork完整网络访问支持更新检查install/update_checker.cpp等联网功能--socketwayland/--socketfallback-x11Wayland / X11 显示服务渲染窗口与 UI 的基础fallback-x11保证无 Wayland 会话时自动回退--socketpulseaudioPulseAudio 音频服务游戏音频输出对应 apu/audio.cpp 与 SDL_mixer 音频后端--deviceall访问所有设备节点允许游戏读取手柄等输入设备--filesystemhost及/media、/run/media、/mnt访问主机文件系统与可移动存储允许用户在安装向导中直接浏览主机目录、从外置硬盘/U 盘提供游戏文件/run/media正是 Steam Deck 挂载 microSD 卡的路径这套权限设计服务于游戏文件需用户自行提供的安装模型沙箱需要看到主机上的游戏镜像或目录同时保留必要的图形、音频与输入能力。4.3 构建步骤build-commandsbuild-commands: [ cmake --preset linux-release -DUNLEASHED_RECOMP_FLATPAKON -DSDL2MIXER_VORBISVORBISFILE -DCMAKE_CXX_COMPILER_LAUNCHERccache -DCMAKE_C_COMPILER_LAUNCHERccache, cmake --build out/build/linux-release --target UnleashedRecomp, mkdir -p /app/bin, cp out/build/linux-release/UnleashedRecomp/UnleashedRecomp /app/bin/UnleashedRecomp, install -Dm644 UnleashedRecompResources/images/game_icon.png /app/share/icons/hicolor/128x128/apps/${FLATPAK_ID}.png, install -Dm644 flatpak/io.github.hedge_dev.unleashedrecomp.metainfo.xml /app/share/metainfo/${FLATPAK_ID}.metainfo.xml, install -Dm644 flatpak/io.github.hedge_dev.unleashedrecomp.desktop /app/share/applications/${FLATPAK_ID}.desktop ]逐条拆解CMake 配置使用linux-releasepreset 并追加三个关键变量-DUNLEASHED_RECOMP_FLATPAKON启用 Flatpak 兼容编译定义见第五章-DSDL2MIXER_VORBISVORBISFILE指示 SDL_mixer 使用 VORBISFILE 后端解码 Ogg Vorbis 音频这是 Flatpak 沙箱环境下依赖链接更干净的选择-DCMAKE_(C|CXX)_COMPILER_LAUNCHERccache启用 ccache 加速增量构建对反复打包的场景收益明显。构建目标cmake --build out/build/linux-release --target UnleashedRecomp产物输出到out/build/linux-release/UnleashedRecomp/与 CMakePresets.json 中linux-base的binaryDir约定一致。安装可执行文件将编译出的UnleashedRecomp复制到/app/bin/即 Flatpak 应用的运行时根目录。安装图标、AppStream 元数据与桌面入口分别安装到/app/share/icons/hicolor/128x128/apps/、/app/share/metainfo/与/app/share/applications/文件名的app前缀统一替换为${FLATPAK_ID}。这三步是应用在软件中心与桌面环境中可见的基础。4.4 源码与构建环境sources: [ { type: dir, path: ../ } ], build-options: { append-path: /usr/lib/sdk/llvm18/bin, prepend-ld-library-path: /usr/lib/sdk/llvm18/lib, build-args: [ --sharenetwork ] }源码以dir类型直接引用仓库根目录Manifest 所在flatpak/的上级因此无需下载 tarball仓库克隆后即可打包build-args: [--sharenetwork]单独为构建阶段授予网络供 CMake/vcpkg 拉取依赖buildsystem: simple表示不使用任何外部构建系统包装直接逐条执行build-commands。五、CMake 侧的 Flatpak 适配Manifest 中的UNLEASHED_RECOMP_FLATPAKON会触发 UnleashedRecomp/CMakeLists.txt 中的逻辑if (UNLEASHED_RECOMP_FLATPAK) target_compile_definitions(UnleashedRecomp PRIVATE UNLEASHED_RECOMP_FLATPAK GAME_INSTALL_DIRECTORY\/var/data\ ) endif()该选项在 UnleashedRecomp/CMakeLists.txt 中定义且仅在 Linux 平台暴露CMAKE_SYSTEM_NAME MATCHES Linux编译期定义UNLEASHED_RECOMP_FLATPAK宏供源码分支判断当前是否运行在 Flatpak 环境定义GAME_INSTALL_DIRECTORY常量指向/var/data作为沙箱内游戏数据的安装路径锚点。与之对应从项目 README.md 的 FAQ 可确认最终用户视角的数据位置Flatpak 版本的游戏数据安装在~/.var/app/io.github.hedge_dev.unleashedrecomp/data且该构建只认可这一数据目录如果将来想切换回原生 Linux 构建这个数据目录可以直接复用。若需迁移数据位置可通过创建符号链接将上述目录指向新的安装位置。六、Bundle生成可分发、可离线安装的单文件包构建完成后flatpak/README.md 给出的第二条命令将本地 OSTree 仓库导出为单一 bundle 文件flatpak build-bundle repo io.github.hedge_dev.unleashedrecomp.flatpak io.github.hedge_dev.unleashedrecomp --runtime-repohttps://flathub.org/repo/flathub.flatpakrepo参数含义repo输入仓库即上一步--reporepo生成的本地 OSTree 仓库io.github.hedge_dev.unleashedrecomp.flatpak输出的 bundle 文件名io.github.hedge_dev.unleashedrecomp要打包进 bundle 的应用 ID--runtime-repohttps://flathub.org/repo/flathub.flatpakrepo声明运行时依赖如org.freedesktop.Platform 24.08需从 Flathub 获取因此 bundle 本体只包含应用自身体积更小bundle 文件适合拷贝到其他机器离线安装flatpak install --user io.github.hedge_dev.unleashedrecomp.flatpak首次安装时若本机缺少运行时Flatpak 会提示并尝试从 Flathub即 bundle 中声明的--runtime-repo拉取。分发的机器上需先执行flatpak remote-add flathub ...完成远程仓库注册。七、桌面集成与软件中心元数据7.1 桌面入口文件io.github.hedge_dev.unleashedrecomp.desktop 定义了应用在桌面环境中的启动方式[Desktop Entry] NameUnleashed Recompiled Exec/app/bin/UnleashedRecomp TypeApplication Iconio.github.hedge_dev.unleashedrecomp CategoriesGame; CommentStatic recompilation of Sonic Unleashed. MimeTypex-scheme-handler/unleashedrecompExec指向/app/bin/UnleashedRecomp与 Manifest 构建步骤中的复制目标一致Icon对应 Manifest 安装的game_icon.png安装后被重命名为${FLATPAK_ID}.pngCategoriesGame;让应用出现在游戏分类自定义的x-scheme-handler/unleashedrecompMimeType 注册了unleashedrecomp://协议处理为将来的链接式启动预留能力。7.2 AppStream 元数据io.github.hedge_dev.unleashedrecomp.metainfo.xml 提供软件中心如 GNOME Software / KDE Discover展示所需的描述信息应用名称Unleashed Recompiled摘要为 An unofficial PC port of Sonic Unleashed.许可声明metadata_license为 CC0-1.0项目代码许可为 GPL-3.0supports声明支持鼠标pointing、键盘keyboard与触控touch三种输入方式launchable指向io.github.hedge_dev.unleashedrecomp.desktop与桌面入口文件形成闭环。7.3 安装目录规范Manifest 将所有集成文件安装到标准位置这是 Flatpak 应用能被正确识别的硬性要求可执行文件在/app/bin图标在/app/share/icons元数据在/app/share/metainfo桌面入口在/app/share/applications。构建步骤中的install -Dm644会按需创建缺失目录。八、运行验证、数据目录与 Steam Deck 使用构建并安装完成后可用以下方式启动flatpak run io.github.hedge_dev.unleashedrecomp首次启动时游戏的安装向导会引导你提供合法获取的游戏文件Xbox 360 镜像/容器或已解包的原始文件。相关的游戏文件获取流程硬盘/ U 盘导出见 docs/DUMPING-en.md 与 docs/DUMPING-USB-en.md。几个与本打包方式直接相关的使用要点数据目录如前所述Flatpak 版本的游戏数据固定位于~/.var/app/io.github.hedge_dev.unleashedrecomp/data保存数据与配置config.toml均在~/.config/UnleashedRecomp/体系内Flatpak 环境下映射到该data目录。Steam Deck项目 README 明确推荐 Flatpak 构建用于 Steam Deck——它可以在桌面模式下直接安装并作为非 Steam 游戏添加。由于沙箱授予了--filesystem/run/media从 microSD 卡提供游戏文件完全可行安装过程建议在桌面模式下进行以避免游戏模式下文件选择器不可用的问题。窗口系统调试若在 Wayland/X11 会话间切换遇到显示问题可用 SDL 视频驱动参数强制指定例如flatpak run io.github.hedge_dev.unleashedrecomp --sdl-video-driver wayland。更新应用已安装的 Flatpak 应用可用flatpak update io.github.hedge_dev.unleashedrecomp更新重新打包时建议配合--force-clean保证干净构建。九、常见问题与排查建议构建提示缺少运行时/SDK确认已执行flatpak remote-add --if-not-exists flathub ...且--install-deps-fromflathub参数拼写正确构建期网络由 Manifest 的build-args: [--sharenetwork]保障无需额外处理。ccache 缓存目录不可写ccache默认缓存位于用户主目录在 Flatpak 构建沙箱中如遇权限问题可通过设置CCACHE_DIR环境变量指向可写位置。CMake 阶段下载 vcpkg 依赖失败多为网络波动可重新执行flatpak-builder命令配合--force-clean从干净状态重试。安装向导提示文件无效请检查游戏文件来源是否合法且未被修改、区域是否一致美版/欧版以及是否误将.zip/.7z等压缩包直接传入详细校验规则见 README.md 的 FAQ。数据目录不被识别Flatpak 构建只认可~/.var/app/io.github.hedge_dev.unleashedrecomp/data请勿把游戏数据放在仓库目录或安装目录中。结语本文完整还原了 flatpak/README.md 的构建与打包流程并将其与 Manifest、CMake 适配、桌面入口与 AppStream 元数据逐一对齐。理解这套打包链后你既可以自行产出可分发的 Flatpak bundle也能为后续移植其他游戏或扩展沙箱权限提供直接的参考模板。【免费下载链接】UnleashedRecompAn unofficial PC port of the Xbox 360 version of Sonic Unleashed created through the process of static recompilation.项目地址: https://gitcode.com/GitHub_Trending/un/UnleashedRecomp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
