docs(oss): how to build the Windows desktop installer
This commit is contained in:
@@ -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`.
|
||||
|
||||
108
docs/oss/build-windows.md
Normal file
108
docs/oss/build-windows.md
Normal file
@@ -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. |
|
||||
Reference in New Issue
Block a user