CoCreate Modeling FAQ: Debugging Lisp code in CoCreate Modeling

topic end
<!--
   * Set TOPICTITLE = <nop>CoCreate Modeling FAQ: Debugging Lisp code in <nop>CoCreate Modeling
-->

---++!! <nop>CoCreate Modeling FAQ: Debugging Lisp code in <nop>CoCreate Modeling
%TOC%

<style type="text/css">
pre { background-color:#FFEECC; }
</style>



---
#EnableDebugger
---+++ %ENGLISH% How do I activate the Lisp debugger?

By default, the Lisp debugger is disabled in release versions of <nop>CoCreate Modeling.
Instead, when a Lisp error occurs, it is reported in a "Lisp error" message box.

To enable the debugger, enter the following in the user input line:
<pre>
  (setf si::*enter-break-handler* t)
</pre>

-- Main.ClausBrod, 21 December 2006

---
#UsingTheDebugger
---+++ %ENGLISH% How do I use the Lisp debugger?

With the break handler enabled as [[#EnableDebugger][shown above]], 
Lisp errors will activate the Lisp
debugger. This debugger is command-line based; it allows to list
stack backtraces, inspect local and global variables, manipulate
symbols and variables, call your own Lisp code to view data
structures et cetera. In fact, you can call _any_ Lisp code from
the debugger prompt!

As an example, define the following function:

<pre>
 (defun testfn(x y)
    (print x)
    (print foobar)
    (print y))
</pre>

Load the function and run it. You will now get the usual
error message box. Click "OK". The prompt line now reads

<pre>
  [1]: Enter break command</tt>
</pre>

which indicates that the Lisp break handler is now active. The Lisp error
message from the error box is also echoed to standard output,
so the console window says something like

<pre>
Error: LISP error:
MEI::TESTFN requires two arguments,
       but only zero were supplied.
Signalled by MEI::TESTFN
Broken at MEI::TESTFN.  Type :H for Help.
</pre>

<img src="%ATTACHURL%/debuggerprompt.jpg" alt="Debugger prompt" />
<br clear="all" />

Entering <tt>:H</tt> in the user input line results in a list
of break handler commands which can be used to inspect the
state of your program. The most useful of these commands
are described hereafter.

All debugger output is printed to the console window; all inputs are
expected in the user input line.

If a Lisp error occurs in compiled Lisp code, the error message
issued by the break handler is often a little vague. It can help
to load the original Lisp file which contains the function in question, and
then to run the test again. With more source information,
the Lisp error information which you get from the break handler is often
a lot more precise and useful.

You can enter any Lisp code directly at the debugger prompt to execute it.
This allows to inspect values of variables by simply entering their name,
or to call debug functions which visualize the state of the code or the
current model.

In addition, the debugger prompt loop understands special debugging commands:

<dl>
<dt><b>:h</b>, <b>:hh</b>
<dd>Show short and long versions of the break handler
    command list

<dt><b>:m</b>
<dd>Print the LISP error message again.

<dt><b>:c</b>
<dd>Show current function name

<dt><b>:b</b>, <b>:ihs</b>

<dd>Show short and long versions of the invocation stack

<dt><b>:hs</b>
<dd>Show a list of functions which can be used to access
    objects on the Lisp value stack anywhere in the
    call hierarchy.

<dt><b>:lv</b>, <b>:l</b>
<dd>Shows the names of all local variables, or the names
    plus current values.

<dt><b>:r</b>, <b>:q</b>
<dd>Resume execution

<dt><b>:q</b>
<dd>Quit break handler, return to toploop

<dt><b>:p</b>, <b>:n</b>

<dd>Move one step up or down in the invocation history stack.
</dl>

Some functions accept a parameter; if you specify one, you must
use the command in a special list notation. As an example,
<tt>:go 4</tt> will not work, but <tt>(:go 4)</tt> takes
you to level 4 in the invocation stack.

-- Main.ClausBrod, 21 December 2005

---

#TraceFunctions
---+++ %ENGLISH% How can I trace function calls?

Sometimes you only want to check if a certain function is called, or which parameters
it receives. This is the domain of the =trace= function:

<pre>
  (defun testfn(x)
     (* 3 x))

  (trace testfn)
</pre>

From now on, all calls to =testfn= will be logged to standard output. The log
contains both the arguments for the function call and the return value.
A typical trace log looks like this:

<pre>
  1> (TESTFN 42)
  <1 (TESTFN 126)
</pre>

This output indicates that the function =TESTFN= was called with the parameter
<tt>x=42</tt> and returns with a result of 126 (=3*42).

To stop tracing a function, use =untrace=:

<pre>
  (untrace testfn)
</pre>

-- Main.ClausBrod - 21 Dec 2006

---

#RedirectTraceOutput
---+++ %ENGLISH% Can I redirect the trace output to a file?

=(trace)= prints to a special Lisp stream called <tt>*trace-output*</tt>.
You can open a file stream and then bind <tt>*trace-output*</tt> to that
stream; all trace output will then go to the file. Just remember to
restore the previous state of affairs when you're done.

Usually, it is more convenient to use the Common Lisp standard 
command <tt>dribble</tt> to capture all Lisp input and output to a file:

<pre>
  (dribble "c:/temp/logfile.txt")
</pre>

To turn off "dribbling":

<pre>
  (dribble)
</pre>

-- Main.ClausBrod - 21 Dec 2006

---

#SetBreakpoint
---+++ %ENGLISH% How do I set a breakpoint?

The <tt>trace</tt> macro can also be used to set breakpoints
in Lisp code. Here is a simple example:

<pre>
   (trace (testfn :entry (break)))
</pre>

Whenever someone calls <tt>testfn</tt> now, the break handler
will be entered, and you can inspect the state of the program
at this point. Use <tt>:r</tt> in the user input line to resume program execution.

The same can be accomplished using the convenience macro
=set-breakpoint= which was introduced with <nop>CoCreate Modeling 2006/v14.50:

<pre>
  (set-breakpoint testfn)
</pre>

To clear the breakpoint, use =clear-breakpoint=.

You can even set conditional breakpoints:

<pre>
  (trace (testfn :entrycond someconditionalform :entry (break))) ;; using trace
  (set-breakpoint testfn :if someconditionalform) ;; using set-breakpoint
</pre>

---
%COMMENT{type="below" nonotify="on"}%
to top
End of topic
Skip to action links | Back to top
You are here: CoCreateModeling > FaqLispDebugging

r1.3 - 25 May 2016 - 12:31 - ClausBrod to top
CoCreateModeling
Welcome
