Source Level Debugging
======================

Maxima has source level capabilities.  A user can set a breakpoint at a line in a file, and then step line by line from there.  The call stack may be examined, together with the variables bound at that level.  If the user is running the code under GNU emacs in a shell window (dbl shell), or is running xmaxima the graphical interface version, then if he stops at a break point, he will see his current position in the source file which will be displayed in the other half of the window, either highlighted in red, or with a little arrow pointing at the right line.  He can advance single lines at a time by typing M-n (Alt-n) or alternately by entering :n.  To see the names of the keyword commands type :help (or :h).  In general commands may be abbreviated if the abbreviation is unique.  If not unique the alternatives will be listed.

Under Emacs you should run in a dbl shell, which requires the dbl.el file in the elisp directory. Make sure you install the elisp files or add the maxima elisp directory to your path: eg add the following to your .emacs file or the site-init.el

     (setq load-path (cons "/usr/local/maxima-5.5/elisp" load-path))
     (autoload 'dbl "dbl")

then in emacs

     M-x dbl

should start a shell window in which you can run programs, for example maxima, gcl, gdb etc.   This shell window also knows about source level debugging, and display of source code in the other window.

     maxima
     Maxima 5.5 Wed Apr 18 19:02:00 CDT 2001 (with enhancements by W. Schelter).
     Licensed under the GNU Public License (see file COPYING)
     (C1) batchload("/tmp/joe.mac");
     (D1) 				 /tmp/joe.mac
     (C2) :br joe
     Turning on debugging debugmode(true)
     Bkpt 0 for joe (in /tmp/joe.mac line 8)
     (C2) foo(2,3);
     Bkpt 0:(joe.mac 8)
     (dbm:1) :bt                        <-- :bt typed here gives a backtrace
     #0: joe(y=5)(joe.mac line 8)
     #1: foo(x=2,y=3)(joe.mac line 5)
     (joe.mac 9)                        <-- Here type M-n to advance line
     (joe.mac 10)                       <-- Here type M-n to advance line
                                        In the other buffer the source code
                                        appears with an arrow.
     (dbm:1) u;                         Investigate value of 'u
     28
     (dbm:1) u:33;                      Alter it to be 33
     (dbm:1) :r                         :r Resumes the computation
     (D3) 				     1094

The actual file /tmp/joe.mac is the following:

     foo(x,y):=(
       x:x+2,
       y:y+2,
       x:joe(y),
       x+y);

     joe(y):=block([u:y^2],
       u:u+3,
       u:u^2,
        u);

If you are running in Gnu Emacs then if you are looking at the file joe.mac, you may set a break point at a certain line of that file by typing C-x space.  This figures out which function your cursor is in, and then it sees which line of that function you are on.   If you are on say line 2 of joe, then it will insert in the other window :br joe 2 the command to break joe at its second line.   To have this enabled you must have maxima-mode.el on in the window in which the file joe.mac is visiting. There are additional commands available in that file window, such as evaluating the function into the maxima, by typing Alt-Control-x

Keyword Commands
================

Break commands start with ':'.   Thus to evaluate a lisp form you may type :lisp  followed by the argument which is the form to be evaluated.

     (C3) :lisp (+ 2 3)
     5

The number of arguments taken depends on the particular command.  Also you need not type the whole command, just enough to be unique among the keyword commands.   Thus :br would suffice for :break. The current commands are:

:break
     Set a breakpoint in the specified FUNCTION at the specified LINE offset from the beginning of the function. If FUNCTION is given as a string, then it is presumed to be a FILE and LINE is the offset from the beginning of the file.

:bt
     Undocumented

:continue
     Continue the computation.

:delete
     Delete all breakpoints, or if arguments are supplied delete the specified breakpoints

:disable
     Disable the specified breakpoints, or all if none are specified

:enable
     Enable the specified breakpoints, or all if none are specified

:frame
     With an argument print the selected stack frame. Otherwise the current frame.

:help
     Print help on a break command or with no arguments on all break commands

:info
     Undocumented

:lisp
     Evaluate the lisp form following on the line

:lisp-quiet
     Evaluate its arg as a lisp form without printing a prompt.

:next     Like :step, except that subroutine calls are stepped over

:quit
     Quit this level

:resume
     Continue the computation.

:step
     Step program until it reaches a new source line

:top
     Throw to top level

Definitions for Debugging
=========================

 -- Variable: REFCHECK
     default: [FALSE] - if TRUE causes a message to be printed each time a bound variable is used for the first time in a computation.

 -- Function: REMTRACE ()
     This function is no longer used with the new TRACE package.

 -- Variable: SETCHECK
     default: [FALSE] - if set to a list of variables (which can be subscripted) will cause a printout whenever the variables, or subscripted occurrences of them, are bound (with : or :: or function argument binding).  The printout consists of the variable and the value it is bound to.  SETCHECK may be set to ALL or TRUE thereby including all variables.  Note: No printout is generated when a SETCHECKed variable is set to itself, e.g. X:'X.

 -- Variable: SETCHECKBREAK
     default: [FALSE] - if set to TRUE will cause a (MACSYMA-BREAK) to occur whenever the variables on the SETCHECK list are bound.  The break occurs before the binding is done.  At this point, SETVAL holds the value to which the variable is about to be set.  Hence, one may change this value by resetting SETVAL.

 -- Variable: SETVAL
     - holds the value to which a variable is about to be set when a SETCHECKBREAK occurs.  Hence, one may change this value by resetting SETVAL.  (See SETCHECKBREAK).

 -- Function: TIMER (F)
     will put a timer-wrapper on the function F, within the TRACE package, i.e. it will print out the time spent in computing F.

 -- Variable: TIMER_DEVALUE
     default: [FALSE] - when set to TRUE then the time charged against a function is the time spent dynamically inside the function devalued by the time spent inside other TIMED functions.

 -- Function: TIMER_INFO (F)
     will print the information on timing which is stored also as GET('F,'CALLS); GET('F,'RUNTIME); and GET('F,'GCTIME); .  This is a TRACE package function.

 -- Function: TRACE (name1, name2, ...)
     gives a trace printout whenever the functions mentioned are called.  TRACE() prints a list of the functions currently under TRACE.  On MC see MACDOC;TRACE USAGE for more information.  Also, DEMO("trace.dem"); .  To remove tracing, see UNTRACE.

 -- Function: TRACE_OPTIONS (F,option1,option2,...)
     gives the function F the options indicated.  An option is either a keyword or an expression. The possible Keywords are: Keyword     Meaning of return value ---------------------------------------- NOPRINT     If TRUE do no printing. BREAK       If TRUE give a breakpoint. LISP_PRINT  If TRUE use lisp printing. INFO        Extra info to print. ERRORCATCH  If TRUE errors are caught. A keyword means that the option is in effect.  Using a keyword as an expression, e.g. NOPRINT(predicate_function) means to apply the predicate_function (which is user-defined) to some arguments to determine if the option is in effect. The argument list to this predicate_function is always [LEVEL, DIRECTION, FUNCTION, ITEM] where LEVEL is the recursion level for the function.  DIRECTION is either ENTER or EXIT.  FUNCTION is the name of the function.  ITEM is either the argument list or the return value.  On MC see DEMO("trace.dem"); for more details.

 -- Function: UNTRACE (name1, ...)
     removes tracing invoked by the TRACE function. UNTRACE() removes tracing from all functions.