TrustedUser
574
edits
Difference between revisions of "Debugging ScummVM"
Jump to navigation
Jump to search
→Tips: Add links on Git Bisect and Event Recorder to Debugging Tips section.
(Update list for addition of debug console to engines) |
(→Tips: Add links on Git Bisect and Event Recorder to Debugging Tips section.) |
||
| (7 intermediate revisions by 3 users not shown) | |||
| Line 15: | Line 15: | ||
== Interactive Engine Debugging == | == Interactive Engine Debugging == | ||
ScummVM engines should implement an interactive debug console.<br> | |||
<br> | <br> | ||
This is especially useful on embedded ports which usually lack the stdout console used currently for debug output as described above.<br> | |||
<br> | <br> | ||
The key combination to activate the debug console is CTRL-d <br> | The key combination to activate the debug console is CTRL-d <br> | ||
| Line 35: | Line 34: | ||
TODO: Document debug flags/levels for the various ports.<br> | TODO: Document debug flags/levels for the various ports.<br> | ||
== Platform Specific Debugging == | |||
Unlike the previous engine specific debugging output which is present in all builds including releases, debugging the platform backend code requires procedure and tools specific to the platform.<br> | |||
It also generally requires a debug build (either compiled yourself or a nightly build from [http://buildbot.scummvm.org/builds.html here]) as release builds are generally stripped of debugging symbols | |||
for reason of binary size.<br> | |||
If the observed bug only occurs on certain platforms or is unstable to reproduce, it is likely that the engine debugging output will not be sufficient, even with the possibility of adding further | |||
debug output and recompiling.<br> | |||
The following hints are provided for how to do low level debugging on various platforms. | |||
=== Android === | |||
When debugging on Android, the Android Debug Bridge provides developers with access to the system log.<br> | |||
Specifically, the logcat command will display the log: | |||
[https://developer.android.com/tools/help/adb.html#logcat] | |||
This should record any ScummVM related errors, warnings or other information, especially related to failures of the application to start or application crashes. | |||
For investigating user bug reports, it would useful to get this information, but the ADB requires a USB connection to a host PC with the ADK. | |||
If you are using Android 4.1 or below (Android 4.2 requires root access to view logs), there is an easier to use log viewer application which runs on the device called "alogcat": | |||
[https://code.google.com/p/alogcat/]<br> | |||
This requires no Host PC, USB connection or software setup beyond installing this app and can be downloaded from the Android Store (Google Play) for no cost. | |||
=== Dreamcast === | |||
The debug builds with serial enabled from [http://buildbot.scummvm.org/snapshots/master/dc-serial-master-latest.tar.bz2 here] provide debug output to the Dreamcast serial port. | |||
With the appropriate cable to convert the 3V3 serial port to RS232 serial and a terminal program set to 57600 baud 8-N-1, you can view the debug output<br> | |||
from libronin, including the sbrk indication of remaining memory, which can be useful in diagnosing Out Of Memory crashes. | |||
=== Unix (Linux, Solaris, Mac OS X, MinGW ...) === | |||
When debugging on Unix, the main tool is the [http://www.gnu.org/software/gdb/ GNU debugger]. This can be invoked as <tt>gdb ./scummvm</tt>. | |||
Like most debuggers, if a crash (segfault) occurs, then control is returned to the debugger i.e. the gdb command prompt will appear. This then allows commands to be entered to query the state at the | |||
point of the crash. The most useful command is <tt>bt</tt> which prints a backtrace of the point of the crash, showing the function call stack state. | |||
Unless <tt>--enable-release</tt> is passed to configure, ScummVM will be compiled with debug symbols and the backtrace should be readable with annotations of ScummVM function names and line numbers. | |||
If you want to use gdb for setting breakpoints, examining variables, then the graphical wrapper for gdb, called the [http://www.gnu.org/software/ddd/ GNU Data Display Debugger] makes this easier. | |||
If the bug is suspected to be caused by memory management issues i.e. uninitialized variables, bad memory accesses, memory leaks or thread problems then a better tool is the [http://valgrind.org/ Valgrind instrumentation framework]. | |||
This can be invoked similar to gdb as <tt>valgrind ./scummvm</tt>. On Mac OS X, you will also want to pass the <tt>--dsymutil=yes</tt> argument so that you will get debug symbol information. | |||
By default, this will output memory access issues. If you want to do leak checking, you should invoke as <tt>valgrind --leakcheck=full ./scummvm</tt>. | |||
For further details, you should consult the relevant documentation of these tools on their web sites or manual pages. | |||
== Tips == | == Tips == | ||
| Line 43: | Line 88: | ||
command line option. | command line option. | ||
* Apart from using git [https://www.kernel.org/pub/software/scm/git/docs/git-bisect.html bisect] to locate regressions, the (experimental) [[Event_Recorder|Event Recorder]] provides a framework for recording and replaying gameplay to detect regressions which may be useful. | |||