Installing Nimble Viewer on Linux
==================================

Two formats are provided. Pick whichever fits your distribution.

Option A — AppImage (works on most Linux distributions)
-------------------------------------------------------

The AppImage is a single self-contained executable. No root required.

1. Make the AppImage executable:

       chmod +x NimbleViewer-<version>.AppImage

2. Run it:

       ./NimbleViewer-<version>.AppImage

If you get a "fuse: failed to open /dev/fuse" or "libfuse.so.2 not found"
error (common on Ubuntu 22.04+ and Fedora 36+), use the included
launcher script instead, which runs without FUSE:

       chmod +x NimbleViewer.sh
       ./NimbleViewer.sh

For full desktop integration (launcher menu entry and "Open With"
file associations), install AppImageLauncher:

    https://github.com/TheAssassin/AppImageLauncher

It moves AppImages into a managed directory and wires them into your
desktop environment automatically.

Option B — Debian package (.deb) for Debian/Ubuntu/Mint
-------------------------------------------------------

1. Install with dpkg:

       sudo dpkg -i nimble-viewer_<version>_<arch>.deb

2. If dpkg reports missing dependencies, resolve them with:

       sudo apt-get install -f

3. Launch "Nimble Viewer" from your application menu, or run:

       nimble-viewer

The .deb installs to /opt/nimble-viewer/ and registers itself with
the desktop environment automatically (launcher entry, file
associations, MIME types).

Uninstalling
------------

AppImage: delete the .AppImage file. If you used AppImageLauncher,
remove the entry from its management UI.

Debian package:

    sudo apt-get remove nimble-viewer

System requirements
-------------------

  - 64-bit x86_64 Linux
  - glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+, Fedora 36+,
    RHEL 9+, openSUSE Leap 15.5+, Arch Linux). Older distributions
    such as Ubuntu 20.04 are not supported.
  - X11 or Wayland display server. The app forces the X11 backend
    by default for compatibility; it works under Wayland through
    XWayland.

Troubleshooting
---------------

"./NimbleViewer-<version>.AppImage: cannot execute: required file not
found" or "dlopen: error loading libfuse.so.2".

  Your distribution does not ship libfuse2. Use the bundled launcher:

      chmod +x NimbleViewer.sh
      ./NimbleViewer.sh

  Or install libfuse2:

      sudo apt-get install libfuse2          # Debian/Ubuntu
      sudo dnf install fuse                  # Fedora/RHEL

"error while loading shared libraries: libxcb-cursor.so.0: cannot open
shared object file".

  Some minimal installations are missing Qt's runtime dependencies.
  Install them:

      sudo apt-get install libxcb-cursor0 libxkbcommon-x11-0 libxcb-icccm4 \
                           libxcb-image0 libxcb-keysyms1 libxcb-randr0 \
                           libxcb-render-util0 libxcb-shape0 libxcb-sync1 \
                           libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1

"GLIBC_2.35 not found" or similar glibc version mismatch.

  Your Linux distribution is too old. Upgrade to a release based on
  glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+, Fedora 36+, etc.).

App launches with a black or blank window on Wayland.

  Try forcing X11 backend explicitly:

      QT_QPA_PLATFORM=xcb ./NimbleViewer-<version>.AppImage