7.3 KiB

Raw Blame History

Easy2D Nintendo Switch 编译指南

概述

本文档说明如何使用 xmake 为 Nintendo Switch 编译 Easy2D 引擎及其示例程序。

前置条件

1. 必需工具

devkitPro - Nintendo Switch 开发工具包
xmake - 跨平台构建系统（v3.0.6+）
devkitA64 - ARM64编译器工具链（devkitPro 的一部分）

2. 安装 devkitPro

Windows

从 https://devkitpro.org/wiki/Getting_Started/devkitPro_installer 下载 devkitPro 安装程序
运行安装程序，选择以下组件：
- devkitA64 (ARM64)
- libnx (Nintendo Switch库)
- mesa (OpenGL ES)
- tools (nacptool, elf2nro 等)
默认安装路径：C:\devkitPro

Linux/macOS

请参考官方文档：https://devkitpro.org/wiki/Getting_Started

3. 验证安装

# 检查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. 配置项目

cd C:\Users\soulcoco\Desktop\Easy2D\Easy2D-dev

# 配置编译（使用Switch工具链）
xmake config -p switch -a arm64

# 或者使用默认配置
xmake config

2. 编译核心库

编译 Easy2D 静态库：

xmake build easy2d

输出：

Release: build/switch/libeasy2d.a
Debug: build/switch/libeasy2dd.a

3. 编译示例程序

编译音频演示

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可执行文件)

编译动画演示

xmake build switch_animation_demo

输出：

NRO: build/switch/switch_animation_demo.nro

4. 一次编译所有目标

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)

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)

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

解决方案：

确认 DEVKITPRO 环境变量已设置
检查 devkitPro 安装路径：C:\devkitPro (Windows) 或 /opt/devkitpro (Linux)
验证 devkitA64/bin 下的编译器存在

错误：找不到 libnx 库

Error: cannot find -lnx

解决方案：

验证 devkitPro 安装了 libnx 包
检查 DEVKITPRO/libnx 目录是否存在

错误：OpenGL ES 头文件缺失

Error: GL/gl.h: No such file or directory

解决方案：

验证 mesa 已安装：DEVKITPRO/portlibs/switch/include
检查 xmake.lua 中的包含目录配置

链接错误

未定义的引用到 EGL 函数

undefined reference to 'eglInitialize'

解决方案：

确保 EGL 库链接顺序正确（xmake.lua 第 93 行）

运行时错误

NRO 文件无法在 Switch 上运行

检查清单：

确认 DEVKITPRO 环境变量设置正确
验证 RomFS 资源已正确打包（如果需要）
检查应用元数据（NACP 文件）是否正确生成

Switch 开发资源

官方文档: https://switchbrew.org/wiki/Main_Page
libnx 文档: https://libnx.readthedocs.io/
devkitPro 论坛: https://devkitpro.org/
Easy2D 文档: https://github.com/easy2d/Easy2D

编译选项

编译模式

# Debug 模式（包含调试符号）
xmake config -m debug
xmake build easy2d

# Release 模式（优化编译）
xmake config -m release
xmake build easy2d

并行编译

# 使用 8 个线程编译
xmake build -j 8

清理构建

# 清理所有构建文件
xmake clean

# 仅清理目标
xmake clean easy2d

下一步

修改示例程序 - 编辑 Easy2D/examples/switch_*_demo/main.cpp
添加资源 - 将资源放在 assets/ 目录
优化性能 - 使用 Release 模式编译
部署到 Switch - 将 NRO 文件复制到 Switch SD 卡

常见问题

Q: 如何调试 Switch 应用？

A: 可以使用以下方法：

使用 nxlink 输出日志到 PC
在应用中使用 E2D_LOG_INFO() 宏输出调试信息
使用支持 Switch 的调试器（如 GDB with nxlink）

Q: 如何部署资源到 Switch？

将资源放在 examples/switch_*_demo/assets/ 目录
xmake 会自动将资源打包到 RomFS
在代码中使用 romfs:/ 前缀访问资源

Q: 支持哪些音频格式？

A: miniaudio 支持：

WAV
FLAC
MP3
VORBIS

许可证

Easy2D 采用 MIT 许可证。详见 LICENSE 文件。

最后更新: 2026年2月9日 Easy2D 版本: 3.1.0 Switch 工具链: devkitA64 (devkitPro)

7.3 KiB Raw Blame History Unescape Escape

Easy2D Nintendo Switch 编译指南

概述

前置条件

1. 必需工具

2. 安装 devkitPro

Windows

Linux/macOS

3. 验证安装

编译步骤

1. 配置项目

2. 编译核心库

3. 编译示例程序

编译音频演示

编译动画演示

4. 一次编译所有目标

项目结构

编译配置详解

xmake.lua 中的关键配置

1. Switch 工具链定义 (行 15-51)

2. Easy2D 静态库配置 (行 60-134)

3. Switch 示例程序配置 (行 139-257)

故障排除

编译错误

错误：找不到 Switch 工具链

错误：找不到 libnx 库

错误：OpenGL ES 头文件缺失

链接错误

未定义的引用到 EGL 函数

运行时错误

NRO 文件无法在 Switch 上运行

Switch 开发资源

编译选项

编译模式

并行编译

清理构建

下一步

常见问题

Q: 如何调试 Switch 应用？

Q: 如何部署资源到 Switch？

Q: 支持哪些音频格式？

许可证

7.3 KiB

Raw Blame History