Skip to content

fix(linux): replace Win32-only mutex with cross-platform lock (startup crash) - #14

Open
zaddi-zk wants to merge 2 commits into
DMotionX:mainfrom
zaddi-zk:fix/linux-startup
Open

zaddi-zk wants to merge 2 commits into
DMotionX:mainfrom
zaddi-zk:fix/linux-startup

Conversation

@zaddi-zk

Copy link
Copy Markdown

Summary

The Linux and macOS builds crash before the UI appears:

Traceback (most recent call last):
  File "main.py", line 935, in <module>
AttributeError: module 'ctypes' has no attribute 'windll'

ctypes.windll is a Windows-only attribute. main.py calls it unconditionally
for the single-instance guard, so on any non-Windows platform the application
dies during bootstrap.

Reproduction

# Kali Linux / Debian, v1.7.14 AppImage from the releases page
chmod +x DrawMotion-x86_64.AppImage
./DrawMotion-x86_64.AppImage

Fails 100% of the time, immediately, before Qt starts.

Fix

  • Guard the Win32 mutex in the single-instance enforcer behind
    sys.platform == "win32", and use an fcntl.flock advisory lock on POSIX.
  • Guard ctypes.windll.user32.MessageBoxW in _install_native_crash_handler.
  • Guard ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID.

The two windll calls in main.py were already inside try/except for the
taskbar call, but the crash handler's MessageBoxW and the mutex were not.

Verification

Tested on Kali Linux (rolling), Python 3.12.16, with the pinned
requirements.txt (PySide6 6.11.1, opencv-contrib-python 5.0.0.93,
numpy 2.5.1):

  • python main.py reaches the Project Hub with
    [BOOT_HEALTHY] Startup completed cleanly with zero errors.
  • Launching a second instance correctly reports
    [MUTEX_BLOCKED] Another instance of DrawMotion_Dev_Mutex is already active.
    and exits, matching the Windows behaviour.
  • The build-linux.yml workflow completes and produces a working
    AppImage / .deb / tarball.

Windows behaviour is unchanged — the original code path is preserved under the
platform check.

Notes

LINUX_FIX.md documents the diagnosis and how to run from source. Happy to
adjust the approach (e.g. use QLockFile instead of fcntl) if you prefer.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant