From: Eli Zaretskii Date: Mon, 5 Sep 2016 16:32:21 +0000 (+0300) Subject: ; * etc/DEBUG: Improve documentation of getting control to GDB. X-Git-Tag: emacs-25.1~8 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=304a5c8;p=emacs.git ; * etc/DEBUG: Improve documentation of getting control to GDB. Suggested by Alain Schneble . --- diff --git a/etc/DEBUG b/etc/DEBUG index eef67dad500..17c41092a67 100644 --- a/etc/DEBUG +++ b/etc/DEBUG @@ -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