Debugging ScummVM

Debug Output

The functions in common/debug.* provide a basic debug output interface in a platform portable form.

The debuglevel is a global single integer which varies between -1 (minimum - default) and 11 (maximum).
This parameter indicates increasing verbosity of debug output, but does not separate by function.
This is set by passing the command line parameter, -d <int> to scummvm at runtime.

Debugflags (also known as Debug Channels) are booleans and are engine specific.
An engine can have up to 32 channels.
These can be set by passing the command line parameter, --debugflags=<flag1, flag2, ...> to scummvm at runtime.
They are generally preferred to just using debuglevel, since they allow separation of debug output into clearly named groupings and can be changed during runtime using the debug console.

Interactive Engine Debugging

ScummVM engines should implement an interactive debug console.

This is especially useful on embedded ports which usually lack the stdout console used currently for debug output as described above.

The key combination to activate the debug console is CTRL-d
(though this can be varied by engine if it conflicts with gameplay - See README).

The default console provides the following default commands :

• help : Display the list of available commands
  
• exit : Exit the debug console
  
• debugflag_list : list the available debug flags and their status
  
• debugflag_enable <debugflag> : enable a given debugflag
  
• debugflag_disable <debugflag> : disable a given debugflag
  

This can be extended with further engine-specific commands.

TODO: Document commands for specific engines, or link to subpages in each engine for this.

TODO: Document debug flags/levels for the various ports.

Platform Specific Debugging

Android

When debugging on Android, the Android Debug Bridge provides developers with access to the system log.
Specifically, the logcat command will display the log: [1]

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": [2]
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.

Unix (Linux, Solaris, Mac OS X, MinGW ...)

When debugging on Unix, the main tool is the GNU debugger. This can be invoked as gdb ./scummvm.

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 bt which prints a backtrace of the point of the crash, showing the function call stack state.

Unless --enable-release 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 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 Valgrind instrumentation framework.

This can be invoked similar to gdb as valgrind ./scummvm. On Mac OS X, you will also want to pass the --dsymutil=yes 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 valgrind --leakcheck=full ./scummvm.

For further details, you should consult the relevant documentation of these tools on their web sites or manual pages.

Tips

• To prevent SDL from catching segmentation faults (the SDL Parachute), add the following key to the configuration file under [scummvm]:

disable_sdl_parachute=true

or use command line switch

--disable-sdl-parachute

command line option.