installation guide
This commit is contained in:
160
INSTALLATION.md
Normal file
160
INSTALLATION.md
Normal file
@@ -0,0 +1,160 @@
|
|||||||
|
# Installation & Run
|
||||||
|
|
||||||
|
Tauri 2 desktop app. The frontend is React 19 + Vite + TypeScript; the backend is Rust + SQLite via sqlx.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Prerequisites
|
||||||
|
|
||||||
|
### Common (all platforms)
|
||||||
|
- **Node.js ≥ 18** and **npm** (or pnpm / yarn — the lockfile is `package-lock.json`).
|
||||||
|
- **Rust** stable, installed via [rustup](https://rustup.rs/):
|
||||||
|
```bash
|
||||||
|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||||
|
source "$HOME/.cargo/env"
|
||||||
|
```
|
||||||
|
- **Tauri CLI** (project-local; no global install needed — `npm install` pulls `@tauri-apps/cli`).
|
||||||
|
|
||||||
|
### Linux (Debian / Ubuntu / Pop!_OS)
|
||||||
|
```bash
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install -y \
|
||||||
|
build-essential curl wget file \
|
||||||
|
libwebkit2gtk-4.1-dev \
|
||||||
|
libssl-dev \
|
||||||
|
libayatana-appindicator3-dev \
|
||||||
|
librsvg2-dev \
|
||||||
|
libsoup-3.0-dev \
|
||||||
|
pkg-config
|
||||||
|
```
|
||||||
|
On Ubuntu 22.04 / 24.04 the `4.1` WebKitGTK packages are correct for Tauri 2. If `apt` complains, also try `libjavascriptcoregtk-4.1-dev`.
|
||||||
|
|
||||||
|
### Linux (Fedora / RHEL)
|
||||||
|
```bash
|
||||||
|
sudo dnf install -y \
|
||||||
|
webkit2gtk4.1-devel openssl-devel curl wget file \
|
||||||
|
libappindicator-gtk3-devel librsvg2-devel \
|
||||||
|
libsoup3-devel @development-tools
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linux (Arch)
|
||||||
|
```bash
|
||||||
|
sudo pacman -S --needed \
|
||||||
|
webkit2gtk-4.1 base-devel curl wget file \
|
||||||
|
openssl appmenu-gtk-module libayatana-appindicator \
|
||||||
|
librsvg libsoup3
|
||||||
|
```
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
- **Xcode Command Line Tools**:
|
||||||
|
```bash
|
||||||
|
xcode-select --install
|
||||||
|
```
|
||||||
|
- That's it — Apple ships everything else (WebKit, Core Foundation, etc.).
|
||||||
|
|
||||||
|
### Windows
|
||||||
|
- **Microsoft C++ Build Tools** (Visual Studio Installer → "Desktop development with C++").
|
||||||
|
- **WebView2 runtime** — pre-installed on Windows 11 / recent Win10. Otherwise grab it from <https://developer.microsoft.com/microsoft-edge/webview2/>.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Clone and install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <your-repo-url> KML_Tool
|
||||||
|
cd KML_Tool/kml_map_tool
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
`npm install` also fetches `@tauri-apps/cli`. Rust dependencies build on the first `tauri dev` / `tauri build`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Run in development mode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run tauri dev
|
||||||
|
```
|
||||||
|
|
||||||
|
What this does:
|
||||||
|
- Starts Vite on `http://localhost:1420` (HMR for React).
|
||||||
|
- Compiles the Rust backend (`cargo build` — first run takes 5–10 min as sqlx, geo, kml, deck.gl deps cache).
|
||||||
|
- Launches the desktop window. Closing the window stops both processes.
|
||||||
|
|
||||||
|
**First-run database** — the app creates `markers.db` inside the OS app-data directory:
|
||||||
|
- Linux: `~/.local/share/com.kml_map_tool.app/markers.db` (or similar — varies by distro / Tauri identifier).
|
||||||
|
- macOS: `~/Library/Application Support/com.kml_map_tool.app/markers.db`
|
||||||
|
- Windows: `%APPDATA%\com.kml_map_tool.app\markers.db`
|
||||||
|
|
||||||
|
You'll see migrations run silently in the logs. To wipe the DB and start over, use **Reset DB** in the Data section of the app, or delete the file.
|
||||||
|
|
||||||
|
### Useful scripts
|
||||||
|
```bash
|
||||||
|
npm run dev # frontend only (Vite, no Tauri window) — for browser-only UI testing
|
||||||
|
npm run build # type-check + production frontend build (output: dist/)
|
||||||
|
npm run preview # preview the production frontend (no Tauri)
|
||||||
|
npm run tauri dev # full Tauri dev (frontend + Rust backend + desktop window)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rust-only compile check
|
||||||
|
From `kml_map_tool/src-tauri`:
|
||||||
|
```bash
|
||||||
|
cargo check # fast type-check
|
||||||
|
cargo build # full debug build
|
||||||
|
```
|
||||||
|
|
||||||
|
### TypeScript check
|
||||||
|
From `kml_map_tool`:
|
||||||
|
```bash
|
||||||
|
npx tsc --noEmit
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Build a production binary
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run tauri build
|
||||||
|
```
|
||||||
|
|
||||||
|
Outputs to `src-tauri/target/release/bundle/`:
|
||||||
|
|
||||||
|
- **Linux**: `*.AppImage`, `*.deb`, `*.rpm` (depending on installed packagers; `appimagetool` and `dpkg-deb` need to be on `$PATH` for the corresponding bundle to be produced).
|
||||||
|
- **macOS**: `*.app` and `*.dmg`. For a signed/notarised build, set `APPLE_*` env vars per the Tauri docs.
|
||||||
|
- **Windows**: `*.msi` (WiX) and `*.exe` (NSIS).
|
||||||
|
|
||||||
|
Single-arch native build only — cross-compiling Tauri apps (e.g. macOS → Linux) is not supported out of the box.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. First steps after launch
|
||||||
|
|
||||||
|
1. **Login screen** — create a user (any username + display name) and click Login. The username is recorded on every audit-log entry.
|
||||||
|
2. **Import…** → pick `Fixed assets (JSON)` and point at one of the sample files in the repo (e.g. `Double_Arm_Street_Light_mcw.json`).
|
||||||
|
3. The map auto-centers on the first imported asset; pan / zoom to explore.
|
||||||
|
4. See [README.md](./README.md) for the full feature tour.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Troubleshooting
|
||||||
|
|
||||||
|
### `error: linker 'cc' not found` (Linux)
|
||||||
|
`build-essential` (Debian/Ubuntu) or the equivalent dev tools group is missing. See prerequisites above.
|
||||||
|
|
||||||
|
### `failed to find webkit2gtk-4.1` (Linux)
|
||||||
|
The dev package is missing. On Ubuntu < 22.04 you may have only `4.0` available — Tauri 2 requires `4.1`. Upgrade or build WebKitGTK from source.
|
||||||
|
|
||||||
|
### `WebView2 runtime not found` (Windows)
|
||||||
|
Install from <https://developer.microsoft.com/microsoft-edge/webview2/>.
|
||||||
|
|
||||||
|
### Rust build is incredibly slow / OOM
|
||||||
|
The first build pulls hundreds of crates. Add `RUSTFLAGS="-C codegen-units=16"` and use a release machine with ≥ 8 GB RAM. Subsequent builds are incremental and fast.
|
||||||
|
|
||||||
|
### `g_object_unref: assertion 'G_IS_OBJECT (object)' failed` on shutdown (Linux)
|
||||||
|
Harmless — upstream WebKitGTK / libsoup ref-counting noise. Ignore.
|
||||||
|
|
||||||
|
### "Database is locked" errors during heavy bulk operations
|
||||||
|
sqlx pool size is 4. If you hit contention, increase `max_connections` in `src-tauri/src/db.rs` and rebuild.
|
||||||
|
|
||||||
|
### App window blank / white on Wayland
|
||||||
|
Try `WEBKIT_DISABLE_COMPOSITING_MODE=1 npm run tauri dev`.
|
||||||
Reference in New Issue
Block a user