6.26.7 Debugging

Languages with a slow edit/compile/link/test development loop tend to require sophisticated tracing/stepping debuggers to facilate debugging.

A much better (faster) way in fast-compiling languages is to add printing code at well-selected places, let the program run, look at the output, see where things went wrong, add more printing code, etc., until the bug is found.

The simple debugging aids provided in debugs.fs are meant to support this style of debugging.

The word ~~ prints debugging information (by default the source location and the stack contents). It is easy to insert. If you use Emacs it is also easy to remove (C-x ~ in the Emacs Forth mode to query-replace them with nothing). The deferred words printdebugdata and .debugline control the output of ~~. The default source location output format works well with Emacs’ compilation mode, so you can step through the program at the source level using C-x ` (the advantage over a stepping debugger is that you can step in any direction and you know where the crash has happened or where the strange data has occurred).

~~ ( ) gforth-0.2 “tilde-tilde”

Prints the source code location of the ~~ and the stack contents with .debugline.

printdebugdata ( ) gforth-0.2 “print-debug-data”
.debugline ( nfile nline –  ) gforth-0.6 “print-debug-line”

Print the source code location indicated by nfile nline, and additional debugging information; the default .debugline prints the additional information with printdebugdata.

debug-fid ( – file-id  ) gforth-1.0 “File-id

debugging words for output. By default it is the process’s stderr.

~~ (and assertions) will usually print the wrong file name if a marker is executed in the same file after their occurance. They will print ‘*somewhere*’ as file name if a marker is executed in the same file before their occurance.

once ( ) gforth-1.0 “once”

do the following up to THEN only once

~~bt ( ) gforth-1.0 “~~bt”

print stackdump and backtrace

~~1bt ( ) gforth-1.0 “~~1bt”

print stackdump and backtrace once

??? ( ) gforth-0.2 “???”

Open a debuging shell

WTF?? ( ) gforth-1.0 “WTF??”

Open a debugging shell with backtrace and stack dump

!!FIXME!! ( ) gforth-1.0 “!!FIXME!!”

word that should never be reached

replace-word ( xt1 xt2 –  ) gforth-1.0 “replace-word”

make xt2 do xt1, both need to be colon definitions

~~Variable ( "name" –  ) gforth-1.0 “~~Variable”

Variable that will be watched on every access

~~Value ( n "name" –  ) gforth-1.0 “~~Value”

Value that will be watched on every access

+ltrace ( ) gforth-1.0 “+ltrace”

turn on line tracing

-ltrace ( ) gforth-1.0 “-ltrace”

turn off line tracing

#loc ( nline nchar "file" –  ) gforth-1.0 “#loc”

set next word’s location to nline nchar in "file"