<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
from maxima.texi on 25 April 2001 -->
<TITLE>Maxima Manual - Debugging</TITLE>
<link href="maxima_40.html" rel=Next>
<link href="maxima_38.html" rel=Previous>
<link href="maxima_toc.html" rel=ToC>
</HEAD>
<BODY>
<p>Go to the <A HREF="maxima_1.html">first</A>, <A HREF="maxima_38.html">previous</A>, <A HREF="maxima_40.html">next</A>, <A HREF="maxima_41.html">last</A> section, <A HREF="maxima_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC125" HREF="maxima_toc.html#TOC125">Debugging</A></H1>
<H2><A NAME="SEC126" HREF="maxima_toc.html#TOC126">Source Level Debugging</A></H2>
<P>
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 <CODE>xmaxima</CODE> 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 <CODE>:n</CODE>. 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.
</P>
<P>
Under Emacs you should run in a <CODE>dbl</CODE> 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 <TT>`.emacs'</TT> file or the <CODE>site-init.el</CODE>
</P>
<PRE>
(setq load-path (cons "/usr/local/maxima-5.5/elisp" load-path))
(autoload 'dbl "dbl")
</PRE>
<P>
then in emacs
<PRE>
M-x dbl
</PRE>
<P>
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.
</P>
<PRE>
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
</PRE>
<P>
The actual file /tmp/joe.mac is the following:
<PRE>
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);
</PRE>
<P>
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 <CODE>C-x space</CODE>. 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 <CODE>:br joe 2</CODE> 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 <CODE>Alt-Control-x</CODE>
</P>
<H2><A NAME="SEC127" HREF="maxima_toc.html#TOC127">Keyword Commands</A></H2>
<P>
Break commands start with ':'. Thus to evaluate a lisp form you
may type <CODE>:lisp </CODE> followed by the argument which is the form
to be evaluated.
<PRE>
(C3) :lisp (+ 2 3)
5
</PRE>
<P>
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 <CODE>:br</CODE> would suffice for <CODE>:break</CODE>.
The current commands are:
</P>
<DL COMPACT>
<DT><CODE>:break</CODE>
<DD>
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.
<DT><CODE>:bt</CODE>
<DD>
Undocumented
<DT><CODE>:continue</CODE>
<DD>
Continue the computation.
<DT><CODE>:delete</CODE>
<DD>
Delete all breakpoints, or if arguments are supplied delete the specified
breakpoints
<DT><CODE>:disable</CODE>
<DD>
Disable the specified breakpoints, or all if none are specified
<DT><CODE>:enable</CODE>
<DD>
Enable the specified breakpoints, or all if none are specified
<DT><CODE>:frame</CODE>
<DD>
With an argument print the selected stack frame.
Otherwise the current frame.
<DT><CODE>:help</CODE>
<DD>
Print help on a break command or with no arguments on all break commands
<DT><CODE>:info</CODE>
<DD>
Undocumented
<DT><CODE>:lisp</CODE>
<DD>
Evaluate the lisp form following on the line
<DT><CODE>:lisp-quiet</CODE>
<DD>
Evaluate its arg as a lisp form without printing a prompt.
<DT><CODE>:next Like :step, except that subroutine calls are stepped over</CODE>
<DD>
<DT><CODE>:quit</CODE>
<DD>
Quit this level
<DT><CODE>:resume</CODE>
<DD>
Continue the computation.
<DT><CODE>:step</CODE>
<DD>
Step program until it reaches a new source line
<DT><CODE>:top</CODE>
<DD>
Throw to top level
</DL>
<H2><A NAME="SEC128" HREF="maxima_toc.html#TOC128">Definitions for Debugging</A></H2>
<P>
<DL>
<DT><U>Variable:</U> <B>REFCHECK</B>
<DD><A NAME="IDX957"></A>
default: [FALSE] - if TRUE causes a message to be printed
each time a bound variable is used for the first time in a
computation.
</P>
</DL>
<P>
<DL>
<DT><U>Function:</U> <B>REMTRACE</B> <I>()</I>
<DD><A NAME="IDX958"></A>
This function is no longer used with the new TRACE
package.
</P>
</DL>
<P>
<DL>
<DT><U>Variable:</U> <B>SETCHECK</B>
<DD><A NAME="IDX959"></A>
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.
</P>
</DL>
<P>
<DL>
<DT><U>Variable:</U> <B>SETCHECKBREAK</B>
<DD><A NAME="IDX960"></A>
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.
</P>
</DL>
<P>
<DL>
<DT><U>Variable:</U> <B>SETVAL</B>
<DD><A NAME="IDX961"></A>
- 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).
</P>
</DL>
<P>
<DL>
<DT><U>Function:</U> <B>TIMER</B> <I>(F)</I>
<DD><A NAME="IDX962"></A>
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.
</P>
</DL>
<P>
<DL>
<DT><U>Variable:</U> <B>TIMER_DEVALUE</B>
<DD><A NAME="IDX963"></A>
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.
</P>
</DL>
<P>
<DL>
<DT><U>Function:</U> <B>TIMER_INFO</B> <I>(F)</I>
<DD><A NAME="IDX964"></A>
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.
</P>
</DL>
<P>
<DL>
<DT><U>Function:</U> <B>TRACE</B> <I>(name1, name2, ...)</I>
<DD><A NAME="IDX965"></A>
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.
</P>
</DL>
<P>
<DL>
<DT><U>Function:</U> <B>TRACE_OPTIONS</B> <I>(F,option1,option2,...)</I>
<DD><A NAME="IDX966"></A>
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.
</P>
</DL>
<P>
<DL>
<DT><U>Function:</U> <B>UNTRACE</B> <I>(name1, ...)</I>
<DD><A NAME="IDX967"></A>
removes tracing invoked by the TRACE function.
UNTRACE() removes tracing from all functions.
</P>
</DL>
<P><HR><P>
<p>Go to the <A HREF="maxima_1.html">first</A>, <A HREF="maxima_38.html">previous</A>, <A HREF="maxima_40.html">next</A>, <A HREF="maxima_41.html">last</A> section, <A HREF="maxima_toc.html">table of contents</A>.
</BODY>
</HTML>
