Commit | Line | Data |
---|---|---|
c0274f38 ER |
1 | ;;; debug.el --- debuggers and related commands for Emacs |
2 | ||
14769773 | 3 | ;; Copyright (C) 1985, 1986, 1994 Free Software Foundation, Inc. |
9750e079 | 4 | |
e5167999 | 5 | ;; Maintainer: FSF |
e9571d2a | 6 | ;; Keywords: lisp, tools, maint |
e5167999 | 7 | |
0231f2dc JB |
8 | ;; This file is part of GNU Emacs. |
9 | ||
10 | ;; GNU Emacs is free software; you can redistribute it and/or modify | |
11 | ;; it under the terms of the GNU General Public License as published by | |
e5167999 | 12 | ;; the Free Software Foundation; either version 2, or (at your option) |
0231f2dc JB |
13 | ;; any later version. |
14 | ||
15 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
16 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | ;; GNU General Public License for more details. | |
19 | ||
20 | ;; You should have received a copy of the GNU General Public License | |
21 | ;; along with GNU Emacs; see the file COPYING. If not, write to | |
22 | ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. | |
23 | ||
e41b2db1 ER |
24 | ;;; Commentary: |
25 | ||
26 | ;; This is a major mode documented in the Emacs manual. | |
27 | ||
e5167999 | 28 | ;;; Code: |
0231f2dc JB |
29 | |
30 | (defvar debug-function-list nil | |
31 | "List of functions currently set for debug on entry.") | |
32 | ||
cf1c8cd9 | 33 | (defvar debugger-outer-match-data) |
35cf010d RS |
34 | (defvar debugger-outer-track-mouse) |
35 | (defvar debugger-outer-last-command) | |
36 | (defvar debugger-outer-this-command) | |
37 | (defvar debugger-outer-unread-command-char) | |
38 | (defvar debugger-outer-unread-command-events) | |
39 | (defvar debugger-outer-last-input-event) | |
40 | (defvar debugger-outer-last-command-event) | |
41 | (defvar debugger-outer-last-nonmenu-event) | |
42 | (defvar debugger-outer-last-event-frame) | |
43 | (defvar debugger-outer-standard-input) | |
44 | (defvar debugger-outer-standard-output) | |
45 | (defvar debugger-outer-cursor-in-echo-area) | |
46 | ||
0231f2dc JB |
47 | ;;;###autoload |
48 | (setq debugger 'debug) | |
49 | ;;;###autoload | |
50 | (defun debug (&rest debugger-args) | |
2512acba | 51 | "Enter debugger. To return, type \\<debugger-mode-map>`\\[debugger-continue]'. |
0231f2dc JB |
52 | Arguments are mainly for use when this is called from the internals |
53 | of the evaluator. | |
54 | ||
55 | You may call with no args, or you may pass nil as the first arg and | |
56 | any other args you like. In that case, the list of args after the | |
57 | first will be printed into the backtrace buffer." | |
58 | (message "Entering debugger...") | |
59 | (let (debugger-value | |
0231f2dc JB |
60 | (debug-on-error nil) |
61 | (debug-on-quit nil) | |
62 | (debugger-buffer (let ((default-major-mode 'fundamental-mode)) | |
36363ac1 | 63 | (get-buffer-create "*Backtrace*"))) |
0231f2dc JB |
64 | (debugger-old-buffer (current-buffer)) |
65 | (debugger-step-after-exit nil) | |
66 | ;; Don't keep reading from an executing kbd macro! | |
67 | (executing-macro nil) | |
35cf010d RS |
68 | ;; Save the outer values of these vars for the `e' command |
69 | ;; before we replace the values. | |
cf1c8cd9 | 70 | (debugger-outer-match-data (match-data)) |
35cf010d RS |
71 | (debugger-outer-track-mouse track-mouse) |
72 | (debugger-outer-last-command last-command) | |
73 | (debugger-outer-this-command this-command) | |
74 | (debugger-outer-unread-command-char unread-command-char) | |
75 | (debugger-outer-unread-command-events unread-command-events) | |
76 | (debugger-outer-last-input-event last-input-event) | |
77 | (debugger-outer-last-command-event last-command-event) | |
78 | (debugger-outer-last-nonmenu-event last-nonmenu-event) | |
79 | (debugger-outer-last-event-frame last-event-frame) | |
80 | (debugger-outer-standard-input standard-input) | |
81 | (debugger-outer-standard-output standard-output) | |
82 | (debugger-outer-cursor-in-echo-area cursor-in-echo-area)) | |
83 | ;; Don't let these magic variables affect the debugger itself. | |
84 | (let ((last-command nil) this-command track-mouse | |
b2ecc630 | 85 | (unread-command-char -1) unread-command-events |
35cf010d RS |
86 | last-input-event last-command-event last-nonmenu-event |
87 | last-event-frame | |
88 | (standard-input t) (standard-output t) | |
89 | (cursor-in-echo-area nil)) | |
90 | (unwind-protect | |
91 | (save-excursion | |
92 | (save-window-excursion | |
93 | (pop-to-buffer debugger-buffer) | |
94 | (erase-buffer) | |
95 | (let ((standard-output (current-buffer)) | |
96 | (print-escape-newlines t) | |
97 | (print-length 50)) | |
98 | (backtrace)) | |
99 | (goto-char (point-min)) | |
100 | (debugger-mode) | |
101 | (delete-region (point) | |
102 | (progn | |
103 | (search-forward "\n debug(") | |
104 | (forward-line 1) | |
105 | (point))) | |
106 | (debugger-reenable) | |
f4249c6f RS |
107 | ;; lambda is for debug-on-call when a function call is next. |
108 | ;; debug is for debug-on-entry function called. | |
35cf010d RS |
109 | (cond ((memq (car debugger-args) '(lambda debug)) |
110 | (insert "Entering:\n") | |
111 | (if (eq (car debugger-args) 'debug) | |
112 | (progn | |
f4249c6f RS |
113 | ;; Skip the frames for backtrace-debug, byte-code, |
114 | ;; and debug. | |
115 | (backtrace-debug 3 t) | |
35cf010d RS |
116 | (delete-char 1) |
117 | (insert ?*) | |
118 | (beginning-of-line)))) | |
f4249c6f | 119 | ;; Exiting a function. |
35cf010d RS |
120 | ((eq (car debugger-args) 'exit) |
121 | (insert "Return value: ") | |
122 | (setq debugger-value (nth 1 debugger-args)) | |
123 | (prin1 debugger-value (current-buffer)) | |
124 | (insert ?\n) | |
125 | (delete-char 1) | |
126 | (insert ? ) | |
127 | (beginning-of-line)) | |
f4249c6f | 128 | ;; Debugger entered for an error. |
35cf010d RS |
129 | ((eq (car debugger-args) 'error) |
130 | (insert "Signalling: ") | |
131 | (prin1 (nth 1 debugger-args) (current-buffer)) | |
132 | (insert ?\n)) | |
f4249c6f | 133 | ;; debug-on-call, when the next thing is an eval. |
35cf010d RS |
134 | ((eq (car debugger-args) t) |
135 | (insert "Beginning evaluation of function call form:\n")) | |
f4249c6f | 136 | ;; User calls debug directly. |
35cf010d RS |
137 | (t |
138 | (prin1 (if (eq (car debugger-args) 'nil) | |
139 | (cdr debugger-args) debugger-args) | |
140 | (current-buffer)) | |
141 | (insert ?\n))) | |
0231f2dc | 142 | (message "") |
35cf010d RS |
143 | (let ((inhibit-trace t) |
144 | (standard-output nil) | |
145 | (buffer-read-only t)) | |
146 | (message "") | |
147 | (recursive-edit)))) | |
36363ac1 KH |
148 | ;; Kill or at least neuter the backtrace buffer, so that users |
149 | ;; don't try to execute debugger commands in an invalid context. | |
150 | (if (get-buffer-window debugger-buffer 'visible) | |
151 | ;; Still visible despite the save-window-excursion? Maybe it | |
152 | ;; it's in a pop-up frame. It would be annoying to delete and | |
153 | ;; recreate it every time the debugger stops, so instead we'll | |
154 | ;; erase it but leave it visible. | |
155 | (save-excursion | |
156 | (set-buffer debugger-buffer) | |
157 | (erase-buffer) | |
158 | (fundamental-mode)) | |
159 | (kill-buffer debugger-buffer)) | |
cf1c8cd9 | 160 | (store-match-data debugger-outer-match-data))) |
35cf010d RS |
161 | ;; Put into effect the modified values of these variables |
162 | ;; in case the user set them with the `e' command. | |
163 | (setq track-mouse debugger-outer-track-mouse) | |
164 | (setq last-command debugger-outer-last-command) | |
165 | (setq this-command debugger-outer-this-command) | |
166 | (setq unread-command-char debugger-outer-unread-command-char) | |
167 | (setq unread-command-events debugger-outer-unread-command-events) | |
168 | (setq last-input-event debugger-outer-last-input-event) | |
169 | (setq last-command-event debugger-outer-last-command-event) | |
170 | (setq last-nonmenu-event debugger-outer-last-nonmenu-event) | |
171 | (setq last-event-frame debugger-outer-last-event-frame) | |
172 | (setq standard-input debugger-outer-standard-input) | |
173 | (setq standard-output debugger-outer-standard-output) | |
14769773 | 174 | (setq cursor-in-echo-area debugger-outer-cursor-in-echo-area) |
0231f2dc JB |
175 | (setq debug-on-next-call debugger-step-after-exit) |
176 | debugger-value)) | |
177 | \f | |
178 | (defun debugger-step-through () | |
179 | "Proceed, stepping through subexpressions of this expression. | |
180 | Enter another debugger on next entry to eval, apply or funcall." | |
181 | (interactive) | |
182 | (setq debugger-step-after-exit t) | |
183 | (message "Proceeding, will debug on next eval or call.") | |
184 | (exit-recursive-edit)) | |
185 | ||
186 | (defun debugger-continue () | |
187 | "Continue, evaluating this expression without stopping." | |
188 | (interactive) | |
189 | (message "Continuing.") | |
190 | (exit-recursive-edit)) | |
191 | ||
192 | (defun debugger-return-value (val) | |
193 | "Continue, specifying value to return. | |
194 | This is only useful when the value returned from the debugger | |
195 | will be used, such as in a debug on exit from a frame." | |
196 | (interactive "XReturn value (evaluated): ") | |
197 | (setq debugger-value val) | |
198 | (princ "Returning " t) | |
199 | (prin1 debugger-value) | |
200 | (exit-recursive-edit)) | |
201 | ||
202 | (defun debugger-jump () | |
203 | "Continue to exit from this frame, with all debug-on-entry suspended." | |
204 | (interactive) | |
205 | ;; Compensate for the two extra stack frames for debugger-jump. | |
206 | (let ((debugger-frame-offset (+ debugger-frame-offset 2))) | |
207 | (debugger-frame)) | |
208 | ;; Turn off all debug-on-entry functions | |
209 | ;; but leave them in the list. | |
210 | (let ((list debug-function-list)) | |
211 | (while list | |
212 | (fset (car list) | |
213 | (debug-on-entry-1 (car list) (symbol-function (car list)) nil)) | |
214 | (setq list (cdr list)))) | |
215 | (message "Continuing through this frame") | |
216 | (exit-recursive-edit)) | |
217 | ||
218 | (defun debugger-reenable () | |
219 | "Turn all debug-on-entry functions back on." | |
220 | (let ((list debug-function-list)) | |
221 | (while list | |
222 | (or (consp (symbol-function (car list))) | |
223 | (debug-convert-byte-code (car list))) | |
224 | (fset (car list) | |
225 | (debug-on-entry-1 (car list) (symbol-function (car list)) t)) | |
226 | (setq list (cdr list))))) | |
227 | ||
228 | (defun debugger-frame-number () | |
229 | "Return number of frames in backtrace before the one point points at." | |
230 | (save-excursion | |
231 | (beginning-of-line) | |
232 | (let ((opoint (point)) | |
233 | (count 0)) | |
234 | (goto-char (point-min)) | |
235 | (if (or (equal (buffer-substring (point) (+ (point) 6)) | |
236 | "Signal") | |
237 | (equal (buffer-substring (point) (+ (point) 6)) | |
238 | "Return")) | |
239 | (progn | |
240 | (search-forward ":") | |
241 | (forward-sexp 1))) | |
242 | (forward-line 1) | |
243 | (while (progn | |
244 | (forward-char 2) | |
245 | (if (= (following-char) ?\() | |
246 | (forward-sexp 1) | |
247 | (forward-sexp 2)) | |
248 | (forward-line 1) | |
249 | (<= (point) opoint)) | |
250 | (setq count (1+ count))) | |
251 | count))) | |
252 | ||
253 | ;; Chosen empirically to account for all the frames | |
254 | ;; that will exist when debugger-frame is called | |
255 | ;; within the first one that appears in the backtrace buffer. | |
256 | ;; Assumes debugger-frame is called from a key; | |
257 | ;; will be wrong if it is called with Meta-x. | |
258 | (defconst debugger-frame-offset 8 "") | |
259 | ||
260 | (defun debugger-frame () | |
261 | "Request entry to debugger when this frame exits. | |
262 | Applies to the frame whose line point is on in the backtrace." | |
263 | (interactive) | |
264 | (beginning-of-line) | |
265 | (let ((level (debugger-frame-number))) | |
266 | (backtrace-debug (+ level debugger-frame-offset) t)) | |
267 | (if (= (following-char) ? ) | |
268 | (let ((buffer-read-only nil)) | |
269 | (delete-char 1) | |
270 | (insert ?*))) | |
271 | (beginning-of-line)) | |
272 | ||
273 | (defun debugger-frame-clear () | |
274 | "Do not enter to debugger when this frame exits. | |
275 | Applies to the frame whose line point is on in the backtrace." | |
276 | (interactive) | |
277 | (beginning-of-line) | |
278 | (let ((level (debugger-frame-number))) | |
279 | (backtrace-debug (+ level debugger-frame-offset) nil)) | |
280 | (if (= (following-char) ?*) | |
281 | (let ((buffer-read-only nil)) | |
282 | (delete-char 1) | |
283 | (insert ? ))) | |
284 | (beginning-of-line)) | |
285 | ||
286 | (defun debugger-eval-expression (exp) | |
8782c06b RS |
287 | "Eval an expression, in an environment like that outside the debugger." |
288 | (interactive | |
289 | (list (read-from-minibuffer "Eval: " | |
290 | nil read-expression-map t | |
291 | 'read-expression-history))) | |
0231f2dc JB |
292 | (save-excursion |
293 | (if (null (buffer-name debugger-old-buffer)) | |
294 | ;; old buffer deleted | |
295 | (setq debugger-old-buffer (current-buffer))) | |
296 | (set-buffer debugger-old-buffer) | |
35cf010d RS |
297 | (let ((track-mouse debugger-outer-track-mouse) |
298 | (last-command debugger-outer-last-command) | |
299 | (this-command debugger-outer-this-command) | |
300 | (unread-command-char debugger-outer-unread-command-char) | |
301 | (unread-command-events debugger-outer-unread-command-events) | |
302 | (last-input-event debugger-outer-last-input-event) | |
303 | (last-command-event debugger-outer-last-command-event) | |
304 | (last-nonmenu-event debugger-outer-last-nonmenu-event) | |
305 | (last-event-frame debugger-outer-last-event-frame) | |
306 | (standard-input debugger-outer-standard-input) | |
307 | (standard-output debugger-outer-standard-output) | |
308 | (cursor-in-echo-area debugger-outer-cursor-in-echo-area)) | |
cf1c8cd9 | 309 | (store-match-data debugger-outer-match-data) |
35cf010d | 310 | (prog1 (eval-expression exp) |
cf1c8cd9 | 311 | (setq debugger-outer-match-data (match-data)) |
35cf010d RS |
312 | (setq debugger-outer-track-mouse track-mouse) |
313 | (setq debugger-outer-last-command last-command) | |
314 | (setq debugger-outer-this-command this-command) | |
315 | (setq debugger-outer-unread-command-char unread-command-char) | |
316 | (setq debugger-outer-unread-command-events unread-command-events) | |
317 | (setq debugger-outer-last-input-event last-input-event) | |
318 | (setq debugger-outer-last-command-event last-command-event) | |
319 | (setq debugger-outer-last-nonmenu-event last-nonmenu-event) | |
320 | (setq debugger-outer-last-event-frame last-event-frame) | |
321 | (setq debugger-outer-standard-input standard-input) | |
322 | (setq debugger-outer-standard-output standard-output) | |
323 | (setq debugger-outer-cursor-in-echo-area cursor-in-echo-area))))) | |
0231f2dc JB |
324 | \f |
325 | (defvar debugger-mode-map nil) | |
326 | (if debugger-mode-map | |
327 | nil | |
328 | (let ((loop ? )) | |
329 | (setq debugger-mode-map (make-keymap)) | |
330 | (suppress-keymap debugger-mode-map) | |
331 | (define-key debugger-mode-map "-" 'negative-argument) | |
332 | (define-key debugger-mode-map "b" 'debugger-frame) | |
333 | (define-key debugger-mode-map "c" 'debugger-continue) | |
334 | (define-key debugger-mode-map "j" 'debugger-jump) | |
335 | (define-key debugger-mode-map "r" 'debugger-return-value) | |
336 | (define-key debugger-mode-map "u" 'debugger-frame-clear) | |
337 | (define-key debugger-mode-map "d" 'debugger-step-through) | |
338 | (define-key debugger-mode-map "l" 'debugger-list-functions) | |
339 | (define-key debugger-mode-map "h" 'describe-mode) | |
340 | (define-key debugger-mode-map "q" 'top-level) | |
341 | (define-key debugger-mode-map "e" 'debugger-eval-expression) | |
342 | (define-key debugger-mode-map " " 'next-line))) | |
343 | ||
344 | (put 'debugger-mode 'mode-class 'special) | |
345 | ||
346 | (defun debugger-mode () | |
347 | "Mode for backtrace buffers, selected in debugger. | |
348 | \\<debugger-mode-map> | |
349 | A line starts with `*' if exiting that frame will call the debugger. | |
350 | Type \\[debugger-frame] or \\[debugger-frame-clear] to set or remove the `*'. | |
351 | ||
352 | When in debugger due to frame being exited, | |
353 | use the \\[debugger-return-value] command to override the value | |
354 | being returned from that frame. | |
355 | ||
356 | Use \\[debug-on-entry] and \\[cancel-debug-on-entry] to control | |
357 | which functions will enter the debugger when called. | |
358 | ||
359 | Complete list of commands: | |
360 | \\{debugger-mode-map}" | |
361 | (kill-all-local-variables) | |
362 | (setq major-mode 'debugger-mode) | |
363 | (setq mode-name "Debugger") | |
364 | (setq truncate-lines t) | |
365 | (set-syntax-table emacs-lisp-mode-syntax-table) | |
366 | (use-local-map debugger-mode-map)) | |
367 | \f | |
368 | ;;;###autoload | |
369 | (defun debug-on-entry (function) | |
370 | "Request FUNCTION to invoke debugger each time it is called. | |
2512acba RS |
371 | If you tell the debugger to continue, FUNCTION's execution proceeds. |
372 | This works by modifying the definition of FUNCTION, | |
0231f2dc JB |
373 | which must be written in Lisp, not predefined. |
374 | Use \\[cancel-debug-on-entry] to cancel the effect of this command. | |
2512acba | 375 | Redefining FUNCTION also cancels it." |
0231f2dc JB |
376 | (interactive "aDebug on entry (to function): ") |
377 | (debugger-reenable) | |
378 | (if (subrp (symbol-function function)) | |
379 | (error "Function %s is a primitive" function)) | |
380 | (or (consp (symbol-function function)) | |
381 | (debug-convert-byte-code function)) | |
382 | (or (consp (symbol-function function)) | |
383 | (error "Definition of %s is not a list" function)) | |
384 | (fset function (debug-on-entry-1 function (symbol-function function) t)) | |
385 | (or (memq function debug-function-list) | |
386 | (setq debug-function-list (cons function debug-function-list))) | |
387 | function) | |
388 | ||
389 | ;;;###autoload | |
390 | (defun cancel-debug-on-entry (&optional function) | |
391 | "Undo effect of \\[debug-on-entry] on FUNCTION. | |
392 | If argument is nil or an empty string, cancel for all functions." | |
10a4c11f JB |
393 | (interactive |
394 | (list (let ((name | |
395 | (completing-read "Cancel debug on entry (to function): " | |
396 | ;; Make an "alist" of the functions | |
397 | ;; that now have debug on entry. | |
398 | (mapcar 'list | |
399 | (mapcar 'symbol-name | |
400 | debug-function-list)) | |
401 | nil t nil))) | |
402 | (if name (intern name))))) | |
0231f2dc JB |
403 | (debugger-reenable) |
404 | (if (and function (not (string= function ""))) | |
405 | (progn | |
406 | (fset function | |
407 | (debug-on-entry-1 function (symbol-function function) nil)) | |
408 | (setq debug-function-list (delq function debug-function-list)) | |
409 | function) | |
410 | (message "Cancelling debug-on-entry for all functions") | |
411 | (mapcar 'cancel-debug-on-entry debug-function-list))) | |
412 | ||
413 | (defun debug-convert-byte-code (function) | |
414 | (let ((defn (symbol-function function))) | |
415 | (if (not (consp defn)) | |
416 | ;; Assume a compiled code object. | |
417 | (let* ((contents (append defn nil)) | |
418 | (body | |
419 | (list (list 'byte-code (nth 1 contents) | |
420 | (nth 2 contents) (nth 3 contents))))) | |
421 | (if (nthcdr 5 contents) | |
422 | (setq body (cons (list 'interactive (nth 5 contents)) body))) | |
423 | (if (nth 4 contents) | |
c8c76dd3 RS |
424 | ;; Use `documentation' here, to get the actual string, |
425 | ;; in case the compiled function has a reference | |
426 | ;; to the .elc file. | |
427 | (setq body (cons (documentation function) body))) | |
0231f2dc JB |
428 | (fset function (cons 'lambda (cons (car contents) body))))))) |
429 | ||
430 | (defun debug-on-entry-1 (function defn flag) | |
431 | (if (subrp defn) | |
432 | (error "%s is a built-in function" function) | |
433 | (if (eq (car defn) 'macro) | |
434 | (debug-on-entry-1 function (cdr defn) flag) | |
435 | (or (eq (car defn) 'lambda) | |
436 | (error "%s not user-defined Lisp function" function)) | |
437 | (let (tail prec) | |
438 | (if (stringp (car (nthcdr 2 defn))) | |
439 | (setq tail (nthcdr 3 defn) | |
440 | prec (list (car defn) (car (cdr defn)) | |
441 | (car (cdr (cdr defn))))) | |
442 | (setq tail (nthcdr 2 defn) | |
443 | prec (list (car defn) (car (cdr defn))))) | |
444 | (if (eq flag (equal (car tail) '(debug 'debug))) | |
445 | defn | |
446 | (if flag | |
447 | (nconc prec (cons '(debug 'debug) tail)) | |
448 | (nconc prec (cdr tail)))))))) | |
449 | ||
450 | (defun debugger-list-functions () | |
451 | "Display a list of all the functions now set to debug on entry." | |
452 | (interactive) | |
453 | (with-output-to-temp-buffer "*Help*" | |
454 | (if (null debug-function-list) | |
455 | (princ "No debug-on-entry functions now\n") | |
456 | (princ "Functions set to debug on entry:\n\n") | |
457 | (let ((list debug-function-list)) | |
458 | (while list | |
459 | (prin1 (car list)) | |
460 | (terpri) | |
461 | (setq list (cdr list)))) | |
462 | (princ "Note: if you have redefined a function, then it may no longer\n") | |
89961ff8 KH |
463 | (princ "be set to debug on entry, even if it is in the list.")) |
464 | (save-excursion | |
465 | (set-buffer standard-output) | |
466 | (help-mode)))) | |
c0274f38 ER |
467 | |
468 | ;;; debug.el ends here |