Building from Source

QB-TECH-001 Technical

QuantaBox is a Rust Cargo workspace plus a Tauri desktop app. This guide covers building the CLI, the core libraries, and the GUI, and packaging a release.

Prerequisites #

ToolPurpose
Rust (stable, 2021 edition)Building all crates. Install via rustup.
Node.js + npmBuilding the Svelte frontend for the GUI.
Tauri CLIBuilding the desktop app. cargo install tauri-cli --version "^1".
QEMURuntime engine (qemu-system-x86_64, qemu-img) -- needed to run VMs, not to build.
Platform webviewLinux: WebKitGTK and related -dev packages. Windows/macOS: provided by the OS.

Get the Source #

git clone https://github.com/dyber-pqc/quantabox.git
cd quantabox

Build the Workspace (CLI + Libraries) #

# Debug build of everything
cargo build --workspace

# Optimized release build
cargo build --workspace --release

The quantabox CLI binary lands in target/debug/ or target/release/.

Run the test suite:

cargo test --workspace

Build the Desktop App #

The GUI lives in gui/ (Svelte frontend) and gui/src-tauri/ (Tauri Rust backend).

cd gui
npm install            # first time only
npm run tauri dev      # run the app in development

For a production build, use the Tauri CLI rather than plain cargo build -- this compiles the frontend and embeds it into the binary:

# from gui/
cargo tauri build              # full build + platform bundles
cargo tauri build --bundles none   # just the executable, no installer bundles
Important -- the custom-protocol feature. Production Tauri builds must enable the custom-protocol feature so the app serves its embedded frontend through the tauri:// protocol instead of a dev server. The GUI crate declares: 
[features]
custom-protocol = ["tauri/custom-protocol"]
cargo tauri build enables this automatically. A plain cargo build of the GUI does not embed the frontend and will try to load http://localhost:<port> at runtime -- resulting in a blank "can't reach this page" window.

Frontend output directory

The Svelte build (adapter-static) emits to gui/build/, and the Tauri config's distDir points there. If you change the static adapter's output location, update distDir in gui/src-tauri/tauri.conf.json to match.

Packaging Installers #

QuantaBox ships platform installers built from the release binary:

  • Windows -- an installer is produced from target/release/QuantaBox.exe plus the app icon and license, bundling the QEMU engine optionally. See the installer/ directory.
  • Linux -- .deb, .rpm, and AppImage can be produced via cargo tauri build's bundlers or distro tooling.
  • macOS -- a .dmg via cargo tauri build.

Common Build Issues #

SymptomFix
GUI window shows "can't reach this page" after installBuild with cargo tauri build and ensure the custom-protocol feature exists (see above).
target directory locked on WindowsClose any running app/dev server holding the binary, then rebuild.
Frontend changes not reflectedRe-run npm run build (or cargo tauri build, which runs it for you).
Webview/link errors on LinuxInstall WebKitGTK and the platform -dev dependencies.

Cross-Platform Notes #

  • The codebase routes every subprocess spawn through a helper that suppresses console windows on Windows (CREATE_NO_WINDOW). Preserve this when adding new Command invocations -- see Components: the proc helper.
  • The GUI's main.rs uses #![cfg_attr(all(not(debug_assertions), target_os = "windows"), windows_subsystem = "windows")] so release builds run without a console window.

Next #

See Contributing for coding conventions and the pull-request process.

← Previous: Architecture Next: Components →