diff --git a/AGENTS.md b/AGENTS.md index 8e72229..be24e1e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -152,7 +152,8 @@ npm run dev:server # sidecar on http://localhost:3333, serves the UI from - The desktop app (`app/`) has its own dependencies outside the npm workspaces: run `npm ci` in `app/` once, then `npm run tauri:build:mac:arm64` (or the script for your platform). It needs a current Rust toolchain. Set `CI=true` when the build runs without - access to Finder, or the DMG step fails while styling the disk image window. + access to Finder, or the DMG step fails while styling the disk image window. The Windows + installer must be built on Windows: see [docs/oss/build-windows.md](docs/oss/build-windows.md). - The sidecar registers routes for the files in `dist/` when it starts (`@fastify/static` with `wildcard: false`), so assets from a later build return 404. Restart the sidecar after `npm run build`. diff --git a/docs/oss/build-windows.md b/docs/oss/build-windows.md new file mode 100644 index 0000000..ab4fca6 --- /dev/null +++ b/docs/oss/build-windows.md @@ -0,0 +1,108 @@ +# Building the Windows desktop app + +How to build the Waggle desktop installer for Windows from the `oss/community-edition` +branch. The build has to run on Windows: the packaging scripts take the bundled Node.js +runtime and the native modules (better-sqlite3, onnxruntime) from the machine they run on, +so a build made on macOS would ship macOS binaries. + +The community edition has not been built on Windows yet. The first build is part of the +week 3 acceptance; record what fails in `docs/oss/upstream-fixes.md` or `docs/oss/baseline.md`. + +## 1. Prepare the machine + +- Windows 10 or 11, x64, with about 20 GB of free disk space. +- [Git for Windows](https://git-scm.com/download/win). +- [Node.js 22](https://nodejs.org/en/download), x64. Use 22.23.2 if you can: the installer + bundles exactly this version, CI uses it, and the build checks that the bundled runtime can + load the native modules installed by your Node. +- [Rust](https://rustup.rs) through rustup, stable 1.94 or newer, with the default host + `x86_64-pc-windows-msvc`. +- [Visual Studio 2022 Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) + with the **Desktop development with C++** workload (MSVC and the Windows SDK). Rust links + with it, and npm uses it if a native module has to be compiled. +- WebView2 Runtime. It ships with current Windows 10 and 11. + +Run every command below in **PowerShell**, not Git Bash. The build unpacks the Node.js zip +with `tar`; Windows' own `tar` reads zip files, the GNU `tar` in Git Bash does not. + +Check the tools: + +```powershell +node --version # v22.x +rustc --version # 1.94 or newer +cargo --version +git --version +``` + +## 2. Get the code + +The branch is not on a shared remote, so copy it as a git bundle. On the machine that has +the repository: + +```bash +git bundle create waggle-oss.bundle oss/community-edition +``` + +The bundle holds the full history, including the leaked Stripe secret (UF-005). Copy it to +the Windows machine directly and do not upload it anywhere. + +On Windows, clone into a short path; `node_modules` and the Rust `target` folder produce +long paths: + +```powershell +git clone --branch oss/community-edition C:\path\to\waggle-oss.bundle C:\w\waggle-os +``` + +To update later, make a new bundle and pull from it: + +```powershell +git -C C:\w\waggle-os pull C:\path\to\waggle-oss.bundle oss/community-edition +``` + +## 3. Build + +```powershell +cd C:\w\waggle-os +npm ci +cd app +npm ci +npm run tauri:build:win -- --bundles nsis +``` + +`tauri:build:win` downloads and verifies the Node.js 22.23.2 runtime, bundles the sidecar, +copies the native modules, builds the web UI and then the Tauri shell. The first run compiles +the Rust shell from scratch and takes much longer than later runs. + +`--bundles nsis` builds only the NSIS installer, the one the app is configured for (a +per-user install without administrator rights); CI builds the same. Without the flag Tauri +also builds an MSI, for which it downloads WiX. + +The installer: + +``` +app\src-tauri\target\x86_64-pc-windows-msvc\release\bundle\nsis\Waggle_0.2.0_x64-setup.exe +``` + +## 4. Check the result + +1. Run the installer. It is not signed, so SmartScreen shows "Windows protected your PC": + choose **More info**, then **Run anyway**. Waggle installs for the current user. +2. Start Waggle from the Start menu. The window should move past "Starting Waggle…" to the + Home screen. +3. If it stays on "Starting Waggle…", close it and take the log from + `%USERPROFILE%\.waggle\logs\service.log`. +4. Chat needs a model: an API key in Settings → API Keys, or a running Ollama. + +Waggle keeps its data in `%USERPROFILE%\.waggle`. If the commercial edition was used on this +machine, the first start copies its data once and leaves the old files unchanged. + +## Troubleshooting + +| Symptom | Fix | +|---|---| +| `link.exe` not found, or a Rust linker error | Install the **Desktop development with C++** workload of the Build Tools. | +| `npm ci` compiles better-sqlite3 and fails | The prebuilt binary could not be downloaded. Check the network or proxy; compiling it needs the C++ workload and Python 3. | +| `[bundle-node]` reports an ABI or architecture mismatch | The Node.js you build with is not 22.x x64. Install 22.23.2. | +| `tar` cannot open the Node.js archive | The build ran in Git Bash. Use PowerShell. | +| Errors about paths that are too long | Clone to a shorter folder such as `C:\w\waggle-os`. | +| Files in `target` are locked during the build | Antivirus is scanning them. Run the build again, or exclude the folder. |