Skip to content

Commit 9c37885

Browse files
jonoomphjonoomph
authored
Merge pull request #5528 from OpenShot/docs-jun-8-2024
Documentation: Additional Debug and Troubleshooting steps
2 parents e258aaf + 84b9b71 commit 9c37885

File tree

3 files changed

+117
-0
lines changed

3 files changed

+117
-0
lines changed

‎doc/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ Table of Contents:
4848
import_export
4949
preferences
5050
playback
51+
troubleshoot
5152
developers
5253
contributing
5354
learn_more

‎doc/preferences.rst

+2
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,8 @@ NOTE: On systems with older graphics cards, hardware acceleration may not always
165165
(May be default in Blender 4.1? -
166166
May work backfire if system has multiple GPUs and high-end GPU recognizes Blender automatically)
167167
168+
.. _preferences_keyboard_ref:
169+
168170
Keyboard
169171
--------
170172
.. image:: images/preferences-7-keyboard.jpg

‎doc/troubleshoot.rst

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
.. Copyright (c) 2008-2024 OpenShot Studios, LLC
2+
(http://www.openshotstudios.com). This file is part of
3+
OpenShot Video Editor (http://www.openshot.org), an open-source project
4+
dedicated to delivering high quality video editing and animation solutions
5+
to the world.
6+
7+
.. OpenShot Video Editor is free software: you can redistribute it and/or modify
8+
it under the terms of the GNU General Public License as published by
9+
the Free Software Foundation, either version 3 of the License, or
10+
(at your option) any later version.
11+
12+
.. OpenShot Video Editor is distributed in the hope that it will be useful,
13+
but WITHOUT ANY WARRANTY; without even the implied warranty of
14+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15+
GNU General Public License for more details.
16+
17+
.. You should have received a copy of the GNU General Public License
18+
along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
19+
20+
.. _troubleshoot_ref:
21+
22+
Troubleshooting
23+
===============
24+
25+
If you are experiencing an issue with OpenShot, such as a freeze, crash, or error message, there are many different
26+
techniques which can be useful for troubleshooting the issue.
27+
28+
Windows 11 Unresponsive
29+
-----------------------
30+
31+
If you experience a freeze on Windows 11, this is a known issue with PyQt5 and Windows 11, related to the
32+
accessibility features in Qt. This is triggered by pressing :kbd:`Ctrl+C` in OpenShot (*only on Windows 11*).
33+
OpenShot will become unresponsive and a memory leak is also present (i.e. the longer OpenShot is unresponsive,
34+
the larger your memory leak will become until OpenShot finally crashes or the user kills the process).
35+
36+
A simple work-around is to avoid :kbd:`Ctrl+C` on Windows 11, and instead use the right-click Copy/Paste menus. Another
37+
work-around is to remap your "Copy" from :kbd:`Ctrl+C` to something else, for example :kbd:`Alt+C`. You can change
38+
your keyboard mappings in the OpenShot Preferences. See :ref:`preferences_keyboard_ref`.
39+
40+
Windows Debugging with GDB
41+
--------------------------
42+
43+
If you are experiencing a crash or freeze with OpenShot in Windows 10/11, the following step by step instructions
44+
will help you determine the cause of the crash. These instructions will display a stack trace of OpenShot's source code,
45+
at the location of the crash. This information can be extremely useful for our development team, and very useful to
46+
attach to bug reports (for a quicker resolution).
47+
48+
Install the Latest Daily Build
49+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
50+
51+
Before attaching a debugger, please download the **latest version** of OpenShot: https://www.openshot.org/download#daily.
52+
Install this version of OpenShot to the default location: ``C:\Program Files\OpenShot Video Editor\``. For details
53+
instructions on debugging OpenShot on Windows, please see `this wiki <https://github.com/OpenShot/openshot-qt/wiki/Windows-Debugging-with-GDB>`_.
54+
55+
Install MSYS2
56+
^^^^^^^^^^^^^
57+
58+
The Windows version of OpenShot is compiled using an environment called MSYS2. In order to attach the GDB debugger
59+
to our executable, ``openshot-qt.exe``, you must first install MSYS2. This step is only required once.
60+
61+
1. Download & Install MSYS2: `<http://www.msys2.org/>`_
62+
2. Run ``MSYS2 MinGW x64`` command prompt (for example: ``C:\msys64\msys2_shell.cmd -mingw64``)
63+
3. Update all packages (*Copy/Paste the following command*):
64+
65+
.. code-block:: shell
66+
67+
pacman -Syu
68+
69+
4. Install GDB debugger (*Copy/Paste the following command*):
70+
71+
.. code-block:: shell
72+
73+
pacman -S --needed --disable-download-timeout mingw-w64-x86_64-toolchain
74+
75+
Launch OpenShot with GDB Debugger
76+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
77+
78+
Run ``MSYS2 MinGW x64`` command prompt (for example: ``C:\msys64\msys2_shell.cmd -mingw64``)
79+
80+
Update the PATH (*Copy/Paste the following commands*):
81+
82+
.. code-block:: bash
83+
84+
export PATH="/c/Program Files/OpenShot Video Editor/lib:$PATH"
85+
export PATH="/c/Program Files/OpenShot Video Editor/lib/PyQt5:$PATH"
86+
87+
Load OpenShot into the GDB debugger (*Copy/Paste the following commands*):
88+
89+
.. code-block:: bash
90+
91+
cd "/c/Program Files/OpenShot Video Editor"/
92+
gdb openshot-qt.exe
93+
94+
Launch OpenShot from GDB prompt (*Copy/Paste the following command*):
95+
96+
.. code-block:: bash
97+
98+
run --debug
99+
100+
Print Debugging Info
101+
^^^^^^^^^^^^^^^^^^^^
102+
103+
Once OpenShot has launched successfully with GDB attached, all you need to do is trigger a crash or freeze in OpenShot.
104+
When a crash occurs, switch back to the MSYS2 MinGW64 terminal and run one of the following commands
105+
(by typing it and pressing ENTER). Usually, the first command to enter is ``bt``, which stands for ``backtrace``.
106+
More commands are listed below.
107+
108+
.. code-block:: bash
109+
110+
(gdb) run (launch openshot-qt.exe)
111+
(gdb) CTRL + C (to manually break out OR wait for a crash / segmentation fault)
112+
(gdb) bt (Print stack trace for the current thread #)
113+
(gdb) info threads (to view all threads, and what they are doing. Look for `__lll_lock_wait` for Mutex/deadlocks)
114+
(gdb) thread 35 (Switch to thread number, for example thread 35)

0 commit comments

Comments
 (0)