311 lines
7.3 KiB
Markdown
311 lines
7.3 KiB
Markdown
# Easy2D Nintendo Switch 编译指南
|
||
|
||
## 概述
|
||
|
||
本文档说明如何使用 xmake 为 Nintendo Switch 编译 Easy2D 引擎及其示例程序。
|
||
|
||
## 前置条件
|
||
|
||
### 1. 必需工具
|
||
|
||
- **devkitPro** - Nintendo Switch 开发工具包
|
||
- **xmake** - 跨平台构建系统（v3.0.6+）
|
||
- **devkitA64** - ARM64编译器工具链（devkitPro 的一部分）
|
||
|
||
### 2. 安装 devkitPro
|
||
|
||
#### Windows
|
||
|
||
1. 从 https://devkitpro.org/wiki/Getting_Started/devkitPro_installer 下载 devkitPro 安装程序
|
||
2. 运行安装程序，选择以下组件：
|
||
- devkitA64 (ARM64)
|
||
- libnx (Nintendo Switch库)
|
||
- mesa (OpenGL ES)
|
||
- tools (nacptool, elf2nro 等)
|
||
3. 默认安装路径：`C:\devkitPro`
|
||
|
||
#### Linux/macOS
|
||
|
||
请参考官方文档：https://devkitpro.org/wiki/Getting_Started
|
||
|
||
### 3. 验证安装
|
||
|
||
```bash
|
||
# 检查devkitPro是否正确安装
|
||
$env:DEVKITPRO = "C:\devkitPro" # Windows PowerShell
|
||
export DEVKITPRO=/opt/devkitpro # Linux/macOS
|
||
|
||
# 检查工具链
|
||
aarch64-none-elf-gcc --version # 应该显示 GCC 版本
|
||
|
||
# 检查xmake
|
||
xmake --version # 应该显示 v3.0.6 或更高
|
||
```
|
||
|
||
## 编译步骤
|
||
|
||
### 1. 配置项目
|
||
|
||
```bash
|
||
cd C:\Users\soulcoco\Desktop\Easy2D\Easy2D-dev
|
||
|
||
# 配置编译（使用Switch工具链）
|
||
xmake config -p switch -a arm64
|
||
|
||
# 或者使用默认配置
|
||
xmake config
|
||
```
|
||
|
||
### 2. 编译核心库
|
||
|
||
编译 Easy2D 静态库：
|
||
|
||
```bash
|
||
xmake build easy2d
|
||
```
|
||
|
||
**输出：**
|
||
- Release: `build/switch/libeasy2d.a`
|
||
- Debug: `build/switch/libeasy2dd.a`
|
||
|
||
### 3. 编译示例程序
|
||
|
||
#### 编译音频演示
|
||
|
||
```bash
|
||
xmake build switch_audio_demo
|
||
```
|
||
|
||
**输出：**
|
||
- ELF: `build/switch/switch_audio_demo`
|
||
- NACP: `build/switch/switch_audio_demo.nacp`
|
||
- NRO: `build/switch/switch_audio_demo.nro` (Switch可执行文件)
|
||
|
||
#### 编译动画演示
|
||
|
||
```bash
|
||
xmake build switch_animation_demo
|
||
```
|
||
|
||
**输出：**
|
||
- NRO: `build/switch/switch_animation_demo.nro`
|
||
|
||
### 4. 一次编译所有目标
|
||
|
||
```bash
|
||
xmake build -a
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
Easy2D-dev/
|
||
├── xmake.lua # 构建配置
|
||
├── Easy2D/
|
||
│ ├── include/ # 头文件
|
||
│ │ ├── easy2d/ # 引擎头文件
|
||
│ │ │ ├── app/ # 应用系统
|
||
│ │ │ ├── platform/ # 平台层
|
||
│ │ │ ├── graphics/ # 图形系统
|
||
│ │ │ ├── audio/ # 音频系统
|
||
│ │ │ ├── scene/ # 场景管理
|
||
│ │ │ ├── resource/ # 资源管理
|
||
│ │ │ └── utils/ # 工具类
|
||
│ │ ├── glm/ # GLM数学库
|
||
│ │ ├── stb/ # STB图像库
|
||
│ │ └── pfd/ # 文件对话框库
|
||
│ ├── src/ # 实现文件
|
||
│ │ ├── app/ # 应用实现
|
||
│ │ ├── platform/ # 平台实现（Switch优化）
|
||
│ │ │ └── switch/ # Switch特定代码
|
||
│ │ ├── graphics/ # 图形实现
|
||
│ │ ├── audio/ # 音频实现
|
||
│ │ └── ...
|
||
│ └── examples/ # 示例程序
|
||
│ ├── switch_audio_demo/ # Switch音频演示
|
||
│ ├── switch_animation_demo/ # Switch动画演示
|
||
│ └── ...
|
||
└── squirrel/ # Squirrel脚本引擎
|
||
```
|
||
|
||
## 编译配置详解
|
||
|
||
### xmake.lua 中的关键配置
|
||
|
||
#### 1. Switch 工具链定义 (行 15-51)
|
||
|
||
```lua
|
||
toolchain("switch")
|
||
set_kind("standalone")
|
||
set_description("Nintendo Switch devkitA64 toolchain")
|
||
|
||
local devkitPro = "C:/devkitPro"
|
||
local devkitA64 = path.join(devkitPro, "devkitA64")
|
||
|
||
-- 编译器
|
||
set_toolset("cc", path.join(devkitA64, "bin/aarch64-none-elf-gcc.exe"))
|
||
set_toolset("cxx", path.join(devkitA64, "bin/aarch64-none-elf-g++.exe"))
|
||
|
||
-- 架构标志
|
||
local arch_flags = "-march=armv8-a+crc+crypto -mtune=cortex-a57 -mtp=soft -fPIE"
|
||
|
||
-- 链接 EGL 和 OpenGL ES (mesa)
|
||
add_syslinks("EGL", "GLESv2", "glapi", "drm_nouveau")
|
||
```
|
||
|
||
#### 2. Easy2D 静态库配置 (行 60-134)
|
||
|
||
```lua
|
||
target("easy2d")
|
||
set_kind("static")
|
||
set_plat("switch") -- 平台
|
||
set_arch("arm64") -- 架构
|
||
set_toolchains("switch") -- 工具链
|
||
|
||
add_files(SRC_DIR .. "/**.cpp") -- 源文件
|
||
add_files("squirrel/squirrel/*.cpp") -- 脚本引擎
|
||
add_includedirs(INC_DIR) -- 头文件目录
|
||
```
|
||
|
||
#### 3. Switch 示例程序配置 (行 139-257)
|
||
|
||
xmake 自动处理：
|
||
- **编译** ELF 文件
|
||
- **生成 NACP** 应用元数据
|
||
- **转换为 NRO** (Switch 可执行格式)
|
||
- **打包 RomFS** (资源文件系统)
|
||
|
||
## 故障排除
|
||
|
||
### 编译错误
|
||
|
||
#### 错误：找不到 Switch 工具链
|
||
|
||
```
|
||
Error: toolchain 'switch' not found
|
||
```
|
||
|
||
**解决方案：**
|
||
1. 确认 `DEVKITPRO` 环境变量已设置
|
||
2. 检查 devkitPro 安装路径：`C:\devkitPro` (Windows) 或 `/opt/devkitpro` (Linux)
|
||
3. 验证 `devkitA64/bin` 下的编译器存在
|
||
|
||
#### 错误：找不到 libnx 库
|
||
|
||
```
|
||
Error: cannot find -lnx
|
||
```
|
||
|
||
**解决方案：**
|
||
1. 验证 devkitPro 安装了 libnx 包
|
||
2. 检查 `DEVKITPRO/libnx` 目录是否存在
|
||
|
||
#### 错误：OpenGL ES 头文件缺失
|
||
|
||
```
|
||
Error: GL/gl.h: No such file or directory
|
||
```
|
||
|
||
**解决方案：**
|
||
1. 验证 mesa 已安装：`DEVKITPRO/portlibs/switch/include`
|
||
2. 检查 xmake.lua 中的包含目录配置
|
||
|
||
### 链接错误
|
||
|
||
#### 未定义的引用到 EGL 函数
|
||
|
||
```
|
||
undefined reference to 'eglInitialize'
|
||
```
|
||
|
||
**解决方案：**
|
||
- 确保 EGL 库链接顺序正确（xmake.lua 第 93 行）
|
||
|
||
### 运行时错误
|
||
|
||
#### NRO 文件无法在 Switch 上运行
|
||
|
||
**检查清单：**
|
||
1. 确认 `DEVKITPRO` 环境变量设置正确
|
||
2. 验证 RomFS 资源已正确打包（如果需要）
|
||
3. 检查应用元数据（NACP 文件）是否正确生成
|
||
|
||
## Switch 开发资源
|
||
|
||
- **官方文档**: https://switchbrew.org/wiki/Main_Page
|
||
- **libnx 文档**: https://libnx.readthedocs.io/
|
||
- **devkitPro 论坛**: https://devkitpro.org/
|
||
- **Easy2D 文档**: https://github.com/easy2d/Easy2D
|
||
|
||
## 编译选项
|
||
|
||
### 编译模式
|
||
|
||
```bash
|
||
# Debug 模式（包含调试符号）
|
||
xmake config -m debug
|
||
xmake build easy2d
|
||
|
||
# Release 模式（优化编译）
|
||
xmake config -m release
|
||
xmake build easy2d
|
||
```
|
||
|
||
### 并行编译
|
||
|
||
```bash
|
||
# 使用 8 个线程编译
|
||
xmake build -j 8
|
||
```
|
||
|
||
### 清理构建
|
||
|
||
```bash
|
||
# 清理所有构建文件
|
||
xmake clean
|
||
|
||
# 仅清理目标
|
||
xmake clean easy2d
|
||
```
|
||
|
||
## 下一步
|
||
|
||
1. **修改示例程序** - 编辑 `Easy2D/examples/switch_*_demo/main.cpp`
|
||
2. **添加资源** - 将资源放在 `assets/` 目录
|
||
3. **优化性能** - 使用 Release 模式编译
|
||
4. **部署到 Switch** - 将 NRO 文件复制到 Switch SD 卡
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何调试 Switch 应用？
|
||
|
||
A: 可以使用以下方法：
|
||
- 使用 `nxlink` 输出日志到 PC
|
||
- 在应用中使用 `E2D_LOG_INFO()` 宏输出调试信息
|
||
- 使用支持 Switch 的调试器（如 GDB with nxlink）
|
||
|
||
### Q: 如何部署资源到 Switch？
|
||
|
||
A:
|
||
1. 将资源放在 `examples/switch_*_demo/assets/` 目录
|
||
2. xmake 会自动将资源打包到 RomFS
|
||
3. 在代码中使用 `romfs:/` 前缀访问资源
|
||
|
||
### Q: 支持哪些音频格式？
|
||
|
||
A: miniaudio 支持：
|
||
- WAV
|
||
- FLAC
|
||
- MP3
|
||
- VORBIS
|
||
|
||
## 许可证
|
||
|
||
Easy2D 采用 MIT 许可证。详见 LICENSE 文件。
|
||
|
||
---
|
||
|
||
**最后更新**: 2026年2月9日
|
||
**Easy2D 版本**: 3.1.0
|
||
**Switch 工具链**: devkitA64 (devkitPro)
|