# Debugging

Wikipedia has an article about:
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.

Contents

1 GDB

1.1 Attach to an already running process
1.2 Run executable from within GDB

2 Fuzzer

GDB

Unix manual for gdb:
FreeBSD
NetBSD
OpenBSD
Linux

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&nbsp;+ 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&nbsp;+ 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.