Creating a GDB stacktrace
From time to time, this happens to all good programs, and SMC is not an exception: it crashes. Crashes are usually the result of some coding error and are hence to be qualified as a bug that needs to be fixed for a future version. However, developers can’t fix what they can’t see. So, if you get a crash with SMC and you want to have it fixed to make it disappear, you should provide a stacktrace to the developers in your bug report. A stacktrace is the complete function call chain at a given point of runtime in the program.
For creating a stacktrace you will need to have GDB, the GNU Debugger, installed. Get it from your Linux distributor’s package repository, e.g. for Ubuntu:
# apt-get install gdb
For Windows, you have to install MinGW and install GDB inside MinGW.
Next, you need a version of SMC that contains debugging symbols. These are special builds that have the file and line information attached to all the functions in SMC, and this information is required for the developers to find the place in the code where everything blows up. Currently, as we do not yet have reached version 2.0.0 final, all precompiled binaries available from the SMC team have this debugging information (and hence are huge, usually way over 100 MiB), so you don’t have to worry about that. If you compile SMC yourself from the sourcecode, be sure you do it like this or a smiliar way:
$ cmake -DCMAKE_INSTALL_PREFIX=$PWD/testinstall -DCMAKE_BUILD_TYPE=Debug ..
The essential part here is the -DCMAKE_BUILD_TYPE=Debug flag which tells cmake to compile SMC with gcc’s -g switch, which in turn adds the debugging information to the symbols.
Also, in order to ease switching between SMC and GDB, you want to configure SMC to run in windowed mode rather than fullscreen mode.
Creating the stacktrace
First you need to find out where your smc binary is. For now, let’s assume it’s in
/opt/smc/bin/smc; on your box it will certainly be somewhere else.
Open a terminal (on Windows you want to open the MinGW environment shell or an MSYS shell) and run
$ gdb /opt/smc/bin/smc GNU gdb (GDB) 7.7.1 Copyright (C) 2014 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "x86_64-unknown-linux-gnu". Type "show configuration" for configuration details. For bug reporting instructions, please see: <http://www.gnu.org/software/gdb/bugs/>. Find the GDB manual and other documentation resources online at: <http://www.gnu.org/software/gdb/documentation/>. For help, type "help". Type "apropos word" to search for commands related to "word". Reading symbols from /opt/smc/bin/smc...done. (gdb)
(gdb) is the GDB prompt. You now issue the run command to start SMC.
(gdb) run Starting program: /opt/smc/bin/smc warning: Could not load shared library symbols for linux-vdso.so.1. Do you need "set solib-search-path" or "set sysroot"? [Thread debugging using libthread_db enabled] Using host libthread_db library "/usr/lib/libthread_db.so.1". Initializing resource manager and core classes Game data directory: /opt/smc/share/smc User data directory: /home/quintus/.local/share/smc User cache directory: /home/quintus/.cache/smc User config directory: /home/quintus/.config/smc Configuration file is '/home/quintus/.config/smc/config.xml'. Translation locale is de_DE.UTF-8 ...
Now reproduce your crash. When SMC crashes, the window will freeze and you will see something like this in GDB’s interface:
Program received SIGSEGV, segmentation fault. (gdb)
Issue the bt command in order to obtain the stacktrace.
(gdb) bt #0 0x00007ffff57cdd2d in nanosleep () from /usr/lib/libpthread.so.0 #1 0x00007ffff5a309a5 in SDL_Delay () from /usr/lib/libSDL-1.2.so.0 #2 0x000000000069e636 in SMC::Correct_Frame_Time (fps=100) at /home/quintus/repos/privat/projekte/c++/SMC/smc/src/core/framerate.cpp:208 #3 0x0000000000675439 in SMC::Update_Game () at /home/quintus/repos/privat/projekte/c++/SMC/smc/src/core/main.cpp:640 #4 0x000000000067400c in main (argc=1, argv=0x7fffffffe8e8) at /home/quintus/repos/privat/projekte/c++/SMC/smc/src/core/main.cpp:207 (gdb)
This is the stacktrace information you need to supply to the developers. It tends to vary in length, so be careful to copy the entire stacktrace, starting with the line that begins with
#0 and finishing with the line that immediately preceeds the following
In order to leave the debugging session, use quit.
(gdb) quit A debugging session is active. Inferior 1 [process 5659] will be killed. Quit anyway? (y or n) y