RiCoCoSoul
/
Extra2D
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Extra2D/.trae/documents/Extra2D 构建系统文档.md

7.1 KiB
Raw Blame History

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

  2. 安装 Xmake

  3. 安装依赖包

    xmake require -y

Nintendo Switch 平台

  1. 安装 devkitPro

  2. 设置环境变量

    # PowerShell
$env:DEVKITPRO="C:/devkitPro"

# 或永久设置（系统属性 -> 环境变量）
[Environment]::SetEnvironmentVariable("DEVKITPRO", "C:/devkitPro", "User")

  3. 在 MSYS2 中安装 Switch 库

    # 打开 MSYS2 (devkitPro 提供的)
pacman -S switch-sdl2 switch-sdl2_mixer switch-glm

# 或安装所有 Switch 开发库
pacman -S $(pacman -Slq dkp-libs | grep switch-)

  4. 验证安装

    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 平台)

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 平台

add_includedirs(devkitPro .. "/portlibs/switch/include")
add_linkdirs(devkitPro .. "/portlibs/switch/lib")
add_syslinks("SDL2_mixer", "SDL2", "opusfile", "opus", ...)

MinGW 平台

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)

示例程序构建脚本

通用结构

-- 使用与主项目相同的平台配置
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
  • 构建后复制资源文件

构建命令

配置项目

# 默认配置 (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)

xmake require -y

构建项目

# 构建所有目标
xmake

# 构建特定目标
xmake -r extra2d
xmake -r push_box

# 并行构建
xmake -j4

运行程序

# 运行示例
xmake run push_box
xmake run hello_world

清理构建

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. 依赖包找不到

xmake repo -u
xmake require -y

2. Switch 工具链找不到

  • 确保 DEVKITPRO 环境变量设置正确
  • 默认路径: C:/devkitPro

3. 平台配置不匹配

  • 使用 xmake show 查看当前配置
  • 使用 xmake f -c 重新配置

4. MinGW 路径问题

如果 MinGW 安装在非默认位置，使用 --mingw 参数指定：

xmake f -c -p mingw --mingw=D:\Tools\mingw64

5. Switch 库找不到

确保在 MSYS2 中安装了必要的库：

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 中添加平台配置