Debugging
Debugging helps finding bugs in the code, or allows cheating in the manner of "memory cheats".
On Linux, you most likely want to use the GNU Debugger, or gdb.
GDB
First make sure NetHack has been compiled with the debugging flag -g (CFLAGS in src/Makefile should include -g)
You can start gdb in two different ways: attach to an already running process, or start gdb and run the executable from it.
Attach to an already running process
- Find the process ID, for example with ps f -A
- Run gdb --pid=XXX, where XXX is the process ID.
- You will now be in the gdb command line; to let the game continue, type continue and press enter.
Run executable from within GDB
- Start gdb by typing gdb, which will bring you into the gdb command line.
- Set arguments you want to give to NetHack, for example set args -D -u yourname
- Set the HACKDIR environment variable, for example set environment HACKDIR ./
- Load the executable, for example file nethack
- Start the executable with run
While a program is being run, you can type ctrl + c at any time to get to the gdb command line, where you can type commands to the gdb. You should then see something like this on the screen:
Program received signal SIGINT, Interrupt. 0xb778d424 in __kernel_vsyscall () (gdb)
| GDB Commands | |
|---|---|
| continue | Continue the program being debugged. (You might need to do ctrl + l to refresh the screen) |
| quit | Quit gdb. |
| step | Execute one (source-code) line of the program. |
| next | Like step, but does not go into subroutines. |
| finish | Execute to the end of the current subroutine. |
| print flags.debug | Shows the current value of a variable (in this example, Flag.h, line 34). Can also print complex structures, for example print *invent or print u. |
| set flags.debug = 1 | Set the value of a variable (in this example, makes NetHack believe the game is in wizard mode). |
| break dopickup | Set a break point on function dopickup. When NetHack next executes that function, gdb will stop NetHack and return to the gdb command line. |
| clear dopickup | Clears any break points set on function dopickup(). |
| bt | Shows a backtrace (a list of called functions). |
| help | Shows help for gdb commands. |
Fuzzer
The "fuzzer" is a relatively new utility for NetHack development. It automates the sending of many random commands into the game window, which can help test the game in ways that would take a long time to expose via regular gameplay.
One way to "launch" the fuzzer is to start gdb, launch the game, break out with ^c, set iflags.debug_fuzzer = 1, then continue.
