Mercurial > emacs
comparison etc/DEBUG @ 35791:7c5f4564ff27
Changes, clean-ups, and typo fixes from Richard Stallman.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Wed, 31 Jan 2001 17:34:45 +0000 |
parents | c6ae90d82552 |
children | 9cc9788cc61b |
comparison
equal
deleted
inserted
replaced
35790:3fc2133e50d9 | 35791:7c5f4564ff27 |
---|---|
26 "kill -TSTP PID", where PID is the Emacs process ID, will cause GDB to | 26 "kill -TSTP PID", where PID is the Emacs process ID, will cause GDB to |
27 kick in, provided that you run under GDB. | 27 kick in, provided that you run under GDB. |
28 | 28 |
29 ** Getting control to the debugger | 29 ** Getting control to the debugger |
30 | 30 |
31 `Fsignal' is a very useful place to stop in. | 31 `Fsignal' is a very useful place to put a breakpoint in. |
32 All Lisp errors go through there. | 32 All Lisp errors go through there. |
33 | 33 |
34 It is useful, when debugging, to have a guaranteed way | 34 It is useful, when debugging, to have a guaranteed way to return to |
35 to return to the debugger at any time. If you are using | 35 the debugger at any time. When using X, this is easy: type C-c at the |
36 interrupt-driven input, which is the default, then Emacs is using | 36 window where Emacs is running under GDB, and it will stop Emacs just |
37 RAW mode and the only way you can do it is to store | 37 as it would stop any ordinary program. When Emacs is running in a |
38 the code for some character into the variable stop_character: | 38 terminal, things are not so easy. |
39 | |
40 The src/.gdbinit file in the Emacs distribution arranges for SIGINT | |
41 (C-g in Emacs) to be passed to Emacs and not give control back to GDB. | |
42 On modern POSIX systems, you can override that with this command: | |
43 | |
44 handle int stop nopass | |
45 | |
46 After this `handle' command, SIGINT will return control to GDB. If | |
47 you want the C-g to cause a QUIT within Emacs as well, omit the | |
48 `nopass'. | |
49 | |
50 A technique that can work when `handle SIGINT' does not is to store | |
51 the code for some character into the variable stop_character. Thus, | |
39 | 52 |
40 set stop_character = 29 | 53 set stop_character = 29 |
41 | 54 |
42 makes Control-] (decimal code 29) the stop character. | 55 makes Control-] (decimal code 29) the stop character. |
43 Typing Control-] will cause immediate stop. You cannot | 56 Typing Control-] will cause immediate stop. You cannot |
44 use the set command until the inferior process has been started. | 57 use the set command until the inferior process has been started. |
45 Put a breakpoint early in `main', or suspend the Emacs, | 58 Put a breakpoint early in `main', or suspend the Emacs, |
46 to get an opportunity to do the set command. | 59 to get an opportunity to do the set command. |
47 | |
48 If you are using cbreak input (see the Lisp function set-input-mode), | |
49 then typing Control-g will cause a SIGINT, which will return control | |
50 to GDB immediately if you type this command first: | |
51 | |
52 handle 2 stop | |
53 | |
54 By default the src/.gdbinit file in the Emacs distribution arranges | |
55 for SIGINT to be passed to Emacs. You can type C-z, which generates | |
56 SIGTSTP, to cause GDB to regain control. | |
57 | 60 |
58 ** Examining Lisp object values. | 61 ** Examining Lisp object values. |
59 | 62 |
60 When you have a live process to debug, and it has not encountered a | 63 When you have a live process to debug, and it has not encountered a |
61 fatal error, you can use the GDB command `pr'. First print the value | 64 fatal error, you can use the GDB command `pr'. First print the value |
67 to stack overflow), or crucial data structures, such as `obarray', | 70 to stack overflow), or crucial data structures, such as `obarray', |
68 corrupted, etc. In such cases, the Emacs subroutine called by `pr' | 71 corrupted, etc. In such cases, the Emacs subroutine called by `pr' |
69 might make more damage, like overwrite some data that is important for | 72 might make more damage, like overwrite some data that is important for |
70 debugging the original problem. | 73 debugging the original problem. |
71 | 74 |
72 If you can't use `pr' command, either because the process can't run a | 75 Also, on some systems it is impossible to use `pr' if you stopped |
73 subroutine or because the data is invalid or Emacs already got a fatal | 76 Emacs while it was inside `select'. This is in fact what happens if |
74 signal, you can fall back on lower-level commands. | 77 you stop Emacs while it is waiting. In such a situation, don't try to |
75 | 78 use `pr'. Instead, use `s' to step out of the system call. Then |
76 Use the `xtype' command to print out the data type of the last data | 79 Emacs will be between instructions and capable of handling `pr'. |
77 value. Once you know the data type, use the command that corresponds | 80 |
78 to that type. Here are these commands: | 81 If you can't use `pr' command, for whatever reason, you can fall back |
82 on lower-level commands. Use the `xtype' command to print out the | |
83 data type of the last data value. Once you know the data type, use | |
84 the command that corresponds to that type. Here are these commands: | |
79 | 85 |
80 xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd | 86 xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd |
81 xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe | 87 xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe |
82 xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar | 88 xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar |
83 | 89 |
188 prints `i' elements of the vector `v' ending at the index `n'. | 194 prints `i' elements of the vector `v' ending at the index `n'. |
189 end | 195 end |
190 | 196 |
191 ** Getting Lisp-level backtrace information within GDB | 197 ** Getting Lisp-level backtrace information within GDB |
192 | 198 |
193 The most convenient way is to use the `xbacktrace' command. | 199 The most convenient way is to use the `xbacktrace' command. This |
200 shows the names of the Lisp functions that are currently active. | |
194 | 201 |
195 If that doesn't work (e.g., because the `backtrace_list' structure is | 202 If that doesn't work (e.g., because the `backtrace_list' structure is |
196 corrupted), type "bt" at the GDB prompt, to produce the C-level | 203 corrupted), type "bt" at the GDB prompt, to produce the C-level |
197 backtrace, and look for stack frames that call Ffuncall. Select them | 204 backtrace, and look for stack frames that call Ffuncall. Select them |
198 one by one in GDB, by typing "up N", where N is the appropriate number | 205 one by one in GDB, by typing "up N", where N is the appropriate number |
358 the machine where you started GDB and use the debugger from there. | 365 the machine where you started GDB and use the debugger from there. |
359 | 366 |
360 | 367 |
361 ** Running Emacs with Purify | 368 ** Running Emacs with Purify |
362 | 369 |
370 Some people who are willing to use non-free software use Purify. We | |
371 can't ethically ask you to you become a Purify user; but if you have | |
372 it, and you test Emacs with it, we will not refuse to look at the | |
373 results you find. | |
374 | |
363 Emacs compiled with Purify won't run without some hacking. Here are | 375 Emacs compiled with Purify won't run without some hacking. Here are |
364 some of the changes you might find necessary (SYSTEM-NAME and | 376 some of the changes you might find necessary (SYSTEM-NAME and |
365 MACHINE-NAME are the names of your OS- and CPU-specific headers in the | 377 MACHINE-NAME are the names of your OS- and CPU-specific headers in the |
366 subdirectories of `src'): | 378 subdirectories of `src'): |
367 | 379 |
384 Note that Purify might print lots of false alarms for bitfields used | 396 Note that Purify might print lots of false alarms for bitfields used |
385 by Emacs in some data structures. If you want to get rid of the false | 397 by Emacs in some data structures. If you want to get rid of the false |
386 alarms, you will have to hack the definitions of these data structures | 398 alarms, you will have to hack the definitions of these data structures |
387 on the respective headers to remove the ":N" bitfield definitions | 399 on the respective headers to remove the ":N" bitfield definitions |
388 (which will cause each such field to use a full int). | 400 (which will cause each such field to use a full int). |
389 | |
390 | 401 |
391 ** Debugging problems which happen in GC | 402 ** Debugging problems which happen in GC |
392 | 403 |
393 The array `last_marked' (defined on alloc.c) can be used to display | 404 The array `last_marked' (defined on alloc.c) can be used to display |
394 up to 500 last objects marked by the garbage collection process. The | 405 up to 500 last objects marked by the garbage collection process. The |
405 | 416 |
406 Once you discover the corrupted Lisp object or data structure, it is | 417 Once you discover the corrupted Lisp object or data structure, it is |
407 useful to look at it in a fresh session and compare its contents with | 418 useful to look at it in a fresh session and compare its contents with |
408 a session that you are debugging. | 419 a session that you are debugging. |
409 | 420 |
410 | |
411 ** Some suggestions for debugging on MS Windows: | 421 ** Some suggestions for debugging on MS Windows: |
412 | 422 |
413 (written by Marc Fleischeuers, Geoff Voelker and Andrew Innes) | 423 (written by Marc Fleischeuers, Geoff Voelker and Andrew Innes) |
414 | 424 |
415 To debug emacs with Microsoft Visual C++, you either start emacs from | 425 To debug Emacs with Microsoft Visual C++, you either start emacs from |
416 the debugger or attach the debugger to a running emacs process. To | 426 the debugger or attach the debugger to a running emacs process. To |
417 start emacs from the debugger, you can use the file bin/debug.bat. The | 427 start emacs from the debugger, you can use the file bin/debug.bat. The |
418 Microsoft Developer studio will start and under Project, Settings, | 428 Microsoft Developer studio will start and under Project, Settings, |
419 Debug, General you can set the command-line arguments and emacs' | 429 Debug, General you can set the command-line arguments and Emacs's |
420 startup directory. Set breakpoints (Edit, Breakpoints) at Fsignal and | 430 startup directory. Set breakpoints (Edit, Breakpoints) at Fsignal and |
421 other functions that you want to examine. Run the program (Build, | 431 other functions that you want to examine. Run the program (Build, |
422 Start debug). Emacs will start and the debugger will take control as | 432 Start debug). Emacs will start and the debugger will take control as |
423 soon as a breakpoint is hit. | 433 soon as a breakpoint is hit. |
424 | 434 |
425 You can also attach the debugger to an already running emacs process. | 435 You can also attach the debugger to an already running Emacs process. |
426 To do this, start up the Microsoft Developer studio and select Build, | 436 To do this, start up the Microsoft Developer studio and select Build, |
427 Start debug, Attach to process. Choose the Emacs process from the | 437 Start debug, Attach to process. Choose the Emacs process from the |
428 list. Send a break to the running process (Debug, Break) and you will | 438 list. Send a break to the running process (Debug, Break) and you will |
429 find that execution is halted somewhere in user32.dll. Open the stack | 439 find that execution is halted somewhere in user32.dll. Open the stack |
430 trace window and go up the stack to w32_msg_pump. Now you can set | 440 trace window and go up the stack to w32_msg_pump. Now you can set |
431 breakpoints in Emacs (Edit, Breakpoints). Continue the running Emacs | 441 breakpoints in Emacs (Edit, Breakpoints). Continue the running Emacs |
432 process (Debug, Step out) and control will return to Emacs, until a | 442 process (Debug, Step out) and control will return to Emacs, until a |
433 breakpoint is hit. | 443 breakpoint is hit. |
434 | 444 |
435 To examine the contents of a lisp variable, you can use the function | 445 To examine the contents of a Lisp variable, you can use the function |
436 'debug_print'. Right-click on a variable, select QuickWatch (it has | 446 'debug_print'. Right-click on a variable, select QuickWatch (it has |
437 an eyeglass symbol on its button in the toolbar), and in the text | 447 an eyeglass symbol on its button in the toolbar), and in the text |
438 field at the top of the window, place 'debug_print(' and ')' around | 448 field at the top of the window, place 'debug_print(' and ')' around |
439 the expression. Press 'Recalculate' and the output is sent to stderr, | 449 the expression. Press 'Recalculate' and the output is sent to stderr, |
440 and to the debugger via the OutputDebugString routine. The output | 450 and to the debugger via the OutputDebugString routine. The output |
450 halt execution. Emacs should halt in `ZwUserGetMessage' waiting for | 460 halt execution. Emacs should halt in `ZwUserGetMessage' waiting for |
451 an input event. Use the `Call Stack' window to select the procedure | 461 an input event. Use the `Call Stack' window to select the procedure |
452 `w32_msp_pump' up the call stack (see below for why you have to do | 462 `w32_msp_pump' up the call stack (see below for why you have to do |
453 this). Open the QuickWatch window and enter | 463 this). Open the QuickWatch window and enter |
454 "debug_print(Vexec_path)". Evaluating this expression will then print | 464 "debug_print(Vexec_path)". Evaluating this expression will then print |
455 out the contents of the lisp variable `exec-path'. | 465 out the contents of the Lisp variable `exec-path'. |
456 | 466 |
457 If QuickWatch reports that the symbol is unknown, then check the call | 467 If QuickWatch reports that the symbol is unknown, then check the call |
458 stack in the `Call Stack' window. If the selected frame in the call | 468 stack in the `Call Stack' window. If the selected frame in the call |
459 stack is not an Emacs procedure, then the debugger won't recognize | 469 stack is not an Emacs procedure, then the debugger won't recognize |
460 Emacs symbols. Instead, select a frame that is inside an Emacs | 470 Emacs symbols. Instead, select a frame that is inside an Emacs |
467 thread and try using debug_print again. Note that the debugger halts | 477 thread and try using debug_print again. Note that the debugger halts |
468 execution (e.g., due to a breakpoint) in the context of the current | 478 execution (e.g., due to a breakpoint) in the context of the current |
469 thread, so this should only be a problem if you've explicitly switched | 479 thread, so this should only be a problem if you've explicitly switched |
470 threads. | 480 threads. |
471 | 481 |
472 It is also possible to keep appropriately masked and typecast lisp | 482 It is also possible to keep appropriately masked and typecast Lisp |
473 symbols in the Watch window, this is more convenient when steeping | 483 symbols in the Watch window, this is more convenient when steeping |
474 though the code. For instance, on entering apply_lambda, you can | 484 though the code. For instance, on entering apply_lambda, you can |
475 watch (struct Lisp_Symbol *) (0xfffffff & args[0]). | 485 watch (struct Lisp_Symbol *) (0xfffffff & args[0]). |