Debugging - Revision history

Phol ende wodan: /* Fuzzer */ 3.7: nethack --debug:fuzzer on command line

2026-01-24T01:50:37Z

‎Fuzzer: 3.7: nethack --debug:fuzzer on command line

Phol ende wodan: /* Fuzzer */ put upcoming block; mention easier way to enter the fuzzer

2026-01-23T22:06:57Z

‎Fuzzer: put upcoming block; mention easier way to enter the fuzzer

K2: /* Run executable from within GDB */ frame command

2025-03-06T23:53:09Z

‎Run executable from within GDB: frame command

Testbutt: big old news

2021-10-06T12:12:02Z

big old news

Aximili: Add man page link

2020-03-20T04:32:49Z

Add man page link

Paxed: striped table

2011-10-01T09:53:19Z

striped table

Paxed: +cat

2011-02-15T15:33:41Z

+cat

Paxed: add 'bt' command

2011-02-13T15:28:20Z

add 'bt' command

Paxed: first info dump

2011-02-13T11:06:07Z

first info dump

New page

{{wikipedia|Debugging}}
'''Debugging''' helps finding [[bug]]s in the code, or allows [[cheat]]ing 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 <tt>ps f -A</tt>
*Run <tt>gdb --pid=XXX</tt>, where XXX is the process ID.
*You will now be in the gdb command line; to let the game continue, type <tt>continue</tt> and press enter.

===Run executable from within GDB===
*Start gdb by typing <tt>gdb</tt>, which will bring you into the gdb command line.
*Set arguments you want to give to NetHack, for example <tt>set args -D -u yourname</tt>
*Set the HACKDIR [[environment variable]], for example <tt>set environment HACKDIR ./</tt>
*Load the executable, for example <tt>file nethack</tt>
*Start the executable with <tt>run</tt>

While a program is being run, you can type {{kbd|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)

{|class="prettytable"
!colspan="2"|GDB Commands
|-
|<tt>continue</tt>
|Continue the program being debugged. (You might need to do {{kbd|ctrl|l}} to refresh the screen)
|-
|<tt>quit</tt>
|Quit gdb.
|-
|<tt>step</tt>
|Execute one (source-code) line of the program.
|-
|<tt>next</tt>
|Like <tt>step</tt>, but does not go into subroutines.
|-
|<tt>finish</tt>
|Execute to the end of the current subroutine.
|-
|<tt>print flags.debug</tt>
|Shows the current value of a variable (in this example, {{sourcecode|Flag.h|34}}). Can also print complex structures, for example <tt>print *invent</tt> or <tt>print u</tt>.
|-
|<tt>set flags.debug = 1</tt>
|Set the value of a variable (in this example, makes NetHack believe the game is in [[wizard mode]]).
|-
|<tt>break dopickup</tt>
|Set a break point on function {{sourceref|dopickup}}. When NetHack next executes that function, gdb will stop NetHack and return to the gdb command line.
|-
|<tt>clear dopickup</tt>
|Clears any break points set on function dopickup().
|-
|<tt>help</tt>
|Shows help for gdb commands.
|}

[[Category:Annotations]]
[[Category:Development]]

@@ Line 72: / Line 72: @@
 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 from within a wizard-mode game by running the #debugfuzzer command. 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.
+The fuzzer can be entered in several ways:
 [[Category:Annotations]]
 [[Category:Development]]
 [[Category:Utilities]]

@@ Line 68: / Line 68: @@
 ==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.
+The fuzzer can be entered from within a wizard-mode game by running the #debugfuzzer command. 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.
 [[Category:Annotations]]
 [[Category:Development]]
 [[Category:Utilities]]

@@ Line 58: / Line 58: @@
 |-
 |<tt>bt</tt>
-|Shows a backtrace (a list of called functions).
+|Shows a backtrace (a list/frame count of called functions, also known as a 'call stack').
 |-
 |<tt>help</tt>
 |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.

← Older revision		Revision as of 04:32, 20 March 2020
Line 5:		Line 5:

	==GDB==		==GDB==
		+	{{man\|gdb}}
	First make sure NetHack has been compiled with the debugging flag '''-g''' (CFLAGS in src/Makefile should include -g)		First make sure NetHack has been compiled with the debugging flag '''-g''' (CFLAGS in src/Makefile should include -g)

← Older revision		Revision as of 15:33, 15 February 2011
Line 65:		Line 65:
	[[Category:Annotations]]		[[Category:Annotations]]
	[[Category:Development]]		[[Category:Development]]
		+	[[Category:Utilities]]

@@ Line 26: / Line 26: @@
   (gdb)
-{|class="prettytable"
+{|class="prettytable striped"
 !colspan="2"|GDB Commands
 |-

@@ Line 55: / Line 55: @@
 |<tt>clear dopickup</tt>
 |Clears any break points set on function dopickup().
 |-
 |<tt>help</tt>