This file documents Edebug

This is edition 1.6 of the Edebug User Manual for edebug Version 3.4,

Copyright (C) 1991,1992,1993,1994 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

Edebug User Manual
******************

Edebug is a source-level debugger for XEmacs Lisp programs.

     [file edebug-inc.texi not included]

Bugs and Todo List
==================

A debugger should be as bug free as possible, and I strive to achieve perfection.  But Edebug is fairly complex and I don't understand all of it any more, so bugs happen.  Please report anything suspicious to save someone else the trouble of finding the same bug.  Email to liberte@cs.uiuc.edu.  There is also a mailing list for Edebug beta testers: edebug-request@cs.uiuc.edu.

If you want to run Edebug on Edebug itself, often it is easiest to first copy a reliable version of edebug.el into another file, say fdebug.el, and replace all strings edebug with fdebug, then evaluate the fdebug buffer and run Fdebug on the buggy Edebug.

The following is a list of things I might do in the future, but often I do other things not on the list as I discover the need for them.  Send me your suggestions and priorities.

  * Bug: I've noticed that the point of some buffers is reset to the point of some other buffer, but I haven't been able to repeat it so perhaps it is fixed.

  * There may be a bug in the trace buffer display.  It should display as much as it can of the bottom of the buffer, but I think it scrolls off sometimes.

     There is a bug in window updating when there is both a trace buffer and an evaluation list - the source buffer doesn't get displayed.

  * Killing and reinserting an instrumented definition or parts of it leaves marks in the buffer which may confuse Edebug later.

  * Design problem: The position of definitions with complex names (e.g. defmethod) cannot be remembered properly, but nor can the names of such definitions be determined from calls of them.

  * After some errors, with edebug-on-error non-nil, continuing execution succeeds, returning nil.

  * There are some interesting problems with defining or executing keyboard macros across the Edebug activation boundary.

  * There are no other known bugs, so if you find any, please let me know. There is nothing worse than a buggy debugger!

  * I need to rethink locally binding debug-on-error, debug-on-quit, and keyboard macro state variables.  Should we allow the global values to be changed by the user?

  * "(" in the first column of doc strings messes up edebug reading. But no more than normal.

  * There could be a command to return a value from the debugger - particularly useful for errors.

  * Let me know if you find any side effects that could be avoided or at least documented in the manual. Also see The Outside Context.

  * Make edebug work with selective display - don't stop in hidden lines.

  * Debug just one or selected subexpressions of a definition - the rest is evalled normally.

  * Should overlay-arrow-position and -string be buffer local? It would be better if they could be window-local.

  * Use copy of current-local-map instead of emacs-lisp-mode-map (but only copy the first time after lower level command - to save time).

  * Better integration with standard debug.

  * Use inhibit-quit while edebugging?

  * Crawl mode would sit-for 0 or 1 in the outside window configuration between each edebug step. Maybe it should be a separate option that applies to trace as well.

  * Customizable sit-for time.  Less than a second would be nice.

  * Generalize step, trace, Trace-fast to one command with argument for sit-for time. Generalize go, continue, Continue-fast to another command with argument

  * Counting conditions - stop after n iterations.  You can do it manually now with conditional breakpoints.

  * Performance monitoring - summarize trace data.

  * Preserve breakpoints across instrumenting. You can now install calls to edebug in your code.

  * After stepping into code not previously instrumented (with edebug-step-in), maybe restore to non-instrumented code after entered.

  * Optionally replace expressions with results in a separate buffer from the source code.  This idea is based on discussions with Carl Witty regarding his stepper debugger.  Also, unparse code into its own buffer if source code is not available, or if user wishes to use replace-with-results mode.

  * Preserve previous bindings of local variables, and allow user to jump back to previous frames, particularly binding frames (i.e. let, condition-case, function and macro calls) to view values at that frame.  What about buffer local variables?  It would be simpler to have access to the Lisp stack.

     Variables display, like the evaluation list but automatically display all local variables and values.

  * Investigate minimal instrumentation that doesn't call edebug functions but instead sets edebug index and result variables.  Stepping is done through standard debugger features such as setting debug-on-next-call.  Breakpoints are done by modifying code as well as calling backtrace-debug for active frames.

  * Edebugging of uninstrumented code.  Similar to above minimal instrumentation but find out where we are at each edebug call by looking in a map from each list form in the code to its position. Problem is symbols are not unique.

  * Investigate hiding debugger internal stack frames.  This is both to simplify the standard debugger (which currently must be byte compiled to work) and to better support the integration of edebug and the standard debugger.

  * Fix Emacs' lack of stack checking.  The current workaround of incrementing max-lisp-eval-depth and max-specpdl-size is unsafe.

  * Although variables can't be tracked everywhere, watchpoints would be nice for variables that edebug can monitor.  That is, when the value of a specific variable changes, edebug would stop.  This can be done now with the edebug-global-break-condition, though it is awkward.

  * How about a command to add the previous sexp (?) to the eval-list?

  * Highlight all instrumented code, breakpoints, and subexpressions about to be evaluated or just evaluated.  This should be done in a way that works with Epoch, XEmacs, and Emacs 19.