Files
GC-XH/GC-UI/CI.md
T
Morris 2c0c566c81 build: 支持在 Linux/macOS 上交叉编译 Windows 前端
此前 Windows 包内不含 Flutter 界面,只能回退到内置 Avalonia 界面,
原因是 Flutter 官方不支持在非 Windows 主机上执行 flutter build windows。

实际上 Windows 嵌入层(windows/runner + cpp_client_wrapper)是纯 Win32
加标准 C++,只通过 C ABI 调用 flutter_windows.dll,因此用 mingw-w64 即可
编译。整条链路上唯一必须执行的 Windows 二进制是 AOT 快照生成器
gen_snapshot.exe,交给 wine 运行即可。全流程不需要 Windows 机器或 MSVC。

实现:
- buildsh/cross/toolchain-mingw.cmake  CMake 交叉工具链,posix 线程模型,
  静态链接 libstdc++/libgcc,产物只依赖系统 DLL 和 flutter_windows.dll
- buildsh/cross/CMakeLists.txt         只编 C++ 外壳,绕开 tool_backend.bat
  与 MSVC 专用编译参数
- buildsh/cross/build-ui-win-cross.sh  拉取引擎产物、为 gen_snapshot 装 wine
  包装、生成 AOT 快照、组装出与官方 toolchain 一致的目录结构
- build_flutter_ui_cross / build.sh    非 Windows 主机走交叉编译分支,
  x64 产物同时放进 win-amd64 与 win-arm64 两个包

顺带修掉 shell.dart 的常量求值错误:强调色改为跟随设置的动态 getter 后,
const Text 里引用 GcColors.accent 会让编译器报错。

已在 Linux 上用 wine 验证产物:Flutter 引擎正常初始化,Dart AOT 快照加载
并执行到业务代码,后端 /api/health 正常返回。
2026-11-18 13:29:53 +08:00

119 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# GC-UI 持续集成
夜间 alpha 构建的工作流在 [`.gitea/workflows/gc-ui-alpha.yml`](../.gitea/workflows/gc-ui-alpha.yml)。
本仓库是自建 Gitea(不是 GitHub),所以目录是 `.gitea/workflows/`,语法与 GitHub Actions 基本一致,
差异集中在 **runner 标签** 和 **API 前缀** 两处。
## 它做什么
| 任务 | 运行环境 | 产出 |
|---|---|---|
| `prepare` | `ubuntu-latest` | 算版本号,建一个 **草稿 + prerelease** 的 Release |
| `windows` | `windows-latest` | `gc-ui-alpha-windows-x64.zip`(Flutter release 目录) |
| `macos` | `macos-latest` | `gc-ui-alpha-macos-<arch>.zip`(`gc_ui.app`,用 `ditto` 打包保真) |
| `publish` | `ubuntu-latest` | 两个平台都成功后才把草稿翻成可见,并断言 latest 没被占用 |
- **定时**:每天 **21:00(Asia/Shanghai)**,cron 写作 `TZ=Asia/Shanghai 0 21 * * *`。
Gitea 1.23 起 Actions 的 cron 默认按 **UTC** 解释,所以这里显式带时区前缀;
若你的实例不认 `TZ=`,改成等效的 UTC 写法 `0 13 * * *`。
- **alpha 不占用 latest**:Gitea 的 `/releases/latest` 只返回「最近一个既非草稿、也非 prerelease」
的发布,所以 `prerelease: true` 的夜间版本永远不会成为 latest。`publish` 任务最后会再查一次
`/releases/latest`,一旦指向本次 tag 就 fail。
- **手动触发**:Actions 页面 Run workflow;或
```bash
curl -X POST -u "USER:TOKEN" \
"https://git.xhmcl.com/api/v1/repos/Morris/GC/actions/workflows/gc-ui-alpha.yml/dispatches" \
-H 'Content-Type: application/json' -d '{"ref":"gc-ui","inputs":{"note":"手动验证"}}'
```
## 前置条件(缺一不可)
### 1. 必须有 act_runner,并且带这三个标签
```bash
# 在准备当构建机的机器上(Windows / macOS 各一台,或一台 Linux 只跑 prepare/publish)
docker run -d --name gitea-runner \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /path/to/runner-data:/data \
-e GITEA_INSTANCE_URL=https://git.xhmcl.com \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<在 站点管理 → Actions → Runners 里拿> \
-e GITEA_RUNNER_LABELS=ubuntu-latest:docker://gitea/runner-images:ubuntu-latest,windows-latest:docker://<你的 windows 镜像>,macos-latest:docker://<你的 macos 镜像> \
gitea/act_runner:latest
```
关键点:**`runs-on` 的值必须和 runner 上注册的 label 完全一致**,否则任务永远排队。
Windows / macOS 的构建**不能**跑在 Linux docker 容器里(一个要 MSVC,一个要 Xcode),
所以那两个 label 需要指向真实的 Windows / macOS 机器(自托管 runner)。
### 2. Flutter SDK
工作流里有一条「准备 Flutter SDK」:机器上已有 `flutter` 就直接用;没有就按
`FLUTTER_VERSION`(默认 3.24.5,需 >= 3.5.4 以匹配 `pubspec.yaml` 的 `sdk: ^3.5.4`)从
`storage.googleapis.com` 下载官方 SDK 并写进 `PATH`。所以机器只要能上外网就够,不必预装。
网络受限时请预装 Flutter 并确保 `flutter` 在 `PATH` 里。
Windows 还需要 **VS Build Tools 的「使用 C++ 的桌面开发」工作负载**;macOS 需要 **Xcode**。
### 3. Token
优先用仓库 Secrets 里的 `RELEASE_TOKEN`(Gitea 设置 → Actions → Secrets,需 `repo` 权限的个人访问令牌);
没配就退回 Gitea 自动注入的 `github.token`。若自动 token 没有 release 权限,
创建 Release 那步会报 401/403 —— 这时配一个 `RELEASE_TOKEN` 即可,不用改工作流文件。
## 本地构建(不经 CI)
```bash
# Linux / macOS:三平台一次出齐。Windows 前端用 mingw-w64 + wine 交叉编译,
# 不需要 Windows 机器。
./build.sh build
# 只编 macOS 前端
./GC-UI/build-ui.sh macos
# Windows 主机原生构建
GC-UI\build-ui.cmd
```
### Windows 前端交叉编译
Flutter 官方不支持在非 Windows 主机上 `flutter build windows`,但 Windows 嵌入层
(`windows/runner/*.cpp` + `cpp_client_wrapper`)是纯 Win32 + 标准 C++,只通过 C ABI
调用 `flutter_windows.dll`,所以 mingw-w64 就能编译。整条链路上唯一必须执行的
Windows 二进制是 AOT 快照生成器 `gen_snapshot.exe`,交给 wine 跑即可。
```bash
# 依赖
sudo apt install mingw-w64 cmake ninja-build wine # Linux
brew install mingw-w64 cmake ninja # macOS
brew install --cask wine-stable # macOS 的 wine
# 单独构建(默认输出到 GC-UI/frontend/build/windows/x64/runner/Release)
./buildsh/cross/build-ui-win-cross.sh [输出目录]
```
产物与官方 toolchain 完全一致,可直接拷到 Windows 运行:
```
GC-UI.exe flutter_windows.dll data/{icudtl.dat, app.so, flutter_assets/}
```
实现分三层:
| 文件 | 职责 |
|---|---|
| `buildsh/cross/toolchain-mingw.cmake` | CMake 交叉工具链(posix 线程模型,静态链接 libstdc++,产物只依赖系统 DLL) |
| `buildsh/cross/CMakeLists.txt` | 只编 C++ 外壳;绕开 `tool_backend.bat` 与 MSVC 专用参数 |
| `buildsh/cross/build-ui-win-cross.sh` | 拉引擎产物、装 `gen_snapshot` 的 wine 包装、生成 AOT 快照、组装 |
两个容易踩的坑,脚本里已处理:
- `flutter_tools` 会 exec 路径为 `.../windows-x64-release/gen_snapshot`(**没有 `.exe`**)
的文件,所以脚本在原 `.exe` 旁边放一个同名 shell 脚本转调 wine。
- `Runner.rc` 在 windres 下有两处不兼容:图标用反斜杠相对路径、`VERSION_AS_STRING`
依赖命令行传 `-D` 的转义字符串。脚本生成一份路径与宏都已规整的 rc 副本再编译。
`.gitea/workflows` 里的 `windows` 任务仍然跑在 `windows-latest` 上;若手头只有 macOS/Linux
构建机,可以把该任务的 `runs-on` 换成对应标签,直接复用这套交叉编译脚本,
不再需要 VS Build Tools。