Building from Source

Building from Source

Toolchain

Tool	Why
Windows 10 or 11 (x64)	Homebase is Windows-only
Rust 1.85 or newer (stable, MSVC)	The app
Visual Studio Build Tools (MSVC, Windows SDK)	Linking and Windows APIs
CMake and Ninja	SDL3 builds from source
.NET 8 SDK	The WiX MSI installer (optional)
Python 3 with Pillow	Only to regenerate the logo, icons and sounds

Commands

cargo build --workspace          # debug build of everything
cargo run -p homebase            # run from source
cargo test --workspace           # tests
cargo xtask verify               # formatting check, Clippy with warnings denied, tests
cargo xtask dist                 # release exe, portable zip, sample packages and the MSI
cargo xtask install              # build and install this checkout for the current user
cargo xtask pack                 # package the example .hbpkg files
python scripts/gen_assets.py     # regenerate the logo, icons and UI sounds

cargo xtask install builds a release, packages the MSI with the workspace version, asks a running Homebase to quit (homebase --quit), installs over any existing copy and refreshes the icon cache when the logo changed.

Tests

cargo test --workspace runs unit tests for every crate plus controller_reaches_everything, which starts the real app offscreen on a fresh profile (its own temporary data folder, no downloads) and drives it with controller input only. It checks that every screen and sheet can be reached with the D-pad, opens with its real button and closes with B.

Variable	Effect
HOMEBASE_DATA_DIR	Use this folder for data instead of %LOCALAPPDATA%\Homebase
HOMEBASE_NO_NETWORK	No site icon or Steam artwork downloads

Outputs

File	From
target/release/homebase.exe	cargo build --release
dist/homebase-portable.zip	cargo xtask dist
installer/bin/x64/Release/Homebase-Setup.msi	cargo xtask dist / install
dist/*.hbpkg	cargo xtask pack

Screenshots

The screenshots in docs/screenshots are rendered offscreen from a real Homebase with the software renderer, without opening a window:

$env:HOMEBASE_SHOTS = "docs/screenshots"
cargo test -p homebase screenshots -- --ignored

It uses this PC's Homebase data, mutes sounds, and leaves out personal details (what's playing, the Steam account name).

Packages

.hbpkg files are zip archives with a package.toml manifest. Kinds:

Kind	Contents
theme	A JSON set of theme colors and radii
app_defs	App definitions: names, executables, store IDs, https URLs
input_profile	A set of bindings
code	A sandboxed WebAssembly extension; needs the wasm-runtime feature, off by default

Packages are validated before install: no path traversal, size limits (16 MiB per file, 32 MiB per package), required entries, a valid manifest and a compatible min_homebase. Examples are in packages/.

Publishing the wiki

The wiki's source lives in docs/wiki. To update the GitHub wiki, clone it next to the repo and sync:

git clone https://github.com/<owner>/Homebase.wiki.git ..\Homebase.wiki
powershell -File scripts\sync-wiki.ps1 -WikiPath ..\Homebase.wiki

The script copies the pages and screenshots and rewrites links for the wiki. Review the changes in the wiki clone, then commit and push them there.