mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-03 08:30:09 +00:00
Code Issues Releases Activity

; * etc/DEBUG: Improve documentation of getting control to GDB.

Browse Source 
Suggested by Alain Schneble <a.s@realize.ch>.
This commit is contained in:
Eli Zaretskii 2016-09-05 19:32:21 +03:00
parent 56bf7d7e27
commit 304a5c8ef9
1 changed files with 49 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
etc/DEBUG
View File

@ -190,24 +190,40 @@ kick in, provided that you run under GDB.
** Getting control to the debugger
Setting a breakpoint in a strategic place, after loading Emacs into
the debugger, but before running it, is the most efficient way of
making sure control will be returned to the debugger when you need
that.
'Fsignal' is a very useful place to put a breakpoint in. All Lisp
errors go through there. If you are only interested in errors that
would fire the debugger, breaking at 'maybe_call_debugger' is useful.
would fire the Lisp debugger, breaking at 'maybe_call_debugger' is
useful.
It is useful, when debugging, to have a guaranteed way to return to
the debugger at any time. When using X, this is easy: type C-z at the
window where Emacs is running under GDB, and it will stop Emacs just
as it would stop any ordinary program. When Emacs is running in a
terminal, things are not so easy.
Another technique for get control to the debugger is to put a
breakpoint in some rarely used function. One such convenient function
is Fredraw_display, which you can invoke at will interactively with
"M-x redraw-display RET".
It is also useful to have a guaranteed way to return to the debugger
at any arbitrary time. When using X, this is easy: type C-z at the
window where you are interacting with GDB, and it will stop Emacs just
as it would stop any ordinary program. When Emacs is displaying on a
text terminal, things are not so easy, so we describe the various
alternatives below (however, those of them that use signals only work
on Posix systems).
The src/.gdbinit file in the Emacs distribution arranges for SIGINT
(C-g in Emacs) to be passed to Emacs and not give control back to GDB.
On modern POSIX systems, you can override that with this command:
(C-g in Emacs on a text-mode frame) to be passed to Emacs and not give
control back to GDB. On modern systems, you can override that with
this command:
handle SIGINT stop nopass
After this 'handle' command, SIGINT will return control to GDB. If
you want the C-g to cause a QUIT within Emacs as well, omit the 'nopass'.
See the GDB manual for more details about signal handling and the
'handle' command.
A technique that can work when 'handle SIGINT' does not is to store
the code for some character into the variable stop_character. Thus,
@ -216,26 +232,37 @@ the code for some character into the variable stop_character. Thus,
makes Control-] (decimal code 29) the stop character.
Typing Control-] will cause immediate stop. You cannot
use the set command until the inferior process has been started.
Put a breakpoint early in 'main', or suspend the Emacs,
to get an opportunity to do the set command.
use the set command until the inferior process has been started, so
start Emacs with the 'start' command, to get an opportunity to do the
above 'set' command.
Another technique for get control to the debugger is to put a
breakpoint in some rarely used function. One such convenient function
is Fredraw_display, which you can invoke at will interactively with
"M-x redraw-display RET".
On a Posix host, you can also send a signal using the 'kill' command
from a shell prompt, like this:
When Emacs is running in a terminal, it is sometimes useful to use a separate
terminal for the debug session. This can be done by starting Emacs as usual,
then attaching to it from gdb with the 'attach' command which is explained in
the node "Attach" of the GDB manual.
kill -TSTP Emacs-PID
On MS-Windows, you can start Emacs in its own separate terminal by
setting the new-console option before running Emacs under GDB:
where Emacs-PID is the process ID of Emacs being debugged. Other
useful signals to send are SIGUSR1 and SIGUSR2; see "Error Debugging"
in the ELisp manual for how to use those.
When Emacs is displaying on a text terminal, it is useful to have a
separate terminal for the debug session. This can be done by starting
Emacs as usual, then attaching to it from gdb with the 'attach'
command which is explained in the node "Attach" of the GDB manual.
On MS-Windows, you can alternatively start Emacs from its own separate
console by setting the new-console option before running Emacs under
GDB:
(gdb) set new-console 1
(gdb) run
If you do this, then typing C-c or C-BREAK into the console window
through which you interact with GDB will stop Emacs and return control
to the debugger, no matter if Emacs displays GUI or text-mode frames.
This is the only reliable alternative on MS-Windows to get control to
the debugger, besides setting breakpoints in advance.
** Examining Lisp object values.
When you have a live process to debug, and it has not encountered a
@ -848,7 +875,7 @@ directed to the xterm window you opened above.
Similar arrangement is possible on a character terminal by using the
'screen' package.
On MS-Windows, you can start Emacs in its own separate terminal by
On MS-Windows, you can start Emacs in its own separate console by
setting the new-console option before running Emacs under GDB:
(gdb) set new-console 1