Fix Flatpak build issues, upgrade to ngspice-46, and vendor Python dependencies

appimage/README.md

@@ -139,35 +139,47 @@ If OMEdit fails to launch, it's usually a missing Qt5 library. The builder autom
 
 To manually check: run `ldd eSim.AppDir/usr/bin/OMEdit.bin | grep "not found"` inside the build directory.
 
-### Python Import Errors
-If you see `ModuleNotFoundError` for PyQt5 or other Python packages:
-- On **Arch**: Ensure `python-pyqt5` is installed (`sudo pacman -S python-pyqt5`)
-- On **Fedora**: Ensure `python3-PyQt5` is installed (`sudo dnf install python3-PyQt5`)
+### Qt / Wayland Display Issues
+The AppImage automatically detects Wayland and X11 sessions and handles setting `QT_QPA_PLATFORM` and prioritizing bundled PyQt5 libraries. However, if you experience display initialization errors, you can force a platform by prepending the environment variable:
+```bash
+# Force X11 compatibility mode
+QT_QPA_PLATFORM=xcb ./eSim-2.5.AppImage
+
+# Force Wayland native mode
+QT_QPA_PLATFORM=wayland ./eSim-2.5.AppImage
+```
 
 ### Build Failures
 Common causes:
 - **Interrupted internet** during large downloads (KiCad AppImage is ~600 MB)
 - **Missing disk space** (at least 5 GB required)
 - **Unsupported architecture** (only x86_64 is currently supported)
 
+For details on past issues faced and how they were resolved, see:
+- [appimage_issues.md](file:///home/ashu/Downloads/eSim_packagemanager/appimage/appimage_issues.md) — Documentation of error logs and root causes.
+- [appimage_fix_implementation.md](file:///home/ashu/Downloads/eSim_packagemanager/appimage/appimage_fix_implementation.md) — Technical details of the python bundling and library isolation fixes.
+
 ---
 
 ## 📁 Project Structure
 
 ```
 eSim_Universal_packagemanager_linux/
-├── build-appimage.sh         # Main build script (~7800 lines)
-├── README.md                 # This file
-└── build-eSim-AppImage/      # Created during build
-    ├── downloads/            # Downloaded tools & dependencies
-    ├── eSim.AppDir/          # AppImage filesystem
-    │   ├── AppRun            # Entry point launcher
+├── build-appimage.sh            # Main build script (~7800 lines)
+├── README.md                    # This file
+├── appimage_issues.md           # Documentation of errors and issues faced
+├── appimage_fix_implementation.md # Technical details of the fixes implemented
+└── build-eSim-AppImage/         # Created during build
+    ├── downloads/               # Downloaded tools & dependencies
+    ├── eSim.AppDir/             # AppImage filesystem
+    │   ├── AppRun               # Entry point launcher (Wayland/X11 & Python wrapper)
     │   ├── usr/
-    │   │   ├── bin/          # eSim, KiCad, OMEdit, NgSpice binaries
-    │   │   ├── lib/          # Bundled shared libraries
-    │   │   └── share/        # eSim source, resources, models
+    │   │   ├── bin/             # eSim, KiCad, OMEdit, NgSpice binaries
+    │   │   ├── lib/             # Bundled shared libraries
+    │   │   ├── python/          # Standalone bundled CPython 3.12 environment
+    │   │   └── share/           # eSim source, resources, models
     │   └── ...
-    └── eSim-2.5.AppImage     # Final portable AppImage
+    └── eSim-2.5.AppImage        # Final portable AppImage
 ```
 
 ---

appimage/appimage_fix_implementation.md

@@ -0,0 +1,85 @@
+# eSim AppImage: Fixes and Implementation Approach
+
+This document explains the technical details, implementation plan, and approach used to resolve build-time and runtime issues for the eSim AppImage.
+
+---
+
+## 1. Portable Python & Dependency Bundling
+### Approach
+To bypass host-system Python version mismatches and restrictions like PEP 668 (system-managed environments), we integrated a fully self-contained Python interpreter into the AppImage bundle.
+
+### Implementation
+- During build time, the build script downloads a pre-compiled, portable CPython distribution (`python-build-standalone` version 3.12.1).
+- It extracts this distribution to `$APPDIR/usr/python`.
+- The build script installs all Python dependencies (including `PyQt5`, `hdlparse`, and others) directly into this bundled Python environment.
+- At runtime, the `AppRun` launcher configures python env variables:
+  ```bash
+  export PYTHONHOME="${HERE}/usr/python"
+  export PYTHONPATH="${HERE}/usr/share/eSim/src"
+  export PATH="${HERE}/usr/python/bin:${PATH}"
+  ```
+- This completely eliminates dependency on the host's python interpreter or internet access for pip packages at runtime.
+
+---
+
+## 2. Dynamic APT Package Detection
+### Approach
+To make the build script compatible across multiple generations of Debian and Ubuntu releases, we replaced hardcoded package lists with dynamic package detection.
+
+### Implementation
+- We updated the `install_deps_apt` function in `build-appimage.sh` to query package managers:
+  ```bash
+  install_gdk_pixbuf() {
+      if apt-cache show libgdk-pixbuf-2.0-dev >/dev/null 2>&1; then
+          sudo apt-get install -y libgdk-pixbuf-2.0-dev
+      elif apt-cache show libgdk-pixbuf2.0-dev >/dev/null 2>&1; then
+          sudo apt-get install -y libgdk-pixbuf2.0-dev
+      fi
+  }
+  ```
+- This ensures the build process automatically adapts to changing package nomenclature upstream.
+
+---
+
+## 3. Runtime Qt Platform Server Auto-Detection
+### Approach
+To support both modern Wayland-based desktops (like Ubuntu 22.04+ and 26.04 GNOME) and older X11-based desktops, we added a runtime display server detector to the main `AppRun` launcher.
+
+### Implementation
+- Added detection code in the `AppRun` heredoc:
+  ```bash
+  if [ -z "${QT_QPA_PLATFORM}" ]; then
+      if [ -n "${WAYLAND_DISPLAY}" ] && [ "${XDG_SESSION_TYPE}" = "wayland" ]; then
+          export QT_QPA_PLATFORM=wayland
+      elif [ -n "${DISPLAY}" ]; then
+          export QT_QPA_PLATFORM=xcb
+      else
+          export QT_QPA_PLATFORM=xcb
+      fi
+  fi
+  ```
+- Pointed the Qt platform plugins engine to the bundled plugins directory from PyQt5:
+  ```bash
+  PYQT5_QT_PLUGINS="${HERE}/usr/python/lib/python3.12/site-packages/PyQt5/Qt5/plugins"
+  if [ -d "${PYQT5_QT_PLUGINS}" ]; then
+      export QT_PLUGIN_PATH="${PYQT5_QT_PLUGINS}:${HERE}/usr/lib/qt5/plugins:${QT_PLUGIN_PATH}"
+  else
+      export QT_PLUGIN_PATH="${HERE}/usr/lib/qt5/plugins:${QT_PLUGIN_PATH}"
+  fi
+  ```
+
+---
+
+## 4. Resolving Qt Library Version Conflicts
+### Approach
+We isolated the AppImage's Qt plugins from host system libraries by forcing the dynamic linker to prioritize the bundled PyQt5 Qt libraries.
+
+### Implementation
+- Prepend the PyQt5 Qt5 library directory to `LD_LIBRARY_PATH` inside `AppRun`:
+  ```bash
+  _PYQT5_QT_LIB="${HERE}/usr/python/lib/python3.12/site-packages/PyQt5/Qt5/lib"
+  if [ -d "${_PYQT5_QT_LIB}" ]; then
+      export LD_LIBRARY_PATH="${_PYQT5_QT_LIB}:${LD_LIBRARY_PATH}"
+  fi
+  ```
+- This forces the system loader to resolve dependencies for `libqwayland-generic.so` and `libqxcb.so` against the bundled Qt libraries (`5.15.19`) instead of mixing them with host Qt libraries (like `5.15.18` on the host).

appimage/appimage_issues.md

@@ -0,0 +1,57 @@
+# eSim AppImage: Encountered Issues and Errors
+
+This document details the issues and error messages encountered during the build and runtime phases of the eSim AppImage on modern Linux environments (specifically tested on Ubuntu 26.04 Resolute with Wayland).
+
+---
+
+## 1. Missing Python Packages (PyQt5 Dependency)
+### Error Message
+```
+Traceback (most recent call last):
+  File "/tmp/.mount_eSimXXXXXX/usr/bin/esim", line 3, in <module>
+    from PyQt5.QtWidgets import QApplication
+ModuleNotFoundError: No module named 'PyQt5'
+```
+
+### Context & Root Cause
+Originally, the AppImage did not package its own Python environment or dependencies (like PyQt5). Instead, the `AppRun` entry point relied on the host system's Python interpreter (`/usr/bin/python3`) and attempted to run pip installation at runtime or assume that PyQt5 was installed on the host system. This failed because:
+- Host systems may restrict ad-hoc package installations due to **PEP 668 (system-managed environments)**.
+- Mismatched host Python versions caused binary package incompatibilities.
+- The AppImage was not truly self-contained or portable.
+
+---
+
+## 2. APT Package Installation Failures (Build-time Dependency)
+### Error Message
+```
+E: Unable to locate package libgdk-pixbuf2.0-dev
+```
+
+### Context & Root Cause
+During the prerequisite installation stage on newer Ubuntu/Debian releases, the build script failed because package names had changed in the upstream repositories (e.g., `libgdk-pixbuf2.0-dev` became `libgdk-pixbuf-2.0-dev`). Hardcoded package names in the build script broke support on newer distributions.
+
+---
+
+## 3. Qt Platform Plugin Initialization Failure (XCB)
+### Error Message
+```
+qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
+This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
+
+Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, webgl, xcb.
+```
+
+### Context & Root Cause
+The host environment was running a **Wayland** session (`XDG_SESSION_TYPE=wayland`). However, Qt5 defaults to the `xcb` (X11) platform plugin. Inside the AppImage container's execution sandbox, the host's X11/XCB libraries were either missing or misaligned with the loader's library path (`LD_LIBRARY_PATH`), causing the `libqxcb.so` plugin to fail to load.
+
+---
+
+## 4. Incompatible Qt Libraries (Qt Version Mismatch)
+### Error Message
+```
+Cannot mix incompatible Qt library (5.15.19) with this library (5.15.18)
+Aborted (core dumped)
+```
+
+### Context & Root Cause
+When trying to run the Wayland platform plugin bundled with the PyQt5 wheel (`libqwayland-generic.so`), Qt attempted to resolve its dependencies. The bundled PyQt5 was compiled against Qt **5.15.19**, but the host system had Qt **5.15.18** installed. Because the host's `/usr/lib/x86_64-linux-gnu` took precedence in `LD_LIBRARY_PATH` over the PyQt5-specific directories, the dynamic linker loaded the host's older `libQt5Core.so.5`, causing a critical version conflict.