Building from Source

Building from Source

This guide covers everything you need to set up a development environment and build the RoK Tracker Suite installer from source.

---

Prerequisites

Before you begin, make sure you have the following installed:

Tool	Version	Purpose	Download
Python	3.14+	Scanner backend (Nuitka-compiled sidecar)	python.org
uv	Latest	Fast Python package manager	docs.astral.sh/uv
Node.js	18+	Frontend build tooling	nodejs.org
pnpm	Latest	Node.js package manager	pnpm.io
Rust	Stable	Tauri desktop shell	rustup.rs
C++ Build Tools	Latest	Required by Nuitka and some Python packages	Visual Studio

Tip: You can install uv quickly with: curl -LsSf https://astral.sh/uv/install.sh | sh (or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" on Windows).

---

Setting Up for Development

1. Clone the Repository

git clone https://github.com/Nexor256/RoK-Tracker.git
cd RokTracker

2. Install Python Dependencies

We use uv as the Python package manager. It reads dependencies from pyproject.toml and creates a virtual environment automatically.

uv sync

This will:

• Create a .venv/ virtual environment (if it doesn't exist)
• Install all Python dependencies from the lockfile (uv.lock)
• Ensure exact, reproducible builds every time

3. Install Frontend Dependencies

cd gui_frontend
pnpm install
cd ..

4. Add Runtime Dependencies

Place ADB and Tesseract data in the deps/ folder (same as the Installation guide):

• Download ADB Platform Tools → extract into deps/platform-tools/
• Download Tesseract trained data (eng.traineddata at minimum) → place in deps/tessdata/

5. Run in Development Mode

npx --prefix gui_frontend tauri dev

This opens the app with hot-reload — changes to the Vue frontend update instantly without restarting. The Python sidecar runs from source (not compiled).

---

Building the Installer

To build the standalone installer (.exe) that end-users download:

Step 1: Bundle the Python Sidecar

This compiles the Python backend into a single standalone executable using Nuitka.

uv run scripts/bundle_sidecar.py

Note: The first Nuitka build takes 20–30 minutes because it compiles Python to C code. Subsequent builds use a cache and are much faster (~2–5 minutes).

The compiled sidecar is placed at src-tauri/binaries/scanner_sidecar-<target-triple>.exe.

Step 2: Build the Tauri Installer

npx --prefix gui_frontend tauri build

This will:

1. Build the Vue frontend for production
2. Compile the Rust backend
3. Bundle everything into an NSIS installer

The final installer is created at:

src-tauri/target/release/bundle/nsis/RoK-Tracker-Suite-setup.exe

---

Project Structure

Here's how the key parts of the codebase fit together:

RokTracker/
├── gui_frontend/              ← Vue 3 + shadcn-vue frontend
│   ├── src/
│   │   ├── components/        ← UI components
│   │   ├── pages/             ← App pages (scanners, settings)
│   │   └── stores/            ← Pinia state management
│   └── package.json
├── roktracker/                ← Python scanner engine
│   ├── kingdom/               ← Kingdom scanner logic
│   ├── alliance/              ← Alliance scanner logic
│   ├── honor/                 ← Honor scanner logic
│   └── utils/                 ← OCR, ADB, data processing utilities
├── src-tauri/                 ← Tauri v2 Rust backend
│   ├── src/
│   │   ├── commands.rs        ← IPC commands (frontend ↔ backend)
│   │   └── sidecar.rs         ← Python sidecar process management
│   └── tauri.conf.json        ← App configuration
├── scripts/
│   └── bundle_sidecar.py      ← Nuitka build script
├── scanner_sidecar.py         ← Python sidecar entry point
├── pyproject.toml             ← Python dependencies & tool config
├── uv.lock                    ← Locked dependency versions
└── config.json                ← Default app configuration

---

Architecture Overview

┌─────────────────────────────────────┐
│           Tauri v2 Shell            │
│  ┌───────────────────────────────┐  │
│  │   Vue 3 + shadcn-vue Frontend │  │
│  │   (HTML/CSS/JS in WebView)    │  │
│  └──────────────┬────────────────┘  │
│                 │ invoke / listen   │
│  ┌──────────────▼────────────────┐  │
│  │   Rust Backend (commands.rs)  │  │
│  │   Sidecar Manager (sidecar.rs)│  │
│  └──────────────┬────────────────┘  │
│                 │ stdin/stdout JSON │
│  ┌──────────────▼────────────────┐  │
│  │   Python Sidecar (Nuitka exe) │  │
│  │   scanner_sidecar.py          │  │
│  │   └── roktracker/ (scanners)  │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Component	Technology	Purpose
Desktop shell	Tauri v2 (Rust)	Native window, IPC, bundling
Frontend	Vue 3, shadcn-vue, Tailwind CSS	UI (pages, components, styling)
Backend bridge	Rust (commands.rs, sidecar.rs)	Routes commands to Python sidecar
Scanner engine	Python (Nuitka-compiled)	OCR, ADB, data processing
Auto-updater	Tauri Updater Plugin	Checks GitHub Releases for new versions

---

Common Development Tasks

Updating Python dependencies

# Add or change a dependency in pyproject.toml, then:
uv lock
uv sync

Updating frontend dependencies

cd gui_frontend
pnpm update

Regenerating Zod schemas from Python models

uv run schema_generator.py
cd gui_frontend && pnpm run generate:zod

---

CI/CD Pipeline

The project uses GitHub Actions for automated builds and releases:

• Test Build (test_bundle.yml) — triggered manually via workflow_dispatch, builds the full installer for validation
• Release (release.yml) — triggered by pushing a version tag (e.g., v1.2.0), builds the installer, generates latest.json for the auto-updater, and creates a GitHub Release

The version number in the installer is automatically injected from the Git tag — no manual version bumps needed anywhere in the codebase.