Re: Revise etc/DEBUG documentation

[Alain Schneble]

Eli Zaretskii <address@hidden> writes:

> I tried to find that boundary, see below.

Ok, thanks.

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

I see.

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

That is very obliging.

>> 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.

Ok.  Good idea.  But not sure if we can distinguish between executing
Emacs as GUI or terminal application in .gdbinit.  Because for the
latter, we certainly still want it to 'pass' (as it is currently
arranged for in .gdbinit).

> 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.

I was certainly biased by my personal findings that helped me to
understand the mechanisms, I agree.

>> 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.

Thanks.

>> 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).

I think I was again not clear enough, sorry. FWIW, what I meant is:

start a new command prompt
gdb
file emacs
set new-console 1
run

=> there are three windows: 1) GDB console, 2) Emacs console
(empty/"black" window) and 3) Emacs GUI window.

What I wanted to say is that one /can/ use 2) to enter C-c or C-break as
well. This results in GDB displaying 'Thread [n] received signal SIGINT,
Interrupt.'.

Of course you can use 1) as well.  But this will show a SIGTRAP instead
of a SIGINT message in GDB ('Thread [m] received signal SIGTRAP,
Trace/breakpoint trap').  Because 1) and 2) do not share the same
console, GDB can't send a GenerateConoleCtrlEvent and it falls back to
DebugBreakProcess.  That's the reason for the differernt behavior.

That was what confused me while studying the behavior.  BTW, I don't
think that this is different on XP (I tested this on MS Windows 10
here).  Is it?

>> 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.

Well, see my example above.  At least GDB shows it as a SIGINT.

> 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 was talking about Emacs *with GUI* started after 'set new-console 1'
here.  But after reading the paragraph again, I realized that I forgot
to mention it -- my apologies.

>> 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:

Thank you very much.

> 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.
> +

Perfect.

>  '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).

Now it's clear to me as well.  Thanks.

>  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.

Fair enough.

>  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
                                                ^^^^^^^^^^^^^^^^^^^^^^
Isn't this always useful or even required?  Or is there a standard use
case that requires not doing so?

> +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

Using here the term console instead of terminal is wise.

>  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

I agree with your changes.  These are the important points.  Thanks for
your help.