Building from Source - Riqqqque/Homebase GitHub Wiki
| 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 |
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 soundscargo 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.
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 |
| 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 |
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 -- --ignoredIt uses this PC's Homebase data, mutes sounds, and leaves out personal details (what's playing, the Steam account name).
.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/.
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.wikiThe 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.