From NetHackWiki
Jump to navigation Jump to search

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.


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 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.


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.