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

3.8 KiB
Raw Blame History

Extra2D 构建系统文档

本文档详细介绍 Extra2D 引擎的构建系统配置和使用方法。

构建工具

Extra2D 使用 xmake 作为构建工具，支持多平台构建。

安装 xmake

# Windows (使用 PowerShell)
Invoke-Expression (Invoke-WebRequest 'https://xmake.io/psget.text' -UseBasicParsing).Content

# macOS
brew install xmake

# Linux
sudo add-apt-repository ppa:xmake-io/xmake
sudo apt update
sudo apt install xmake

平台支持

平台 目标 说明
Windows mingw MinGW-w64 工具链
Nintendo Switch switch devkitPro 工具链

构建配置

Windows (MinGW)

# 配置构建
xmake f -p mingw --mode=release

# 安装依赖
xmake require -y

# 构建引擎
xmake

# 构建示例
xmake -g examples

# 运行示例
xmake run hello_world

Nintendo Switch

# 配置构建
xmake f -p switch --mode=release

# 构建引擎
xmake

# 构建示例
xmake -g examples

# 打包 NSP
xmake package push_box

构建选项

配置参数

# 设置构建模式
xmake f --mode=debug      # 调试模式
xmake f --mode=release    # 发布模式

# 设置目标平台
xmake f -p mingw          # Windows
xmake f -p switch         # Nintendo Switch

构建目标

# 构建所有目标
xmake

# 构建特定目标
xmake -t extra2d          # 引擎库
xmake -t hello_world      # Hello World 示例
xmake -t push_box         # 推箱子游戏
xmake -t collision_demo   # 碰撞检测演示
xmake -t spatial_index_demo # 空间索引演示

# 构建示例组
xmake -g examples

项目结构

Extra2D/
├── xmake.lua              # 主构建配置
├── xmake/
│   ├── engine.lua         # 引擎构建规则
│   └── toolchains/        # 工具链定义
├── Extra2D/               # 引擎源码
│   ├── include/           # 头文件
│   └── src/               # 源文件
└── examples/              # 示例程序
    ├── hello_world/
    ├── push_box/
    ├── collision_demo/
    └── spatial_index_demo/

添加新示例

创建新的示例程序：

  1. 在 examples/ 下创建目录
  2. 添加 main.cpp 和 xmake.lua

示例 xmake.lua

-- examples/my_demo/xmake.lua
target("my_demo")
    set_kind("binary")
    add_deps("extra2d")
    add_files("*.cpp")
    add_packages("spdlog", "glm")
    
    -- 资源文件
    add_files("romfs/**", {install = true})
    
    -- Switch 特定配置
    if is_plat("switch") then
        add_rules("switch.nro")
        add_files("icon.jpg")
    end

常见问题

依赖安装失败

# 强制重新安装依赖
xmake require -f -y

# 清理构建缓存
xmake clean
xmake f -c

Switch 构建失败

确保已安装 devkitPro：

# 安装 Switch 开发工具链
pacman -S switch-dev switch-portlibs

# 设置环境变量
$env:DEVKITPRO = "C:\devkitPro"
$env:DEVKITA64 = "C:\devkitPro\devkitA64"

运行时找不到资源

确保资源文件已正确配置：

-- 在 xmake.lua 中添加资源
add_files("romfs/**", {install = true})

高级配置

自定义编译选项

-- 添加编译选项
add_cxxflags("-O3", "-ffast-math")

-- 添加宏定义
add_defines("E2D_ENABLE_PROFILING")

-- 添加包含路径
add_includedirs("third_party/include")

-- 添加链接库
add_links("pthread")

条件编译

if is_plat("windows") then
    add_defines("E2D_PLATFORM_WINDOWS")
elseif is_plat("switch") then
    add_defines("E2D_PLATFORM_SWITCH")
end

if is_mode("debug") then
    add_defines("E2D_DEBUG")
    add_cxxflags("-g", "-O0")
else
    add_defines("E2D_RELEASE")
    add_cxxflags("-O3")
end

参考链接