Mercurial > emacs
comparison lispref/edebug.texi @ 21682:90da2489c498
*** empty log message ***
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Mon, 20 Apr 1998 17:43:57 +0000 |
parents | 66d807bdc5b4 |
children | d4ac295a98b3 |
comparison
equal
deleted
inserted
replaced
21681:11eafe90b842 | 21682:90da2489c498 |
---|---|
1 @comment -*-texinfo-*- | 1 @comment -*-texinfo-*- |
2 | 2 @c This is part of the GNU Emacs Lisp Reference Manual. |
3 @c This file is intended to be used as a section within the Emacs Lisp | 3 @c Copyright (C) 1992, 1993, 1994, 1998 Free Software Foundation, Inc. |
4 @c Reference Manual. It may also be used by an independent Edebug User | 4 @c See the file elisp.texi for copying conditions. |
5 @c Manual, edebug.tex, in which case the Edebug node below should be used | 5 |
6 @c This file can also be used by an independent Edebug User | |
7 @c Manual in which case the Edebug node below should be used | |
6 @c with the following links to the Bugs section and to the top level: | 8 @c with the following links to the Bugs section and to the top level: |
7 | 9 |
8 @c , Bugs and Todo List, Top, Top | 10 @c , Bugs and Todo List, Top, Top |
9 | 11 |
10 @node Edebug,, Compilation Errors, Debugging | 12 @node Edebug,, Compilation Errors, Debugging |
165 definition @emph{unless} it has a prefix argument. The default value of | 167 definition @emph{unless} it has a prefix argument. The default value of |
166 @code{edebug-all-defs} is @code{nil}. The command @kbd{M-x | 168 @code{edebug-all-defs} is @code{nil}. The command @kbd{M-x |
167 edebug-all-defs} toggles the value of the variable | 169 edebug-all-defs} toggles the value of the variable |
168 @code{edebug-all-defs}. | 170 @code{edebug-all-defs}. |
169 | 171 |
170 @findex edebug-all-forms | 172 @findex eval-region @r{(Edebug)} |
171 @findex eval-region (Edebug) | 173 @findex eval-current-buffer @r{(Edebug)} |
172 @findex eval-current-buffer (Edebug) | |
173 If @code{edebug-all-defs} is non-@code{nil}, then the commands | 174 If @code{edebug-all-defs} is non-@code{nil}, then the commands |
174 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} | 175 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} |
175 also instrument any definitions they evaluate. Similarly, | 176 also instrument any definitions they evaluate. Similarly, |
176 @code{edebug-all-forms} controls whether @code{eval-region} should | 177 @code{edebug-all-forms} controls whether @code{eval-region} should |
177 instrument @emph{any} form, even non-defining forms. This doesn't apply | 178 instrument @emph{any} form, even non-defining forms. This doesn't apply |
178 to loading or evaluations in the minibuffer. The command @kbd{M-x | 179 to loading or evaluations in the minibuffer. The command @kbd{M-x |
179 edebug-all-forms} toggles this option. | 180 edebug-all-forms} toggles this option. |
180 | 181 |
181 @findex edebug-eval-top-level-form | 182 @findex edebug-eval-top-level-form |
182 Another command, @kbd{M-x edebug-eval-top-level-form}, is available to | 183 Another command, @kbd{M-x edebug-eval-top-level-form}, is available to |
183 instrument any top-level form regardless of the values of | 184 instrument any top-level form regardless of the values of |
184 @code{edebug-all-defs} and @code{edebug-all-forms}. | 185 @code{edebug-all-defs} and @code{edebug-all-forms}. |
185 | 186 |
186 When Edebug is about to instrument code for the first time in a session, | 187 While Edebug is active, the command @kbd{I} |
187 it runs the hook @code{edebug-setup-hook}, then sets it to @code{nil}. | |
188 You can use this to load up Edebug specifications associated with a | |
189 package you are using, but only when you also use Edebug. | |
190 | |
191 While Edebug is active, the command @kbd{I} | |
192 (@code{edebug-instrument-callee}) instruments the definition of the | 188 (@code{edebug-instrument-callee}) instruments the definition of the |
193 function or macro called by the list form after point, if is not already | 189 function or macro called by the list form after point, if is not already |
194 instrumented. This is possible only if Edebug knows where to find the | 190 instrumented. This is possible only if Edebug knows where to find the |
195 source for that function; after loading Edebug, @code{eval-region} | 191 source for that function; after loading Edebug, @code{eval-region} |
196 records the position of every definition it evaluates, even if not | 192 records the position of every definition it evaluates, even if not |
199 | 195 |
200 @cindex special forms (Edebug) | 196 @cindex special forms (Edebug) |
201 @cindex interactive commands (Edebug) | 197 @cindex interactive commands (Edebug) |
202 @cindex anonymous lambda expressions (Edebug) | 198 @cindex anonymous lambda expressions (Edebug) |
203 @cindex Common Lisp (Edebug) | 199 @cindex Common Lisp (Edebug) |
204 @pindex cl.el (Edebug) | 200 @pindex cl.el @r{(Edebug)} |
205 @pindex cl-specs.el | 201 @pindex cl-specs.el |
206 Edebug knows how to instrument all the standard special forms, an | 202 Edebug knows how to instrument all the standard special forms, an |
207 interactive form with an expression argument, anonymous lambda | 203 interactive form with an expression argument, anonymous lambda |
208 expressions, and other defining forms. Edebug cannot know what a | 204 expressions, and other defining forms. Edebug cannot know what a |
209 user-defined macro will do with the arguments of a macro call, so you | 205 user-defined macro will do with the arguments of a macro call, so you |
210 must tell it; @xref{Instrumenting Macro Calls}, for details. | 206 must tell it; @xref{Instrumenting Macro Calls}, for details. |
211 | 207 |
212 @findex eval-expression (Edebug) | 208 When Edebug is about to instrument code for the first time in a |
209 session, it runs the hook @code{edebug-setup-hook}, then sets it to | |
210 @code{nil}. You can use this to arrange to load Edebug specifications | |
211 (@pxref{Instrumenting Macro Calls}) associated with a package you are | |
212 using, but actually load them only if you use Edebug. | |
213 | |
214 @findex eval-expression @r{(Edebug)} | |
213 To remove instrumentation from a definition, simply reevaluate its | 215 To remove instrumentation from a definition, simply reevaluate its |
214 definition in a way that does not instrument. There are two ways of | 216 definition in a way that does not instrument. There are two ways of |
215 evaluating forms that never instrument them: from a file with | 217 evaluating forms that never instrument them: from a file with |
216 @code{load}, and from the minibuffer with @code{eval-expression} | 218 @code{load}, and from the minibuffer with @code{eval-expression} |
217 (@kbd{M-:}). | 219 (@kbd{M-:}). |
470 expression in the minibuffer. Setting a conditional breakpoint at a | 472 expression in the minibuffer. Setting a conditional breakpoint at a |
471 stop point that has a previously established conditional breakpoint puts | 473 stop point that has a previously established conditional breakpoint puts |
472 the previous condition expression in the minibuffer so you can edit it. | 474 the previous condition expression in the minibuffer so you can edit it. |
473 | 475 |
474 You can make a conditional or unconditional breakpoint | 476 You can make a conditional or unconditional breakpoint |
475 @dfn{temporary} by using a prefix arg with the command to set the | 477 @dfn{temporary} by using a prefix argument with the command to set the |
476 breakpoint. When a temporary breakpoint stops the program, it is | 478 breakpoint. When a temporary breakpoint stops the program, it is |
477 automatically unset. | 479 automatically unset. |
478 | 480 |
479 Edebug always stops or pauses at a breakpoint except when the Edebug | 481 Edebug always stops or pauses at a breakpoint except when the Edebug |
480 mode is Go-nonstop. In that mode, it ignores breakpoints entirely. | 482 mode is Go-nonstop. In that mode, it ignores breakpoints entirely. |
502 evaluates to a non-@code{nil} value, then execution stops or pauses | 504 evaluates to a non-@code{nil} value, then execution stops or pauses |
503 depending on the execution mode, as if a breakpoint had been hit. If | 505 depending on the execution mode, as if a breakpoint had been hit. If |
504 evaluating the condition gets an error, execution does not stop. | 506 evaluating the condition gets an error, execution does not stop. |
505 | 507 |
506 @findex edebug-set-global-break-condition | 508 @findex edebug-set-global-break-condition |
507 @vindex edebug-global-break-condition | |
508 The condition expression is stored in | 509 The condition expression is stored in |
509 @code{edebug-global-break-condition}. You can specify a new expression | 510 @code{edebug-global-break-condition}. You can specify a new expression |
510 using the @kbd{X} command (@code{edebug-set-global-break-condition}). | 511 using the @kbd{X} command (@code{edebug-set-global-break-condition}). |
511 | 512 |
512 The global break condition is the simplest way to find where in your | 513 The global break condition is the simplest way to find where in your |
531 (if (< 0 n) | 532 (if (< 0 n) |
532 (* n (fac (1- n))) | 533 (* n (fac (1- n))) |
533 1)) | 534 1)) |
534 @end example | 535 @end example |
535 | 536 |
536 When the @code{fac} definition is instrumented and the function is | 537 When the @code{fac} definition is instrumented and the function is |
537 called, the call to @code{edebug} acts as a breakpoint. Depending on | 538 called, the call to @code{edebug} acts as a breakpoint. Depending on |
538 the execution mode, Edebug stops or pauses there. | 539 the execution mode, Edebug stops or pauses there. |
539 | 540 |
540 If no instrumented code is being executed when @code{edebug} is called, | 541 If no instrumented code is being executed when @code{edebug} is called, |
541 that function calls @code{debug}. | 542 that function calls @code{debug}. |
542 @c This may not be a good idea anymore. | 543 @c This may not be a good idea anymore. |
543 | 544 |
544 @node Trapping Errors | 545 @node Trapping Errors |
545 @subsection Trapping Errors | 546 @subsection Trapping Errors |
546 | 547 |
547 Emacs normally displays an error message when an error is signaled and | 548 Emacs normally displays an error message when an error is signaled and |
548 not handled with @code{condition-case}. While Edebug is active, it | 549 not handled with @code{condition-case}. While Edebug is active and |
549 normally responds to all unhandled errors. You can customize this with | 550 executing instrumented code, it normally responds to all unhandled |
550 the options @code{edebug-on-error} and @code{edebug-on-quit}; see | 551 errors. You can customize this with the options @code{edebug-on-error} |
551 @ref{Edebug Options}. | 552 and @code{edebug-on-quit}; see @ref{Edebug Options}. |
552 | 553 |
553 When Edebug responds to an error, it shows the last stop point | 554 When Edebug responds to an error, it shows the last stop point |
554 encountered before the error. This may be the location of a call to a | 555 encountered before the error. This may be the location of a call to a |
555 function which was not instrumented, within which the error actually | 556 function which was not instrumented, within which the error actually |
556 occurred. For an unbound variable error, the last known stop point | 557 occurred. For an unbound variable error, the last known stop point |
557 might be quite distant from the offending variable reference. In that | 558 might be quite distant from the offending variable reference. In that |
558 case you might want to display a full backtrace (@pxref{Edebug Misc}). | 559 case you might want to display a full backtrace (@pxref{Edebug Misc}). |
559 | 560 |
560 @c Edebug should be changed for the following: -- dan | 561 @c Edebug should be changed for the following: -- dan |
561 If you change @code{debug-on-error} or @code{debug-on-quit} while | 562 If you change @code{debug-on-error} or @code{debug-on-quit} while |
562 Edebug is active, these changes will be forgotten when Edebug becomes | 563 Edebug is active, these changes will be forgotten when Edebug becomes |
563 inactive. Furthermore, during Edebug's recursive edit, these variables | 564 inactive. Furthermore, during Edebug's recursive edit, these variables |
564 are bound to the values they had outside of Edebug. | 565 are bound to the values they had outside of Edebug. |
565 | 566 |
566 @node Edebug Views | 567 @node Edebug Views |
567 @subsection Edebug Views | 568 @subsection Edebug Views |
568 | 569 |
569 These Edebug commands let you view aspects of the buffer and window | 570 These Edebug commands let you view aspects of the buffer and window |
570 status that obtained before entry to Edebug. The outside window | 571 status that obtained before entry to Edebug. The outside window |
571 configuration is the collection of windows and contents that were in | 572 configuration is the collection of windows and contents that were in |
572 effect outside of Edebug. | 573 effect outside of Edebug. |
573 | 574 |
574 @table @kbd | 575 @table @kbd |
595 With a prefix argument, @code{W} only toggles saving and restoring of | 596 With a prefix argument, @code{W} only toggles saving and restoring of |
596 the selected window. To specify a window that is not displaying the | 597 the selected window. To specify a window that is not displaying the |
597 source code buffer, you must use @kbd{C-x X W} from the global keymap. | 598 source code buffer, you must use @kbd{C-x X W} from the global keymap. |
598 @end table | 599 @end table |
599 | 600 |
600 You can view the outside window configuration with @kbd{v} or just | 601 You can view the outside window configuration with @kbd{v} or just |
601 bounce to the point in the current buffer with @kbd{p}, even if | 602 bounce to the point in the current buffer with @kbd{p}, even if |
602 it is not normally displayed. After moving point, you may wish to jump | 603 it is not normally displayed. After moving point, you may wish to jump |
603 back to the stop point with @kbd{w} from a source code buffer. | 604 back to the stop point with @kbd{w} from a source code buffer. |
604 | 605 |
605 Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the | 606 Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the |
606 saved outside window configuration---so that even if you turn saving | 607 saved outside window configuration---so that even if you turn saving |
607 back @emph{on}, the current window configuration remains unchanged when | 608 back @emph{on}, the current window configuration remains unchanged when |
608 you next exit Edebug (by continuing the program). However, the | 609 you next exit Edebug (by continuing the program). However, the |
609 automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may | 610 automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may |
610 conflict with the buffers you wish to see unless you have enough windows | 611 conflict with the buffers you wish to see unless you have enough windows |
611 open. | 612 open. |
612 | 613 |
613 @node Edebug Eval | 614 @node Edebug Eval |
614 @subsection Evaluation | 615 @subsection Evaluation |
615 | 616 |
616 While within Edebug, you can evaluate expressions ``as if'' Edebug were | 617 While within Edebug, you can evaluate expressions ``as if'' Edebug were |
617 not running. Edebug tries to be invisible to the expression's | 618 not running. Edebug tries to be invisible to the expression's |
618 evaluation and printing. Evaluation of expressions that cause side | 619 evaluation and printing. Evaluation of expressions that cause side |
619 effects will work as expected except for things that Edebug explicitly | 620 effects will work as expected except for things that Edebug explicitly |
620 saves and restores. @xref{The Outside Context}, for details on this | 621 saves and restores. @xref{The Outside Context}, for details on this |
621 process. | 622 process. |
633 Evaluate the expression before point, in the context outside of Edebug | 634 Evaluate the expression before point, in the context outside of Edebug |
634 (@code{edebug-eval-last-sexp}). | 635 (@code{edebug-eval-last-sexp}). |
635 @end table | 636 @end table |
636 | 637 |
637 @cindex lexical binding (Edebug) | 638 @cindex lexical binding (Edebug) |
638 Edebug supports evaluation of expressions containing references to | 639 Edebug supports evaluation of expressions containing references to |
639 lexically bound symbols created by the following constructs in | 640 lexically bound symbols created by the following constructs in |
640 @file{cl.el} (version 2.03 or later): @code{lexical-let}, | 641 @file{cl.el} (version 2.03 or later): @code{lexical-let}, |
641 @code{macrolet}, and @code{symbol-macrolet}. | 642 @code{macrolet}, and @code{symbol-macrolet}. |
642 | 643 |
643 | |
644 @node Eval List | 644 @node Eval List |
645 @subsection Evaluation List Buffer | 645 @subsection Evaluation List Buffer |
646 | 646 |
647 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to | 647 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to |
648 evaluate expressions interactively. You can also set up the | 648 evaluate expressions interactively. You can also set up the |
649 @dfn{evaluation list} of expressions to be evaluated automatically each | 649 @dfn{evaluation list} of expressions to be evaluated automatically each |
650 time Edebug updates the display. | 650 time Edebug updates the display. |
651 | 651 |
652 @table @kbd | 652 @table @kbd |
653 @item E | 653 @item E |
654 Switch to the evaluation list buffer @samp{*edebug*} | 654 Switch to the evaluation list buffer @samp{*edebug*} |
655 (@code{edebug-visit-eval-list}). | 655 (@code{edebug-visit-eval-list}). |
656 @end table | 656 @end table |
657 | 657 |
658 In the @samp{*edebug*} buffer you can use the commands of Lisp | 658 In the @samp{*edebug*} buffer you can use the commands of Lisp |
659 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs | 659 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs |
660 Manual}) as well as these special commands: | 660 Manual}) as well as these special commands: |
661 | 661 |
662 @table @kbd | 662 @table @kbd |
663 @item LFD | 663 @item C-j |
664 Evaluate the expression before point, in the outside context, and insert | 664 Evaluate the expression before point, in the outside context, and insert |
665 the value in the buffer (@code{edebug-eval-print-last-sexp}). | 665 the value in the buffer (@code{edebug-eval-print-last-sexp}). |
666 | 666 |
667 @item C-x C-e | 667 @item C-x C-e |
668 Evaluate the expression before point, in the context outside of Edebug | 668 Evaluate the expression before point, in the context outside of Edebug |
679 @item C-c C-w | 679 @item C-c C-w |
680 Switch back to the source code buffer at the current stop point | 680 Switch back to the source code buffer at the current stop point |
681 (@code{edebug-where}). | 681 (@code{edebug-where}). |
682 @end table | 682 @end table |
683 | 683 |
684 You can evaluate expressions in the evaluation list window with | 684 You can evaluate expressions in the evaluation list window with |
685 @kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*}; | 685 @kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*}; |
686 but they are evaluated in the context outside of Edebug. | 686 but they are evaluated in the context outside of Edebug. |
687 | 687 |
688 The expressions you enter interactively (and their results) are lost | 688 The expressions you enter interactively (and their results) are lost |
689 when you continue execution; but you can set up an @dfn{evaluation list} | 689 when you continue execution; but you can set up an @dfn{evaluation list} |
690 consisting of expressions to be evaluated each time execution stops. | 690 consisting of expressions to be evaluated each time execution stops. |
691 | 691 |
692 @cindex evaluation list group | 692 @cindex evaluation list group |
693 To do this, write one or more @dfn{evaluation list groups} in the | 693 To do this, write one or more @dfn{evaluation list groups} in the |
694 evaluation list buffer. An evaluation list group consists of one or | 694 evaluation list buffer. An evaluation list group consists of one or |
695 more Lisp expressions. Groups are separated by comment lines. | 695 more Lisp expressions. Groups are separated by comment lines. |
696 | 696 |
697 The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the | 697 The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the |
698 evaluation list, scanning the buffer and using the first expression of | 698 evaluation list, scanning the buffer and using the first expression of |
699 each group. (The idea is that the second expression of the group is the | 699 each group. (The idea is that the second expression of the group is the |
700 value previously computed and displayed.) | 700 value previously computed and displayed.) |
701 | 701 |
702 Be careful not to add expressions that execute instrumented code since | 702 Each entry to Edebug redisplays the evaluation list by inserting each |
703 that would cause an infinite loop. | |
704 @c There ought to be a way to fix this. | |
705 | |
706 Each entry to Edebug redisplays the evaluation list by inserting each | |
707 expression in the buffer, followed by its current value. It also | 703 expression in the buffer, followed by its current value. It also |
708 inserts comment lines so that each expression becomes its own group. | 704 inserts comment lines so that each expression becomes its own group. |
709 Thus, if you type @kbd{C-c C-u} again without changing the buffer text, | 705 Thus, if you type @kbd{C-c C-u} again without changing the buffer text, |
710 the evaluation list is effectively unchanged. | 706 the evaluation list is effectively unchanged. |
711 | 707 |
712 If an error occurs during an evaluation from the evaluation list, the | 708 If an error occurs during an evaluation from the evaluation list, the |
713 error message is displayed in a string as if it were the result. | 709 error message is displayed in a string as if it were the result. |
714 Therefore, expressions that use variables not currently valid do not | 710 Therefore, expressions that use variables not currently valid do not |
715 interrupt your debugging. | 711 interrupt your debugging. |
716 | 712 |
717 Here is an example of what the evaluation list window looks like after | 713 Here is an example of what the evaluation list window looks like after |
718 several expressions have been added to it: | 714 several expressions have been added to it: |
719 | 715 |
720 @smallexample | 716 @smallexample |
721 (current-buffer) | 717 (current-buffer) |
722 #<buffer *scratch*> | 718 #<buffer *scratch*> |
757 @cindex printing circular structures | 753 @cindex printing circular structures |
758 @pindex cust-print | 754 @pindex cust-print |
759 If an expression in your program produces a value containing circular | 755 If an expression in your program produces a value containing circular |
760 list structure, you may get an error when Edebug attempts to print it. | 756 list structure, you may get an error when Edebug attempts to print it. |
761 | 757 |
762 @vindex edebug-print-length | |
763 @vindex edebug-print-level | |
764 One way to cope with circular structure is to set @code{print-length} | 758 One way to cope with circular structure is to set @code{print-length} |
765 or @code{print-level} to truncate the printing. Edebug does this for | 759 or @code{print-level} to truncate the printing. Edebug does this for |
766 you; it binds @code{print-length} and @code{print-level} to 50 if they | 760 you; it binds @code{print-length} and @code{print-level} to 50 if they |
767 were @code{nil}. (Actually, the variables @code{edebug-print-length} | 761 were @code{nil}. (Actually, the variables @code{edebug-print-length} |
768 and @code{edebug-print-level} specify the values to use within Edebug.) | 762 and @code{edebug-print-level} specify the values to use within Edebug.) |
769 @xref{Output Variables}. | 763 @xref{Output Variables}. |
770 | 764 |
765 @defopt edebug-print-length | |
766 If non-@code{nil}, bind @code{print-length} to this while printing | |
767 results in Edebug. The default value is @code{50}. | |
768 @xref{Printing in Edebug}. | |
769 @end defopt | |
770 | |
771 @defopt edebug-print-level | |
772 If non-@code{nil}, bind @code{print-level} to this while printing | |
773 results in Edebug. The default value is @code{50}. | |
774 @end defopt | |
775 | |
771 You can also print circular structures and structures that share | 776 You can also print circular structures and structures that share |
772 elements more informatively by using the @file{cust-print} package. | 777 elements more informatively by using the @file{cust-print} package. |
773 | 778 |
774 To load @file{cust-print} and activate custom printing only for | 779 To load @file{cust-print} and activate custom printing only for |
775 Edebug, simply use the command @kbd{M-x edebug-install-custom-print}. | 780 Edebug, simply use the command @kbd{M-x edebug-install-custom-print}. |
787 Custom printing prints this as @samp{Result: #1=(#1# y)}. The | 792 Custom printing prints this as @samp{Result: #1=(#1# y)}. The |
788 @samp{#1=} notation labels the structure that follows it with the label | 793 @samp{#1=} notation labels the structure that follows it with the label |
789 @samp{1}, and the @samp{#1#} notation references the previously labelled | 794 @samp{1}, and the @samp{#1#} notation references the previously labelled |
790 structure. This notation is used for any shared elements of lists or | 795 structure. This notation is used for any shared elements of lists or |
791 vectors. | 796 vectors. |
797 | |
798 @defopt edebug-print-circle | |
799 If non-@code{nil}, bind @code{print-circle} to this while printing | |
800 results in Edebug. The default value is @code{nil}. | |
801 @end defopt | |
792 | 802 |
793 Other programs can also use custom printing; see @file{cust-print.el} | 803 Other programs can also use custom printing; see @file{cust-print.el} |
794 for details. | 804 for details. |
795 | 805 |
796 @node Trace Buffer | 806 @node Trace Buffer |
848 @cindex performance analysis | 858 @cindex performance analysis |
849 Edebug provides rudimentary coverage testing and display of execution | 859 Edebug provides rudimentary coverage testing and display of execution |
850 frequency. All execution of an instrumented function accumulates | 860 frequency. All execution of an instrumented function accumulates |
851 frequency counts, both before and after evaluation of each instrumented | 861 frequency counts, both before and after evaluation of each instrumented |
852 expression, even if the execution mode is Go-nonstop. Coverage testing | 862 expression, even if the execution mode is Go-nonstop. Coverage testing |
853 is more expensive, so it is only done if @code{edebug-test-coverage} is | 863 is more expensive, so it is done only if @code{edebug-test-coverage} is |
854 non-@code{nil}. The command @kbd{M-x edebug-display-freq-count} | 864 non-@code{nil}. The command @kbd{M-x edebug-display-freq-count} |
855 displays both the frequency data and the coverage data (if recorded). | 865 displays both the frequency data and the coverage data (if recorded). |
856 | 866 |
857 @deffn Command edebug-display-freq-count | 867 @deffn Command edebug-display-freq-count |
858 This command displays the frequency count data for each line of the | 868 This command displays the frequency count data for each line of the |
859 current definition. | 869 current definition. |
860 | 870 |
861 The frequency counts appear as comment lines after each line of code, and | 871 The frequency counts appear as comment lines after each line of code, |
862 you can undo all insertions with one @code{undo} command. The counts | 872 and you can undo all insertions with one @code{undo} command. The |
863 appear under the @kbd{(} before an expression or the @kbd{)} after | 873 counts appear under the @samp{(} before an expression or the @samp{)} |
864 an expression, or on the last character of a symbol. Values do not appear if | 874 after an expression, or on the last character of a symbol. Values do |
865 they are equal to the previous count on the same line. | 875 not appear if they are equal to the previous count on the same line. |
866 | 876 |
867 The character @samp{=} following the count for an expression says that | 877 The character @samp{=} following the count for an expression says that |
868 the expression has returned the same value each time it was evaluated | 878 the expression has returned the same value each time it was evaluated |
869 This is the only coverage information that Edebug records. | 879 This is the only coverage information that Edebug records. |
870 | 880 |
1033 @end itemize | 1043 @end itemize |
1034 | 1044 |
1035 @node Instrumenting Macro Calls | 1045 @node Instrumenting Macro Calls |
1036 @subsection Instrumenting Macro Calls | 1046 @subsection Instrumenting Macro Calls |
1037 | 1047 |
1038 When Edebug instruments an expression that calls a Lisp macro, it needs | 1048 When Edebug instruments an expression that calls a Lisp macro, it needs |
1039 additional advice to do the job properly. This is because there is no | 1049 additional information about the macro to do the job properly. This is |
1040 way to tell which subexpressions of the macro call are forms to be | 1050 because there is no a-priori way to tell which subexpressions of the |
1041 evaluated. (Evaluation may occur explicitly in the macro body, or when | 1051 macro call are forms to be evaluated. (Evaluation may occur explicitly |
1042 the resulting expansion is evaluated, or any time later.) You must | 1052 in the macro body, or when the resulting expansion is evaluated, or any |
1043 explain the format of calls to each macro to enable Edebug to handle it. | 1053 time later.) |
1044 To do this, use @code{def-edebug-spec} to define the format of | 1054 |
1045 calls to a given macro. | 1055 Therefore, you must define an Edebug specification for each macro that |
1056 Edebug will encounter, to explain the format of calls to that macro. To | |
1057 do this, use @code{def-edebug-spec}. | |
1046 | 1058 |
1047 @deffn Macro def-edebug-spec macro specification | 1059 @deffn Macro def-edebug-spec macro specification |
1048 Specify which expressions of a call to macro @var{macro} are forms to be | 1060 Specify which expressions of a call to macro @var{macro} are forms to be |
1049 evaluated. For simple macros, the @var{specification} often looks very | 1061 evaluated. For simple macros, the @var{specification} often looks very |
1050 similar to the formal argument list of the macro definition, but | 1062 similar to the formal argument list of the macro definition, but |
1051 specifications are much more general than macro arguments. | 1063 specifications are much more general than macro arguments. |
1052 | 1064 |
1053 The @var{macro} argument may actually be any symbol, not just a macro | 1065 The @var{macro} argument can actually be any symbol, not just a macro |
1054 name. | 1066 name. |
1055 @end deffn | 1067 @end deffn |
1056 | 1068 |
1057 Here is a simple example that defines the specification for the | 1069 Here is a simple example that defines the specification for the |
1058 @code{for} macro described in the Emacs Lisp Reference Manual, followed | 1070 @code{for} macro described in the Emacs Lisp Reference Manual, followed |
1106 as @code{&optional}). | 1118 as @code{&optional}). |
1107 | 1119 |
1108 A specification list may contain sublists which match arguments that are | 1120 A specification list may contain sublists which match arguments that are |
1109 themselves lists, or it may contain vectors used for grouping. Sublists | 1121 themselves lists, or it may contain vectors used for grouping. Sublists |
1110 and groups thus subdivide the specification list into a hierarchy of | 1122 and groups thus subdivide the specification list into a hierarchy of |
1111 levels. Specification keywords only apply to the remainder of the | 1123 levels. Specification keywords apply only to the remainder of the |
1112 sublist or group they are contained in. | 1124 sublist or group they are contained in. |
1113 | 1125 |
1114 When a specification list involves alternatives or repetition, matching | 1126 When a specification list involves alternatives or repetition, matching |
1115 it against an actual macro call may require backtracking. | 1127 it against an actual macro call may require backtracking. |
1116 @xref{Backtracking}, for more details. | 1128 @xref{Backtracking}, for more details. |
1260 sublist-elements@dots{})}. | 1272 sublist-elements@dots{})}. |
1261 @end table | 1273 @end table |
1262 | 1274 |
1263 @c Need to document extensions with &symbol and :symbol | 1275 @c Need to document extensions with &symbol and :symbol |
1264 | 1276 |
1265 Here is a list of additional specifications that may only appear after | 1277 Here is a list of additional specifications that may appear only after |
1266 @code{&define}. See the @code{defun} example below. | 1278 @code{&define}. See the @code{defun} example below. |
1267 | 1279 |
1268 @table @code | 1280 @table @code |
1269 @item name | 1281 @item name |
1270 The argument, a symbol, is the name of the defining form. | 1282 The argument, a symbol, is the name of the defining form. |
1302 tracing information is not output when the form is executed. See the | 1314 tracing information is not output when the form is executed. See the |
1303 @code{interactive} example below. | 1315 @code{interactive} example below. |
1304 @end table | 1316 @end table |
1305 | 1317 |
1306 @node Backtracking | 1318 @node Backtracking |
1307 @subsubsection Backtracking | 1319 @subsubsection Backtracking in Specifications |
1308 | 1320 |
1309 @cindex backtracking | 1321 @cindex backtracking |
1310 @cindex syntax error (Edebug) | 1322 @cindex syntax error (Edebug) |
1311 If a specification fails to match at some point, this does not | 1323 If a specification fails to match at some point, this does not |
1312 necessarily mean a syntax error will be signaled; instead, | 1324 necessarily mean a syntax error will be signaled; instead, |
1471 The default value is @code{step}. | 1483 The default value is @code{step}. |
1472 @xref{Edebug Execution Modes}. | 1484 @xref{Edebug Execution Modes}. |
1473 @end defopt | 1485 @end defopt |
1474 | 1486 |
1475 @defopt edebug-trace | 1487 @defopt edebug-trace |
1476 @findex edebug-print-trace-before | |
1477 @findex edebug-print-trace-after | |
1478 Non-@code{nil} means display a trace of function entry and exit. | 1488 Non-@code{nil} means display a trace of function entry and exit. |
1479 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one | 1489 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one |
1480 function entry or exit per line, indented by the recursion level. | 1490 function entry or exit per line, indented by the recursion level. |
1481 | 1491 |
1482 The default value is @code{nil}. | 1492 The default value is @code{nil}. |
1502 that is executing outside of Edebug. Use this with caution since it is not | 1512 that is executing outside of Edebug. Use this with caution since it is not |
1503 debugged. | 1513 debugged. |
1504 @xref{Edebug Execution Modes}. | 1514 @xref{Edebug Execution Modes}. |
1505 @end defopt | 1515 @end defopt |
1506 | 1516 |
1507 @defopt edebug-print-length | |
1508 If non-@code{nil}, bind @code{print-length} to this while printing | |
1509 results in Edebug. The default value is @code{50}. | |
1510 @xref{Printing in Edebug}. | |
1511 @end defopt | |
1512 | |
1513 @defopt edebug-print-level | |
1514 If non-@code{nil}, bind @code{print-level} to this while printing | |
1515 results in Edebug. The default value is @code{50}. | |
1516 @end defopt | |
1517 | |
1518 @defopt edebug-print-circle | |
1519 If non-@code{nil}, bind @code{print-circle} to this while printing | |
1520 results in Edebug. The default value is @code{nil}. | |
1521 @end defopt | |
1522 | |
1523 @defopt edebug-on-error | 1517 @defopt edebug-on-error |
1524 Edebug binds @code{debug-on-error} to this value, if | 1518 Edebug binds @code{debug-on-error} to this value, if |
1525 @code{debug-on-error} was previously @code{nil}. @xref{Trapping | 1519 @code{debug-on-error} was previously @code{nil}. @xref{Trapping |
1526 Errors}. | 1520 Errors}. |
1527 @end defopt | 1521 @end defopt |