debug-package: How to use the debug package

Description

debug is an alternative to trace and browser, offering:

a visible code window with line-numbered code and highlighted execution point;
the ability to set (conditional) breakpoints in advance, at any line number;
the opportunity to keep going after errors;
multiple debugging windows open at once (when one debuggee calls another, or itself);
full debugging ofon.exitcode;
the ability to move the execution point around without executing intervening statements;
direct interpretation of typed-in statements, as if they were in the function itself.

Even if you don't write functions, or even if you don't write buggy functions, you may find it helpful to run the debugger on functions in package:base or other packages. Watching what actually happens while a function is executing, can be much more informative than staring at a piece of code or terse documentation. Debugging your function f is a two-stage process. First, call mtrace(f) to store debugging information on f, and to overwrite f with a debug-ready version that will call the debugger itself. Second, do whatever you normally do at the command prompt to invoke f. This is often a direct call to f, but can be any command that eventually results in f being invoked. [The third, fourth, etc. stages, in which you actually fix the problem, are not covered here!] When f is invoked, a window will appear at the bottom of the screen, showing the code of f with a highlight on the first numbered line. (There is also an asterisk in the far left hand column of the same row, showing that there's a breakpoint.) The command prompt in R{} will change to "D(...

Arguments

code

from

itemize

useskipto move to the start of the exit code;
then usego(n)to run to the final NULL in the exit code;
then useqqq()to finish debugging.

pkg

mvbutils

Special functions

Certain system functions with "code" arguments are handled specially in step-mode: currently try, eval, evalq and with (see below for within). In step-mode only, the code in these is stepped-into by default if it is more than a simple statement, using a new code window. In go-mode, and in step-mode if the default behaviour has been changed, these functions are handled entirely by R{}. Hence, if you are in go-mode and an error occurs in one of these statements, the debugger will stop at the with etc. statement, not inside it; but you can step inside by pressing . The step-into-in-step-mode behaviour can be controlled globally using step.into.funs. To avoid step-in at a specific line, you can also just use go to proceed to the following statement; this can be much faster than first stepping-in and then calling go, because R{} itself handles the evaluation. To mimic the true behaviour of try, the debugger should really just return a try-error if there is an error. However, that is probably not what you want when debugging. Instead, the debugger just behaves as usual with errors, i.e. it breaks into step-mode. If you do then want try to return the try-error, just as it would if you weren't debugging, type return( last.try.error()). Note that the code window for with etc. contains an on-exit block, just like normal debugger code windows. Its main use is probably to let you set a breakpoint-on-return. However, it seems that you can successfully put on.exit statements inside your eval etc. call, whether debugging or not. For within, just mtrace( within.data.frame), assuming you're about to apply it to a data.frame.

Options

As of version 1.2.0, output is sent by default to "stderr"; this means that you get to see the step-mode output even if the debuggee is redirecting "real" output (e.g. via sink). If you don't like this (and I believe Tinn-R doesn't), set options( debug.catfile="stdout"). Command recall is ON by default, but this means that anything typed while debugging will also be seen in history() after leaving the debugger. If this is a problem, set options( debug.command.recall=FALSE) (probably in .First). In step mode, only objects with object.size < 8192 bytes will be printed in full by default; for larger objects, a summary is given instead. You can force printing of any individual object via print, but you can also increase (or decrease) the threshold to X bytes, by setting options( threshold.debug.autoprint.size=X). Various TCL/TK-related aspects of the code window can be altered:

tab.widthdefaults to 4, for indenting code lines (not related to TCL/TK)
debug.fontdefaults to "Courier"; try e.g. ="Courier 24 italic"
debug.height(in lines) defaults to 10
debug.width(in characters) defaults to 120
debug.screen.posdefaults to "+5-5" for BL corner; try "-5-5" for BR, "-5+5" for TR, "+5+5" for TL.
debug.fgis foreground text colour, defaulting toblack