LuaSTGPlus

# 编译

# 前置依赖

前置依赖不区分具体平台，无论您希望在哪个平台构建LuaSTGPlus，都需安装下述依赖项。

  • 支持 C++17 特性的编译器
  • cmake >= 3.19
  • git >= 2.25
  • python >= 3.6

需要注意，构建过程中需要连接网络以安装依赖，请确保具有可以连通 Github 的网络环境。

# 构建选项

下述构建选项可以在编译时传递给 CMake，以开关某些功能，或配置交叉编译环境。

# LSTG_SHIPPING

  • 可选值：ON(1)/OFF(0)
  • 默认值：ON

当配置有LSTG_SHIPPING时，代码中供开发所用的功能会全数关闭，包括但不局限于：

  • 脚本及资产热加载
  • 性能剖析视图
  • 调试控制台
  • 部分代码逻辑检查和断言

建议仅当发布时开启该选项。

当LSTG_SHIPPING=0时，我们称之为开发模式。

# LSTG_ENABLE_ASSERTIONS

  • 可选值：ON(1)/OFF(0)
  • 默认值：ON(Debug)/OFF(其他)

该选项用于强制开启-D_DEBUG等调试宏，您通常无需关注该选项。

# LSTG_APP_NAME

  • 可选值：字符串
  • 默认值：default

该选项用于指定在用户存储路径（如AppData）中的子文件夹名称，以防止存储的分数信息、Replay数据冲突。

# LSTG_PARSE_CMDLINE

  • 可选值：ON(1)/OFF(0)
  • 默认值：ON

是否允许引擎解析命令行字符串，当开启该选项时，用户将可以通过命令行参数调整引擎的行为，例如：

./LuaSTGPlus2 -graphics=vulkan

命令行参数详见命令行章节。

需要注意，当开启该功能时，所传递给Lua侧的参数必须附加在--之后，例如：

./LuaSTGPlus2 -graphics=vulkan -- launch

如果您希望还原之前的行为，可以关闭该选项，但同时将无法通过命令行参数调整引擎行为。

# LSTG_DISABLE_HOT_RELOAD

  • 可选值：ON(1)/OFF(0)
  • 默认值：OFF

是否关闭热加载功能（仅限开发模式）。

# LSTG_CROSSCOMPILING_EARLY_BUILD

  • 可选值：ON(1)/OFF(0)
  • 默认值：ON

在交叉编译时是否启用二阶段编译。

二阶段编译用于生成Native工具链，若关闭功能，需要手工指定编译时依赖的工具。

# LSTG_EARLY_BUILD_GENERATOR

  • 默认值：N/A

用于指定在二阶段编译时使用的Generator，若不设置，将使用CMake默认值。

# 编译方式

WARNING

我们不提供安装脚本，请不要使用 make install 尝试进行安装。

# Windows

在安装完前置依赖后，您可以通过CMake命令行或CMake图形化工具进行构建工作。

TIP

我们推荐直接在Visual Studio中通过打开文件夹功能进行编译和开发工作。

# MacOS

在安装完前置依赖后，您可以通过CMake命令行进行构建工作。

git clone https://github.com/9chu/LuaSTGPlus
cd LuaSTGPlus
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

TIP

我们推荐直接在CLion中进行编译和开发工作。

# Linux

由于Linux环境相对灵活，请参照SDL2的各类前置依赖按需构建。

此处给出在Ubuntu 22.04 Arm64下的构建流程供参考。

# 安装构建工具

sudo apt install cmake git gcc g++ make python3

WARNING

您所用Linux发行版对应的git、cmake等工具可能不满足需要，若版本过低可能需要您手工编译符合前置要求的版本。

# 安装依赖

sudo apt install libx11-xcb-dev libpulse-dev libssl-dev libxext-dev libglx-dev libgl-dev

# 编译

git clone http://github.com/9chu/LuaSTGPlus
cd LuaSTGPlus
mkdir build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

TIP

若构建SDL2时出现找不到依赖的头文件的提示，但是确实已经安装了对应的包，则您可能需要删除CMakeCache.txt后重试。

# Emscripten

LuaSTGPlus使用emscripten编译到wasm，使之可以在浏览器中执行。

当您使用emscripten构建LuaSTGPlus时，请确保emsdk已经升级到了最新版本，较老的版本可能会造成无法编译的情况。

emscripten的环境准备请参考官方文档 (opens new window)。

TIP

我们推荐在Linux或者macOS环境下进行构建。

# 编译

mdkir cmake-build-release-emscripten
cd cmake-build-release-emscripten
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=~/emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake ..
make -j$(nproc)

# 手工构建本机工具（不推荐）

下述内容仅在不启用LSTG_CROSSCOMPILING_EARLY_BUILD时参考。

# 准备原生版本

由于交叉编译过程依赖一些本机可执行的二进制工具，您需要预先编译好原生版本供使用。

具体构建命令可参考上文，这里不再赘述。

# 构建Emscripten版本
mdkir cmake-build-release-emscripten
cd cmake-build-release-emscripten
# 请根据实际情况调整工具链位置和原生版本的构建产物目录（需要绝对路径）
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=~/emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -DLSTG_CROSSCOMPILING_EARLY_BUILD=OFF -DIcuBuildTools_DIR=~/LuaSTGPlus/build ..
make -j$(nproc)

# Android

安卓端参考LuaSTGPlusAndroid (opens new window)项目。

← 命令行 →