Learning Edebug

Learning Edebug

[Lewis Creary via Users list for the GNU Emacs text editor]

Hello,
I'm trying to learn how to use the Emacs lisp function Edebug, but so far am not having any success.  The documentation says that I need to "instrument" the function that I want to debug, and I'm even having trouble with that.
I've been programming in Emacs Lisp for over a decade, and have always found that print statements were sufficient for debugging my programs.  But now I have a bug that I won't be able to understand without stepping through the code with a debugger -- hence the need for Edebug.  I'm looking for a person who is willing and able to help me learn to use this tool.  If you are such a person, I'd be very glad to hear from you.
  --  Lew Creary

Re: Learning Edebug

[mbork]

On 2024-12-20, at 03:11, Lewis Creary via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> wrote:

> Hello,
> I'm trying to learn how to use the Emacs lisp function Edebug, but so far am not having any success.  The documentation says that I need to "instrument" the function that I want to debug, and I'm even having trouble with that.
> I've been programming in Emacs Lisp for over a decade, and have always
> found that print statements were sufficient for debugging my
> programs.  But now I have a bug that I won't be able to understand
> without stepping through the code with a debugger -- hence the need
> for Edebug.  I'm looking for a person who is willing and able to help
> me learn to use this tool.  If you are such a person, I'd be very glad
> to hear from you.

Hi Lew,

instrumenting a function is easy (at least in my Emacs) -- you just
evaluate the defun with C-u C-M-x.  Then, when the function is called,
you will enter Edebug and wll be able to step through it.

Hth,

-- 
Marcin Borkowski
https://mbork.pl
https://crimsonelevendelightpetrichor.net/

Re: Learning Edebug

[Eduardo Ochs]

On Fri, 20 Dec 2024 at 00:15, Lewis Creary via Users list for the GNU
Emacs text editor <help-gnu-emacs@gnu.org> wrote:
>
> Hello,
>
> I'm trying to learn how to use the Emacs lisp function Edebug, but
> so far am not having any success.  The documentation says that I
> need to "instrument" the function that I want to debug, and I'm even
> having trouble with that.
>
> I've been programming in Emacs Lisp for over a decade, and have
> always found that print statements were sufficient for debugging my
> programs.  But now I have a bug that I won't be able to
> understand without stepping through the code with a debugger --
> hence the need for Edebug.  I'm looking for a person who is
> willing and able to help me learn to use this tool.  If you are
> such a person, I'd be very glad to hear from you.


Hi Lewis,

this is a mini-tutorial on Edebug that I wrote for a friend some time
ago:

--snip--snip--
;; Preparation:
;;   (emacs-lisp-mode)
;;   (require 'edebug)
;;
;; See: (find-elinode "edebug")
;;      (find-elnode "Edebug")
;;      (find-efunctiondescr 'eval-defun "instrument")
;;      (find-efunctiondescr 'edebug-mode)
;;      (find-efunctiondescr 'edebug-mode "C-M-x" "eval-defun")
;;      (eek "M-h M-k  M-C-x  ;; eval-defun")
;;
(defun ee-triangle-buggy (n)
  (if (= n 1) 1
    (+ n (ee-triangle-buggy (1= n)))))

;; Instrument the defun above with:   (eek "3*<up> C-u M-C-x")
;; Run it in edebug mode with:        (ee-triangle-buggy 4)
;; Start by learning these keys:
;;      (find-elnode "Edebug Execution Modes" "<SPC>" "Step:")
;;      (find-elnode "Edebug Misc" "q" "Return to the top level")
--snip--snip--

It needs eev, and it uses elisp hyperlinks. Everything there should
make sense to people who understand the sections 2 and 3 of the main
tutorial of eev - see:

  Trying eev with a sexp (2024)
  http://anggtwu.net/2024-find-tryit-links.html

Usually Brazilians understand eev immediately, but for many people in
developed countries using explicit sexps feels so wrong that examples
like the one above don't make any sense at all, even after years. I
talked a bit about that in my presentation at the EmacsConf2024 and in
a related video. Here are links to their subtitles:

  http://anggtwu.net/emacsconf2024.html#0:00
  http://anggtwu.net/2024-bash-test-blocks.html#0:00

My holidays have just started and I am planning to hang out a lot in
the #emacs IRC channel in the next days. If you would like to chat
meet me there or send me an e-mail!

  Cheers,
    Eduardo Ochs
    http://anggtwu.net/#eev

Re: Learning Edebug

[Joost Kremers]

On Fri, Dec 20 2024, Lewis Creary via Users list for the GNU Emacs text editor wrote:
> Hello,
> I'm trying to learn how to use the Emacs lisp function Edebug, but so far
> am not having any success.  The documentation says that I need to
> "instrument" the function that I want to debug, and I'm even having trouble
> with that.
> I've been programming in Emacs Lisp for over a decade, and have always
> found that print statements were sufficient for debugging my programs.  But
> now I have a bug that I won't be able to understand without stepping
> through the code with a debugger -- hence the need for Edebug.  I'm looking
> for a person who is willing and able to help me learn to use this tool.  If
> you are such a person, I'd be very glad to hear from you.
>   --  Lew Creary


Have you looked at the Edebug section in the Elisp manual:

(info "(elisp) Edebug")

It's quite long, but IME you don't need to read all of it right away. For
starters, read the first chapter "Using Edebug":

(info "(elisp) Using Edebug")

In fact, for the longest time, this was basically all I knew about
Edebug... 😆 One additional command I often find useful: `e`, which allows
you to evaluate an expression in the context of the program being debugged.

HTH


-- 
Joost Kremers
Life has its moments

Re: Learning Edebug

[Michael Heerdegen via Users list for the GNU Emacs text editor]

Hello Lewis,

note there are two debuggers.  The other one, sometimes called the
"built-in debugger", is conceptually a bit simpler.

Michael.

RE: [External] : Re: Learning Edebug

[Drew Adams]

> note there are two debuggers.  The other one, sometimes called the
> "built-in debugger", is conceptually a bit simpler.

Yes.
In the Elisp manual, it's just called "The Lisp Debugger".

https://www.gnu.org/software/emacs/manual/html_node/elisp/Debugger.html

Re: Learning Edebug

[tpeplt]

Lewis Creary via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:

> Hello,
> I'm trying to learn how to use the Emacs lisp function Edebug, but so
> far am not having any success.  The documentation says that I need to
> "instrument" the function that I want to debug, and I'm even having
> trouble with that.
> I've been programming in Emacs Lisp for over a decade, and have always
> found that print statements were sufficient for debugging my
> programs.  But now I have a bug that I won't be able to understand
> without stepping through the code with a debugger -- hence the need
> for Edebug.  I'm looking for a person who is willing and able to help
> me learn to use this tool.  If you are such a person, I'd be very glad
> to hear from you.

1. The manual titled "An Introduction to Programming in Emacs Lisp" has
   a chapter of introduction to debugging using both the built-in
   debugger and edebug.  This (info) manual is included in the standard
   set of manuals included in the Emacs distribution.

   There are two ways to read the manual from within Emacs:

   - The ‘Help’ menu item has the sub-menu ‘More Manuals’, which in turn
     has the sub-menu entry ‘Introduction to Emacs Lisp’.  Click on that
     entry to read the manual starting from the beginning.  On the first
     page of that manual is a menu.  The menu entry for the lessons on
     using the debuggers is titled ‘Debugging’.

   - If you do not want to go through the many lessons in the Intro to
     Programming in Emacs Lisp, but instead want to read the sub-section
     on Edebug, then evaluate the following expression (type C-x C-e after
     the expression) in Emacs to open Info at that section:

        (info "(eintr) edebug")

2. In its description of how to "instrument" a function, the manual
   (correctly) says this can be done using the command: 

      M-x edebug-defun.  

   This command works in any buffer (that contains an Emacs Lisp function
   definition), which is useful for the manual because it allows a
   reader to evaluate a function definition in an Info buffer without
   first copying it to an Elisp buffer.

   But it does not mention the other method, which is to use the key
   sequence C-u M-C-x.  This method works in Emacs Lisp buffers because
   in those buffers the key sequence M-C-x is bound to the function
   ‘eval-defun’ by default.  The function ‘eval-defun’ accepts an
   argument or a prefix argument (such as C-u), which tells ‘eval-defun’
   to "instrument" the function definition.

3. Do not forget to "un-instrument" your function definition(s) when you
   have finished debugging.  If you do not, then any time an
   instrumented function is called, Emacs will jump to that function’s
   definition and wait for the user to step through the function’s definition.

-- 
The lyf so short, the craft so long to lerne.
- Geoffrey Chaucer, The Parliament of Birds.

Re: Learning Edebug

[Eduardo Ochs]

Hi Lewis and all,

I cleaned up my instructions for "installing eev and opening a
mini-tutorial for edebug with a single sexp". They are here, with
links and screenshots:

  http://anggtwu.net/2024-find-tryit-links.html#edebug

The sexp is:

(progn
  (package-initialize)
  ;;
  ;; See: http://anggtwu.net/2024-no-public-key.html
  (setq package-check-signature nil)
  (package-refresh-contents)
  (package-install 'gnu-elpa-keyring-update)
  (setq package-check-signature 'allow-unsigned)
  ;;
  (package-install 'eev)
  (eev-beginner)
  (eval (ee-read (ee-dot-emacs-concat "angges")))
  ;;
  (find-2a
   ' (find-eev-quick-intro "2. Evaluating Lisp")
   ' (find-wget-elisp "http://anggtwu.net/elisp/edebug-2024.el")
  )
)

I tested it on an "emacs -Q" running in a fake directory, and
discussed it a bit on the eev mailing list.

  Cheers =),
    Eduardo Ochs

Re: Learning Edebug

[Joel Reicher]

Lewis Creary via Users list for the GNU Emacs text editor 
<help-gnu-emacs@gnu.org> writes:

> I'm trying to learn how to use the Emacs lisp function Edebug, 
> but so far am not having any success.  The documentation says 
> that I need to "instrument" the function that I want to debug, 
> and I'm even having trouble with that.
> I've been programming in Emacs Lisp for over a decade, and have 
> always found that print statements were sufficient for debugging 
> my programs.

I think the other replies have good practical info, but just in 
case some conceptual info is useful, instrumenting code is 
basically what you've been doing with print statements. When 
edebug instruments the code and inserts its own debugging 
snippets, you can execute the code normally and the 
instrumentation that edebug inserted will call the edebug 
functionality.

The built-in lisp debugger works the "other" way; it affects the 
evaluation machinery rather than the code being evaluated.

Regards,

        - Joel

RE: [External] : Re: Learning Edebug

[Drew Adams]

> instrumenting code is basically what you've been 
> doing with print statements. When edebug 
> instruments the code and inserts its own debugging
> snippets, you can execute the code normally and
> the instrumentation that edebug inserted will call 
> the edebug functionality.

In Elisp the equivalent of a print statement
is a `message' call:
  (message "foo value at position 42: %S" foo)

You can insert calls to `message' in your code 
anywhere, to provide trace-like behavior and
not invoke any debugger.

You can also invoke the (classic) Lisp debugger
by inserting breakpoints in your code anywhere.
These are just calls to function `debug'.

In the debugger, you can use the key `e' to
evaluate any Lisp expression _within the
context of the stack_, i.e., the current
control context.

As a shortcut, you can insert a `debug'
breakpoint that immediately evaluates a sexp
you pass to function `debug' as an argument,
saving you from typing it and hitting `e'.
If you just immediately hit `c', to continue
(exiting) the debugger that was just entered
(or `q' to quit), then This is akin to using 
`message' (or `error').

You pass the sexp to evaluate as the second
arg to `debug', using `nil' as the first:

  (debug nil (some-expression))

These are _ad hoc_ ways to get info at
particular places.  Easy to control (on/off
for particular breakpoints by commenting out 
their `debug' calls).