Add detailed comments to script and comprehensive README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,139 @@
+# DaVinci Resolve - openSUSE Tumbleweed
+
+Install [DaVinci Resolve](https://www.blackmagicdesign.com/products/davinciresolve) on openSUSE Tumbleweed with all the compatibility fixes needed for this rolling-release distro.
+
+Handles gdk-pixbuf ABI mismatches, GLib conflicts, OpenCL setup, libtiff shims, and XWayland wrapper creation — so Resolve just works.
+
+## Requirements
+
+- **OS**: openSUSE Tumbleweed
+- **GPU**: NVIDIA with proprietary drivers installed
+- **DaVinci Resolve**: ZIP or .run file downloaded to `~/Downloads/`
+
+## Quick Start
+
+1. **Download DaVinci Resolve** from [blackmagicdesign.com](https://www.blackmagicdesign.com/products/davinciresolve) — save to `~/Downloads/`
+
+2. **Run the installer**:
+```bash
+git clone https://github.com/28allday/DaVinci-Resolve-openSUSE-Tumbleweed.git
+cd DaVinci-Resolve-openSUSE-Tumbleweed
+chmod +x install-resolve-tw.sh
+sudo ./install-resolve-tw.sh
+```
+
+3. **Launch Resolve**: `resolve`
+
+You can also pass the file path directly:
+```bash
+sudo ./install-resolve-tw.sh /path/to/DaVinci_Resolve_Linux.zip
+```
+
+## What It Does
+
+### 1. Installs Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `libOpenCL1` | GPU-accelerated processing (effects, colour grading) |
+| `libjpeg62` | JPEG image support (older ABI that Resolve needs) |
+| `libX11-xcb1` + `xcb-*` | X11/XCB protocol libraries for display |
+| `libglib/gio/gmodule/gthread` | GLib stack (system versions) |
+| `libapr1-0`, `libapr-util1-0` | Apache Portable Runtime (Resolve's DB engine) |
+| `xwayland` | X11 compatibility layer for Wayland desktops |
+
+### 2. Runs Blackmagic's Installer
+
+- Tries running as the current user first
+- Falls back to sudo with X11 display passthrough if needed
+- Bypasses distro check (`SKIP_PACKAGE_CHECK=1`)
+- Forces X11 mode (`QT_QPA_PLATFORM=xcb`)
+
+### 3. Applies Tumbleweed-Specific Fixes
+
+| Fix | Why |
+|-----|-----|
+| **Fedora gdk-pixbuf2** | Tumbleweed's version is too new for Resolve's Qt — fetches a compatible one from Fedora archives |
+| **System GLib** | Replaces bundled GLib with system version (stable C ABI, safe to swap) |
+| **OpenCL symlink** | Links system libOpenCL.so.1 into Resolve's lib directory |
+| **libtiff5 shim** | Tumbleweed ships libtiff.so.6, Resolve wants .so.5 — symlink bridges the gap |
+
+### 4. Creates XWayland Wrapper
+
+Resolve doesn't support native Wayland. The wrapper at `/usr/local/bin/resolve` forces X11 mode and sets up the correct library paths and NVIDIA environment variables.
+
+### 5. Patches Desktop Entries
+
+Updates `.desktop` files so launching from the app menu uses the wrapper with all the correct environment settings.
+
+## Debug Mode
+
+For verbose output showing every command:
+```bash
+sudo DEBUG=1 ./install-resolve-tw.sh
+```
+
+## Troubleshooting
+
+### Resolve crashes on launch
+
+- Launch from terminal to see errors: `resolve`
+- Check NVIDIA driver: `nvidia-smi`
+- Verify gdk-pixbuf was installed: `ls /opt/resolve/libs/libgdk_pixbuf*`
+
+### Installer GUI doesn't appear
+
+- Make sure X11/XWayland is running: `echo $DISPLAY`
+- The script automatically handles xhost for sudo — if it still fails, try:
+  ```bash
+  xhost +SI:localuser:root
+  sudo ./install-resolve-tw.sh
+  ```
+
+### OpenCL errors / GPU not detected
+
+- Check OpenCL is available: `ls /opt/resolve/libs/libOpenCL.so.1`
+- Verify NVIDIA OpenCL: `zypper in nvidia-compute-utils && clinfo`
+
+### "libtiff.so.5 not found"
+
+The script creates a shim automatically. If it's still missing:
+```bash
+sudo ln -s /usr/lib64/libtiff.so.6 /opt/resolve/libs/libtiff.so.5
+```
+
+## Updating Resolve
+
+Download the new ZIP and run the script again:
+```bash
+sudo ./install-resolve-tw.sh
+```
+
+## Uninstalling
+
+```bash
+# Remove application
+sudo rm -rf /opt/resolve
+
+# Remove wrapper
+sudo rm -f /usr/local/bin/resolve
+
+# Remove desktop entries
+rm -f ~/.local/share/applications/davinci-resolve.desktop
+rm -f ~/.local/share/applications/com.blackmagicdesign.resolve.desktop
+sudo rm -f /usr/share/applications/davinci-resolve.desktop
+
+# Remove user data (WARNING: deletes all projects)
+rm -rf ~/.local/share/DaVinciResolve
+rm -rf ~/.config/Blackmagic\ Design
+```
+
+## Credits
+
+- [openSUSE](https://www.opensuse.org/) - Tumbleweed rolling-release distro
+- [Blackmagic Design](https://www.blackmagicdesign.com/) - DaVinci Resolve
+- Mark Himsley and the openSUSE community for the gdk-pixbuf workaround
+
+## License
+
+This project is provided as-is.

install-resolve-tw.sh

@@ -1,30 +1,79 @@
 #!/usr/bin/env bash
-# openSUSE Tumbleweed — DaVinci Resolve + gdk-pixbuf (Fedora) + GLib + OpenCL + APR
+# ==============================================================================
-# Folds in the working recipe discussed by Mark Himsley and others.
+# DaVinci Resolve Installer for openSUSE Tumbleweed
-# Works for Resolve 19/20 (free or Studio).
+#
+# Installs DaVinci Resolve (19/20, free or Studio) on openSUSE Tumbleweed.
+# Tumbleweed is a rolling-release distro that's always on the bleeding edge,
+# which means it often has newer library versions than Resolve expects.
+#
+# This script handles several Tumbleweed-specific compatibility issues:
+#
+#   1. gdk-pixbuf2 — Tumbleweed's version is too new for Resolve's bundled
+#      Qt libraries. We fetch a compatible version from Fedora's archives
+#      and place it in Resolve's lib directory.
+#
+#   2. GLib replacement — Same as other distros: Resolve's bundled GLib
+#      conflicts with the system version. We replace it with system GLib.
+#
+#   3. OpenCL symlink — Resolve looks for libOpenCL.so.1 in its own lib
+#      directory. We symlink the system's OpenCL there.
+#
+#   4. libtiff shim — Tumbleweed ships libtiff.so.6, but Resolve wants
+#      libtiff.so.5. We create a compatibility symlink.
+#
+#   5. APR libraries — Apache Portable Runtime libs that Resolve's internal
+#      database engine sometimes needs on Tumbleweed.
+#
+#   6. XWayland wrapper — Forces Resolve to run under X11 (via XWayland)
+#      since it doesn't support native Wayland.
+#
+# Works for Resolve 19 and 20 (free and Studio editions).
+#
+# Prerequisites:
+#   - openSUSE Tumbleweed with NVIDIA drivers installed
+#   - DaVinci Resolve ZIP or .run downloaded to ~/Downloads/
+#
+# Usage:
+#   sudo ./install-resolve-tw.sh
+#   # or specify a file directly:
+#   sudo ./install-resolve-tw.sh /path/to/DaVinci_Resolve_Linux.zip
+# ==============================================================================
+
+# Ensure we're running in bash (not sh/dash)
 [ -n "${BASH_VERSION:-}" ] || exec /usr/bin/env bash "$0" "$@"
 set -euo pipefail
+# Add sbin paths — some tools like ldconfig live in /sbin on openSUSE
 export PATH="$PATH:/sbin:/usr/sbin"
+# Enable debug mode with DEBUG=1 for verbose output
 [[ "${DEBUG:-0}" == "1" ]] && set -x
 
+# Coloured logging helpers for easy visual scanning of output
 say()  { echo -e "\033[1;32m==>\033[0m $*"; }
 warn() { echo -e "\033[1;33m[!]\033[0m $*"; }
 err()  { echo -e "\033[1;31m[ERROR]\033[0m $*"; }
 have() { command -v "$1" >/dev/null 2>&1; }
+# zypper wrapper — --no-recommends keeps the install lean, || true prevents
+# a missing optional package from killing the script
 pkg_install() { sudo zypper -n in --no-recommends "$@" || true; }
 
+# Resolve the real user's home directory for finding the ZIP in ~/Downloads/
 TARGET_USER="${SUDO_USER:-$USER}"
 TARGET_HOME="$(getent passwd "$TARGET_USER" | cut -d: -f6)"
 USR_APP_DIR="$TARGET_HOME/.local/share/applications"
+# Track temp dirs and X11 auth changes for cleanup on exit
 WORKDIR=""
 XHOST_ADDED=""
 
+# Cleanup handler — removes temp extraction directory and revokes X11 root
+# access that we may have granted for the GUI installer
 cleanup() {
   [[ -n "$WORKDIR" && -d "$WORKDIR" ]] && rm -rf "$WORKDIR"
   [[ -n "$XHOST_ADDED" ]] && xhost -SI:localuser:root >/dev/null 2>&1 || true
 }
 trap cleanup EXIT
 
+# Auto-detect the newest Resolve installer in ~/Downloads/. Checks for
+# both .zip and .run files, preferring .zip (more common download format).
 pick_latest() {
   local z r
   z=$(ls -t "$TARGET_HOME"/Downloads/DaVinci_Resolve*_Linux.zip 2>/dev/null | head -n1 || true)
@@ -40,7 +89,15 @@ SRC="${1:-}"
 [[ -n "$SRC" ]] || { err "Give a path to DaVinci Resolve Linux .zip or .run (or put it in ~/Downloads)."; exit 1; }
 [[ -e "$SRC" ]] || { err "File not found: $SRC"; exit 1; }
 
-# -------- deps ----------
+# ==================== Dependencies ====================
+#
+# Install runtime libraries that Resolve needs. Tumbleweed uses zypper
+# as its package manager. Key packages:
+#   libOpenCL1:        OpenCL support for GPU-accelerated processing
+#   libjpeg62:         JPEG library (Resolve uses the older ABI)
+#   libX11-xcb1 + xcb-*: X11/XCB protocol libraries for display
+#   libglib/gio/etc:   GLib stack (system versions to replace bundled ones)
+#   libapr1/util:      Apache Portable Runtime (Resolve's DB engine needs these)
 say "Installing runtime tools + common libs…"
 sudo zypper -n ref || true
 RUNTIME_PKGS=(
@@ -77,7 +134,17 @@ else
 fi
 say "Using installer: $RUN_PATH"
 
-# -------- run installer --------
+# ==================== Run Installer ====================
+#
+# Blackmagic's installer is a GUI application. We try running it as the
+# current user first. If that doesn't result in /opt/resolve/bin/resolve
+# being created (e.g. permission denied writing to /opt), we retry with
+# sudo while passing through the display environment variables so the
+# GUI can still render.
+#
+# QT_QPA_PLATFORM=xcb forces the installer to use X11 (not Wayland).
+# SKIP_PACKAGE_CHECK=1 bypasses Resolve's distro check (it doesn't
+# recognise openSUSE as a supported distro).
 say "Running Blackmagic installer (user)…"
 chmod +x "$RUN_PATH" || true
 set +e
@@ -102,7 +169,14 @@ fi
 
 [[ -d /opt/resolve/libs ]] || { err "/opt/resolve not present; installer likely cancelled."; exit 1; }
 
-# -------- TW fix: fetch Fedora gdk-pixbuf2 and copy into /opt/resolve/libs --------
+# ==================== Tumbleweed-Specific Fixes ====================
+#
+# gdk-pixbuf2 fix:
+# Tumbleweed's gdk-pixbuf2 is too new for Resolve's bundled Qt libraries
+# (ABI mismatch causes crashes). The workaround is to grab a compatible
+# version from Fedora's package archives and place it in Resolve's lib
+# directory. We try archived Fedora 38/40 builds first, then fall back
+# to scraping Rawhide for the latest version.
 say "Applying gdk-pixbuf + GLib + OpenCL + APR tweaks for Tumbleweed…"
 tmp="$(mktemp -d)"
 rpmfile="$tmp/gdk.rpm"
@@ -139,12 +213,17 @@ else
 fi
 rm -rf "$tmp"
 
-# Symlink system OpenCL into Resolve dir
+# Symlink the system's OpenCL library into Resolve's lib directory.
+# Resolve needs libOpenCL.so.1 for GPU-accelerated processing (effects,
+# colour grading, neural engine). On Tumbleweed it's usually provided
+# by ocl-icd (OpenCL Installable Client Driver).
 ocl="$(ldconfig -p 2>/dev/null | awk '/libOpenCL\.so\.1/{print $4; exit}')"
 [[ -z "${ocl:-}" && -e /usr/lib64/ocl-icd/libOpenCL.so.1.0.0 ]] && ocl=/usr/lib64/ocl-icd/libOpenCL.so.1.0.0
 [[ -n "${ocl:-}" ]] && sudo ln -sf "$ocl" /opt/resolve/libs/libOpenCL.so.1 || warn "libOpenCL.so.1 not found."
 
-# Copy system GLib into Resolve’s lib folder (overwrites bundled copies)
+# Replace Resolve’s bundled GLib with the system version. Same fix as on
+# Arch/Mint/Rocky — the bundled version is older and conflicts with other
+# system libraries that Resolve also loads.
 if ls /lib64/libglib-2.0.* >/dev/null 2>&1; then
   sudo rm -f /opt/resolve/libs/libglib-2.0.so* || true
   sudo cp -va /lib64/libglib-2.0.* /opt/resolve/libs/
@@ -153,13 +232,27 @@ elif ls /usr/lib64/libglib-2.0.* >/dev/null 2>&1; then
   sudo cp -va /usr/lib64/libglib-2.0.* /opt/resolve/libs/
 fi
 
-# Optional: libtiff5 shim (TW ships libtiff6)
+# libtiff compatibility shim — Tumbleweed ships libtiff.so.6, but Resolve
+# links against libtiff.so.5. Creating a symlink works because the ABI
+# is backwards-compatible between these versions.
 if ! ldconfig -p | grep -q 'libtiff\.so\.5'; then
   [[ -e /usr/lib64/libtiff.so.6 && ! -e /opt/resolve/libs/libtiff.so.5 ]] && \
     sudo ln -s /usr/lib64/libtiff.so.6 /opt/resolve/libs/libtiff.so.5 || true
 fi
 
-# -------- wrapper --------
+# ==================== XWayland Wrapper ====================
+#
+# Create a wrapper script that forces Resolve to run under X11 (XWayland)
+# and sets up the library search path. Tumbleweed defaults to Wayland on
+# most desktop environments, but Resolve doesn't support native Wayland.
+#
+# Key environment variables:
+#   QT_QPA_PLATFORM=xcb:              Force X11 mode
+#   __GLX_VENDOR_LIBRARY_NAME=nvidia:  Use NVIDIA's GLX implementation
+#   QT_XCB_GL_INTEGRATION=none:       Disable Qt's XCB GL integration
+#                                      (avoids conflicts with NVIDIA GL)
+#   QT_OPENGL=desktop:                Use desktop OpenGL (not GLES)
+#   LD_LIBRARY_PATH:                  Prioritise our patched libs in /opt/resolve/
 say "Creating /usr/local/bin/resolve wrapper…"
 sudo tee /usr/local/bin/resolve >/dev/null <<'EOF'
 #!/usr/bin/env bash
@@ -174,7 +267,9 @@ exec /opt/resolve/bin/resolve "$@"
 EOF
 sudo chmod +x /usr/local/bin/resolve
 
-# -------- desktop entries --------
+# Copy and patch desktop entries to use our wrapper instead of launching
+# Resolve directly. User-level entries in ~/.local/share/applications/
+# take priority over system entries in /usr/share/applications/.
 say "Patching desktop entries to use wrapper…"
 mkdir -p "$USR_APP_DIR"
 for f in /usr/share/applications/davinci-resolve.desktop \