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
|
- 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
|
`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
|
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`
|
- 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
|
with `wildcard: false`), so assets from a later build return 404. Restart the sidecar after
|
||||||
`npm run build`.
|
`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