安装指南¶
本指南将帮助您在不同平台的开发环境中正确安装和配置 SOUI5。SOUI5 基于 swinx 框架，支持 Windows、Linux、macOS 等多个平台。
前提条件¶
在开始安装之前，请确保您的系统满足以下要求：
Windows¶
- Windows XP
- Visual Studio 2005 或更高版本（推荐 VS2022）
- CMake 3.16 或更高版本
Linux¶
- Ubuntu 18.04 LTS 或更高版本
- GCC 8.0 或 Clang 7.0 或更高版本
- CMake 3.16 或更高版本
- 必要的开发库（详见下文）
macOS¶
- macOS 10.12 (Sierra) 或更高版本
- Xcode 10 或更高版本
- CMake 3.16 或更高版本
- Homebrew 包管理器（推荐）
获取 SOUI5 源代码¶
方法一：从 GitHub 获取（推荐）¶
# 克隆 SOUI5 主仓库
git clone --recursive https://github.com/soui4/soui.git
cd soui
# 更新子模块（包括 swinx）
git submodule update --init --recursive
方法二：从 Gitee 镜像获取¶
# 中国大陆用户推荐使用 Gitee 镜像
git clone --recursive https://gitee.com/setoutsoft/soui4.git
cd soui4
git submodule update --init --recursive
方法三：下载预编译版本¶
访问 SOUI5 Releases 页面下载最新的预编译版本。
编译 SOUI5¶
SOUI5 使用 CMake 作为统一的构建系统，支持在多个平台上编译。
Windows 编译¶
使用 Visual Studio¶
- 编译步骤：
# 创建构建目录 cd soui5 mkdir build cd build # 配置项目 cmake .. -G "Visual Studio 17 2022" -A x64 # 编译 cmake --build . --config Release
使用 MinGW¶
# 使用 MSYS2 安装依赖
pacman -S mingw-w64-x86_64-cairo mingw-w64-x86_64-fontconfig
# 编译
cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release
mingw32-make -j$(nproc)
Linux 编译¶
Ubuntu/Debian¶
-
安装依赖：
sudo apt-get update sudo apt-get install -y \ build-essential cmake ninja-build pkg-config \ ibxcb1-dev libgl1-mesa-dev freeglut3-dev -
编译步骤：
cd soui5 mkdir build cd build # 配置项目 cmake .. -G Ninja \ -DCMAKE_BUILD_TYPE=Release # 编译 ninja
CentOS/RHEL/Fedora¶
# CentOS/Fedora/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install cmake3 ninja-build pkgconfig \
libxcb-devel mesa-libGL-devel libuuid-devel
# 编译（使用 cmake3 在 CentOS 上）
cmake3 .. -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja
macOS 编译¶
-
安装依赖：
# 使用 Homebrew 安装依赖 brew install cmake ninja pkg-config \ glfw3 glew -
编译步骤：
cd soui5 mkdir build cd build # 配置项目 cmake .. -G Ninja \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_OSX_DEPLOYMENT_TARGET=10.12 # 编译 ninja
编译选项说明¶
| 选项 | 默认值 | 说明 |
|---|---|---|
| BUILD_DEMOS | ON | 编译示例程序 |
| BUILD_RICHEDIT | OFF | 编译RichEdit 控件 |
编译验证¶
编译完成后，运行示例程序验证安装：
# Windows
.\build\bin\demo.exe
# Linux
./build/bin/demo
# macOS
open ./build/bin/demo.app
配置开发环境¶
编译完成后，您需要配置开发环境以使用 SOUI5。
1. 设置环境变量¶
Windows¶
运行 wizard\wizard.setup.exe, 这个工具会为指定的VS版本安装SOUI向导并完成环境变量的设置。
Linux/macOS¶
# 使用ninja/make install将soui5安装到系统目录
ninja install
3. Visual Studio 项目配置（Windows）¶
如果使用 Visual Studio 直接开发：
使用VS向导开发¶
SOUI向导安装后，可以在VS的项目中选择“向导”->“新建SOUI5项目”，没有看到SOUI5向导的话，建议搜索向导关键词：soui5。
从cmake模板开始开发，参考(../03-developer-tutorials/project-creation/cmake-template.md)¶
- 从wizarc/cmakeApp这个模板复制一份作为新项目的模板。
- 使用VS打开这个模板目录，VS自动识别cmake文件，并生成项目。
Linux/macOS: - 从wizarc/cmakeApp这个模板复制一份作为新项目的模板。 - 使用VS打开这个模板目录，VS自动识别cmake文件，并生成项目。
常见问题¶
编译错误¶
Windows¶
问题: CMake 找不到 Visual Studio
# 解决方案：明确指定生成器
cmake .. -G "Visual Studio 17 2022" -A x64
Linux¶
问题: 缺少开发库
# Ubuntu/Debian
sudo apt-get install libxcb1-dev libgl1-mesa-dev freeglut3-dev
# CentOS/RHEL
sudo yum install libxcb-devel mesa-libGL-devel libuuid-devel
问题: CMake 版本过旧
# 安装新版 CMake
wget https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0-Linux-x86_64.sh
sudo sh cmake-3.20.0-Linux-x86_64.sh --prefix=/usr/local
macOS¶
问题: Xcode 命令行工具未安装
xcode-select --install
问题: Homebrew 依赖安装失败
brew update
brew install cmake ninja
资源文件找不到¶
- 检查
uires目录是否在可执行文件同一目录 - 验证 XML 语法是否正确
- 检查资源文件路径是否正确
性能问题¶
优化编译设置¶
# 使用发布版配置
cmake .. -DCMAKE_BUILD_TYPE=Release
# 启用 LTO 优化
cmake .. -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON
下一步¶
安装完成后，您可以： - 阅读 第一个项目 开始创建跨平台应用 - 查看 快速入门教程 学习基本用法 - 参考 用户指南 深入学习 - 了解 跨平台开发 的高级特性
如果从 SOUI3 升级，请查看 迁移指南。