109 lines
4.4 KiB
Markdown
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. |
|