Merge from origin/emacs-25

[gnu-emacs] / etc / DEBUG

diff --git a/etc/DEBUG b/etc/DEBUG
index 55102d3d9919dc780e160a5dd7ff42708b97cd40..d5d582902ab9b57f4762cb151721f7467145f31a 100644 (file)
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -1,6 +1,6 @@
 Debugging GNU Emacs
 
 Debugging GNU Emacs
 

-Copyright (C) 1985, 2000-2015 Free Software Foundation, Inc.
+Copyright (C) 1985, 2000-2016 Free Software Foundation, Inc.

 See the end of the file for license conditions.
 
 ** Preliminaries
 See the end of the file for license conditions.
 
 ** Preliminaries


@@ -72,12 +72,12 @@ prompt, to unconditionally load the GDB init file.
 *** Use the Emacs GDB UI front-end
 
 We recommend using the GUI front-end for GDB provided by Emacs.  With
 *** Use the Emacs GDB UI front-end
 
 We recommend using the GUI front-end for GDB provided by Emacs.  With

-it, you can start GDB by typing "M-x GDB RET".  This will suggest the
-default binary to debug; if you are going to start a new Emacs
-process, change it as needed to point to the correct binary.
-Alternatively, if you want to attach the debugger to an already
-running Emacs process, change the GDB command shown in the minibuffer
-to say this:
+it, you can start GDB by typing "M-x gdb RET".  This will suggest the
+file name of the default binary to debug; if the suggested default is
+not the Emacs binary you want to debug, change the file name as
+needed.  Alternatively, if you want to attach the debugger to an
+already running Emacs process, change the GDB command shown in the
+minibuffer to say this:

 
    gdb -i=mi -p PID
 
 
    gdb -i=mi -p PID
 


@@ -143,9 +143,16 @@ Many variables you will encounter while debugging are Lisp objects.
 These are displayed as integer values (or structures, if you used the
 "--enable-check-lisp-object-type" option at configure time) that are
 hard to interpret, especially if they represent long lists.  You can
 These are displayed as integer values (or structures, if you used the
 "--enable-check-lisp-object-type" option at configure time) that are
 hard to interpret, especially if they represent long lists.  You can

-use the 'pp' command to display them in their Lisp form.  Additional
-information about displaying Lisp objects can be found under
-"Examining Lisp object values" below.
+use the 'pp' command to display them in their Lisp form.  That command
+displays its output on the standard error stream, which you
+can redirect to a file using "M-x redirect-debugging-output".
+This means that if you attach GDB to a running Emacs that was invoked
+from a desktop icon, chances are you will not see the output at all,
+or it will wind up in an obscure place (check the documentation of
+your desktop environment).
+
+Additional information about displaying Lisp objects can be found
+under "Examining Lisp object values" below.

 
 The rest of this document describes specific useful techniques for
 debugging Emacs; we suggest reading it in its entirety the first time
 
 The rest of this document describes specific useful techniques for
 debugging Emacs; we suggest reading it in its entirety the first time


@@ -240,6 +247,12 @@ You can also use 'pp value' to print the emacs value directly.
 
 To see the current value of a Lisp Variable, use 'pv variable'.
 
 
 To see the current value of a Lisp Variable, use 'pv variable'.
 

+These commands send their output to stderr; if that is closed or
+redirected to some file you don't know, you won't see their output.
+This is particularly so for Emacs invoked on MS-Windows from the
+desktop shortcut.  You can use the command 'redirect-debugging-output'
+to redirect stderr to a file.
+

 Note: It is not a good idea to try 'pr', 'pp', or 'pv' if you know that Emacs
 is in deep trouble: its stack smashed (e.g., if it encountered SIGSEGV
 due to stack overflow), or crucial data structures, such as 'obarray',
 Note: It is not a good idea to try 'pr', 'pp', or 'pv' if you know that Emacs
 is in deep trouble: its stack smashed (e.g., if it encountered SIGSEGV
 due to stack overflow), or crucial data structures, such as 'obarray',


@@ -310,7 +323,7 @@ Then Emacs hits the breakpoint:
     [...]
   }
 
     [...]
   }
 

-Now we can use 'pr' to print the frame parameters:
+Now we can use 'pp' to print the frame parameters:

 
   (gdb) pp $->param_alist
   ((background-mode . light) (display-type . color) [...])
 
   (gdb) pp $->param_alist
   ((background-mode . light) (display-type . color) [...])


@@ -668,8 +681,9 @@ not exit when it should.
 On GNU and Unix systems, you can also trying sending Emacs SIGUSR2,
 which, if 'debug-on-event' has its default value, will cause Emacs to
 attempt to break it out of its current loop and into the Lisp
 On GNU and Unix systems, you can also trying sending Emacs SIGUSR2,
 which, if 'debug-on-event' has its default value, will cause Emacs to
 attempt to break it out of its current loop and into the Lisp

-debugger.  This feature is useful when a C-level debugger is not
-conveniently available.
+debugger.  (See the node "Debugging" in the ELisp manual for the
+details about the Lisp debugger.)  This feature is useful when a
+C-level debugger is not conveniently available.

 
 ** If certain operations in Emacs are slower than they used to be, here
 is some advice for how to find out why.
 
 ** If certain operations in Emacs are slower than they used to be, here
 is some advice for how to find out why.