Pull Request: Add native Windows (AmpleWin) and Linux (AmpleLinux) ports (#46)

* Initialize and finalize AmpleWin: Full-featured Windows Port with Adaptive UI, optimized engine, and internationalized documentation

* Update media args

* AmpleWin: Finalized Windows Port with Adaptive UI, Optimized Engine, VGM Recording, and Shared Directory Support

* Fix NameError: subprocess not defined in main.py

* UI: Remove redundant MAME path label from Paths tab

* UI: Implement smart slot validation for disabled options and click-to-browse Shared Directory

* feat(win): editable console, launch logic fixes & doc updates

* Fix path quoting issues, add file selectors for A/V, and normalize shared dir path

* feat: sync with Ample v0.285 resources, update to MAME 0.285, and add ROM search filter

* v0.285: Expand ROM library, implement download failover, and advanced SCSI sub-slot emulation

* Adjust ROM download priority: prefer callapple.org for stability, mdk.cab as fallback

* Sync roms.plist with upstream/master

* docs(agent): record upstream synchronization session

* refactor: rename mame_bin to mame directory

* chore: update .gitignore for mame directory rename

* fix(main): update download and detection paths to 'mame'

* fix(main): robust path resolution for pyinstaller builds

* docs(readme): add build_exe.bat to project structure

* fix(build): remove creation of empty mame directory to avoid confusion

* feat(build): auto-generate application icon from Assets.xcassets

* Add AmpleLinux - Linux Port of Ample (Apple II/Mac emulator frontend)

- Ported from AmpleWin with ~20 Linux-specific adaptations
- Replaced winreg with gsettings/KDE dark mode detection
- Replaced os.startfile with xdg-open
- Removed MAME auto-download (users install via package manager)
- Added system-wide MAME detection (PATH, /usr/bin, /usr/games)
- Removed all .exe suffixes from binary references
- Created AmpleLinux.sh launcher script
- Dual-language READMEs (English + Traditional Chinese)

* Fix: use python3 -m pip instead of pip3/pip for modern Linux compatibility

* feat(linux): Finalize AmpleLinux port documentation and build scripts

* Fix formatting for Windows and Linux user notes

Updated user guidance for Windows and Linux users.

* feat(linux): interactive .desktop install, runtime icon loading, updated docs

* docs(linux): clarify mame_downloader.py usage status

* docs: add PR draft template

* fix(linux): add binutils dependency check for pyinstaller

* Update: mame 0.286

---------

Co-authored-by: User <user@example.com>

Author: anomixer

.gitignore

@@ -9,3 +9,27 @@ embedded/SDL3-*
 build
 embedded/mame-data.tgz
 __pycache__
+
+# Windows Port
+AmpleWin/mame/
+AmpleWin/dist/
+AmpleWin/build/
+AmpleWin/*.spec
+
+nvram/
+cfg/
+diff/
+inp/
+comments/
+sta/
+*.ini
+*.ico
+
+# Linux Port
+AmpleLinux/.venv
+AmpleLinux/.build_venv
+AmpleLinux/icons/
+AmpleLinux/Ample.spec
+AmpleLinux/mame/
+!AmpleLinux/mame/.gitkeep
+

AmpleLinux/Agent.md

@@ -0,0 +1,144 @@
+# Agent Task Audit Log - Ample Linux Port
+
+
+## 📅 Session: 2026-03-02 (Session 3)
+
+### 🎯 Objective: Upstream Version Tracking & Documentation Maintenance
+Focused on updating the Linux port documentation to track MAME 0.286 and simplifying maintainability.
+
+### ✅ Key Achievements:
+1.  **Documentation Refactoring**:
+    *   Renamed version-specific screenshot files (e.g. `screenshot-v0.28x.png` to `screenshot.png`).
+    *   Updated `README.md` and `README_tw.md` to use generic "latest version" terminology to prevent the need for manual text updates upon future Ample/MAME releases.
+
+### 🚀 Current Project Status
+The Linux Port documentation is updated for MAME 0.286 and future-proofed against minor version increments.
+
+---
+
+## 📅 Session: 2026-02-17 (Session 2)
+
+### 🎯 Objective: Real-World Testing & Deployment Fix
+Deployed the Linux Port to an actual Linux machine for testing. Identified and fixed a critical dependency installation issue.
+
+### ✅ Key Achievements:
+
+1.  **Launcher Script Fix (`AmpleLinux.sh`)**:
+    *   **Bug**: Original script used `pip3` / `pip` commands directly, which don't exist on many modern Linux distros (Debian 12+, Ubuntu 23+, Fedora 38+ enforce PEP 668).
+    *   **Fix v1**: Changed to `python3 -m pip` (the universally reliable pip invocation).
+    *   **Fix v2**: Added automatic `--break-system-packages` fallback for PEP 668-compliant systems.
+    *   **Error Messages**: Added distro-specific guidance (apt/dnf/pacman) and venv instructions in error output.
+
+2.  **Git Workflow**:
+    *   Created `linux` branch from `master`.
+    *   Pushed to `origin/linux` for cross-machine testing.
+
+### 🔍 Testing Observations (Real Linux Machine):
+*   `pip3` command was not in PATH → first fallback triggered.
+*   `python3 -m pip` also failed (PEP 668 system Python restriction) → second fallback triggered with `--break-system-packages`.
+*   **Conclusion**: Many modern Linux distros require either system packages (`sudo apt install python3-pyside6 python3-requests`) or a venv approach. The launcher script now documents both paths clearly.
+
+### ⚠️ Known Issue - Pending Resolution:
+*   Systems without any pip module need manual package installation first. The script provides clear guidance but cannot auto-resolve this without `sudo`.
+*   **Recommended solutions** (in priority order):
+    1.  System packages: `sudo apt install python3-pyside6 python3-requests`
+    2.  Install pip: `sudo apt install python3-pip`, then re-run script
+    3.  Use venv: `python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt && python3 main.py`
+
+### 🚀 Current Project Status
+Codebase is ported and pushed to `linux` branch. Launcher script has been hardened for modern Linux distros. Awaiting successful end-to-end test with dependencies installed.
+
+---
+
+## 📅 Session: 2026-02-16 (Session 1)
+
+### 🎯 Objective: Linux Port Creation
+Ported AmpleWin (Windows) to Linux, following the original author's suggestion (ksherlock/ample#45) that Linux support would be easy to add.
+
+### ✅ Key Achievements:
+
+1.  **Codebase Porting (from AmpleWin)**:
+    *   **Zero-Modification Files**: `data_manager.py`, `rom_manager.py`, `mame_launcher.py`, `requirements.txt` — copied directly, no changes needed.
+    *   **Simplified `mame_downloader.py`**: Removed `MameDownloadWorker` entirely (Linux users install MAME via their package manager). Kept `VgmModDownloadWorker` with Linux adaptations (7z via PATH, no `.exe` suffix, helpful `p7zip` install instructions).
+    *   **`main.py` (~20 changes)**: Comprehensive platform adaptation:
+        -   Replaced `winreg` theme detection with `gsettings` (GNOME 42+ `color-scheme`) and KDE (`kdeglobals`) dark mode detection.
+        -   Replaced all `os.startfile()` calls with `xdg-open` via a helper function `_xdg_open()`.
+        -   Removed all `.exe` suffixes from MAME binary references (`mame.exe` → `mame`, `mame-vgm.exe` → `mame-vgm`).
+        -   Enhanced `check_for_mame()` to search system paths (`/usr/bin/mame`, `/usr/games/mame`, `/usr/local/bin/mame`) and use `which mame`.
+        -   Replaced `Download MAME` button with package manager guidance text.
+        -   Updated `shlex.split()` from `posix=False` (Windows) to `posix=True` (Linux).
+        -   Updated file browser filter from `*.exe` to `All Files (*)`.
+        -   Changed window title and help URL.
+
+2.  **Launcher Script**:
+    *   Created `AmpleLinux.sh` as equivalent of `AmpleWin.bat`.
+    *   Includes Python 3 detection, pip dependency installation, and helpful error messages with distro-specific commands.
+
+3.  **Documentation**:
+    *   Created dual-language READMEs (`README.md` English, `README_tw.md` Traditional Chinese).
+    *   Includes installation guide for all major distros (Ubuntu, Fedora, Arch, Flatpak).
+    *   Troubleshooting section for PySide6, MAME detection, and theme issues.
+
+### 🔍 Design Decisions:
+
+1.  **Separate Directory (not shared codebase)**: Chose to create `AmpleLinux/` as a separate directory rather than refactoring `AmpleWin/` into a shared codebase. This maintains the project convention where each platform gets its own additive subdirectory, minimizing risk to the stable Windows port.
+
+2.  **No MAME Auto-Download**: Following the original author's guidance ("let the user download it themselves"), Linux users install MAME via their system package manager. This is the Linux cultural norm and avoids complex binary distribution issues.
+
+3.  **GNOME + KDE Theme Detection**: Implemented multi-strategy dark mode detection covering GNOME 42+ `color-scheme`, older GNOME `gtk-theme`, and KDE `kdeglobals`, with Qt palette as ultimate fallback.
+
+### 🚀 Current Project Status
+The Linux Port is functionally complete. All Windows-specific code has been adapted, and the application should work on major Linux distributions with GNOME or KDE desktops.
+
+---
+
+##  Handover Notes for Future Agents
+
+### 1. Platform Differences from AmpleWin
+*   **No `winreg`**: Theme detection uses `gsettings` and KDE config file parsing.
+*   **No `os.startfile()`**: Uses `xdg-open` via the `_xdg_open()` helper function.
+*   **No `.exe` suffixes**: All binary references use bare names (`mame`, `mame-vgm`).
+*   **No MAME auto-download**: Users install via package manager. Settings dialog shows guidance.
+*   **`shlex.split(posix=True)`**: Linux uses POSIX-mode shell parsing (no special Windows path handling).
+*   **MAME detection**: Checks `PATH` via `which`, plus standard Linux paths (`/usr/bin`, `/usr/games`, `/usr/local/bin`).
+
+### 2. Deployment (CRITICAL)
+*   **PEP 668 Era**: Modern Linux distros (Debian 12+, Ubuntu 23.04+, Fedora 38+) block global pip installs. The launcher script handles this with `--break-system-packages` fallback.
+*   **Recommended Install Methods** (in priority order):
+    1.  System packages: `sudo apt install python3-pyside6 python3-requests mame`
+    2.  venv: `python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt`
+    3.  pip with override: `python3 -m pip install -r requirements.txt --break-system-packages`
+*   **Never use `pip3` or `pip` directly** in scripts — always use `python3 -m pip` for reliability.
+
+### 3. Known Mantras (inherited from AmpleWin)
+*   **Visual Parity is King**: Every margin, font size, and color was cross-referenced with macOS.
+*   **Authorship**: This Linux Port is based on the AmpleWin collaboration between **anomixer** and **Antigravity**.
+
+---
+
+## 📅 Session: 2026-02-17 (Session 2)
+
+### 🎯 Objective: First-Run Experience, Build System & Polish
+
+### ✅ Key Changes:
+
+1.  **Launcher Architecture (`AmpleLinux.sh`)**:
+    *   **Refactored to venv**: Switched from system-level `apt` dependencies to a strictly isolated `python3 -m venv` approach.
+    *   **Automated Setup**: Script now auto-creates `.venv`, installs `python3-venv` (if missing), and pip installs `requirements.txt`.
+    *   **Distro Agnostic**: Only depends on `python3-full` and `libxcb-cursor*` (apt) for the base interpreter; all libraries (PySide6) are pulled via pip.
+    *   **ALSA Fix**: Added auto-detection of `/proc/asound` and `usermod -a -G audio` fix for permission issues.
+
+2.  **User Experience Enhancements (`main.py`)**:
+    *   **Ubuntu Snap Integration**: If MAME is missing on Ubuntu, offers `sudo snap install mame` with a non-blocking `QProgressDialog`.
+    *   **Configuration Fix**: `ensure_mame_ini` now runs `mame -cc` inside `AmpleLinux/mame` to keep config portable.
+    *   **Path Precision**: `update_command_line` now resolves absolute paths for `-inipath` and `-rompath` (e.g., `/home/user/...`).
+    *   **BGFX Cleanup**: Removed Windows-only Direct3D options.
+    *   **UI Polish**: "Generate VGM" now shows a "Feature not implemented" popup.
+
+3.  **Build System (New)**:
+    *   **`make_icon.py`**: Created Linux-specific icon generator (produces standard PNG sizes: 16x16 to 512x512).
+    *   **`build_elf.sh`**: Created PyInstaller build script that uses a temporary venv to bypass PEP 668 restrictions and produce a standalone ELF binary in `dist/`.
+
+### 🔍 Technical Decisions:
+*   **PySide6 via pip**: Moved away from `python3-pyside2` (apt) because the codebase is written for PySide6. Using venv + pip ensures version consistency and avoids the "externally-managed-environment" error on modern distros.
+*   **MAME Snap**: For Ubuntu users, Snap is the most reliable way to get a recent MAME version without PPA complexity.

AmpleLinux/AmpleLinux.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+echo "========================================"
+echo "  Ample - Linux Port Auto Launcher"
+echo "========================================"
+
+# --- First-Time Setup: Install system-level dependencies ---
+if command -v apt &> /dev/null; then
+    # libxcb-cursor0 is required by Qt/PySide6 on X11
+    NEED_INSTALL=0
+    for pkg in python3-full libxcb-cursor0; do
+        if ! dpkg -s "$pkg" &> /dev/null 2>&1; then
+            NEED_INSTALL=1
+            break
+        fi
+    done
+
+    if [ $NEED_INSTALL -eq 1 ]; then
+        echo "[SETUP] Installing required system packages..."
+        echo "  sudo apt install python3-full libxcb-cursor*"
+        sudo apt install -y python3-full libxcb-cursor*
+        if [ $? -ne 0 ]; then
+            echo "[WARN] Some packages may have failed to install. Continuing anyway..."
+        else
+            echo "[SETUP] System packages installed successfully."
+        fi
+    fi
+fi
+
+# --- ALSA Audio Permission Fix ---
+if [ -d /proc/asound ]; then
+    if ! id -nG "$(whoami)" | grep -qw "audio"; then
+        echo "[SETUP] ALSA audio system detected. Adding user to 'audio' group..."
+        sudo usermod -a -G audio "$(whoami)"
+        if [ $? -eq 0 ]; then
+            echo "[SETUP] Added $(whoami) to 'audio' group. Please log out and back in for this to take effect."
+        else
+            echo "[WARN] Failed to add user to 'audio' group. Sound may not work properly."
+        fi
+    fi
+fi
+
+# Check for Python 3
+if ! command -v python3 &> /dev/null; then
+    echo "[ERROR] Python 3 not found! Please install Python 3.9 or newer."
+    echo "  Ubuntu/Debian: sudo apt install python3 python3-full"
+    echo "  Fedora: sudo dnf install python3 python3-pip"
+    echo "  Arch: sudo pacman -S python python-pip"
+    exit 1
+fi
+
+# Navigate to script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# --- Virtual Environment Setup ---
+VENV_DIR=".venv"
+
+# Ensure python3-venv is available
+if ! python3 -m venv --help &> /dev/null; then
+    echo "[INFO] python3-venv is required but not installed."
+    if command -v apt &> /dev/null; then
+        PY_VER=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
+        echo "[INFO] Installing python3.${PY_VER}-venv ..."
+        sudo apt install -y "python3.${PY_VER}-venv" python3-full
+    else
+        echo "[ERROR] Please install python3-venv for your distro and try again."
+        exit 1
+    fi
+fi
+
+# Recreate if venv is broken
+if [ -d "$VENV_DIR" ] && [ ! -f "$VENV_DIR/bin/activate" ]; then
+    echo "[WARN] Virtual environment is broken, recreating..."
+    rm -rf "$VENV_DIR"
+fi
+
+# Create venv if it doesn't exist
+if [ ! -d "$VENV_DIR" ]; then
+    echo "[1/3] Creating virtual environment..."
+    python3 -m venv "$VENV_DIR"
+else
+    echo "[1/3] Virtual environment found."
+fi
+
+# Activate venv
+source "$VENV_DIR/bin/activate"
+
+# Install/Update dependencies
+echo "[2/3] Checking dependencies..."
+pip install -r requirements.txt --quiet 2>/dev/null
+
+if [ $? -ne 0 ]; then
+    echo "[WARN] pip install failed, retrying with upgrade..."
+    pip install --upgrade pip --quiet 2>/dev/null
+    pip install -r requirements.txt --quiet
+    if [ $? -ne 0 ]; then
+        echo "[ERROR] Failed to install requirements."
+        deactivate
+        exit 1
+    fi
+fi
+
+# Run the application
+echo "[3/3] Launching Ample..."
+python3 main.py
+
+if [ $? -ne 0 ]; then
+    echo ""
+    echo "[INFO] Application exited with error."
+    read -p "Press Enter to continue..."
+fi
+
+deactivate