DebuggingLink

GDB (All platforms)Link

The GNU Debugger is the most widely available debugging tool for many platforms.

Windows users

This guide assumes you have already installed the MSYS2/MinGW environment as detailed here and that you are running in the appropriate "MSYS2 MinGW" (32 or 64-bit) shell (not "MSYS2 MSYS").

If you observe a crash with RetroArch and would like to get more information, navigate to the folder where your RetroArch installation is and run:

gdb retroarch

Windows users

If you have not compiled RetroArch yourself with debugging enabled (make DEBUG=1), please specify retroarch_debug.exe here instead of retroarch to use the debug version that ships with our binary package.

After gdb has started, you can then start up RetroArch with run. If RetroArch crashes, gdb should show you a prompt with a message such as:

Program received signal SIGSEGV, Segmentation fault.

From here, type bt full to get a full backtrace of the crash. You can copy/paste this information to a pastebin site such as dpaste to get a link that you can provide to developers to help with your problem. Run quit when you are done to exit gdb.

For more information on using GDB, please see their online documentation here.

ASAN (Linux/Mac/BSD/Android)Link

AddressSanitizer (ASAN) is a very fast memory error detector and an indispensable tool for finding issues with improper memory handling such as use-after-free, buffer overflows and general memory leaks. It is available since GCC 4.8 and Clang 3.1 for Linux (x64 and ARM) systems. Typical slowdown of runtime performance is around 2x.

There are several ways to use RetroArch in conjunction with ASAN and there are many different options that can be combined with each other. The first step is that you need to compile ASAN directly into the RetroArch binary. Here are some simple examples:

For detecting memory errors/leaks and undefined behavior:

make DEBUG=1 SANITIZER=address,undefined

For detecting threading errors such as race conditions:

make DEBUG=1 SANITIZER=thread

Then you can run the RetroArch binary normally with ./retroarch. As problems are detected, they will be printed to the console either at runtime or when the program exits or crashes, depending on the type of error.

For more information, see the gcc, Google and clang documentation.

Dr. Memory (Windows/Linux/Mac/Android)Link

Dr. Memory is another tool for detecting memory errors similar to ASAN. Its website can be found here: http://www.drmemory.org/

After installation, the simplest way to use Dr. Memory with RetroArch is to open the start menu shortcut under "Dr. Memory" called "Explore Dr. Memory", and then drag the retroarch_debug.exe file onto the drmemory.exe file there. No re-compilation is necessary to use this tool. Any errors encountered will be displayed in a notepad window after the program exits or crashes.

VulnScan (Windows/Linux)Link

Also known as Microsoft Security Risk Detection, is a new memory error detection tool that is (at the time of writing) in closed beta status. For more information, please see its website here.

Valgrind (Linux)Link

Valgrind is probably the oldest and most well known memory error and leak detector available. Here is an example command-line usage to run valgrind with RetroArch to check for memory or threading errors:

valgrind -v --tool=memcheck --leak-check=yes --track-origins=yes --show-reachable=yes ./retroarch

No recompilation is necessary to use this tool, but make sure to run it using a debug build of RetroArch (built with make DEBUG=1). Some users have reported a large number of false positives with this tool, as well as much slower runtime performance, so in general we typically recommend to use ASAN instead if that is an option for you.

rr (Linux)Link

rr is a deterministic debugger that enhances gdb by supporting the recording and replay (and even reverse-replay) of your program's execution. Very useful for accurately reproducing a hard-to-trigger issue such as a race condition or crash that only occurs under certain conditions.

For more information on using rr, please see their usage guide here.

Time Travel Debugging (Windows)Link

Time Travel Debugging is a Windows tool for recording and replaying a program's execution, similar to rr. For more information, please visit their website.