Files
waggle-os/docs/oss/build-windows.md
2026-10-26 00:43:43 +01:00

109 lines
4.4 KiB
Markdown

# 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. |