zgui

Shipping

A release checklist — the release build, versions, the application identity, the graphics device, and the steps for Linux, macOS and Windows.

A zgui application is one ordinary Rust binary. Work through this page in order before a release: the first sections apply to every platform, then each platform has its own steps, and the last section is a final test pass.

Build for release

cargo build --release

Use this release profile:

Cargo.toml
[profile.release]
lto = "thin"
codegen-units = 1
debug = "line-tables-only"
  • lto and codegen-units = 1 let the optimiser work across crates. Most of a frame's work (styling, layout, text, paint) happens inside zgui's crates, so cross-crate optimisation matters.
  • debug = "line-tables-only" keeps readable backtraces without changing the generated code.

Keep using debug builds while you develop. They enable checks that a release build compiles out, and that turn silent bugs into clear panics:

  • creating reactive state with no current owner (a leak in release);
  • running reactive work off the UI thread;
  • calling set_timeout outside a window's scope (in release, the timer silently never fires).

To keep debug builds responsive, optimise dependencies but not your own crate:

Cargo.toml
[profile.dev.package."*"]
opt-level = 2

Pin versions

  • zgui is on crates.io as 0.1.x. All zgui crates are released together under one version, so depend on the same version of zgui, zgui-ui, and the other zgui crates you use.
  • Published crates build on stable Rust 1.90 or later (rust-version = "1.90"). You do not need nightly.
  • zgui follows semver for 0.x releases: a new minor version (0.2) may break the API; patch releases do not.
  • zgui::Error and other growing enums are #[non_exhaustive]. A match on them needs a _ arm.
  • Commit Cargo.lock. It is part of what makes an application build reproducible.

Set the application identity

with_title names the window. with_application_id names the program, so the desktop can match it to an icon, a launcher entry, and window rules. It is not set for you.

fn main() -> Result<(), zgui::Error> {
    app()
        .with_application_id("dev.example.Counter")
        .with_title("Counter")
        .run(|| view! { Counter() })
}
PlatformWhere the identity comes from
Linux, Waylandthe toplevel app_id, set from with_application_id
Linux, X11WM_CLASS, set from with_application_id
macOSthe bundle identifier in Info.plist
Windowsthe executable and your installer; zgui sets no Application User Model ID

Use a reverse-domain name. The per-platform sections below show where else it must appear.

Report a missing graphics device

zgui needs a working GPU device. If every adapter fails, run returns zgui::Error::GpuUnavailable instead of opening a window that never paints. Print the error, so a user without a working driver sees why the application did not start:

fn main() {
    if let Err(error) = app().with_title("Counter").run(|| view! { Counter() }) {
        eprintln!("{error}");
        std::process::exit(1);
    }
}

The message reads no usable graphics device: N adapter(s) were tried and rejected, followed by each adapter tried and why it failed. Run with ZGUI_BACKENDS=none to see exactly what such a user sees. The graphics device describes how a device is chosen.

Linux

Install a desktop entry and icon

Ship a .desktop file with the same base name as the application identifier:

/usr/share/applications/dev.example.Counter.desktop
[Desktop Entry]
Type=Application
Version=1.5
Name=Counter
Comment=Counts things
Exec=/usr/bin/counter
Icon=dev.example.Counter
Terminal=false
Categories=Utility;

These three must match: the file name without .desktop, the with_application_id value, and the Icon= name. Without them, the application has no icon of its own, cannot be targeted by window rules, and does not group in a task bar.

Install the icon as /usr/share/icons/hicolor/scalable/apps/dev.example.Counter.svg, or under a sized directory such as 256x256/apps for a PNG. A per-user install puts both under ~/.local/share/.

If the file name cannot match the identifier, add StartupWMClass=dev.example.Counter. X11 uses it to match a window to its entry; Wayland ignores it.

To check the identity, run xprop WM_CLASS on X11, or look at your compositor's window list on Wayland.

Check run-time libraries

List what your binary links:

ldd target/release/my-app
LibraryHow it is loadedNeeded for
libfontconfig.so.1 (plus FreeType, expat, zlib, libpng)linkedfinding installed fonts
libxkbcommon.so.0linkedkeyboard layouts
libwayland-client.so.0opened at run timeWayland sessions
libX11, libxcb, libXcursor, libXi, libXrandr, libxkbcommon-x11opened at run timeX11 sessions
libvulkan.so.1, or libEGL.so.1 and libGL.so.1opened at run timethe graphics device

A missing linked library stops the process from starting. A missing run-time library fails only when the window or device is opened. Install what ldd lists on a clean machine and run the binary there, not only on the machine you built on.

Test each display backend

  • Both backends under Wayland. Run normally (the native Wayland backend), then with ZGUI_PLATFORM=winit (the portable backend). Then run in an X11 session. These are different code paths.
  • Fractional scaling, such as 125% or 150%. A scale change reshapes all text and rasterises all glyphs again, so text problems show up here.
  • Light and dark. Switch the desktop's colour scheme while the application runs.
  • A screen reader. The accessibility tree is published over AT-SPI only while an assistive technology is listening. Start Orca to check it. See Accessibility.

macOS

Build an app bundle

Package the binary in an .app bundle with an Info.plist. The bundle identifier is the application's identity, and the bundle supplies the dock icon; with_application_id and with_icon have no effect on macOS.

Add an application menu

macOS shows one menu bar for the whole application. Build it with with_menu, and handle picks with on_menu from zgui::desktop:

use zgui::desktop::{AppMenu, MenuAction, MenuRole, Shortcut, Submenu, on_menu};
use zgui::prelude::*;

fn menu() -> AppMenu {
    let quit = Shortcut::new(Key::character("q"), Modifiers::PRIMARY);
    AppMenu::new()
        .with(
            Submenu::new("Counter")
                .with(MenuRole::About)
                .separator()
                .with(MenuRole::Hide)
                .with(MenuRole::HideOthers)
                .with(MenuRole::ShowAll)
                .separator()
                .with(MenuAction::new("quit", "Quit Counter").with_shortcut(quit)),
        )
        .with(
            Submenu::new("Edit")
                .with(MenuRole::Undo)
                .with(MenuRole::Redo)
                .separator()
                .with(MenuRole::Cut)
                .with(MenuRole::Copy)
                .with(MenuRole::Paste)
                .with(MenuRole::SelectAll),
        )
        .with(
            Submenu::new("Window")
                .with(MenuRole::Minimize)
                .with(MenuRole::Zoom),
        )
}

fn main() -> Result<(), zgui::Error> {
    app()
        .with_title("Counter")
        .with_menu(menu)
        .with_context(|| {
            let windows = use_windows();
            // Keep the guard for the whole run; dropping it removes the callback.
            provide_local_context(on_menu(move |id| {
                if id.as_str() == "quit" {
                    windows.quit();
                }
            }));
        })
        .run(|| view! { Counter() })
}
  • The first submenu is the application menu; macOS titles it with the application's name.
  • MenuRole entries are standard items. macOS handles the desktop roles (About, Hide, Minimize, Zoom, …). The editing roles (Undo, Cut, Copy, Paste, …) are replayed as their keyboard shortcut in the focused window, so text fields and custom editors handle them as they handle keys.
  • MenuAction entries are yours. Their ids reach on_menu. Use with_enabled and with_checked for state.
  • A menu shortcut is offered to the focused window first. The menu action runs only if nothing in the document handled the key.
  • The with_menu closure re-runs when a signal it read changes, so the menu can follow state.
  • Modifiers::PRIMARY is Command on macOS and Control elsewhere. Use it for cross-platform shortcuts.

Other platforms have no application menu and ignore it.

Handle reopen and exit

HookRuns when
on_reopenthe user clicks the dock icon. Show a hidden window here.
on_exitthe application exits for any reason: last window closed, quit(), or the desktop's Quit. Finish work before returning.
on_menuthe user picks a menu action

Each returns an AppHookGuard. The callback stays registered until the guard is dropped.

Many macOS applications keep running with no windows open. Use with_exit_policy(ExitPolicy::Explicit) for that, and call use_windows().quit() to exit.

Place the title-bar buttons

A window with Decorations::NoTitleBar draws its own top bar, and macOS still draws its window buttons over the content. with_title_buttons(TitleButtons::new(left, band)) places them: left pixels from the left edge, centred vertically in a band band pixels tall. Draw your own bar in the same band. See Windows for client-side decorations.

Windows

  • Add #![windows_subsystem = "windows"] to main.rs so a release build does not open a console window next to yours.
  • with_icon sets the window icon. The executable's own icon comes from your build or installer.
  • zgui uses Direct3D 12 and falls back to OpenGL.

Final checks

Run the release binary on a clean machine for each platform you support, not through cargo run.

Test at 100% and 150% scale, in light and dark mode, on every backend you support.

Run with ZGUI_BACKENDS=none and read what your main prints.

Run your headless tests in release (cargo test --release) so they exercise the same code as the shipped binary. See Testing.

The graphics device

zgui opens one GPU device through wgpu, shared by all windows.

PlatformBackends, in order
macOSMetal
WindowsDirect3D 12, then OpenGL
Linux and othersVulkan, then OpenGL

OpenGL is tried only when no native backend produced a working device. Within a backend, adapters are sorted and tried in turn:

  1. the device named by ZGUI_DEVICE_ID, if set;
  2. discrete, then integrated, then virtual, then software.
VariableValueEffect
ZGUI_BACKENDSvulkan, metal, dx12, gl, all, none; comma-separatedlimits which backends are tried
ZGUI_DEVICE_IDdecimal or 0x hex PCI device ida preference, not a filter

An unrecognised value counts as nothing, so a typo behaves like none instead of silently using every backend. zgui ignores wgpu's own WGPU_BACKEND variable.

Software rendering

Software adapters, such as Mesa's lavapipe and llvmpipe, are valid candidates; they sort last. Vector graphics normally use a compute-shader rasteriser. On a device without compute shaders, zgui switches to a simpler rasteriser: icons and drawings still appear, but edges use multisampled coverage, gradients in vector content are drawn flat, and every path composites source-over.

Pipeline cache

The first launch on a machine spends most of its startup time opening the device and compiling GPU pipelines. zgui keeps the driver's compiled pipelines between runs:

$XDG_CACHE_HOME/zgui/pipelines/<adapter key>
~/.cache/zgui/pipelines/<adapter key>      # when XDG_CACHE_HOME is unset

Set ZGUI_CACHE_DIR to use another directory. If the cache cannot be written, zgui logs it and continues. Delete the cache before timing a cold start. See Measurements for startup numbers.

Next

On this page