yse 0.1.0

Write reactive Qt desktop applications in Rust
Documentation

Yse

Rust-first framework for building serious, cross-platform Qt 6 Widgets applications without QML. Uses CXX-Qt as the interoperability backend and borrows its reactive programming model from Airstream and Laminar.

Yse is for data-rich native desktop applications that want Qt's mature widgets and Linux integration without writing QML or manually managing signal connection lifetimes.

Pre-release: the API is still changing and the crates are not published. Use a local checkout while the clean-machine and packaging paths are hardened.

Five-minute local start

Install the native dependencies:

# Fedora
sudo dnf install qt6-qtbase-devel gcc-c++ cmake ninja-build pkgconf-pkg-config

# Ubuntu
sudo apt install qt6-base-dev g++ cmake ninja-build pkg-config

Create and run an application against this checkout:

cargo install --path crates/gansi
gansi doctor
cd /tmp
gansi create --local /path/to/yse hello-yse
cd hello-yse
gansi run

The generated application owns reactive Rust state, derives its label text, and releases widget bindings with the Qt object tree. Its minimal build.rs retains CXX-Qt dependency initializers; no application-owned C++ or QML is generated.

Supported environments

Environment Status
Fedora, Qt 6, GCC, Wayland/offscreen Primary development environment
Ubuntu, Qt 6, GCC Supported; clean-machine validation in progress
KDE Plasma and GNOME Intended Tier 1 desktops; full UX matrix in progress
Windows Build helpers and task-manager backend available
macOS Experimental; does not block the first release

Run the full display-free Fedora acceptance path without sudo:

CCACHE_DISABLE=1 just release-check

This does not publish or upload anything. It runs the workspace, MSRV, dependency-license, standalone crate-package, generated-project, example, and Valgrind gates. The Linux smoke gate builds and executes the default release bundle; use YSE_SMOKE_BUNDLE_PROFILE=debug just linux-smoke for quicker packaging work. When a live Wayland session is available, just examples-wayland-smoke runs the same eight application flows against the native display plugin.

See docs/validation.md for the exact verified environment and the platform scenarios that remain unverified.

See docs/roadmap-status.md for a requirement-by-requirement mapping from the Phase 0–4 plan to implemented and verified evidence.

See agent_docs/PLAN.md for the full roadmap.

Architecture notes are in docs/architecture.md and the release process in RELEASE.md. Qt and CXX-Qt have separate distribution obligations summarized in docs/licensing.md.

Current state

The implementation described by Phase 0 (CXX-Qt feasibility spike) through Phase 4 (gansi) is present. Fedora-local functional and packaging gates pass, but the roadmap's clean-host and multi-platform exit criteria are not yet all verified; see docs/validation.md. The yse facade re-exports the public API of both layers, so applications can use yse::* for the whole stack.

yse-model is a pure-Rust reactive runtime (no Qt, no unsafe) with transactional, glitch-free propagation, mandatory subscription ownership, the initial operator set, and a cancellable async task API (spawn_task) whose results are delivered onto the graph's thread through a Scheduler (see the QueueScheduler for deterministic tests). It also provides ListModel<T>, an incremental list with a current snapshot and a stream of structural changes (Insert/Remove/ Update/Reset), plus in-place sort_by/retain that emit incremental changes, and an UndoStack with a Command trait whose can_undo/can_redo state is reactive. It also ships Diagnostics (a stream of transactional graph events: nodes processed, observers fired, deferred writes, cycle rejections — useful for explaining why a widget changed) and a leveled Logger with an observable record stream. Run its tests with:

cargo test -p yse-model

yse-ui binds yse-model to a retained Qt Widgets tree through a small C++ shim: window, row/column layouts, label, button, line edit, checkbox, combo box, spin box, slider, progress bar, date/time edits, and grid layouts (with generic add for nesting), plus actions, menus, menu bars, and toolbars with shortcuts. It has signal-to-property bindings, two-way line-edit bindings, and per-component owners released automatically when the Qt object is destroyed. A QtGuiScheduler runs yse_model::spawn_task results on the Qt event loop, and yse_model's time operators (debounce, throttle, delay) are driven by a QtTimer in applications and a ManualTimer in tests. StringListModel drives a QListView through a C++ QAbstractListModel adapter, applying changes incrementally with beginInsertRows/beginRemoveRows so the view never resets for ordinary edits; ListView::selection_changed() exposes QItemSelectionModel changes as a stream of row indices. The settings demo wires Edit-menu Undo/Redo actions to an UndoStack via bind_enabled. StringTableModel does the same for a multi-column QTableView (QAbstractTableModel with headers, incremental row insert/remove/update). Standard dialogs are available as reactive wrappers: MessageBox (Ok/OkCancel/YesNo, result stream) and FileDialog (open-file, optional path result), both non-modal and headless-testable. Settings provides QSettings-backed key/value persistence with string values.

For large-table performance, a rough benchmark is included:

cargo run -p yse-model --release --example bench_large_table

On this machine a 100k-row load takes ~11 ms, 10k per-row incremental updates ~6 ms, and an in-place sort ~9 ms — all without rebuilding the widget tree.

The Phase 3 demonstration, data_browser, assembles the stack: it asynchronously loads records (with cancellation and error states), filters and sorts an incremental table, edits rows through a form with undo/redo, persists settings, and exposes menu shortcuts. Run it headless with:

QT_QPA_PLATFORM=offscreen YSE_SMOKE=1 cargo run -p yse-ui --example data_browser

It prints status, visible row count, active filter, and the first visible row after driving the whole flow.

Developer toolchain (gansi)

gansi is the Phase 4 developer CLI. Install it with:

cargo install --path crates/gansi

Then:

gansi create hello        # inside this checkout, auto-detect the local Yse facade
gansi create --local /path/to/yse hello-facade  # elsewhere, select the checkout explicitly
cd hello
gansi run                 # build and run
gansi test                # run tests
gansi analyze             # Clippy, all targets, warnings denied
gansi format --check      # verify rustfmt output
gansi upgrade -- --offline # refresh Cargo.lock without network access
gansi add serde -- --features derive # add a Cargo dependency
gansi build               # release build + platform bundle (windeployqt/macdeployqt when present)

Linux bundles include a launcher, application binary, required Qt libraries, selected desktop plugins, a Qt runtime inventory, and discoverable Qt license texts. Generated freedesktop and AppStream metadata plus a scalable icon are included under share/ for package integration. GLIBC_REQUIREMENTS.tsv records the newest glibc symbol required by each bundled ELF object. Bundles intentionally keep glibc, graphics drivers, and non-Qt system libraries as target-system dependencies, listing their resolved build-host paths in SYSTEM_RUNTIME.tsv. A .tar.gz artifact preserves the complete relocatable directory for transfer and testing, with a SHA-256 digest in dist/SHA256SUMS.

Generated projects pin the Qt version, compiler family, and target architecture detected at creation in gansi.toml; run, test, and build reject mismatches before invoking Cargo. They also include a RELEASE.md guide that lists what stays application-specific (code signing, notarization, store submissions, native dependencies). Qt SDK archives downloaded by gansi setup are verified against per-archive checksum sidecars before extraction. SHA-256 is preferred, with SHA-1 fallback for Qt repository layouts that do not publish SHA-256 sidecars. The --local variant depends on the yse facade crate from your checkout, so generated apps exercise the full framework without a C++ shim. Until the crates are published, gansi create refuses registry resolution when it cannot discover a checkout. Failed dependency setup is staged separately and does not leave a partial project directory behind. Run its lifecycle tests and the headless settings-form demo with:

cargo test -p yse-ui
QT_QPA_PLATFORM=offscreen YSE_SMOKE=1 cargo run -p yse-ui --example settings

The settings demo drives the form end-to-end in smoke mode: it types a name through the two-way binding, clicks submit (enabled by derived state), loads state from a background task delivered on the GUI thread, and triggers a File menu action, printing the resulting greeting, status, and load state before quitting.

The controls demo shows the value widgets in a declarative tree: a combo box, spin box, slider, and progress bar wired together with signal bindings and value-change handlers. Run it headless with QT_QPA_PLATFORM=offscreen YSE_SMOKE=1 cargo run -p yse-ui --example controls. FFI safety invariants — pointer lifetimes, the destroyed hook, panic containment at the C++ boundary, and the widget-extension pattern — are documented in docs/safety.md.

yse-taskmgr is a cross-platform system task manager (Windows / Linux) built entirely in the Laminar style: all state lives in Vars, the UI binds to derived signals (bind_rows, bind_series, bind_visible, ...), and event handlers only mutate state. System data is collected by platform-specific backends selected with cfg: /proc and /sys on Linux, windows-sys on Windows. It follows the system color scheme (light/dark), shows real per-process icons (shell icons on Windows, PATH lookups on Linux), and is styled with a modern Fusion + stylesheet look. Run it headless with QT_QPA_PLATFORM=offscreen YSE_SMOKE=1 cargo run -p yse-taskmgr (or just windows-run yse-taskmgr on the Windows host).

Development environment

  • Rust 1.89 or newer (edition 2024)
  • C++17 compiler and CMake
  • Qt 6 with the Widgets module: sudo apt install -y qt6-base-dev ninja-build libgl1-mesa-dev

Build and run

just --list                  # list development shortcuts
just check                   # format check, lint, tests, and docs
cargo build

Install just to use the shortcuts; the underlying Cargo commands remain usable directly.

CI

Workflows are intentionally omitted to conserve GitHub Actions quota. The workspace is validated locally with:

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --check