Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions LINUX_FIX.md
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
<div align="center">

# 🎬 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)
Expand Down
41 changes: 31 additions & 10 deletions main.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand All @@ -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
Expand Down