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/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
[](https://apps.microsoft.com/detail/9NMVGFL73RH4)
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