mGBA Logo mGBA

从源码构建 mGBA

本指南说明如何从源代码编译 mGBA。从源码构建允许您使用最新的开发版本、自定义构建或为项目做出贡献。

先决条件

必需工具

  • CMake 3.1 或更高版本： 构建系统生成器
  • C 编译器： GCC 4.9+、Clang 3.4+ 或 MSVC 2015+
  • Git： 版本控制系统

依赖项

  • SDL2： 跨平台多媒体库（2.0.8 或更高版本）
  • Qt5： GUI 工具包（可选，用于 Qt GUI）
  • libpng： PNG 图像库
  • zlib： 压缩库
  • lua： Lua 脚本库（5.4，可选）

获取源代码

克隆存储库

git clone https://github.com/mgba-emu/mgba.git
cd mgba

更新子模块

git submodule update --init --recursive

在 Windows 上构建

使用 Visual Studio

  1. 安装 Visual Studio 2015 或更高版本（支持 C++）
  2. 安装 CMake 并添加到 PATH
  3. 运行 CMake GUI 或使用命令行：
mkdir build
cd build
cmake .. -G "Visual Studio 16 2019" -A x64
cmake --build . --config Release

使用 MinGW

mkdir build
cd build
cmake .. -G "MinGW Makefiles"
cmake --build .

在 macOS 上构建

使用 Xcode

  1. 安装 Xcode 命令行工具：xcode-select --install
  2. 通过 Homebrew 安装依赖项：
brew install cmake sdl2 libpng zlib lua

然后构建：

mkdir build
cd build
cmake .. -G Xcode
cmake --build . --config Release

在 Linux 上构建

Ubuntu/Debian

安装依赖项：

sudo apt-get update
sudo apt-get install build-essential cmake libsdl2-dev libqt5opengl5-dev qtbase5-dev libpng-dev zlib1g-dev liblua5.4-dev

构建：

mkdir build
cd build
cmake ..
make -j4

Fedora

sudo dnf install gcc cmake SDL2-devel qt5-qtbase-devel libpng-devel zlib-devel lua-devel
mkdir build && cd build
cmake ..
make -j4

Arch Linux

sudo pacman -S cmake sdl2 qt5-base libpng zlib lua
mkdir build && cd build
cmake ..
make -j4

CMake 选项

配置构建选项：

  • USE_QT： 启用 Qt GUI（ON/OFF，默认：ON）
  • USE_SDL： 启用 SDL 前端（ON/OFF，默认：ON）
  • USE_DEBUGGERS： 启用调试器支持（ON/OFF，默认：ON）
  • USE_LUA： 启用 Lua 脚本（ON/OFF，默认：ON）
  • BUILD_GL： 构建 OpenGL 渲染器（ON/OFF，默认：ON）
cmake .. -DUSE_QT=ON -DUSE_SDL=ON -DUSE_LUA=ON

安装

构建后，安装 mGBA：

# Linux/macOS
sudo cmake --install . --prefix /usr/local

# 或安装到自定义位置
cmake --install . --prefix ~/local

故障排除构建问题

缺少依赖项

如果 CMake 报告缺少依赖项：

  • 使用包管理器安装缺少的包
  • 确保安装了开发头文件（不仅仅是运行时库）
  • 使用 pkg-config 验证依赖项安装

构建错误

常见的构建错误和解决方案：

  • 编译器错误： 将编译器更新到支持的版本
  • 链接器错误： 确保所有依赖项都已安装
  • CMake 错误： 将 CMake 更新到 3.1 或更高版本
  • Git 子模块问题： 运行 git submodule update --init --recursive
需要帮助？ 如果您遇到构建问题，请在 GitHub Issues 中查找类似问题或在 GitHub Discussions 中寻求帮助。

相关文章

有关 mGBA 开发的更多信息：