================================================================
 AppGrid universal package — installation guide
================================================================

This tarball installs AppGrid into your user prefix (~/.local/). No
root, no system package manager, nothing written under /usr. Works
on immutable distros (KDE Linux, Fedora Kinoite) and on any normal
distro where you prefer a user-local install.

----------------------------------------------------------------
 Requirements
----------------------------------------------------------------

  - Plasma 6.4 or newer
  - KDE Frameworks 6.x (SONAME 6 for KF6 libs)
  - Qt 6.6 or newer (SONAME 6 for Qt6 libs)
  - Python 3.11 or newer (uses stdlib `tomllib`)
  - The runtime libraries AppGrid links against:
        Qt 6:   libQt6Core libQt6Gui libQt6Quick libQt6Qml
                libQt6Network libQt6DBus
        KF6:    libKF6Package libKF6KIO* libKF6Service
                libKF6I18n libKF6CoreAddons libKF6WindowSystem
                libKF6Runner KirigamiPlatform
        Plasma: libPlasma libPlasmaActivities libPlasmaQuick
                (all at SONAME 7 — current Plasma 6.4+)
        Other:  libLayerShellQtInterface (SONAME 6)

If `plasmashell` is not on PATH, the installer refuses to
proceed. If any of the libraries above are missing or have an
older SONAME, install.sh detects it with `ldd` and prints the
exact install command for your distro before aborting.

----------------------------------------------------------------
 SONAME and distro compatibility
----------------------------------------------------------------

KDE bumped the Plasma library SONAME from 6 to 7 around Plasma
6.4. This tarball is built against SONAME 7, so it works on:

  Arch / Manjaro / EndeavourOS / CachyOS / Garuda      ✓
  KDE Linux                                            ✓
  Fedora 42 and newer                                  ✓
  Kinoite / Bazzite / Aurora (Fedora 42+ base)         ✓
  openSUSE Tumbleweed                                  ✓
  openSUSE Kalpa                                       ✓
  SteamOS (Steam Deck Desktop Mode)                    ✓
  Debian 13 / Ubuntu 24.10+ (if shipping Plasma 6.4+)  ✓
  Older Debian/Ubuntu with Plasma 6.1–6.3              ✗

Users on older Plasma should wait for their distro to update,
or install AppGrid via their native package (Arch PKGBUILD,
Fedora RPM, Debian DEB available on the GitHub release page).

----------------------------------------------------------------
 Install
----------------------------------------------------------------

  tar -xzf appgrid-universal-<version>-<arch>.tar.gz
  cd appgrid-universal-<version>-<arch>
  ./install.sh

The installer will:

  1. Detect your distro from /etc/os-release.
  2. Verify SHA256SUMS over the payload.
  3. Run `ldd` over the bundled .so files. If any library is
     unresolved, it prints the per-distro install command and
     exits without touching anything.
  4. Show a summary (file count, target prefix) and ask to
     confirm. Pass `-y` to skip the prompt.
  5. Copy files/ into ~/.local/.
  6. Drop a small plasma-workspace env script at
     ~/.config/plasma-workspace/env/appgrid-user-local.sh
     so Qt's plugin loader finds the .so under ~/.local/.
  7. Refresh KDE's service cache (kbuildsycoca6).
  8. Write a manifest at ~/.local/share/appgrid/MANIFEST.

After the FIRST install, log out and log back in. A plain
plasmashell restart does NOT reload the session environment,
so the env script's QT_PLUGIN_PATH update only takes effect on
the next fresh session.

After a subsequent upgrade or reinstall, no logout is needed —
the session already has QT_PLUGIN_PATH set from the previous
install. Plasmashell still has to restart so it drops the old
.so from memory and loads the new one. The installer offers
to do this for you (default: no on interactive runs, since it
briefly blanks the panel and closes any open AppGrid popup).

Pass -r (or --restart-plasmashell) to skip the prompt and
restart automatically. Combine with -y for a fully unattended
upgrade+restart. Manual command:

    kquitapp6 plasmashell && kstart plasmashell

----------------------------------------------------------------
 Upgrade / reinstall
----------------------------------------------------------------

Just run ./install.sh from the new tarball. The installer reads
the prior manifest, detects the transition (upgrade / reinstall
/ downgrade), removes any files the previous version shipped
that this version no longer ships, then writes the new payload.

Your AppGrid settings live in ~/.config/plasmashell-appletsrc
and are not touched by install or uninstall.

----------------------------------------------------------------
 Uninstall
----------------------------------------------------------------

  ./uninstall.sh

Reads ~/.local/share/appgrid/MANIFEST and removes only the files
listed there. Prunes empty AppGrid-specific directories. The
plasma-workspace env script is removed too. Your plasmoid
configuration in plasmashell-appletsrc is left alone — remove
the AppGrid widget from your panel/desktop first if you want a
fully clean state.

----------------------------------------------------------------
 Flags
----------------------------------------------------------------

  -y, --yes                  Skip all interactive confirms.
                             Install only — does NOT restart
                             plasmashell.
  -r, --restart-plasmashell  On upgrade, restart plasmashell
                             after install. Combine with -y for
                             a fully unattended upgrade+restart.
  --dry-run                  Print what would happen; no files
                             changed.

Quick reference:

  ./install.sh         interactive; prompts for everything
                       (proceed + restart-plasmashell on upgrade)
  ./install.sh -y      unattended install; no prompts, no restart
  ./install.sh -y -r   unattended install + plasmashell restart

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

  "Plasma 6 not found"
      No `plasmashell` on PATH. Install KDE Plasma 6 first.

  "can't resolve these libraries on this system"
      One or more runtime deps are missing. The installer
      prints the package list and the install command for
      your distro. Run that, then retry ./install.sh.

  AppGrid does not appear in the widget chooser
      Did you log out and back in? The env script only takes
      effect on a fresh session. Check that
      ~/.config/plasma-workspace/env/appgrid-user-local.sh
      exists and is executable, then start a new session.

  AppGrid was working, now broken after distro upgrade
      A library it linked against may have changed SONAME.
      Re-run ./install.sh with the matching tarball, or
      rebuild from source.

  "cannot open shared object file: libPlasma.so.X"
      Your distro ships an older (X=6) or newer SONAME than
      the tarball expects (currently 7). Check yours with:
          ls /usr/lib*/libPlasma.so.*
      If you only see libPlasma.so.6, your Plasma is < 6.4
      and not yet supported by this universal package. Use
      your distro's native AppGrid package instead.

  Update indicator never updates / always shows
      Cache lives at
          ~/.cache/plasmashell/dev.xarbit.appgrid.update-checker.json
      Delete it to force a fresh check on next plasmashell
      restart. The setting must be enabled in AppGrid's
      config ("Check the AppGrid website for new releases").

----------------------------------------------------------------
 What lands where
----------------------------------------------------------------

  ~/.local/lib/qt6/plugins/plasma/applets/dev.xarbit.appgrid.so
  ~/.local/lib/qt6/plugins/plasma/applets/dev.xarbit.appgrid.panel.so
  ~/.local/share/icons/hicolor/scalable/apps/dev.xarbit.appgrid.svg
  ~/.local/share/locale/*/LC_MESSAGES/dev.xarbit.appgrid.mo
  ~/.local/share/appgrid/MANIFEST        (installer bookkeeping)
  ~/.config/plasma-workspace/env/appgrid-user-local.sh

Everything else under ~/.local/ is left untouched.

----------------------------------------------------------------
 Verifying the install at runtime
----------------------------------------------------------------

Once AppGrid is added to your panel or desktop, type `i:` into
the search bar to open the info view. It shows:

  AppGrid:  the running version string (e.g. 1.8.0)
  Install:  "Universal package" (vs "Distribution package")
  Variant:  Center / Panel
  Session:  Wayland / X11
  Plasma:   running Plasma version
  KF:       running KDE Frameworks version
  Qt:       running Qt version
  OS:       the PRETTY_NAME from /etc/os-release
  Screens:  attached displays with geometry

A "Copy to Clipboard" button below dumps the same info as plain
text suitable for pasting into bug reports.

The version stamped here matches APPGRID_VERSION at build time —
local dev builds carry a "-dev.<count>+self.g<sha>" suffix, CI
nightlies carry "-dev.<count>", release tarballs are clean.

----------------------------------------------------------------
 Verifying the tarball
----------------------------------------------------------------

The release page ships a matching .sha256 file next to each
tarball:

  sha256sum -c appgrid-universal-<version>-<arch>.tar.gz.sha256

The installer additionally verifies SHA256SUMS over each payload
file before writing anything to disk.

----------------------------------------------------------------
 Reporting issues
----------------------------------------------------------------

  https://github.com/xarbit/plasma6-applet-appgrid/issues

Include: distro + version, output of `./install.sh` (or
`./install.sh --dry-run`), the version stamped in
~/.local/share/appgrid/MANIFEST, and the "Copy to Clipboard"
dump from AppGrid's `i:` info view (system + KDE versions all
in one block).