Advanced Debugging
Contents
WARNING: THIS IS JUST AN OUTDATED / IN PROGRESS OF BEING REWORKED GUIDE HERE TO CONSERVE IT IN CASE THE OLD WIKI BECOMES UNAVAILABLE. DO NOT LINK TO IT
Unpack it so you have C:\mingw64\bin\gdb.exe (different path is ok but you have to adjust it later and it shouldnt contain any special characters or spaces).
Open your ToME folder and create a textfile in it with the content: C:\mingw64\bin\gdb.exe t-engine.exe pause
Save it, and rename it to debug.bat (make sure your file names are showing the ending so you can change it or it will stay a text file).
Doubleclick the debug.bat.
It should show some text and end with "<gdb>". Write "run" (without "") and press enter. This should start the game.
If the game crashes, type info stack to get a stack trace of the issue (apparently backtrace works well too).
Post the stack trace. You can copy text from the command window by right-clicking, selecting "Mark" from the menu, dragging a box around the text you want to copy and then right-clicking again. You can then paste the text into a forum post.
Locate gdb.txt in the tome directory, and send that.
When finished, type quit to exit out of GDB.
As I dont have a crashing game I couldnt test all of this, so please tell me if anything is not working as described.
Running ToME with GDB
GDB is a debugging tool that can help the developers of Tome track down difficult bugs. If you find something that makes the game crash, you can help out by catching this crash inside a GDB session and sending the details to the dev team. This will pinpoint the section of code which caused the crash, allowing the team to focus on the source of the problem.
Installing and using GDB on Windows
Download it from the MinGW GDB sourceforge download page Install it by creating a directory at C:\MinGW\ and extracting the archive to this location (other MinGW software installs itself to this location automatically so it is good to keep it all together) Open a command prompt inside your tome4 directory and load t-engine.exe into GDB by typing this: C:\mingw\bin\gdb.exe t-engine.exe Run the game by simply typing run If the game crashes, type info stack to get a stack trace of the issue (apparently backtrace works well too) Send the stack trace to the developers or post it on the forum. Locate gdb.txt in the tome directory, and send that, or You can copy text from the command window by right-clicking, selecting "Mark" from the menu, dragging a box around the text you want to copy and then right-clicking again. You can then paste the text into a forum post. When finished, type quit to exit out of GDB At the time of writing, the latest version of GDB available on the download page is gdb-7.1-2-mingw32-bin.tar.gz
tome4 user reenen: Any way I can save the stack trace to a .txt file? It kinda sucks that I got to manually copy and paste it. (via a cmd shell which is extremely sucky in windows)
tome4 user shoob: Yes, use **set logging on** before you type **run**, it will copy the log to gdb.txt (edited the above to show this too)
tome4 user netzakh: Notes on installing and running GDB as of 20100628: MinGW installer does NOT include GDB; GDB requires libexpat-1.dll, which is NOT included into either the GDB tarball or MinGW installation so it has to be downloaded separately from the expat subfolder; backtrace can be followed by a number //n// to show first //n// calls in the stack.
Using gdb on Linux
If you're running...
Gentoo See "Segmentation fault" (Is That Good?) under Gentoo.
Other This applies equally well to any other Unix-like system (FreeBSD, etc.). Installing gdb is generally trivial (use your operating system's package manager or ports system, or build it directly from upstream source if necessary). There are too many Unix-like variants to cover installation here.
There are a few different ways to use gdb to help debug ToME. The first is to attach to a "running" (or stuck) ToME process at need. Open up a terminal window. If you can't open a terminal for some reason, you can ssh or telnet in from another machine. You'll need to be the same user who's running t-engine. Find the process ID of the running (or stuck) t-engine process. On most systems, the easiest way to do this is pgrep t-engine but if that doesn't work, you can try ps auxw | grep t-engine or ps -ef | grep t-engine instead. Change directory to wherever you would normally be sitting when you launch t-engine. Type gdb path/to/t-engine (for example gdb ./bin/Debug/t-engine). This tells gdb to load the program into memory, but will not execute it. At the (gdb) prompt, type attach PID where PID is the process ID of the t-engine process. Use bt or any other gdb commands you need (see the Windows section above for general tips).
Another way is to run ToME under gdb's control from the start. This is overkill most of the time, and has been known to cause an occasional problem that doesn't actually happen when running normally. However, for certain extremely rare problems, this has a chance of catching the problem as it happens, before the stack has been irrevocably corrupted.
Instead of running ./bin/Debug/t-engine >>logfile 2>&1, run gdb ./bin/Debug/t-engine (note that you don't put any redirections on the gdb line).
At the (gdb) prompt, type run >>logfile 2>&1 (or whatever redirections you would normally have used from the shell prompt). If t-engine took any command-line arguments, they would also go here, rather than on the gdb command.
