环境准备与编译

通用要求

所有平台均需要以下基础工具链：

依赖版本要求说明
C++ 标准C++17编译器须支持 C++17 特性
CMake3.13.0+建议使用最新版本
Ninja1.9.0+推荐的构建生成器
Node.js14.14.0+用于依赖同步与构建脚本

同步第三方依赖

构建前必须先同步第三方库。macOS 用户可直接运行一键脚本：

./sync_deps.sh

其他平台请先安装 depsync 工具，然后在项目根目录执行：

npm install -g depsync
depsync

Android

环境：Android NDK 20+（推荐 20.1.5948944），Java 17

NDK 默认安装路径：

  • macOS：~/Library/Android/sdk/ndk/20.1.5948944
  • Windows：%LOCALAPPDATA%\Android\Sdk\ndk\20.1.5948944

也可通过环境变量指定：ANDROID_NDK_HOME / ANDROID_NDK_ROOT / NDK_HOME 等。

方式一：在 Android Studio 中打开 android/ 目录，IDE 会自动完成 Gradle 同步与构建。

方式二：命令行构建

cd android/
./gradlew assembleRelease -Parm64-only --no-daemon

iOS

环境：Xcode 11.0+，部署目标 iOS 9.0+

cd ios/
./gen_ios              # 生成 iPhone 真机项目
./gen_simulator        # 生成模拟器项目（当前架构）
./gen_simulator -a x64 # 生成 x64 模拟器项目

生成完成后，打开 ios/Hello2D.xcworkspace 构建运行。

macOS

环境：Xcode 11.0+，部署目标 macOS 10.15+（Apple Silicon 为 11.0+）

cd mac/
./gen_mac              # 生成当前架构的 Xcode 项目

可选参数：

./gen_mac -a x64                     # 指定 x64 架构
./gen_mac -DTGFX_USE_FREETYPE=ON     # 传递 CMake 选项

生成完成后，打开 mac/Hello2D.xcworkspace 构建运行。

Web

环境：Emscripten 3.1.58+

安装 Emscripten（macOS）：

brew install emscripten

编译与运行：

cd web/
npm install
npm run build              # 多线程 Release
npm run server             # 启动本地服务器

浏览器访问 http://localhost:8081/web/demo/index.html 即可查看效果。

更多构建变体

npm run build:debug        # 多线程 Debug（支持 Chrome DevTools C++ 调试）
npm run build:st           # 单线程 Release
npm run build:st:debug     # 单线程 Debug
npm run server:st          # 单线程本地服务器

Linux

环境：GCC 9.0+，SwiftShader（用于 GPU 软件模拟）

安装系统依赖：

# Debian / Ubuntu
sudo apt-get install libx11-dev

# CentOS / RHEL
yum install libX11-devel --nogpg

编译：

cd linux/
cmake -B ./build -DCMAKE_BUILD_TYPE=Release
cmake --build ./build -- -j $(nproc)

Windows

环境：Visual Studio 2019+（需安装 Desktop development with C++ 和 Universal Windows Platform development 工作负载）

CLion：打开 win/ 目录，将 ToolChain 设为 Visual Studio（amd64），Generator 选择 Ninja。

Visual Studio：在 x64 Native Tools Command Prompt for VS 2019 中执行：

cd win/
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_CONFIGURATION_TYPES="Debug" -B ./Debug-x64

然后打开 Debug-x64/Hello2D.sln 构建运行。

Qt

环境：Qt 6.2.0+，CLion（macOS / Windows）

macOS：在 CLion 中打开 qt/ 目录，编辑 qt/QTCMAKE.cfg 将 Qt 路径修改为本地安装路径，然后构建运行 Hello2D 目标。

Windows：在 CLion 中打开 qt/ 目录，确保 ToolChain 设为 Visual Studio（amd64）。编辑 qt/QTCMAKE.cfg 修改 Qt 路径，并在 Hello2D 目标的 Environment Variables 中设置 Qt DLL 路径，例如：

PATH=C:\Qt\6.6.1\msvc2019_64\bin

HarmonyOS

环境：DevEco IDE（自带 HarmonyOS SDK）

  1. 在 DevEco 中打开 ohos/ 目录。
  2. 进入 Preferences → Build Tools → Hvigor，取消勾选 Execute tasks in parallel mode。
    • 或手动预编译第三方库：node build_vendor -p ohos
  3. 连接设备或启动模拟器，构建运行 hello2d 目标。

CMake 构建选项参考

选项默认值说明
TGFX_USE_OPENGLON启用 OpenGL 后端
TGFX_USE_METALOFF启用 Metal 后端（仅 Apple 平台）
TGFX_USE_FREETYPE平台相关使用 FreeType 矢量字体后端
TGFX_USE_SWIFTSHADEROFF使用 SwiftShader 软件渲染
TGFX_USE_ANGLEOFF使用 ANGLE 库
TGFX_USE_QTOFF使用 Qt 框架
TGFX_BUILD_LAYERSOFF构建 Layers 模块
TGFX_BUILD_SVGOFF构建 SVG 模块
TGFX_BUILD_PDFOFF构建 PDF 模块

编译预构建库

使用 build_tgfx 脚本可一键编译各平台的 tgfx 静态库，产物输出到 out/release/ 目录：

node build_tgfx                          # 当前平台 Release
node build_tgfx -p ios                   # 指定平台：win / mac / ios / linux / android / web / ohos
node build_tgfx -p mac -x               # Apple 平台生成 xcframework
node build_tgfx -DTGFX_USE_FREETYPE=ON  # 传递 CMake 选项
node build_tgfx -h                       # 查看完整帮助
← 平台与后端支持Hello2D 示例 →