Skip to content

development.md

Latest commit

 

History

History
72 lines (48 loc) · 3.7 KB

development.md

File metadata and controls

72 lines (48 loc) · 3.7 KB
Raw

Development

Everything you need to hack on SearchBox locally and get a change merged.

Prerequisites

  • Rust (stable — CI tracks dtolnay/rust-toolchain@stable).
  • A C toolchain (the vendored zim crate builds zstd/lzma; MSVC Build Tools on Windows, build-essential on Debian/Ubuntu, plus pkg-config libssl-dev on Linux).
  • Optionally a Meilisearch binary for working on search features (below).

Run it

cargo run
# → http://127.0.0.1:8080  (first run walks you through account setup)

Debug builds are headless on every OS — you use the browser. The native WebView2 window only exists in Windows release builds.

What's live-editable while it runs:

You edited To see it
static/ (JS/CSS) refresh the browser
templates/ restart the app — files are read from disk in debug, but MiniJinja caches compiled templates at startup (src/templates.rs)
src/ cargo run again

Dev data lands in the current working directory (searchbox.db, vault/, meili_data/, log/…) — all gitignored. Point it elsewhere with SEARCHBOX_BASE_DIR=/some/dir cargo run; nuke the dir for a fresh first-run experience.

A Meilisearch for dev

The app looks for a meilisearch binary next to its own executable, then (on unix) in common prefixes, then the meilisearch_path setting — see src/services/meili_process.rs. Easiest dev setup: download a Meilisearch release (match the version pinned in wix/build.ps1) and set its path in Settings → Search Engine → Binary Path. Without it the app still boots — search is just inert.

Checks (run these before pushing)

CI (.github/workflows/ci.yml) runs on ubuntu for every push/PR:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
cargo audit          # security job; config in .cargo/audit.toml

Windows-specific ritual: the WebView window and its deps (wry/tao/rfd) are only compiled for Windows release, which CI never builds — so if you touch anything near src/main.rs's window code or the [target.'cfg(windows)'] sections of Cargo.toml, verify locally with:

cargo check --release

And keep wry 0.46 paired with tao 0.30 (both speak raw-window-handle 0.6).

Conventions that matter

  • Schema: schema.sql is applied idempotently at boot; there are no migrations. Changes must be IF NOT EXISTS-safe and backward compatible with existing databases.
  • Meilisearch documents: single documents index; source field distinguishes origins; file_type has no leading dot anywhere.
  • Security-sensitive areas (src/auth/, vault, services/secret.rs, the updater, CI audit): read SECURITY.md first — several behaviors there (vault re-lock, key sealing, sha256-verified updates) are deliberate hardening, not accidents.
  • Frontend: escape-before-innerHTML, authFetch for mutations, entrance animations use fill-mode backwards — see frontend.md.
  • User-visible changes need a CHANGELOG.md entry and, if the UI changed, updates to the landing-page demo replica and possibly the user manual.

Releasing (short version)

master is protected — changes land via PR. A release is: bump Cargo.toml, finalize the CHANGELOG entry, merge, then

git tag v0.x.y && git push --tags

.github/workflows/release.yml builds and attaches the x64 + ARM64 MSIs (with .sha256 sidecars for the in-app updater) and the Linux tarball; the winget pipeline picks the MSIs up from the published release. Full detail: BUILD.md.

← Back to the dev docs