From 81fa87c967f720cc52d6e65e7b99e760cc8f3c25 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 10 Oct 2026 12:43:14 +0000 Subject: [PATCH] docs: tighten README for install, release, and fork MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lead with Releases download; document MSI upgrade, v* tags, and timeroute/wslc-rs pin. Drop redundant packaging noise. Co-authored-by: 绿岸公式 --- README.md | 178 +++++++++++++++--------------------------------------- 1 file changed, 48 insertions(+), 130 deletions(-) diff --git a/README.md b/README.md index 871f136..4000ba3 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,98 @@ # WSLc Desktop -面向 Windows **WSL Containers（WSLc）** 的轻量级桌面管理器，基于 [GPUI Kit](https://gpui-kit.com)（Zed GPUI + 组件库）构建。 +面向 Windows **WSL Containers（WSLc）** 的轻量级桌面管理器，基于 [GPUI Kit](https://gpui-kit.com) 构建。 -通过 **WSL Containers SDK**（Rust 绑定使用自维护 fork [`timeroute/wslc-rs`](https://github.com/timeroute/wslc-rs)，见下方）浏览与管理容器、镜像与 VHD 卷。应用使用**独立会话** `wslc-desktop`（数据在 `%LOCALAPPDATA%\WSLcDesktop\session\`），与默认 `wslc` CLI 会话隔离——桌面端镜像/容器需在本应用内拉取与创建。MSI **不捆绑** DLL：首次启动以**阻塞弹窗**安装/更新 SDK 到 `%LOCALAPPDATA%\WSLcDesktop\sdk\`；Live 失败则保持锁定直至重试成功或自行修好 WSL。 +用独立会话 `wslc-desktop`（`%LOCALAPPDATA%\WSLcDesktop\`）管理容器、镜像与 VHD 卷，与默认 `wslc` CLI 会话隔离。Rust 绑定使用自维护 fork [`timeroute/wslc-rs`](https://github.com/timeroute/wslc-rs)（OpenContainer / Logs / named volumes）。MSI **不捆绑** `wslcsdk.dll`：首次启动以阻塞弹窗安装/更新 SDK。 -## 功能 - -- **总览（默认）**：引擎 / SDK / 应用版本、会话信息、容器·镜像·卷摘要 -- **Containers**：工具栏创建；行内 Start / Stop / Restart / Logs（fork 的 `LogsOptions` → `wslc container logs`）/ Inspect / Exec / Remove（确认）；catalog + `OpenContainer` 跨重启恢复 -- **Images**：工具栏拉取；行内创建容器 / 删除（确认） -- **Volumes**：工具栏弹窗创建（1/2/5/10 GiB）；行内删除（确认）；创建容器时可挂命名卷 -- **引擎状态**：LIVE（独立 `wslc-desktop` 会话）；未就绪时全屏 SDK 安装弹窗（OFF） -- **设置**：可滚动；语言 / 主题 / 会话 CPU·内存（写入 prefs，下次新建会话生效） - -## 环境要求 - -1. Windows 10/11（x64） -2. WSL **2.9.3+**（`wsl --update`；LIVE 模式需要本机 WSL Containers 运行时） -3. Rust **1.92+**，MSVC 工具链 -4. Visual Studio 2022 C++ 工作负载 + Windows SDK + CMake - -```powershell -wsl --update -rustup default stable-x86_64-pc-windows-msvc -``` +## 安装（推荐） -LIVE 需要：已安装/更新的 WSL（提供 `wslc.exe`），以及首次启动时能访问 nuget.org 以下载 `wslcsdk.dll`。也可预先手动放置 DLL（应用仍会优先用自动缓存）。 +1. 打开 [Releases](https://github.com/timeroute/wslc-desktop/releases) +2. 下载最新 `wslc-desktop-*-x86_64.msi` 并安装 +3. 确保本机 [WSL 2.9.3+](https://learn.microsoft.com/windows/wsl/install)（`wsl --update`） +4. 首次启动按提示完成 SDK 安装；之后即可拉取镜像、创建容器 -## 运行 +同版本 MSI 会覆盖旧安装（固定 `UpgradeCode` + `AllowSameVersionUpgrades`）。若「应用和功能」里已有重复条目，先卸干净再装新包。 -在 **x86_64-pc-windows-msvc** 工具链下： +需要 VC++ 运行库时，安装 [VC++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist)。 -```powershell -cargo run -``` - -发布构建： - -```powershell -cargo build --release -``` - -单元测试（版本匹配与格式化辅助）： - -```powershell -cargo test -``` +## 功能 -## 打包成 Windows 安装包（MSI） +| 页面 | 能力 | +|------|------| +| **总览**（默认） | 引擎 / SDK / 应用版本、会话 CPU·内存、容器·镜像·卷摘要 | +| **Containers** | 创建（端口 / bind / 命名卷）；行内 Start / Stop / Restart / Logs / Inspect / Exec / Remove；catalog + `OpenContainer` 跨重启恢复 | +| **Images** | 拉取弹窗；行内创建容器 / 删除 | +| **Volumes** | 弹窗创建（1/2/5/10 GiB）；行内删除 | +| **设置** | 可滚动；语言、主题、会话 CPU / 内存（下次新建会话生效） | -GPUI Kit 应用是原生 Windows 可执行文件，需在 Windows 本机（或 Windows CI）用 MSVC 工具链构建并打 MSI。 +Logs 走 fork 的 `LogsOptions`（底层 `wslc --session wslc-desktop container logs`）。退出应用**不会** `terminate` 会话，便于下次重连。 -### 1. 准备环境 +## 从源码构建 -1. 安装 [Visual Studio 2022](https://visualstudio.microsoft.com/)（含 **Desktop development with C++**、Windows SDK） -2. 安装 [CMake](https://cmake.org/) 并加入 PATH -3. 安装 Rust MSVC 工具链： +**要求：** Windows 10/11 x64 · WSL 2.9.3+ · Rust stable-MSVC · VS 2022 C++ + Windows SDK + CMake ```powershell +wsl --update rustup default stable-x86_64-pc-windows-msvc -rustc -vV # 确认 host 含 windows-msvc -``` - -4. 安装 [WiX Toolset 3.14+](https://wixtoolset.org/)（`candle.exe` / `light.exe` 在 PATH 中） -5. 安装 cargo-wix： - -```powershell -cargo install cargo-wix +cargo run # 开发 +cargo build --release # 发布二进制 +cargo test ``` -### 2. 打 MSI（含桌面图标） +### 打 MSI -仓库已提交 `wix/main.wxs` 与 `wix/Product.ico`：安装后会创建 **开始菜单** 与 **桌面快捷方式**（**不** 捆绑 `wslcsdk.dll`，**不** 写入 PATH）。`UpgradeCode` 固定，且 `AllowSameVersionUpgrades=yes`：同版本重复安装会覆盖旧实例，不会在「应用和功能」里堆出多个条目。发正式版时仍建议递增 `Cargo.toml` 的 `version`（前三段）。 +另需 [WiX Toolset 3.14+](https://wixtoolset.org/) 与 `cargo install cargo-wix`： ```powershell cargo wix +# 产物：target\wix\wslc-desktop--x86_64.msi ``` -产物一般在： +可选：`cargo wix --no-build`（已有 release 产物时）、`cargo wix --sign`（需 `signtool`）。 -```text -target\wix\wslc-desktop--x86_64.msi -``` - -只打包已有 release 产物时： - -```powershell -cargo build --release -cargo wix --no-build -``` - -### 3. 可选：签名 - -有代码签名证书时（需 Windows SDK 的 `signtool`）： - -```powershell -cargo wix --sign -``` - -### 4. 其他安装包形态 - -| 形态 | 工具 | 说明 | -|------|------|------| -| **MSI**（推荐） | `cargo-wix` + WiX | 企业部署友好，支持静默安装 | -| **EXE 安装向导** | [Inno Setup](https://jrsoftware.org/isinfo.php) / NSIS | 先 `cargo build --release`，再把 `target\release\wslc-desktop.exe` 写进脚本 | -| **便携版** | 直接分发 exe | 拷贝 `target\release\wslc-desktop.exe`（目标机通常还需 [VC++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist)） | +### 发布到 GitHub Release -若运行时报缺 VC++ 运行库，把对应 [VC++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) 一并装上。LIVE 依赖本机 WSL + 可发现的 `wslcsdk.dll`；安装弹窗与状态栏会显示具体失败原因（找不到 DLL / 组件缺失 / SDK 过旧等）。 - -### 5. GitHub Actions 自动打 MSI - -仓库已提供 Windows runner 工作流： - -```text -.github/workflows/windows-msi.yml -``` - -**触发：** - -- push / PR 到 `main`：构建 MSI，上传为 workflow artifact -- tag `v*`：构建 MSI，并创建 GitHub Release 挂载安装包 -- 手动：Actions → **Windows MSI** → **Run workflow** - -发布示例： +打 `v*` tag 会触发 [Windows MSI](.github/workflows/windows-msi.yml) 工作流：构建 MSI 并创建 Release 挂载安装包。 ```powershell +# 版本与 Cargo.toml 对齐，例如 0.1.0 → v0.1.0 git tag v0.1.0 git push origin v0.1.0 ``` -成功后可在对应 workflow run 的 **Artifacts** 下载 `wslc-desktop-msi`；打 tag 时还会出现在 **Releases**。 - -工作流在 `windows-latest` 上安装 Rust MSVC、WiX Toolset、`cargo-wix`，再 `cargo wix` 产出带桌面快捷方式的 MSI。 - -## 依赖自己的 `wslc-rs` fork +也可：push / PR 到 `main` 仅上传 artifact；或 Actions → **Windows MSI** → **Run workflow**。 -本仓库 **不** 再 vendor 整棵树，而是在 `Cargo.toml` 里用 git 依赖钉死 fork 提交： +## 依赖 `wslc-rs` fork ```toml [target.'cfg(windows)'.dependencies] wslc = { git = "https://github.com/timeroute/wslc-rs", rev = "" } ``` -**日常流程：** +在 fork 打补丁并 push 后，更新这里的 `rev`，再 `cargo build` / 提交 `Cargo.lock`。可用 `WSLC_CLI_PATH` 覆盖日志用的 `wslc.exe`。 -1. 在 [timeroute/wslc-rs](https://github.com/timeroute/wslc-rs) 打补丁并 push 到 `master`（或你的分支） -2. 记下新 commit SHA：`git rev-parse HEAD` -3. 改桌面端 `Cargo.toml` 的 `rev = "…"` -4. 在 Windows 上 `cargo update -p wslc`（或直接 `cargo build`），提交更新后的 `Cargo.lock` - -**Logs：** fork 提供 `Container::logs(LogsOptions)` / `Session::logs(...)`。公开 C SDK 尚无 Logs 导出，实现走 `wslc --session container logs`（可用 `WSLC_CLI_PATH` 覆盖可执行文件）。桌面端默认 `tail(200)` + `timestamps`，不用 `follow`（避免卡住 UI）。 - -## 项目结构 +## 架构 ```text -.github/workflows/ # GitHub Actions（Windows MSI） -wix/ # MSI：桌面/开始菜单快捷方式 + 产品图标 -src/ - main.rs # 窗口启动与快捷键 - app/ # GPUI 主界面（按功能拆分：shell、containers、images、…） - i18n.rs # 中英文字符串与系统语言检测 - wslc/ # SDK 封装（types + 独立会话 Live；安装/拉取/创建进度事件） +UI (GPUI Kit) + ├─ SDK 安装弹窗 → NuGet 缓存 wslcsdk.dll + ├─ Session "wslc-desktop"（与 CLI 隔离，退出不 terminate） + └─ 拉取 / 创建 / 日志 → 阻塞弹窗或行内操作 ``` -## 架构说明 +| 资源 | 持久化 | +|------|--------| +| Containers | `%LOCALAPPDATA%\WSLcDesktop\catalog.json` + `OpenContainer` | +| Volumes | catalog | +| 会话 prefs | `%LOCALAPPDATA%\WSLcDesktop\prefs.json` | ```text -UI (GPUI Kit) ──► SDK 安装弹窗 ──► NuGet 缓存 wslcsdk.dll - ──► Session "wslc-desktop"（与 CLI 隔离） - ──► 拉取 / 创建容器 / 日志 均为阻塞弹窗 +.github/workflows/ Windows MSI CI / Release +wix/ MSI 快捷方式与图标 +src/app/ 界面（overview / containers / images / volumes / settings） +src/wslc/ SDK 封装与 Live 会话 ``` -- **Images**：本会话 `list_images` / `pull_image` / `delete_image` -- **Containers**：本进程跟踪的 SDK 句柄 + `%LOCALAPPDATA%\WSLcDesktop\catalog.json`；启动时 `OpenContainer` 重连（退出不 `terminate` 会话） -- **Volumes**：`create_vhd_volume` / `delete_vhd_volume`，catalog 持久化 - ## 许可 Apache-2.0