# SCGUI

**Repository Path**: dmxlight/scgui

## Basic Information

- **Project Name**: SCGUI
- **Description**: /*
*                        SC_GUI for V2. 0
* 一个小内存(1-3k)的开源GUI,支持LVGL抗锯齿字体,动态文字,实用波形图,支持双DMA,简易图层叠加
* 感谢网友开源工具Lvgl Font Tool V0.4 生成 阿里(qq:617622104)
* 作者:黎R(WX:13018616872)
* 社区:(QQ群:799501887)
*/
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: SCGUI_DEV
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 35
- **Created**: 2024-12-29
- **Last Updated**: 2026-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# scgui Designer（Tauri 版）

嵌入式 GUI 设计器桌面版：可视化编排控件、WASM 实时预览、导出 MCU 工程。

纯 **Tauri v2 / Rust + WebView2**，无 Node 运行时、无 TCP 端口，双击即跑。含独立的字库取模工具。

## 组成

| 组件 | 位置 | 说明 |
|---|---|---|
| 设计器主程序 | `designer/src-tauri/` | Tauri 壳：服务前端 + `/api/*`（app:// 协议） |
| 设计器前端 | `frontend/` | 原生 JS + Canvas；`scgui.wasm` 做交互预览 |
| 字库工具 | 内置于设计器 | 取模导出 `.c/.h/.bin`；UI 走 `/tool/font_tool/`，取模引擎 `frontend/js/scgui-font-raster.js` |
| WASM 桥 C 源码 | `wasm/` | Emscripten 编译 C 运行时 → `frontend/scgui.{js,wasm}` |
| MCU C 运行时 | `projects/src/` | C99，极小内存目标；编译为 wasm / 导出给 MCU |
| SDL 宿主与 demo | `projects/`、`projects/examples/`、`host/` | 原生编译/运行验证 |
| 默认资源 | `projects/examples/defaults/` | 内置示例字体、图片、工程资源（随 examples 携带） |
| Keil Pack 打包工具 | `frontend/tools/keil_pack/` + `keil-pack/` | 把库打成 CMSIS-Pack（.pack），双击导入 Keil；设计器工具 + Node CLI |

## 目录结构

```
tauri_pro/
├── README.md                 ← 本文件（入口）
├── docs/
│   ├── ARCHITECTURE.md       ← 架构说明（组件 / 桥接面 / 编译上限 / 构建运行）
│   └── FONT_TOOL.md          ← 字库工具规格
├── designer/src-tauri/       ← 设计器主程序（Tauri v2，含字库工具）
├── frontend/                 ← 设计器前端（含 scgui.wasm 预览产物、tools/font_tool 字库页）
├── wasm/                     ← WASM 桥 C 源码
├── projects/
│   ├── src/                  ← MCU C 运行时
│   ├── examples/             ← 示例
│   ├── fonts/  images/       ← 当前工程资源（设计器就地读写）
│   ├── sdl2/                 ← SDL2 开发包（唯一副本，不入库；导出含 SDL 时拷入工程）
│   └── ...                   ← SDL demo 与工程配置
├── host/                     ← sc_sdl2 宿主（导出到用户工程）
├── projects/examples/defaults/  ← 内置示例资源（demo 用，随 examples 携带）
├── dist/                     ← 便携发布版（gitignore；scgui-designer-portable/ 解压即用）
├── tests/                    ← 冒烟测试（app_smoke.c）+ codegen 单元测试（tests/codegen/，入口 run-codegen-tests.ps1）
└── build-wasm.ps1 / .sh      ← 重建 scgui.wasm（含冒烟）
```

## 构建与运行

### 1. 重建 WASM 预览

```bat
designer\build-wasm.ps1          (或 tauri_pro\build-wasm.ps1)
```

编译 `wasm/` + `projects/src/` 为 `frontend/scgui.{js,wasm}`，随后自动跑 Node 冒烟测试（`WASM smoke OK`）。

**编译模式（`-Configuration` 参数）：**

| 模式 | 命令 | 适用场景 | 差异 |
|---|---|---|---|
|优先使用 MSVC 编译整个 Tauri 桌面应用（Rust 壳）
| `Debug`（默认） | `.\build-wasm.ps1` | 日常开发、迭代验证 | `-O0 -g3`、`-sASSERTIONS=2`（编译速度快、含边界检查，能在迭代时尽早暴露越界/UAF） |
| `Release` | `.\build-wasm.ps1 -Configuration Release` | 验证 OK 后打包发布 | `-O3` 优化、`-sASSERTIONS=0`（体积小、渲染性能最佳，编译耗时较长） |

> **日常用 Debug，发布用 Release。** Debug 模式编译速度更快（`-O0` 无优化 pass），且带运行时检查便于在迭代中及时发现问题；待功能验证 OK、准备打包或出包前再切 Release，以获得最小体积与最优性能。

**执行环境要求：**

- 必须在**系统 PowerShell**中直接运行，不要通过任何沙箱/容器代理（Trae Sandbox、Docker 等）。Emscripten 内部会 spawn `clang`、`lld`、`node` 多级子进程并访问 `%TEMP%`、`%USERPROFILE%\.emscripten_cache`、`D:\emsdk\` 等路径，沙箱拦截任一访问点都会导致 `emcc` 卡死（进程存在但 CPU=0，无法完成）。
- 若从 IDE 调用构建脚本失败或长时间无输出，请关闭 IDE 内置终端，**手动开一个 PowerShell 窗口**（开始菜单 → PowerShell），`cd e:\scd` 后执行上面的命令。

> wasm 构建不再 `-D` 传宏：上限由 `sc_config.h` 的 `__EMSCRIPTEN__` 分支定义（1080P 屏、`SC_PAGE_CNT 16`、`SC_OBJ_MAX 255`、`SC_DIRTY_BUCKET_N 16`）。MCU 导出回落 `sc_common.h` 默认（`SC_OBJ_MAX 255` 等），用户可在 config 的 `#if 0` 块手动覆盖。
>
> `sc_config.h` 兜底方案：工程根（工具生成）优先级最高，构建 include 路径「根在前」天然覆盖；`projects/src/sc_config.h` 是库兜底默认（**空占位**，尺寸/容量默认在 `sc_common.h` / `sc_obj.h` 的 `#ifndef`，Keil 包只带这份，不打包工程根生成版）。

### 2. 启动设计器

```bat
start-designer.vbs        (双击，无控制台窗口；输出见 designer-launch.log)
start-designer.ps1        (终端用)
```

`start-designer.ps1` 选项：

| 选项 | 作用 |
|---|---|
| （默认） | 直接启动已构建的 debug exe（秒开；已在运行则提示） |
| `-Rebuild` | 关掉旧实例 → `cargo build` → 启动（改过 Rust 代码后刷新） |
| `-Dev` | `cargo run` 前台运行（Ctrl+C 退出，改代码后重跑） |
| `-Force` | 已在运行时强制再开一个实例 |

手动方式等价：`cd designer\src-tauri && cargo run`。（`cargo tauri build` 可打 NSIS/portable 安装包。）

### 3. 运行 SDL demo

```bat
set APP_DEMO_ID=17     (17 = transform_demo，0 = 冒烟)
projects\examples\build_demo.bat
projects\build\scgui.exe
```

（编译脚本统一用相对 `projects\sdl2`；SDL2 开发包唯一副本在 `projects\sdl2`。）

### 4. 便携发布（dist/）

`dist/scgui-designer-portable/` 是自包含便携版（`dist/` 不入库）：exe + `projects/`
（含 `sdl2/`、`.vscode/`、`build.bat`）。解压即用，**默认工作区 = exe 同目录 `projects/`**
（以 exe 位置为基准，解压到哪都认）。也可用工具栏「新建工程 / 打开工程」选择任意
目录作为工作区——新建在所选目录生成骨架，打开加载所选目录的工程，之后保存/导出
都写入所选目录（工作区随之切换）：

1. 双击 `scgui-designer.exe` 打开设计器
2. 默认在 `projects/` 工作；或点「新建/打开工程」选其他目录
3. 「导出」勾选含 SDL → 生成 `app_ui.c`、字体等（写入当前工作区）
4. `projects\build.bat` 编译 → `build\scgui.exe` 运行（SDL 模拟器）
5. 也可用 VS Code 打开工作区目录开发（`.vscode/` 已含编译/调试任务）

重新出包（GNU 工具链）：`cargo build --release`（带 `RUSTFLAGS="-C linker=rust-lld"`）后，把 `target\release` 下的 **`scgui-designer.exe` 和 `WebView2Loader.dll`**（Tauri v2 运行时必需，构建脚本只拷到 target 旁边）一起替换进 dist；MSVC 工具链构建则静态链接 WebView2Loader，只需 exe。SDL 开发包唯一副本
在 `projects\sdl2`（导出含 SDL 时自动拷入导出工程）。

## 发布与版本维护

### 版本号规则

遵循语义化版本 `主.次.修订`（如 `0.1.2`），发版时需**同步修改两处**：

- `designer/src-tauri/Cargo.toml` → `version`
- `designer/src-tauri/tauri.conf.json` → `version`

前端版本号通过 `window.__TAURI__.app.getVersion()` 运行时动态获取，无需硬编码，自动与编译时版本一致。

### 发版流程

1. **改版本号**：上述两个文件同步更新
2. **重建 WASM**（如 C 运行时有改动）：`.\build-wasm.ps1 -Configuration Release`
3. **编译 release**：`cd designer\src-tauri && cargo build --release`
4. **打便携包**：将 `target\release\scgui-designer.exe` + `projects\`（排除 `.vscode/`、`generated/`、`build/`）组装为 `dist\scgui-designer-portable\`，压缩为 zip
5. **更新 `frontend/update.json`**：`latest_version`、`release_notes`、`published_at`（`download_url` 固定为 releases 页面地址，无需每次修改）
6. **推送 update.json** 到 Gitee `SCGUI_DEV` 分支根目录（程序检查更新读的是这个分支的 raw 链接）
7. **Gitee 发行版**：创建对应 tag（如 `v0.1.2`），上传 `scgui-designer-portable.zip`

### 检查更新机制

- 程序内「关于」→「检查更新」拉取 `https://gitee.com/li_yucheng/scgui/raw/SCGUI_DEV/update.json`
- 与当前版本（`CARGO_PKG_VERSION`）比较语义化版本号，新版本则显示下载链接
- `download_url` 统一指向发行版列表页 `https://gitee.com/li_yucheng/scgui/releases`，由用户自行选择版本下载，避免附件直链 404

### 注意事项

| 项目 | 说明 |
|---|---|
| **工具链** | 推荐 MSVC（`stable-x86_64-pc-windows-msvc`），WebView2Loader 静态链接，exe 单文件即可运行；GNU 工具链需附带 `WebView2Loader.dll` |
| **包体积** | 便携包含 SDL2 开发包（`projects/sdl2/`，约 15 MB），用户编译 SDL demo 需要；如仅做固件导出可考虑提供无 SDL2 的精简包 |
| **排除目录** | 打包时排除 `projects/.vscode/`、`projects/generated/`（设计器运行时生成产物）、`projects/build/`（编译产物） |
| **target 缓存** | 若工程目录路径变更（如 `scgui` → `scgui2` 再改回），需清理 `target/release/build/tauri-*` 缓存，否则会报权限文件路径错误 |
| **update.json 位置** | 本地在 `frontend/update.json`（离线兜底，打包进 exe），远程必须在 `SCGUI_DEV` 分支**根目录**，否则 raw 链接 404 |
| **更新清单 URL** | 前端 `main.js` 里的 `UPDATE_MANIFEST_URL` 必须指向 `SCGUI_DEV` 分支，与远程推送分支保持一致；改分支时两处同步修改 |
| **源码保密** | 源代码不推送到公开仓库，仅推送 `SCGUI_DEV` 分支的 `update.json` 和 Gitee Release 附件；旧版本代码保留在 `SCGUIV2`/`SCGUIV3` 分支 |

## 文档

- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) —— 架构、桥接面、编译上限、WebView2 差异
- [`docs/FONT_TOOL.md`](docs/FONT_TOOL.md) —— 字库工具规格与验收