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

4.4 KiB

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.
  • Node.js 22, 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 through rustup, stable 1.94 or newer, with the default host x86_64-pc-windows-msvc.
  • Visual Studio 2022 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:

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:

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:

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:

git -C C:\w\waggle-os pull C:\path\to\waggle-oss.bundle oss/community-edition

3. Build

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.