1 10/10/79 - Emacs Lisp Debug Mode
  2 
  3 **This file is intended to be perused via dprint, print, or via an**
  4 **editor.  It is not intended to be perused with the help command **
  5 
  6 
  7 
  8 
  9 ^L
 10      Multics Emacs LDEBUG mode (Lisp Debug) provides an
 11 interactive Lisp environment designed for the debugging of Emacs
 12 extension code.  Facilities are provided for tracing the Lisp
 13 stack, breakpointing code, and interacting with the native
 14 MacLisp "trace" facility.  LDEBUG mode is specifically optimized
 15 for multiple-window interaction.
 16 
 17   LDEBUG Buffers
 18 
 19 The heart of the LDEBUG mode facilities is the "LDEBUG" buffer.
 20 The buffer named "LDEBUG", when created by ldebug-mode
 21 (either in response to a breakpoint being executed, a trapped
 22 Lisp error, or the explicit "ldebug" extended command)
 23 evaluates any Lisp form typed into it when Carriage Return is
 24 struck after it. The form must be all on one line- an error will
 25 occur if the form has syntactic errors (e.g., miscounted
 26 parentheses).  The result of the evaluation is placed in the
 27 LDEBUG buffer on the next line, following the sign "=>", which
 28 indicates the result of such an evaluation.  The Lisp variable
 29 "*" will be set to the result of each successive evaluation,
 30 as at raw Lisp top level: this may be used to reference the last
 31 printed result.
 32 
 33      Random Lisp forms such as "(+ 2 3)" or "current-buffer" can
 34 be typed at LDEBUG buffers, and the resulting buffer contents
 35 will in effect be a dialogue of an interaction with Lisp.  Such
 36 buffers are often dprintable for later perusal.   The values of
 37 variables may be set by evaluating the normal Lisp setq form,
 38 e.g., (setq var (+ foo 27)).   As lines are
 39 placed into the LDEBUG buffer by the LDEBUG facility, the
 40 window (if any) containing it will scroll if necessary.
 41 
 42      Lisp values "printed" into the LDEBUG buffer are by default
 43 limited in length to ten and depth to six.  The values of the
 44 option variables "ldebug-prinlength" and "ldebug-prinlevel"
 45 may be set to alter these defaults.  The default input and output
 46 radices are both 8: these may be altered as the option
 47 variables "ldebug-ibase" and "ldebug-base".
 48 
 49      Most Emacs requests can be used in LDEBUG buffers; they are
 50 in "Lisp Debug" mode, which is an extension of ordinary Lisp
 51 mode, with commands differing as detailed below.
 52 
 53 
 54      Emacs and Lisp Debug Mode
 55 
 56      The "ldebug" (ESC-X ldebug CR) extended command can be
 57 invoked at any time, in the normal way Emacs extended commands
 58 are invoked.  It places Emacs in the LDEBUG buffer as described
 59 above, but also, more significantly, it sets up a system of Lisp
 60 error handlers "under" a new invocation of the Emacs request
 61 loop.  Should any Lisp error happen while these handlers exist,
 62 the LDEBUG buffer will be entered, placed on display if not
 63 already on display, the terminal's bell will be feeped, and the
 64 Lisp error message will be entered in the LDEBUG buffer.  You
 65 will then be at a "second (or greater) level" of LDEBUG, similar
 66 to what happens at Multics Command level when an error occurs.
 67 The level number will be part of the message entered in the
 68 LDEBUG buffer.
 69 
 70      Recursive (level greater than 1) LDEBUG buffers may be
 71 released (aborting all executing code between the LDEBUG level
 72 being released and the previous level) via the ESC G
 73 (ldebug-return-to-emacs-top-level) request, the analogue
 74 of the Multics "release" command. It will beep and type "$g"
 75 in the LDEBUG buffer.  The value of the variable "ldebug-level"
 76 tells the current level of LDEBUG buffers.
 77 
 78      ESC P (for proceed) is the analogue of the Multics "start"
 79 command; there is more to know about its meaning for each
 80 different type of entry to an LDEBUG buffer, and this
 81 will be described below.  In general, it restores the
 82 buffer and window from which the LDEBUG buffer were entered.
 83 
 84 
 85      Error trap entries to LDEBUG
 86 
 87      When an "error trap entry" to the LDEBUG buffer has
 88 occured, the Lisp stack may be traced via the ESC-T
 89 (ldebug-trace-stack) request, and the value of variables may be
 90 inspected simply by typing their names (as they are Lisp forms)
 91 at the LDEBUG buffer.
 92 
 93      A value may be "returned" to the Lisp error handler by
 94 typing it on a line, and instead of ending the line with
 95 carriage return (which would evaluate and "print" the result),
 96 end it with ESC P.  Note that Lisp error handlers often want a
 97 list of the value to replace some erroneous value.  For
 98 instance, in the following dialogue, an LDEBUG trap was entered
 99 because of the unbound variable "stuff": the programmer returned
100 the symbol "value-i-wanted" as the intended value of the unbound
101 variable:
102 
103    (myfun huff stuff)
104 
105    Lisp breakpoint unbnd-vrbl at level 1 in buffer LDEBUG:
106    lisp: undefined atomic symbol   stuff
107 
108    ('value-i-wanted)$p
109 
110 All "correctable" Lisp error breakpoints will accept a "retry"
111 value to be used to retry the failing operation; the undefined
112 function breakpoint ("undf-fnctn") also accepts a list of a new
113 value, in this case a function to be used instead.  The MacLisp
114 manual must be consulted  for the exact format of other retry
115 values.
116 
117      The "$p" is always printed by ESC P, to remind the user of the $p
118 which is used in raw Multics MacLisp to restart breaks (the "$p"
119 is in fact derived from ESC P on the ITS operating system, which
120 is used to restart jobs in general).
121 
122      ESC P may also be used alone on a line (i.e., no value to be
123 returned preceding it) to restart a break and let Lisp's default
124 action occur.
125 
126      ESC G may be used as usual to release a level of errors to
127 the next lower LDEBUG level; note that ^G (command-quit) only
128 does not release past LDEBUG levels.
129 
130 
131      Code Breakpoints
132 
133      Breakpoints may be set in interpreted extension code being
134 debugged by typing ESC & in a Lisp Mode buffer with the cursor
135 pointing at the point in some function being debugged where you
136 would like this break set.  The LDEBUG mechanism will create
137 this breakpoint by putting a call to a tracing function ("%%")
138 in the code in the buffer, and evaluating the function
139 definition it is looking at.  This "break code" will be left
140 in the function to let you know that it is there: it includes
141 a "break number" (they are assigned sequentially) by which
142 this breakpoint can be referred to by requests yet to
143 be described.
144 
145      You should be in at least one level of LDEBUG buffers
146 before setting a break: this means that you should have said
147 "ESC X ldebug CR" some time before setting breaks.
148 
149      Having set a break, you can run the code being debugged.
150 When the breakpoint is entered, the LDEBUG buffer will be
151 entered, at a new, higher level.  A message of the form
152 
153    Break 4 in function testfun
154 
155 will be put in the buffer, and the LDEBUG buffer will be put on
156 display if not already on display. As in all LDEBUG buffers,
157 arbitrary forms can be evaluated (including inspecting
158 variables), and ESC T can be used to trace the Lisp stack.
159 Again, ESC G releases a level of LDEBUG buffers.
160 
161      ESC P is used to restart code breakpoints, as well. A given
162 breakpoint can be set for some number of proceeds (i.e., "3" means
163 proceed, and proceed this breakpoint the next two times it is
164 encountered automatically) by giving that number as a numeric
165 argument to ESC P (i.e., ESC 3 ESC P).  A message indicating the
166 number of proceeds will be inserted in the LDEBUG buffer.
167 ESC P should be used alone on a line (i.e., no "retry value")
168 when restarting code (or trace) breaks.
169 
170      When in a code break, ESC R (ldebug-reset-break) may be
171 used to reset the current breakpoint, before restarting or
172 releasing.  The break code will be removed from the function
173 definition (visibly, if it is on display), and the function
174 definition will be reevaluated.  ESC R with a numeric argument
175 can be used to reset a break by number.
176 
177      When in an LDEBUG buffer, ESC L (ldebug-list-breaks) may be
178 used to list all the known code breakpoints: their numbers, the
179 function in which the break appears, the buffer the function
180 appears in, and the status of the break.
181 
182      The source for the current breakpoint may be shown by
183 issuing the request ESC S (ldebug-show-bkpt-source).  It is
184 placed in an available window (if in multiple windows or
185 pop-up-window mode), and the cursor moved to the break code.
186 (use ^XO to get back, or in one-window mode ^XB CR).
187 
188      A common need during function breakpointing is to determine
189 where the editor was (i.e., what was the current buffer, and
190 where was the current point) at the time the breakpoint was
191 encountered.  The ESC ^S (ldebug-display-where-editor-was)
192 request serves this need; it selects the appropriate buffer,
193 moving the cursor to the point in it where the current point was
194 when the breakpoint was taken.  If the buffer is already on
195 display in some window (or pop-up windows are being used),
196 that window will be selected (i.e., receive the cursor), and ^XO
197 can be used to return to the LDEBUG buffer for further probing
198 or restarting.  In one-window mode, the correct buffer will
199 be switched to, and ^XB can be used to get back.
200 Note that if the cursor (current point) is moved
201 by you explicitly (i.e., via normal Emacs requests) while
202 visiting the buffer where the breakpoint was taken, it will have
203 its new position when the breakpoint is restarted.  This is
204 analogous to setting a variable before restarting with usual
205 Multics debugging.
206 
207    Using two or three windows to contain the LDEBUG buffer, the
208 breakpoint source (function being debugged), and the buffer the
209 functions being debugged are working on is highly effective and
210 recommended.
211 
212 
213      Function tracing with LDEBUG
214 
215      The standard MacLisp trace package can be used while in
216 Emacs; extensibility features of the former allow LDEBUG to
217 take control of the trace output and breakpointing provided by
218 it.
219 
220      All the facilities of the standard trace package can be
221 used, by invoking trace from ESC ESC minibuffers.  The trace
222 package allows tracing of entries and exits to functions,
223 arguments, and return values, and breakpoints when functions are
224 entered.  Some sample forms to trace the function "testfun" are
225 given here: these are the in Lisp syntax, and may be typed as
226 such to LDEBUG mode.  When typed to an ESC-ESC minibuffer, the
227 outer set of parentheses should not be supplied.
228 
229        (trace testfun)        Trace the input arguments and
230                               return value of testfun each time
231                               it is invoked.
232 
233        (trace (testfun break (< x 3)))
234                               Trace input and return value of
235                               testfun, enter a breakpoint when
236                               entered and x (x can be an argument
237                               to testfun) is less than 3.
238        (trace (testfun break t))
239                               Same, but breakpont at every
240                               entry to testfun.
241        (trace (testfun entry (a b) exit (c)))
242                               Trace input args and return value,
243                               also print out the values of a and b
244                               when testfun is entered and the value
245                               of c when it is exited.
246 
247      The general syntax of trace invocations is (brackets are
248 indicating optional clauses, angle brackets are syntactic
249 variables):
250 
251      (trace <fnname-or-clause-1>  ... <fnname-or-clause-n>)
252 
253 where <fnname-or-clause> is either a function name to be traced
254 for only input args and return value, or
255 
256      (<fnname> [break <break-condition>] [entry (<entry-vals>)]
257                                          [exit (<exit-vals>)])
258 
259 There are other options documented in the MacLisp reference
260 manual.
261 
262      When a function is traced within Emacs (it is not
263 recommended to trace internal Lisp or Emacs primitives, and any
264 part of the redisplay should definitely not be traced in this
265 way), trace output for entry and exit tracings will be placed
266 (and scrolled) directly into the LDEBUG buffer if it is on
267 display; if it is not on display, this output will be put in the
268 LDEBUG buffer, AND local-display'ed as it is produced.
269 Note that the -- * * * * * * * * * -- of local displays will NOT
270 be produced, as it cannot be known when the "end" of trace
271 output has been reached.  Thus, traced functions invoked from
272 the minibuffer may often leave the cursor in the minibuffer
273 awaiting clearing the local display via linefeed or ^L.
274 
275      Trace output generally looks like
276 
277    (3 enter testfun (3 5 (a . b)) /|/| (4 5))
278 
279 The indentation level gives the depth in currently active
280 traced functions.  The "3" is the recursion depth of the
281 given function (e.g., testfun) being traced.  "enter"
282 is the type of trace (enter vs. exit), (3 5 (a . b))
283 is the list of arguments (in this case, three arguments).
284 /|/| sets off the "entry values" and "exit values"
285 optionally selectable by the "entry" and "exit" keywords
286 in the trace-invoking form.   Exit traces look like
287 
288    (3 exit testfun 17)
289 
290      If trace is used to set an entry breakpoint, the LDEBUG
291 buffer will be trapped to at the time the traced function is
292 entered, in a way very much like a Lisp error break to LDEBUG.
293 A message such as
294 
295    Entry breakpoint to function testfun
296 
297 will be "printed" into the LDEBUG buffer, and the terminal
298 feeped.  As with LDEBUG code breaks, ESC G releases, ESC P
299 restarts, ESC R resets, and ESC ^S shows where the editor was
300 at the time the break was taken.  When in entry breakpoints to
301 interpreted functions, the arguments may be inspected by name.
302 ESC-T may be used to trace the Lisp stack, but unless
303 *rset t mode was in effect (setting up an LDEBUG level does this
304 automatically), trace information may not be present.
305 
306      It is not necessary to have invoked ldebug before invoking
307 trace in Emacs; LDEBUG will be invoked automatically if an
308 attempt is made to use trace in Emacs.  If some critical
309 mechanism is being debugged and normal trace handling (i.e.,
310 breakpointing/tracing to user_i/o from Lisp, not the Emacs
311 handling just described is necessary, the variables
312 trace-printer and trace-break-fun should be made unbound (e.g.,
313 ESC ESC makunbound 'trace-printer) before the first reference to
314 trace in a given invocation of Emacs.
315 
316 (END)