From c192115553069b69685ceaa98541aaee26ffa45a Mon Sep 17 00:00:00 2001 From: Roy Date: Fri, 20 Nov 2026 01:10:42 +0300 Subject: [PATCH 1/2] fix(linux): replace Win32-only mutex with cross-platform lock main.py called ctypes.windll.kernel32.CreateMutexW unconditionally, which crashes on Linux/macOS with 'AttributeError: module ctypes has no attribute windll' before the UI starts. - Guard all ctypes.windll usage behind sys.platform == 'win32' - Use an fcntl.flock advisory lock for the single-instance guard on POSIX - Add LINUX_FIX.md with the diagnosis and run instructions Verified launching on Kali Linux with Python 3.12 + PySide6 6.11.1. --- LINUX_FIX.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++ main.py | 41 ++++++++++++++++++++++-------- 2 files changed, 102 insertions(+), 10 deletions(-) create mode 100644 LINUX_FIX.md diff --git a/LINUX_FIX.md b/LINUX_FIX.md new file mode 100644 index 0000000..7e67772 --- /dev/null +++ b/LINUX_FIX.md @@ -0,0 +1,71 @@ +# Linux Startup Fix + +## Problem + +On Linux, DrawMotion crashed immediately at startup with: + +``` +AttributeError: module 'ctypes' has no attribute 'windll' +``` + +`main.py` used the Windows-only `ctypes.windll` API unconditionally for its +single-instance "mutex" guard: + +```python +mutex = ctypes.windll.kernel32.CreateMutexW(None, False, mutex_name) +``` + +Because `ctypes.windll` only exists on Windows, the application terminated +before the Qt UI could be created. The same code also called +`ctypes.windll.user32.MessageBoxW` and +`ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID`. + +## Fix + +All Windows-only calls are now guarded behind `sys.platform == "win32"`. +The single-instance guard uses a POSIX advisory lock (`fcntl.flock`) on a lock +file in the application data directory on Linux/macOS. + +Files changed: + +- `main.py` + - `_install_native_crash_handler()`: `MessageBoxW` only on Windows. + - Single-instance enforcer: Win32 mutex on Windows, `fcntl.flock` elsewhere. + - Taskbar / AppUserModelID: only on Windows. + +## Verified + +Tested on Kali Linux with Python 3.12.16 and the pinned +`requirements.txt` (PySide6 6.11.1, OpenCV 5.0.0.93, NumPy 2.5.1): + +```bash +python3.12 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +python main.py +``` + +The application initializes Qt and FFmpeg and stays running. + +## Run from source (Linux) + +```bash +git clone https://github.com/zaddi-zk/DrawMotion.git +cd DrawMotion +uv venv --python 3.12 .venv # or: python3.12 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +python main.py +``` + +## Building installers + +The existing GitHub Actions workflow +(`.github/workflows/build-linux.yml`) builds a standalone Nuitka binary, a +`.deb`, a tarball, and an AppImage. Push a `v*.*.*` tag or run the workflow +manually from the Actions tab. + +## License + +DrawMotion is licensed under the GNU GPL v3.0. This patch is distributed under +the same license. diff --git a/main.py b/main.py index d2225f1..9502291 100644 --- a/main.py +++ b/main.py @@ -42,7 +42,8 @@ def _crash_hook(exctype, value, tb): f"Diagnostic details have been saved to:\n" f"{os.path.join(get_app_data_dir(), 'Logs', 'crash_log.txt')}" ) - ctypes.windll.user32.MessageBoxW(0, msg, "DrawMotion - Critical Error", 0x10 | 0x10000) + if sys.platform == "win32": + ctypes.windll.user32.MessageBoxW(0, msg, "DrawMotion - Critical Error", 0x10 | 0x10000) except Exception: pass @@ -928,12 +929,31 @@ def closeEvent(self, event): # ── 2. Single Instance Enforcer (Environment-Isolated Zero-Crash Mutex) ── # Development uses 'DrawMotion_Dev_Mutex' and Production uses 'DrawMotion_Prod_Mutex' # so they NEVER collide with or block each other. - ERROR_ALREADY_EXISTS = 183 mutex_name = "DrawMotion_Prod_Mutex" if is_frozen_build() else "DrawMotion_Dev_Mutex" StartupLifecycleTracker.trace("MUTEX_CHECK", f"Checking instance mutex: {mutex_name}") - mutex = ctypes.windll.kernel32.CreateMutexW(None, False, mutex_name) - if ctypes.windll.kernel32.GetLastError() == ERROR_ALREADY_EXISTS: + if sys.platform == "win32": + ERROR_ALREADY_EXISTS = 183 + ctypes.windll.kernel32.CreateMutexW(None, False, mutex_name) + already_running = ctypes.windll.kernel32.GetLastError() == ERROR_ALREADY_EXISTS + else: + # POSIX: advisory file lock (cross-platform replacement for the Win32 mutex). + # The open handle is kept for the process lifetime so the lock persists. + import fcntl + try: + _lock_path = os.path.join(get_app_data_dir(), f"{mutex_name}.lock") + os.makedirs(os.path.dirname(_lock_path), exist_ok=True) + _instance_lock = open(_lock_path, "w") + try: + fcntl.flock(_instance_lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB) + already_running = False + except OSError: + already_running = True + except Exception: + # Never block startup because the lock file could not be created. + already_running = False + + if already_running: StartupLifecycleTracker.trace("MUTEX_BLOCKED", f"Another instance of {mutex_name} is already active.") from PySide6.QtWidgets import QApplication, QMessageBox temp_app = QApplication(sys.argv) @@ -945,12 +965,13 @@ def closeEvent(self, event): # ──────────────────────────────────────────────────────────────────────── # ── Windows Taskbar Fix ───────────────────────────────────────────────── - try: - ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID( - "DrawMotion.AnimationStudio.1.0" - ) - except Exception: - pass + if sys.platform == "win32": + try: + ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID( + "DrawMotion.AnimationStudio.1.0" + ) + except Exception: + pass # ──────────────────────────────────────────────────────────────────────── # Force application-wide locale to English to prevent Arabic/Indic numerals in QSpinBox From 08ff7ca6664f17b284644f7b3eee1384730f8bc9 Mon Sep 17 00:00:00 2001 From: Roy Date: Fri, 20 Nov 2026 01:34:05 +0300 Subject: [PATCH 2/2] docs: note the Linux startup fix and prebuilt release in the fork README --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 27f35d3..789c145 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,13 @@
# 🎬 DrawMotion Animation Studio + +> **This is a personal fork of [DMotionX/DrawMotion](https://github.com/DMotionX/DrawMotion) with a Linux startup fix.** +> The upstream Linux builds crash on launch with `AttributeError: module 'ctypes' has no attribute 'windll'`. +> Fixed here — see [LINUX_FIX.md](LINUX_FIX.md) and the +> [v1.7.14-linuxfix release](https://github.com/zaddi-zk/DrawMotion/releases/tag/v1.7.14-linuxfix) +> for ready-to-run AppImage / .deb / tarball. + ### The Open-Source Vector Animation & Whiteboard Studio Powered by Python & Qt [![Microsoft Store](https://img.shields.io/badge/Microsoft%20Store-Available%20Now-0078D4?style=for-the-badge&logo=microsoft-store&logoColor=white)](https://apps.microsoft.com/detail/9NMVGFL73RH4)