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/frame count of called functions, also known as a 'call stack'). |
| frame | Selects a stack frame or displays the currently selected stack frame. Use after executing 'bt' (backtrace) to load a specific frame to obtain values of certain variables in the selected frame. Example frame 1. |
| help | Shows help for gdb commands. |
Fuzzer
The following information pertains to an upcoming version (NetHack 3.7.0). If this version is now released, please verify that the information below is still accurate, then update the page to incorporate it.
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.
The fuzzer can be entered in several ways:
- Start a game in wizard mode normally, and run the #debugfuzzer command.
- Run nethack with the --debug:fuzzer command line option. This can be combined with -D to run the game in wizard mode, and separately -@ to skip initial character selection.
Should you wish to stop the fuzzer at any point, and are running it within GDB, you can break out of the game flow with Ctrl-C, set iflags.debug_fuzzer = 0, and continue.
