Windows Debugging with GDB

If you are experiencing a crash or freeze with OpenShot in Windows 10/11, the following step by step instructions will help you determine the cause of the crash. These instructions will display a stack trace of OpenShot's source code, at the location of the crash. This information can be extremely useful for our development team, and very useful to attach to bug reports (for a quicker resolution).

Install the Latest Daily Build of OpenShot

Before attaching a debugger, please download the latest & greatest version of OpenShot: https://www.openshot.org/download#daily. Install this version of OpenShot to the default location: C:\Program Files\OpenShot Video Editor\.

Install MSYS2 & Dependencies

The Windows version of OpenShot is compiled using an environment called MSYS2. In order to attach the GDB debugger to our executable, openshot-qt.exe, you must first install MSYS2. This step is only required once.

1. Download & Install MSYS2: http://www.msys2.org/
2. Run MSYS2 MinGW x64 command prompt (for example: C:\msys64\msys2_shell.cmd -mingw64)
3. Update all packages (Copy/Paste the following command): pacman -Syu
4. Install GDB debugger (Copy/Paste the following command): pacman -S --needed --disable-download-timeout mingw-w64-x86_64-toolchain

Launch OpenShot with x64/64-bit GDB Debugger

1. Run MSYS2 MinGW x64 command prompt (for example: C:\msys64\msys2_shell.cmd -mingw64)
2. Update the PATH (Copy/Paste the following commands):

export PATH="/c/Program Files/OpenShot Video Editor/lib:$PATH"
export PATH="/c/Program Files/OpenShot Video Editor/lib/PyQt5:$PATH"

6. Load OpenShot into the GDB debugger (Copy/Paste the following commands):

cd "/c/Program Files/OpenShot Video Editor"/
gdb openshot-qt.exe

7. Launch OpenShot from GDB prompt (Copy/Paste the following command):

run --debug

(Optional) OpenShot x86/32-bit with GDB Debugger

1. Install x86 GDB debugger (Copy/Paste the following command): pacman -S --needed base-devel mingw32/mingw-w64-i686-toolchain
2. Run MSYS2 MinGW x86 / 32-bit command prompt (for example: C:\msys64\msys2_shell.cmd -mingw32)
3. Update the PATH for x86 (Copy/Paste the following commands):

export PATH="/c/Program Files (x86)/OpenShot Video Editor/lib:$PATH"
export PATH="/c/Program Files (x86)/OpenShot Video Editor/lib/PyQt5:$PATH"

6. Load OpenShot into the x86 GDB debugger (Copy/Paste the following commands):

cd "/c/Program Files (x86)/OpenShot Video Editor"/
gdb openshot-qt.exe

7. Launch OpenShot from x86 GDB prompt (Copy/Paste the following command):

run --debug

Print Stack Trace (and other useful GDB debugging commands)

Once OpenShot has launched successfully with GDB attached, all you need to do is trigger a crash or freeze in OpenShot. When a crash occurs, switch back to the MSYS2 MinGW64 terminal and run one of the following commands (by typing it and pressing ENTER). Usually, the first command to enter is bt, which stands for backtrace. More commands are listed below.

(gdb) run            (launch openshot-qt.exe)
(gdb) CTRL + C       (to manually break out   OR   wait for a crash / segmentation fault) 
(gdb) bt             (Print stack trace for the current thread #)
(gdb) info threads   (to view all threads, and what they are doing. Look for `__lll_lock_wait` for Mutex/deadlocks)
(gdb) thread 35      (Switch to thread #, for example thread 35)