环境搭建¶

本文介绍如何为 EmbeddedGUI 配置开发环境。当前推荐入口已经统一为：

Windows 使用 setup.bat
Linux / macOS 使用 setup.sh
实际安装逻辑统一由 scripts/setup_env.py 负责

默认情况下，setup 脚本会创建虚拟环境、安装完整 Python 依赖，并准备构建与媒体处理所需的本地工具。

依赖概览¶

工具	用途	是否必需
GCC	C 编译器（PC 模拟器）	必需
GNU Make	构建工具	必需
SDL2	PC 模拟器显示和输入	必需（Windows 版本已内置）
Python 3.8+	资源生成与脚本工具	必需
FFmpeg	MP4 转序列帧、GIF 录制等媒体处理	默认检查，Windows 缺失时自动下载
resvg CLI	SVG 资源光栅化与 SVG 参考渲染	默认检查，缺失时自动下载
ARM GCC	STM32 / QEMU 交叉编译	可选
QEMU	ARM 仿真与性能测试	可选
Emscripten	WASM 构建	可选

Windows 环境搭建¶

推荐方式：运行 `setup.bat`¶

在项目根目录执行：

setup.bat

setup.bat 只负责：

检查系统里是否能找到 Python
调用 scripts/setup_env.py

真正的环境安装逻辑都在 Python 脚本中，后续维护以 Python 版本为准。

默认行为¶

直接执行：

setup.bat

等价于：

python scripts\setup_env.py --python-mode full

默认会完成以下动作：

创建 .venv
升级 pip
安装 requirements.txt
校验 json5、numpy、Pillow、freetype_py、pyelftools
检查 resvg
在缺失时自动安装到 tools/resvg/<version>/<platform>/
检查本地或系统中的 make / gcc
在缺失时自动安装 tools/w64devkit
检查 ffmpeg
在缺失时自动安装 tools/ffmpeg
默认编译一次 HelloSimple 做验证

setup_env.py 的 Summary 会额外报告当前 resvg 是否可用。

常用参数¶

setup.bat --python-mode basic
setup.bat --python-mode none
setup.bat --skip-resvg
setup.bat --skip-toolchain
setup.bat --skip-ffmpeg
setup.bat --skip-build-check
setup.bat --venv-dir .venv_custom
setup.bat --install-resvg
setup.bat --install-toolchain
setup.bat --install-ffmpeg

说明：

--python-mode full 默认值。当前仓库下与 basic 等价，安装 requirements.txt 中的依赖。
--python-mode basic 安装 requirements.txt 中的基础依赖。
--python-mode none 跳过 Python 依赖安装，仅做工具链检查。
--skip-resvg 跳过 resvg 检查和自动安装。仅在本次不涉及 SVG 资源生成或 SVG 校验时使用。
--skip-toolchain 跳过 make / gcc 检查和 w64devkit 自动安装。
--skip-ffmpeg 跳过 ffmpeg 检查和自动安装。仅在不需要 MP4 / GIF 相关流程时使用。
--skip-build-check 跳过 HelloSimple 编译验证。
--venv-dir 指定虚拟环境目录。
--install-resvg 仅安装仓库内的 resvg 并退出。
--install-toolchain 仅安装 Windows 工具链并退出。
--install-ffmpeg 仅安装 Windows 的 FFmpeg 本地包并退出。

关于 `w64devkit`¶

如果系统里没有 make.exe 或 gcc.exe，脚本会自动尝试安装 w64devkit 到：

tools/w64devkit/

安装完成后，脚本会优先使用：

tools/w64devkit/bin

注意：

该路径只会在当前脚本进程中注入
如果你想全局长期使用，需要手动加入系统 PATH

关于 `ffmpeg`¶

脚本会优先检查系统 PATH 中现有的 ffmpeg。如果在 Windows 下未找到，会自动下载并解压到：

tools/ffmpeg/

安装完成后，脚本会优先使用：

tools/ffmpeg/bin

这部分主要用于：

scripts/tools/app_resource_generate.py 内置的 MP4 抽帧流程（由 app_resource_config.json 的 mp4 配置触发）
scripts/recording/gif_recorder.py 的高质量 GIF 导出流程

如果你不需要这些媒体处理能力，可以显式传入 --skip-ffmpeg。

关于 `resvg`¶

仓库已经不再依赖旧的 Python SVG 渲染链路或额外本地运行库。

当前 SVG 资源生成和 HelloSVGSpec 参考渲染统一使用官方 resvg CLI，默认会优先按以下顺序查找：

环境变量 RESVG
仓库内自动下载的 tools/resvg/<version>/<platform>/resvg(.exe)
系统 PATH 中已有的 resvg

如果缺失，setup_env.py 会自动下载官方预编译包；也可以手动执行：

python scripts/setup_resvg.py --install

如果你已经有现成的 resvg，也可以手动指定：

RESVG=<path-to-resvg>

Linux / macOS 环境搭建¶

推荐方式：运行 `setup.sh`¶

在项目根目录执行：

./setup.sh

默认行为与 Windows 一致，也会安装完整 Python 依赖，并检查系统中的 make、gcc 与 ffmpeg。

常用参数同样支持：

./setup.sh --python-mode basic
./setup.sh --python-mode none
./setup.sh --skip-resvg
./setup.sh --skip-ffmpeg
./setup.sh --skip-build-check
./setup.sh --venv-dir .venv_custom
./setup.sh --install-resvg

先安装系统依赖¶

Ubuntu / Debian¶

sudo apt-get update
sudo apt-get install -y build-essential libsdl2-dev python3 python3-venv python3-pip ffmpeg

Fedora¶

sudo dnf install gcc make SDL2-devel python3 python3-pip ffmpeg

Arch Linux¶

sudo pacman -S base-devel sdl2 python python-pip ffmpeg

macOS¶

先安装 Homebrew，然后执行：

brew install gcc make sdl2 python ffmpeg

手动安装方式¶

如果不使用 setup.bat / setup.sh，也可以手动执行。

1. 创建虚拟环境¶

Windows：

python -m venv .venv
.venv\Scripts\activate.bat

Linux / macOS：

python3 -m venv .venv
source .venv/bin/activate

2. 安装 Python 依赖¶

基础依赖：

python -m pip install -r requirements.txt

当前仓库完整依赖：

python -m pip install -r requirements.txt

3. 安装编译工具链¶

Windows 可选：

MSYS2
MinGW-w64
w64devkit

如果使用 w64devkit，解压后确保 bin 目录可被找到。

4. 准备 `ffmpeg`¶

Windows 可直接运行：

setup.bat --install-ffmpeg

Linux / macOS 通过系统包管理器安装后，可用以下命令确认：

ffmpeg -version

5. 准备 `resvg`（SVG 光栅化需要）¶

推荐直接执行：

python scripts/setup_resvg.py --install

也可以通过 setup 入口：

setup.bat --install-resvg
./setup.sh --install-resvg

安装完成后，脚本会把官方 resvg 二进制放到仓库内的 tools/resvg/<version>/<platform>/。

验证安装¶

无论使用哪种方式，建议至少验证一次：

make all APP=HelloSimple PORT=pc
make run

如果一切正常，会弹出 PC 模拟器窗口。

也可以继续验证：

python scripts/code_runtime_check.py --app HelloSimple --timeout 10

可选工具¶

ARM GCC¶

用于 STM32 / QEMU 目标：

ARM_GCC_PATH=<toolchain_root>

QEMU¶

用于性能基准和仿真测试：

QEMU_PATH=<qemu_install_dir>

Emscripten¶

用于 WASM 构建：

EMSDK=<emsdk_root>

使用 `setup_env.py` 安装本地 emsdk（Windows）¶

如需补齐 WASM 构建环境，可在仓库根目录直接执行：

python scripts\setup_env.py --python-mode none --install-emsdk

常用参数：

--install-emsdk：仅安装并激活 emsdk，然后输出环境摘要
--emsdk-version <version>：指定要安装/激活的 emsdk 版本或别名，例如 latest
--skip-emsdk：当本次只验证 PC / QEMU / STM32 工作流时，跳过 Emscripten 检查

安装完成后，脚本会优先使用仓库内的 tools\emsdk。即使系统环境变量中的 EMSDK 或 EMSDK_PATH 指向了失效路径，也会自动回退到本地副本。

Windows 下项目的 WASM 构建已经接入本地 wrapper，因此无需先手动激活 shell，直接执行以下命令即可：

make all APP=HelloSimple PORT=emscripten

如果你希望在当前终端里直接调用 emcc、em++、emar 等命令，再额外执行：

call tools\emsdk\emsdk_env.bat

常见问题¶

`setup.bat` 或 `setup.sh` 提示 Python 未找到¶

先安装 Python 3.8+，并确保 python 或 python3 可执行。

Python 依赖安装失败¶

脚本会先尝试镜像源，再回退到官方 PyPI。若仍失败，会打印手动恢复命令，按提示执行即可。

`ffmpeg` 未找到¶

Windows 下重新运行 setup.bat 即可触发自动安装。Linux / macOS 请先通过系统包管理器安装，或在不需要相关流程时传入 --skip-ffmpeg。

`resvg` 未找到¶

优先运行：

python scripts/setup_resvg.py --install

或者直接重新执行：

setup.bat
./setup.sh

如果你想使用系统里现有的 resvg，设置 RESVG 或确保它在 PATH 中即可。

`emcc` 未找到或版本不对¶