Skip to content

Packaging

Jump to bottom
Bobby Comet edited this page Aug 1, 2026 · 1 revision

Packaging

Conky Studio is distributed primarily as a single AppImage. The goal is: download, mark executable, run, with sensible behaviour on both X11 and Wayland, and without requiring the user to fight Qt plugin paths or leave a broken desktop entry behind.

This page describes what the AppImage contains, what AppRun does on every launch, and how that interacts with display servers and compositors; for runtime deps (Conky, sensors, etc.), see Requirements. For which sessions support desktop HUD overlays, see Compatibility.

What you get

Artifact Role
Conky-Studio-x86_64.AppImage Self-contained app: Python, PyQt6, Studio code, bundled Qt plugins
GitHub Releases Versioned downloads; Studio’s update checker hits /releases/latest
Optional Griffin Updater External helper some users use to replace the AppImage in place

The AppImage does not bundle Conky. Themes always call the system conky binary. That keeps themes portable and avoids shipping a second, possibly mismatched Conky build.

Flat layout (PyInstaller 6+)

PyInstaller 6+ nests support files under _internal/ by default. Conky Studio’s build passes:

--contents-directory .

so libraries, Qt plugins, and data sit in a flat layout next to the executable. AppRun and internal path logic stay predictable; you do not need to guess whether plugins live under _internal/ or beside the binary.

AppRun: what happens on every launch

AppRun is the entry point inside the AppImage. On each start it:

1. Qt platform: Wayland first, X11 fallback

Condition QT_QPA_PLATFORM
$WAYLAND_DISPLAY is set wayland;xcb — Qt tries Wayland, then falls back to XCB silently if needed
Plain X11 session xcb
User already set QT_QPA_PLATFORM Respected — AppRun does not override

So:

  • On Sway / Hyprland / Plasma Wayland / GNOME Wayland, the Studio UI prefers the Wayland QPA plugin.
  • If Wayland QPA fails (missing plugin, broken compositor integration), Qt can still come up on XWayland via xcb.
  • On classic X11, behaviour stays simple and stable.

This is about the authoring app window, not about whether Conky overlays work on that compositor. Overlay rules are separate (see Compatibility).

2. Bundled Qt plugins only

AppRun sets:

  • QT_PLUGIN_PATH
  • QT_QPA_PLATFORM_PLUGIN_PATH

to the AppImage’s own plugin directories. That avoids loading distro system Qt plugins that conflict with the bundled PyQt6 (a common cause of blank windows or crashes on rolling distros).

Build time may warn if libqwayland.so was not bundled; without it, the Wayland branch of QT_QPA_PLATFORM is effectively a no-op and Qt will rely on the XCB fallback.

3. Self-installing desktop entry + icon (no appimaged)

On every launch, AppRun:

  1. Checks whether ~/.local/share/applications/conky-studio.desktop already points at the current AppImage.
  2. If not, installs a corrected .desktop file and the 256×256 icon into the usual XDG locations.
  3. Refreshes desktop/icon caches when the tools are available (update-desktop-database, icon cache helpers).

The process is idempotent and non-fatal: any failure still lets the application open normally.

4. Stable install path (not a transient $APPIMAGE)

Writing Exec="$APPIMAGE" is fragile: the path changes when you download a new file to ~/Downloads or move the binary.

Instead, on first run (and when a newer AppImage is launched):

  1. Copy the AppImage to ~/Applications/conky-studio.AppImage.
  2. Point the desktop entry’s Exec= at that permanent location.

Details:

  • Re-copies when a newer AppImage is run (shipping an update can be “download → run once”).
  • Detects when it is already running from the installed copy (readlink -f comparison) and skips the copy to avoid loops.
  • To repair a broken .desktop that points at a dead path: delete it once
    rm ~/.local/share/applications/conky-studio.desktop
    or launch the AppImage directly; install logic recreates a correct entry.

How this maps to sessions and compositors

Packaging and HUD overlay support are related but not the same thing.

Layer What packaging guarantees What it does not guarantee
Studio window (Qt) Wayland QPA tried when WAYLAND_DISPLAY is set; XCB fallback; isolated plugins Pixel-perfect integration with every compositor’s client-side decorations
Live Preview / built themes (Conky) Same files you would run by hand; window type from session detection Overlays on compositors without layer-shell (e.g. GNOME Mutter Wayland)
Desktop entry Stable path under ~/Applications/, icon, menu entry That every DE shows the icon immediately without a cache refresh

X11

  • Qt uses xcb.
  • Conky HUDs use the classic own-window path; broadest overlay compatibility.
  • Packaging side is uncontroversial; most “it just works” reports are X11.

Wayland (Sway, Hyprland, Plasma, labwc, river, …)

  • Studio UI: wayland;xcb so the editor can run natively when the plugin is present.
  • Themes: need a Wayland-enabled Conky and a layer-shell compositor for desktop overlays.
  • Packaging does not ship Conky; users still install Conky from the distro (see Requirements).

GNOME Wayland

  • Studio may still open (Qt Wayland or XWayland fallback).
  • Conky desktop overlays remain unsupported (Mutter / no wlr-layer-shell). Studio’s Hardware & Session report severity block for overlays; that is intentional, not a packaging miss.

Mixed/odd environments

  • SSH or TTY with no display: no graphical session — Studio needs DISPLAY or WAYLAND_DISPLAY.
  • Nested or experimental compositors: UI may work via fallback; always check Tools → Hardware & Session before assuming Live Preview will show a HUD.

Update model

Mechanism Behaviour
Silent startup check Background thread; GitHub Releases API (/releases/latest); only prompts if a newer version exists
Help → Check for Updates… Same check; always reports up-to-date, update found, or network error
Dialog Current vs latest version; Open GitHub Release; note about Griffin Updater if installed

Checks the API rather than a fixed versioned download URL, so “latest” tracks whatever release is published. Network failure never blocks opening the main window.

Build-time notes (for packagers/contributors)

  • Prefer keeping --contents-directory . with PyInstaller 6+ so AppRun paths stay flat.
  • Bundle Wayland and XCB Qt platform plugins; warn if Wayland is missing.
  • Do not assume system QT_PLUGIN_PATH; AppRun must pin bundled paths.
  • Desktop file should use the stable ~/Applications/conky-studio.AppImage path after first-run install, not a Downloads path.
  • AppImage is x86_64 in the current release line; architecture support is whatever the CI/release pipeline ships.

User checklist

  1. Download the AppImage from GitHub Releases.
  2. chmod +x Conky-Studio-*.AppImage and run it (or open from the file manager).
  3. First launch may copy itself to ~/Applications/ and register a menu entry.
  4. Install system Conky (and optional sensors/playerctl/curl) per Requirements.
  5. Tools → Hardware & Session — confirm display server, Conky Wayland flag, overlay likelihood.
  6. For updates: Help → Check for Updates, or download a new AppImage and run it once so the stable copy refreshes.

Summary

  • One AppImage holds the Studio; system Conky runs themes.
  • AppRun sets Qt to wayland;xcb or xcb, pins plugin paths, and self-installs a stable desktop entry under ~/Applications/.
  • That makes the editor workable across many X11 and Wayland desktops.
  • HUD overlays still follow Conky + compositor rules (X11 best; layer-shell Wayland good; GNOME Mutter Wayland no) — packaging enables the app; it does not rewrite compositor protocols.

See Compatibility and Requirements.

Clone this wiki locally