327 lines
7.1 KiB
Markdown
327 lines
7.1 KiB
Markdown
# Extra2D 构建系统文档
|
||
|
||
## 概述
|
||
|
||
Extra2D 使用 **Xmake** 作为构建系统，支持 **MinGW (Windows)** 和 **Nintendo Switch** 两个平台。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
Extra2D/
|
||
├── xmake.lua # 主构建脚本
|
||
├── xmake/
|
||
│ ├── engine.lua # 引擎库定义
|
||
│ └── toolchains/
|
||
│ └── switch.lua # Switch 工具链定义
|
||
├── Extra2D/
|
||
│ ├── src/ # 引擎源码
|
||
│ └── include/ # 引擎头文件
|
||
├── squirrel/ # Squirrel 脚本引擎
|
||
└── examples/ # 示例程序
|
||
├── hello_world/
|
||
├── collision_demo/
|
||
├── push_box/
|
||
└── spatial_index_demo/
|
||
```
|
||
|
||
## 环境准备
|
||
|
||
### MinGW (Windows) 平台
|
||
|
||
1. **安装 MinGW-w64**
|
||
- 下载地址: https://www.mingw-w64.org/downloads/
|
||
- 或使用 MSYS2: `pacman -S mingw-w64-x86_64-toolchain`
|
||
|
||
2. **安装 Xmake**
|
||
- 下载地址: https://xmake.io/#/zh-cn/guide/installation
|
||
|
||
3. **安装依赖包**
|
||
```bash
|
||
xmake require -y
|
||
```
|
||
|
||
### Nintendo Switch 平台
|
||
|
||
1. **安装 devkitPro**
|
||
- 下载地址: https://devkitpro.org/wiki/Getting_Started
|
||
- Windows 安装程序会自动设置环境变量
|
||
|
||
2. **设置环境变量**
|
||
```powershell
|
||
# PowerShell
|
||
$env:DEVKITPRO="C:/devkitPro"
|
||
|
||
# 或永久设置（系统属性 -> 环境变量）
|
||
[Environment]::SetEnvironmentVariable("DEVKITPRO", "C:/devkitPro", "User")
|
||
```
|
||
|
||
3. **在 MSYS2 中安装 Switch 库**
|
||
```bash
|
||
# 打开 MSYS2 (devkitPro 提供的)
|
||
pacman -S switch-sdl2 switch-sdl2_mixer switch-glm
|
||
|
||
# 或安装所有 Switch 开发库
|
||
pacman -S $(pacman -Slq dkp-libs | grep switch-)
|
||
```
|
||
|
||
4. **验证安装**
|
||
```bash
|
||
ls $DEVKITPRO/portlibs/switch/include/SDL2
|
||
ls $DEVKITPRO/portlibs/switch/include/glm
|
||
```
|
||
|
||
## 主构建脚本 (xmake.lua)
|
||
|
||
### 项目元信息
|
||
- **项目名称**: Extra2D
|
||
- **版本**: 3.1.0
|
||
- **许可证**: MIT
|
||
- **语言标准**: C++17
|
||
- **编码**: UTF-8
|
||
|
||
### 构建选项
|
||
|
||
| 选项 | 默认值 | 描述 |
|
||
|------|--------|------|
|
||
| `examples` | true | 构建示例程序 |
|
||
| `debug_logs` | false | 启用调试日志 |
|
||
|
||
### 平台检测逻辑
|
||
|
||
1. 获取主机平台: `os.host()`
|
||
2. 获取目标平台: `get_config("plat")` 或主机平台
|
||
3. 平台回退: 如果不支持，Windows 回退到 `mingw`
|
||
4. 设置平台: `set_plat(target_plat)`
|
||
5. 设置架构:
|
||
- Switch: `arm64`
|
||
- MinGW: `x86_64`
|
||
|
||
### 依赖包 (MinGW 平台)
|
||
|
||
```lua
|
||
add_requires("glm", "libsdl2", "libsdl2_mixer")
|
||
```
|
||
|
||
## 引擎库定义 (xmake/engine.lua)
|
||
|
||
### 目标: extra2d
|
||
- **类型**: 静态库 (`static`)
|
||
- **源文件**:
|
||
- `Extra2D/src/**.cpp`
|
||
- `Extra2D/src/glad/glad.c`
|
||
- `squirrel/squirrel/*.cpp`
|
||
- `squirrel/sqstdlib/*.cpp`
|
||
|
||
### 头文件路径
|
||
- `Extra2D/include` (public)
|
||
- `squirrel/include` (public)
|
||
- `Extra2D/include/extra2d/platform` (public)
|
||
|
||
### 平台配置
|
||
|
||
#### Switch 平台
|
||
```lua
|
||
add_includedirs(devkitPro .. "/portlibs/switch/include")
|
||
add_linkdirs(devkitPro .. "/portlibs/switch/lib")
|
||
add_syslinks("SDL2_mixer", "SDL2", "opusfile", "opus", ...)
|
||
```
|
||
|
||
#### MinGW 平台
|
||
```lua
|
||
add_packages("glm", "libsdl2", "libsdl2_mixer")
|
||
add_syslinks("opengl32", "glu32", "winmm", "imm32", "version", "setupapi")
|
||
```
|
||
|
||
### 编译器标志
|
||
- `-Wall`, `-Wextra`
|
||
- `-Wno-unused-variable`, `-Wno-unused-function`
|
||
- `-Wno-deprecated-copy`, `-Wno-class-memaccess`
|
||
|
||
### 构建模式
|
||
- **Debug**: `-O0`, `-g`, 定义 `E2D_DEBUG`, `_DEBUG`
|
||
- **Release**: `-O2`, 定义 `NDEBUG`
|
||
|
||
## Switch 工具链 (xmake/toolchains/switch.lua)
|
||
|
||
### 工具链: switch
|
||
- **类型**: standalone
|
||
- **描述**: Nintendo Switch devkitA64 工具链
|
||
|
||
### 工具路径
|
||
- **CC**: `aarch64-none-elf-gcc.exe`
|
||
- **CXX**: `aarch64-none-elf-g++.exe`
|
||
- **LD**: `aarch64-none-elf-g++.exe`
|
||
- **AR**: `aarch64-none-elf-gcc-ar.exe`
|
||
|
||
### 架构标志
|
||
```
|
||
-march=armv8-a+crc+crypto -mtune=cortex-a57 -mtp=soft -fPIE
|
||
```
|
||
|
||
### 链接标志
|
||
```
|
||
-specs=switch.specs -g
|
||
```
|
||
|
||
### 预定义宏
|
||
- `__SWITCH__`
|
||
- `__NX__`
|
||
- `MA_SWITCH`
|
||
- `PFD_SWITCH`
|
||
|
||
### 系统库
|
||
- `nx` (libnx)
|
||
- `m` (math)
|
||
|
||
## 示例程序构建脚本
|
||
|
||
### 通用结构
|
||
|
||
```lua
|
||
-- 使用与主项目相同的平台配置
|
||
if is_plat("switch") then
|
||
-- Switch 平台配置
|
||
elseif is_plat("mingw") then
|
||
-- MinGW 平台配置
|
||
end
|
||
```
|
||
|
||
### Switch 平台配置
|
||
- 设置平台: `set_plat("switch")`
|
||
- 设置架构: `set_arch("arm64")`
|
||
- 设置工具链: `set_toolchains("switch")`
|
||
- 设置输出目录: `set_targetdir("../../build/examples/xxx")`
|
||
- 构建后生成 NRO 文件
|
||
|
||
### MinGW 平台配置
|
||
- 设置平台: `set_plat("mingw")`
|
||
- 设置架构: `set_arch("x86_64")`
|
||
- 设置输出目录: `set_targetdir("../../build/examples/xxx")`
|
||
- 链接标志: `-mwindows`
|
||
- 构建后复制资源文件
|
||
|
||
## 构建命令
|
||
|
||
### 配置项目
|
||
|
||
```bash
|
||
# 默认配置 (MinGW)
|
||
xmake f -c
|
||
|
||
# 指定平台 (使用 -p 参数)
|
||
xmake f -c -p mingw
|
||
xmake f -c -p switch
|
||
|
||
# 指定 MinGW 路径（如果不在默认位置）
|
||
xmake f -c -p mingw --mingw=C:\mingw
|
||
|
||
# 禁用示例
|
||
xmake f --examples=n
|
||
|
||
# 启用调试日志
|
||
xmake f --debug_logs=y
|
||
```
|
||
|
||
### 安装依赖 (MinGW)
|
||
```bash
|
||
xmake require -y
|
||
```
|
||
|
||
### 构建项目
|
||
```bash
|
||
# 构建所有目标
|
||
xmake
|
||
|
||
# 构建特定目标
|
||
xmake -r extra2d
|
||
xmake -r push_box
|
||
|
||
# 并行构建
|
||
xmake -j4
|
||
```
|
||
|
||
### 运行程序
|
||
```bash
|
||
# 运行示例
|
||
xmake run push_box
|
||
xmake run hello_world
|
||
```
|
||
|
||
### 清理构建
|
||
```bash
|
||
xmake clean
|
||
xmake f -c # 重新配置
|
||
```
|
||
|
||
## 输出目录结构
|
||
|
||
```
|
||
build/
|
||
├── examples/
|
||
│ ├── hello_world/
|
||
│ │ ├── hello_world.exe # MinGW
|
||
│ │ ├── hello_world.nro # Switch
|
||
│ │ └── assets/ # 资源文件
|
||
│ ├── push_box/
|
||
│ ├── collision_demo/
|
||
│ └── spatial_index_demo/
|
||
└── ...
|
||
```
|
||
|
||
## 关键设计决策
|
||
|
||
### 1. 平台检测
|
||
- 使用 `is_plat()` 而不是手动检测，确保与主项目一致
|
||
- 示例脚本继承主项目的平台配置
|
||
|
||
### 2. 资源处理
|
||
- **Switch**: 使用 romfs 嵌入 NRO 文件
|
||
- **MinGW**: 构建后复制到输出目录
|
||
|
||
### 3. 依赖管理
|
||
- **MinGW**: 使用 Xmake 包管理器 (`add_requires`)
|
||
- **Switch**: 使用 devkitPro 提供的库
|
||
|
||
### 4. 工具链隔离
|
||
- Switch 工具链定义在单独文件中
|
||
- 通过 `set_toolchains("switch")` 切换
|
||
|
||
## 常见问题
|
||
|
||
### 1. 依赖包找不到
|
||
```bash
|
||
xmake repo -u
|
||
xmake require -y
|
||
```
|
||
|
||
### 2. Switch 工具链找不到
|
||
- 确保 DEVKITPRO 环境变量设置正确
|
||
- 默认路径: `C:/devkitPro`
|
||
|
||
### 3. 平台配置不匹配
|
||
- 使用 `xmake show` 查看当前配置
|
||
- 使用 `xmake f -c` 重新配置
|
||
|
||
### 4. MinGW 路径问题
|
||
如果 MinGW 安装在非默认位置，使用 `--mingw` 参数指定：
|
||
```bash
|
||
xmake f -c -p mingw --mingw=D:\Tools\mingw64
|
||
```
|
||
|
||
### 5. Switch 库找不到
|
||
确保在 MSYS2 中安装了必要的库：
|
||
```bash
|
||
pacman -S switch-sdl2 switch-sdl2_mixer switch-glm
|
||
```
|
||
|
||
## 扩展指南
|
||
|
||
### 添加新示例
|
||
1. 在 `examples/` 下创建新目录
|
||
2. 创建 `xmake.lua` 构建脚本
|
||
3. 在 `xmake.lua` 中添加 `includes("examples/new_example")`
|
||
|
||
### 添加新平台
|
||
1. 在 `xmake/toolchains/` 下创建工具链定义
|
||
2. 在 `xmake.lua` 中添加平台检测逻辑
|
||
3. 在 `xmake/engine.lua` 中添加平台配置 |