# 环境搭建

本文介绍如何为 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`

在项目根目录执行：

```bat
setup.bat
```

`setup.bat` 只负责：

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

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

### 默认行为

直接执行：

```bat
setup.bat
```

等价于：

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

默认会完成以下动作：

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

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

### 常用参数

```bat
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` 到：

```text
tools/w64devkit/
```

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

```text
tools/w64devkit/bin
```

注意：

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

### 关于 `ffmpeg`

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

```text
tools/ffmpeg/
```

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

```text
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` 会自动下载官方预编译包；也可以手动执行：

```bash
python scripts/setup_resvg.py --install
```

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

```text
RESVG=<path-to-resvg>
```

## Linux / macOS 环境搭建

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

在项目根目录执行：

```bash
./setup.sh
```

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

常用参数同样支持：

```bash
./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

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

#### Fedora

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

#### Arch Linux

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

#### macOS

先安装 Homebrew，然后执行：

```bash
brew install gcc make sdl2 python ffmpeg
```

## 手动安装方式

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

### 1. 创建虚拟环境

Windows：

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

Linux / macOS：

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

### 2. 安装 Python 依赖

基础依赖：

```bash
python -m pip install -r requirements.txt
```

当前仓库完整依赖：

```bash
python -m pip install -r requirements.txt
```

### 3. 安装编译工具链

Windows 可选：

- MSYS2
- MinGW-w64
- `w64devkit`

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

### 4. 准备 `ffmpeg`

Windows 可直接运行：

```bat
setup.bat --install-ffmpeg
```

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

```bash
ffmpeg -version
```

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

推荐直接执行：

```bash
python scripts/setup_resvg.py --install
```

也可以通过 setup 入口：

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

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

## 验证安装

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

```bash
make all APP=HelloSimple PORT=pc
make run
```

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

也可以继续验证：

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

## 可选工具

### ARM GCC

用于 STM32 / QEMU 目标：

```text
ARM_GCC_PATH=<toolchain_root>
```

### QEMU

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

```text
QEMU_PATH=<qemu_install_dir>
```

### Emscripten

用于 WASM 构建：

```text
EMSDK=<emsdk_root>
```

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

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

```bat
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，直接执行以下命令即可：

```bat
make all APP=HelloSimple PORT=emscripten
```

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

```bat
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` 未找到

优先运行：

```bash
python scripts/setup_resvg.py --install
```

或者直接重新执行：

```bash
setup.bat
./setup.sh
```

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

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

优先运行：

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

构建系统会优先使用仓库内的 `tools\emsdk`。如果只是想在当前 shell 手动执行 `emcc -v`，再运行：

```bat
call tools\emsdk\emsdk_env.bat
```

## 下一步

环境搭建完成后，请继续阅读：

- [第一个应用](first_app.md)
- [构建系统详解](build_system.md)