Re: Revise etc/DEBUG documentation

[Eli Zaretskii]

> From: Alain Schneble <address@hidden>
> Date: Sat, 3 Sep 2016 15:14:31 +0200
> Cc: address@hidden
> 
> > I also am not sure we should repeat here stuff that is basic GDB
> > usage.  Any such descriptions are bound to be incomplete and thus
> > inaccurate.  It is better to refer the readers to the GDB manual, if
> > they are not already proficient.
> 
> I basically agree.  But 1) there was already some information there and
> 2) some minimal hints really helps one (or at least me) to start off.
> But it's probably hard to find a good boundary where to stop.  I guess
> your point is that I passed it.

I tried to find that boundary, see below.

In general, etc/DEBUG is supposed to be a cookbook-like collection of
tips, not a full-fledged manual.

> > How about if we first add any missing information, and leave
> > rephrasing for a separate patch?  Or maybe just tell what you think is
> > missing in the current version, and let's take it from there.
> 
> Actually, I tried this first but I had the impression that I start
> mixing stuff that somehow does not belong together.  That's why I
> started to restructure it.

I tried to add the missing information without restructuring, see
below.

> > Some specific comments and questions follow.
> >
> >> +When Emacs is running under a window system, reception of a SIGINT and
> >> +SIGQUIT will cause it to terminate.  It might therefore be useful to
> >> +configure the 'handle' command for those signals to use 'nopass', to
> >> +prevent Emacs from terminating on reception of such signals.
> >
> > I don't understand why is this useful.
> 
> Because it allows one to hit C-c in GDB, do some changes such as adding
> breakpoints and then continue.  With 'pass' it would terminate Emacs if
> it is run as a GUI application.  When run in a terminal, it does not
> terminate.  A nuance.

If we believe typing C-c when debugging GUI frames is a frequent
possibility, then we should change .gdbinit to support the above
automatically.  I don't think we should start explaining the
intricacies of signal handling in Emacs and in GDB in this file.

> >> +When using a window system, there is no reason for Emacs to handle C-g
> >> +as a SIGINT, as keyboard input is processed by the window system's
> >> +message pump.  Hence, no signal is sent as a response to a C-g.
> >
> > This explains how Emacs works, but I'm not sure it belongs in DEBUG.
> 
> True.  But I think such background information would have helped me a
> lot.

I understand, but if we start putting in this file everything that
someone found useful because they didn't know it beforehand, we will
end up with a huge and unmanageable file, I'm afraid.

> >> +When using X, 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.
> >
> > The "window where Emacs is running under GDB" part is IMO confusing: I
> > couldn't figure out what window does this refer to.  There might not
> > be such a window at all, AFAIU.
> 
> To be honest, I don't understand this either.  But this was there
> before.  I just took it over and rephrased it slightly.  For example C-z
> in Gnome just minimizes the window (Emacs frame) AFAIK, but doesn't stop
> Emacs.  Do you know what C-z usually does in X window with a GUI
> application?  Does it send a signal to it?

I tried to clarify that, see below.

> > Next, what do you mean by "send a Ctrl-c or +Ctrl-Break to the
> > console"?  What console is alluded to here?
> 
> With new-console 1, when starting Emacs GUI, the console is visible as a
> separate window in MS-Windows.  And it is this console window that can
> be used to enter Ctrl-c or Ctrl-Break, even though we are running Emacs
> as a GUI application.

Are you sure?  I see something different here: when Emacs is started
after setting new-console, the window through which I interact with
GDB is the one where C-c causes GDB to get control back.  Maybe this
depends on the Windows version (it's XP down here, FWIW).

> > Finally, what does the "GDB treats them as a SIGINT, but Emacs won't
> > terminate as it ignores these events" part want to tell?  I couldn't
> > figure that out.
> That it behaves differently than on POSIX, where a SIGINT would
> terminate Emacs when running in "GUI mode".

That's actually inaccurate: on Windows, Emacs doesn't get a SIGINT in
this case, AFAIK.

> >>                                          or it will just ignore it
> >> +otherwise, as the event will be received by Emacs anyway when running
> >> +under the same terminal as GDB.
> >
> > This part is also confusing.  And I wonder why the signal-process
> > feature is not mentioned here.
> All processes sharing the same console will receive the C-c event.  In
> that case GDB doesn't have to escape to using DebugBreakProcess.  GDB
> just ignores C-c and Emacs will receive it anyway.  This was another
> thing that confused me.  That depenting on 'set new-console' setting,
> GDB signals either a SIGINT (due to C-c being received by Emacs) or a
> SIGTRAP (due to DebugBreakProcess) for the same initial C-c/SIGINT
> event.  A nuance.

I think we shouldn't even consider a use case when a text-mode Emacs
is debugged using the same terminal as the one used for communicating
with GDB.  It's not very practical to do so, since the GDB output is
mixed with Emacs's, and the result is a total mess.  Therefore,
allowing for that in the description just complicates the text for no
good reason.

> I hope I could clarify at least the intent of my change.  If you are
> still confused, I'll restart and try what you proposed: To find a way to
> only add missing information in the first place.  And to not rephrase
> existing content.

Please see if the alternative changes below catch everything that was
missing or inaccurate in the original text:

diff --git a/etc/DEBUG b/etc/DEBUG
index eef67da..7f3191d 100644
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -190,24 +190,39 @@ 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.
 
-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 POSIX 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 +231,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
+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 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.
+
+On MS-Windows, you can 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 +874,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