Debugging Emacs

Debugging Emacs

[Phillip Lord]

I debugged Emacs core the other day for the first time. As I have no
experience with C, GDB or any of the Emacs tooling, I found this an
uphill struggle, so I have written up a short "how-to-debug" Emacs file.

It starts from a slightly earlier place than the current DEBUG file, and
is a step by step guide. The existing DEBUG file, I found pretty dense.

I was wondering if it is worth including first? Also, if my approach to
debugging is a good one, in case I am doing something daft. Comments
welcome.



** How to Debug Emacs C core

The following is a brief introduction on how to debug the C core of Emacs. It
assumes reasonable programming knowledge, but not particular knowledge of the
tooling, other than an understanding of how to build Emacs.

This is not a normative guide -- there are many ways to use these tools to
debug Emacs. It's a "hello world" guide. It describes one way that should work.

*** Preparing Emacs to be debugged

To debug Emacs, you need to build it from the tarball source file. First,
Emacs should be compiled with the correct flags to ensure that it can be
debugged cleanly.

This is achieve with the configure script which should be launched with the
following command line.

./configure --enable-checking --enable-check-lisp-object-type --config-cache CFLAGS="-Og -g3"

Strictly, only the CFLAGS part is necessary for debugging. The two "--enable"
flags will pick up some errors for you, and the --config-cache makes configure
run more quickly second time around (useful if you are switching between
branches in git).

Then to build type.

make

You do not need to install Emacs. It runs fine from a source build.

*** Preparing GDB

We will debug with GDB. Emacs comes with a nice set of configuration files for
working with GDB, with many useful functions. To use this, it needs to be
loaded first. Unfortunately, by default GDB disallows this, as it's a security
risk. So, you need to add the following line to your .gdbinit file.

add-auto-load-safe-path path/emacs/src/.gdbinit

This line will is actually printed out by GDB at start up (along with a lot of
other text), so you can copy it from there.
 
*** Preparing your debugging Emacs

We will debug Emacs using Emacs of course. You can debug and use the same
installation of Emacs if you choose. Or you can use an older, stable release.

Debugging with GDB uses quite a bit of screen space. If you do not have a
relatively large screen, then it decrease the font size to about the smallest
you can cope with.

Now open one of the source files of Emacs, found in the emacs/src directory.


*** Starting GDB

Start GDB directly from Emacs. If you do this from a buffer with a Emacs
source file, the it will start in the correct directory, which has to be the
src of Emacs, so that GDB will read the .gdbinit file described earlier.

M-x gdb

Change "bootstrap-emacs" to "emacs".


Next we will open lots of windows, most of which you will need. Unfortunately,
if you are reading this file in the same Emacs, you may no longer be able to
the file, but you can switch back to it as normal.

Now type,

M-x gdb-many-windows

If you want to restore this window configuration later, then

M-x gdb-restore-windows

will work.

One unfortunate side effect of the .gdbinit script is that it's hard to stop
Emacs when it has started, so we add a breakpoint somewhere in C in a function
that is not likely to be called. This will enable us to get Emacs to stop.

So, open the file floatfns.c and find the "log" function (search for "Flog").
You can set a breakpoint using the GDB menu, or by clicking in the fringe. If
you want to save this breakpoint for later use, try:

save breakpoint bplog.txt

in the GDB window. You can source it later.




*** Starting and Debugging Emacs


Now start Emacs. In the GBD window, type:

run -Q

(the -Q gets passed straight to Emacs. Add other options if you want).


GDB will now produce lots of output. Next type "continue" in the GDB window.
Emacs will now start. In this Emacs (not the one you launched GDB with) try
M-: (log 10)

This Emacs should now hang, and floatfns.c should have popped up.

The first argument to the log function is called, prosaically, "arg".
We can print the value of this, using the print command.


(gdb) print arg
$1 = {
  i = 42
}

Unfortunately, because it's actually a LispObject, that is now terrible
useful. If you want to see the "real" value, then try

pp arg

instead. This prints to the window "*input/output of emacs*" where you should
see

10

Another useful function is ppt which brings point

(gdb) ppt
BUF PT: 192[196] of 1..192[196] GAP: 192[196] SZ=2000

There are many more, and emacs/src/.gbdinit is worth reading in full.

Re: Debugging Emacs

[Karl Fogel]

On Fri, Nov 27, 2015 at 11:23 AM, Phillip Lord
<phillip.lord@russet.org.uk> wrote:
> I debugged Emacs core the other day for the first time. As I have no
> experience with C, GDB or any of the Emacs tooling, I found this an
> uphill struggle, so I have written up a short "how-to-debug" Emacs file.
>
> It starts from a slightly earlier place than the current DEBUG file, and
> is a step by step guide. The existing DEBUG file, I found pretty dense.

Have you considered finding a place for this somewhere in the
"Programming Emacs in Lisp and C" section of the Emacs Wiki at
http://www.emacswiki.org/#toc6 ?

Re: Debugging Emacs

[Eli Zaretskii]

> From: phillip.lord@russet.org.uk (Phillip Lord)
> Date: Fri, 27 Nov 2015 17:23:11 +0000
> 
> I debugged Emacs core the other day for the first time. As I have no
> experience with C, GDB or any of the Emacs tooling, I found this an
> uphill struggle, so I have written up a short "how-to-debug" Emacs file.

Thanks.  Some of this is already in etc/DEBUG, other parts belong to
basic GDB operation, so I'm not sure we should describe that in
Emacs.  I suggest that you read etc/DEBUG, if you didn't already, and
suggest changes to that file where you think it leaves something
important uncovered.

Re: Debugging Emacs

[Eli Zaretskii]

> Date: Fri, 27 Nov 2015 19:58:48 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> I suggest that you read etc/DEBUG, if you didn't already, and
> suggest changes to that file where you think it leaves something
> important uncovered.

More specifically, how about a preamble section at the beginning of
etc/DEBUG, named something like "If you are new to debugging Emacs",
and describing the preliminaries you think are important?  You can
refer to later sections instead of repeating what they say.

WDYT?

Re: Debugging Emacs

[Phillip Lord]

Karl Fogel <kfogel@red-bean.com> writes:

> On Fri, Nov 27, 2015 at 11:23 AM, Phillip Lord
> <phillip.lord@russet.org.uk> wrote:
>> I debugged Emacs core the other day for the first time. As I have no
>> experience with C, GDB or any of the Emacs tooling, I found this an
>> uphill struggle, so I have written up a short "how-to-debug" Emacs file.
>>
>> It starts from a slightly earlier place than the current DEBUG file, and
>> is a step by step guide. The existing DEBUG file, I found pretty dense.
>
> Have you considered finding a place for this somewhere in the
> "Programming Emacs in Lisp and C" section of the Emacs Wiki at
> http://www.emacswiki.org/#toc6 ?

I could do, but it makes more sense to me to have in Emacs, especially
as there is an existing DEBUG file.

Phil

Re: Debugging Emacs

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: phillip.lord@russet.org.uk (Phillip Lord)
>> Date: Fri, 27 Nov 2015 17:23:11 +0000
>> 
>> I debugged Emacs core the other day for the first time. As I have no
>> experience with C, GDB or any of the Emacs tooling, I found this an
>> uphill struggle, so I have written up a short "how-to-debug" Emacs file.
>
> Thanks.  Some of this is already in etc/DEBUG, other parts belong to
> basic GDB operation, so I'm not sure we should describe that in
> Emacs.  I suggest that you read etc/DEBUG, if you didn't already, and
> suggest changes to that file where you think it leaves something
> important uncovered.

With etc/DEBUG, I am worried not about what it does not say, but what it
does say. It's really very dense. For example, it starts with a
description of what src/.gdbinit does (at which point I still don't know
how to launch the debugger). Then has a very heavy section on compiler
flags which includes a section on DWARF.


> More specifically, how about a preamble section at the beginning of
> etc/DEBUG, named something like "If you are new to debugging Emacs",
> and describing the preliminaries you think are important?  You can
> refer to later sections instead of repeating what they say.

Yes, that was sort of the idea. Personally, I'd not be too worried about
repeating things. I realise that this adds to the maintainance burden,
but references to later sections make for harder reading.

I'll try and simplify what I wrote a bit further. Basically, I am after
the debugging hello world -- make a breakpoint, get the value of a
LispObject.

Phil

Re: Debugging Emacs

[Eli Zaretskii]

> From: phillip.lord@russet.org.uk (Phillip Lord)
> Date: Fri, 27 Nov 2015 21:53:51 +0000
> Cc: Emacs development discussions <emacs-devel@gnu.org>
> 
> > Have you considered finding a place for this somewhere in the
> > "Programming Emacs in Lisp and C" section of the Emacs Wiki at
> > http://www.emacswiki.org/#toc6 ?
> 
> I could do, but it makes more sense to me to have in Emacs, especially
> as there is an existing DEBUG file.

I agree.  CONTRIBUTE already points to etc/DEBUG, btw.

Re: Debugging Emacs

[Eli Zaretskii]

> From: phillip.lord@russet.org.uk (Phillip Lord)
> Cc: <emacs-devel@gnu.org>
> Date: Fri, 27 Nov 2015 22:05:52 +0000
> 
> With etc/DEBUG, I am worried not about what it does not say, but what it
> does say. It's really very dense.

It is written from the POV of someone who is way beyond basic
debugging techniques, and needs only the Emacs-specific information.
Once upon a time, only people matching that description "dared" to
debug Emacs on the C level.  This file was born back then.

> > More specifically, how about a preamble section at the beginning of
> > etc/DEBUG, named something like "If you are new to debugging Emacs",
> > and describing the preliminaries you think are important?  You can
> > refer to later sections instead of repeating what they say.
> 
> Yes, that was sort of the idea. Personally, I'd not be too worried about
> repeating things. I realise that this adds to the maintainance burden,
> but references to later sections make for harder reading.

It is OK to say something simple in the preamble, and refer to later
sections for more in-depth detail.

But I will now stop writing comments to a text I didn't yet see, and
let you work on it instead ;-)

> I'll try and simplify what I wrote a bit further.

Thanks.

Re: Debugging Emacs

[Marcin Borkowski]

On 2015-11-27, at 23:05, Phillip Lord <phillip.lord@russet.org.uk> wrote:

> but references to later sections make for harder reading.

Out of curiosity: now that Org-mode is a part of Emacs, would it make
sense to have such files written in Org /with links/?

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Debugging Emacs

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> Date: Sat, 28 Nov 2015 09:41:45 +0100
> 
> 
> On 2015-11-27, at 23:05, Phillip Lord <phillip.lord@russet.org.uk> wrote:
> 
> > but references to later sections make for harder reading.
> 
> Out of curiosity: now that Org-mode is a part of Emacs, would it make
> sense to have such files written in Org /with links/?

Please don't, not for etc/DEBUG.  That file must be readable with the
simplest means possible, including when there's no workable Emacs on
the system.

Re: Debugging Emacs

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:
>> Yes, that was sort of the idea. Personally, I'd not be too worried about
>> repeating things. I realise that this adds to the maintainance burden,
>> but references to later sections make for harder reading.
>
> It is OK to say something simple in the preamble, and refer to later
> sections for more in-depth detail.
>
> But I will now stop writing comments to a text I didn't yet see, and
> let you work on it instead ;-)


It was at the bottom of the original email!

While I am mailing, I had one idea which might simplify debugging.
Currently, you need to break-point some function to get control to GDB
before you launch Emacs. Why not add a null function to Emacs core for
the purpose? Guaranteed never to be called from anywhere, does nothing,
and with a breakpoint could be added to .gdbinit. Then, after running
Emacs, "M-x break" would automatically pass control back to GDB without
any further set up.

Just a thought.

Phil

Re: Debugging Emacs

[Eli Zaretskii]

> > But I will now stop writing comments to a text I didn't yet see, and
> > let you work on it instead ;-)
> 
> 
> It was at the bottom of the original email!

I thought you were rewriting it for inclusion in etc/DEBUG.  Sorry for
my misunderstanding.

> While I am mailing, I had one idea which might simplify debugging.
> Currently, you need to break-point some function to get control to GDB
> before you launch Emacs.

Sorry, I don't understand this: if you run Emacs from GDB, then GDB
already has control before you launch Emacs.  So what is exactly the
problem you encountered?

Do you mean get control to GBD _after_ Emacs is launched?  If so, why
do you need that?  You could set breakpoints where you need them
before running Emacs, can't you?

> Why not add a null function to Emacs core for the purpose?
> Guaranteed never to be called from anywhere, does nothing, and with
> a breakpoint could be added to .gdbinit. Then, after running Emacs,
> "M-x break" would automatically pass control back to GDB without any
> further set up.
> 
> Just a thought.

Sometimes I don't want to set a breakpoint before running Emacs,
because Emacs would hit that breakpoint many times during startup.  If
this is the problem you needed to solve, then I use Fredraw_display
for that purpose (I've added that to DEBUG at some point).  There are
other similar functions which can be used in the same role.

But maybe I'm confused by your needs, see above.

Re: Debugging Emacs

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:

>> > But I will now stop writing comments to a text I didn't yet see, and
>> > let you work on it instead ;-)
>> 
>> 
>> It was at the bottom of the original email!
>
> I thought you were rewriting it for inclusion in etc/DEBUG.  Sorry for
> my misunderstanding.

Well, I wrote some text. I think etc/DEBUG would be the best place to
put it, but I just included it to see whether any one (probably you!)
thought it sounded sensible.


>> While I am mailing, I had one idea which might simplify debugging.
>> Currently, you need to break-point some function to get control to GDB
>> before you launch Emacs.
>
> Do you mean get control to GBD _after_ Emacs is launched?  If so, why
> do you need that?  You could set breakpoints where you need them
> before running Emacs, can't you?

You can, yes. And, if you are used to doing this, setting a breakpoint
*before* running Emacs probably seems natural.


>> Why not add a null function to Emacs core for the purpose?
>> Guaranteed never to be called from anywhere, does nothing, and with
>> a breakpoint could be added to .gdbinit. Then, after running Emacs,
>> "M-x break" would automatically pass control back to GDB without any
>> further set up.
>> 
>> Just a thought.
>
> Sometimes I don't want to set a breakpoint before running Emacs,
> because Emacs would hit that breakpoint many times during startup.  If
> this is the problem you needed to solve, then I use Fredraw_display
> for that purpose (I've added that to DEBUG at some point).  There are
> other similar functions which can be used in the same role.

Exactly. And you mention this in the DEBUG file. My text suggests the
"log" function from floatfns.c. But, in a "getting started" file this
adds complexity. You have to explain why it is necessary (because GDB
normally uses Ctrl-G I guess?), you have to explain to set a breakpoint
first, and how to do this.

Now, if we had a command, say `break', implemented in C, then added a
"breakpoint Fbreak" into .gdbinit, then all of this would happen
automatically. Under GDB, then "M-x break" or (break) Emacs would halt.
Outside M-x break would do nothing.

Clearly, nothing that can't be done anyway, and something that an
experienced debugger might never touch. But one of the joys of
emacs-lisp is that getting to a step-through debugger is really very
easy. I found it a little harder with the C core.

Phil

Re: Debugging Emacs

[Stephen Leake]

phillip.lord@russet.org.uk (Phillip Lord) writes:

> Now, if we had a command, say `break', implemented in C, then added a
> "breakpoint Fbreak" into .gdbinit, then all of this would happen
> automatically. Under GDB, then "M-x break" or (break) Emacs would halt.
> Outside M-x break would do nothing.

I would find this convenient; I would not have to remember what function
I had set a break in for my current debug session; it would always be
the same one.

-- 
-- Stephe

Re: Debugging Emacs

[John Wiegley]

>>>>> Stephen Leake <stephen_leake@stephe-leake.org> writes:

> phillip.lord@russet.org.uk (Phillip Lord) writes:
>> Now, if we had a command, say `break', implemented in C, then added a
>> "breakpoint Fbreak" into .gdbinit, then all of this would happen
>> automatically. Under GDB, then "M-x break" or (break) Emacs would halt.
>> Outside M-x break would do nothing.

> I would find this convenient; I would not have to remember what function I
> had set a break in for my current debug session; it would always be the same
> one.

I would also like this. I've injected similar "debug hooks" into other
products before, and it is most helpful.

John

Re: Debugging Emacs

[Marcin Borkowski]

On 2015-11-29, at 19:13, Stephen Leake <stephen_leake@stephe-leake.org> wrote:

> phillip.lord@russet.org.uk (Phillip Lord) writes:
>
>> Now, if we had a command, say `break', implemented in C, then added a
>> "breakpoint Fbreak" into .gdbinit, then all of this would happen
>> automatically. Under GDB, then "M-x break" or (break) Emacs would halt.
>> Outside M-x break would do nothing.
>
> I would find this convenient; I would not have to remember what function
> I had set a break in for my current debug session; it would always be
> the same one.

I guess a name like `c-debug' might fit better here.

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Debugging Emacs

[Phillip Lord]

John Wiegley <jwiegley@gmail.com> writes:

>>>>>> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>
>> phillip.lord@russet.org.uk (Phillip Lord) writes:
>>> Now, if we had a command, say `break', implemented in C, then added a
>>> "breakpoint Fbreak" into .gdbinit, then all of this would happen
>>> automatically. Under GDB, then "M-x break" or (break) Emacs would halt.
>>> Outside M-x break would do nothing.
>
>> I would find this convenient; I would not have to remember what function I
>> had set a break in for my current debug session; it would always be the same
>> one.
>
> I would also like this. I've injected similar "debug hooks" into other
> products before, and it is most helpful.

Okay, well, the general mood seems positive, so I will try and add this.

Phil

Re: Debugging Emacs

[Nicolas Richard]

phillip.lord@russet.org.uk (Phillip Lord) writes:
> Now, if we had a command, say `break', implemented in C, then added a
> "breakpoint Fbreak" into .gdbinit, then all of this would happen
> automatically. Under GDB, then "M-x break" or (break) Emacs would halt.
> Outside M-x break would do nothing.

FWIW I use "killall -TSTP emacs", at which point gdb kicks in. (IIUC.)

-- 
Nico

Re: Debugging Emacs

[Eli Zaretskii]

> From: Nicolas Richard <nrichard@ulb.ac.be>
> Date: Mon, 30 Nov 2015 14:33:00 +0100
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
> phillip.lord@russet.org.uk (Phillip Lord) writes:
> > Now, if we had a command, say `break', implemented in C, then added a
> > "breakpoint Fbreak" into .gdbinit, then all of this would happen
> > automatically. Under GDB, then "M-x break" or (break) Emacs would halt.
> > Outside M-x break would do nothing.
> 
> FWIW I use "killall -TSTP emacs", at which point gdb kicks in. (IIUC.)

This was in etc/DEBUG, of course.

Anyway, I added a "Preliminaries" section to etc/DEBUG, based on
Phillip's text, please take a look.

Re: Debugging Emacs

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Nicolas Richard <nrichard@ulb.ac.be>
>> Date: Mon, 30 Nov 2015 14:33:00 +0100
>> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
>> 
>> phillip.lord@russet.org.uk (Phillip Lord) writes:
>> > Now, if we had a command, say `break', implemented in C, then added a
>> > "breakpoint Fbreak" into .gdbinit, then all of this would happen
>> > automatically. Under GDB, then "M-x break" or (break) Emacs would halt.
>> > Outside M-x break would do nothing.
>> 
>> FWIW I use "killall -TSTP emacs", at which point gdb kicks in. (IIUC.)
>
> This was in etc/DEBUG, of course.

Actually, it wasn't!

etc/DEBUG

has a section called "Getting Control to the Debugger". The section
BEFORE that mentions

kill -TSTP PID

Getting the PID of emacs is somewhat painful because I normally run two.
And three when debugging. It didn't occur to me that I could safely run
killall -TSTP emacs without trashing my other Emacs'

Again, this all sounds small, but getting to the debug "Hello World"
needs to be as simple as possible.

> Anyway, I added a "Preliminaries" section to etc/DEBUG, based on
> Phillip's text, please take a look.


It's good. Slightly more detail that I would have added (less is more in
a brief tutorial).

I would put back my short "run through". Also, the section on "pp" needs
to mention that this prints to standard out (this is true right?). I
spend a long time trying to get "pp" to work and failing because I
expected the output to appear in the GDB window (like "print" does).

Probably, etc/DEBUG needs to be replaced with a section in the elisp
manual. Which probably needs to be renamed (Programming Emacs Manual?)
-- I noticed the section on modules going in the other day which isn't
very lispy!

Phil

Re: Debugging Emacs

[Eli Zaretskii]

> From: phillip.lord@russet.org.uk (Phillip Lord)
> Cc: Nicolas Richard <nrichard@ulb.ac.be>,  <emacs-devel@gnu.org>
> Date: Mon, 07 Dec 2015 09:51:34 +0000
> 
> >> FWIW I use "killall -TSTP emacs", at which point gdb kicks in. (IIUC.)
> >
> > This was in etc/DEBUG, of course.
> 
> Actually, it wasn't!
> 
> etc/DEBUG
> 
> has a section called "Getting Control to the Debugger". The section
> BEFORE that mentions
> 
> kill -TSTP PID

We are miscommunicating.  I didn't mean "kill -TSTP", I meant its
equivalent C-z.  "kill -TSTP" is only needed when Emacs hangs or
infloops while already running under GDB.  By contrast, the sub-thread
to which I responded talked about ways to get control to GDB in
general, where I think C-z is a much more important and much easier
technique than "kill -TSTP".  Safer, too.

(Btw, AFAIK "killall -TSTOP" is better than TSTP, as the former signal
cannot be blocked or ignored.)

> Getting the PID of emacs is somewhat painful because I normally run two.
> And three when debugging. It didn't occur to me that I could safely run
> killall -TSTP emacs without trashing my other Emacs'
> 
> Again, this all sounds small, but getting to the debug "Hello World"
> needs to be as simple as possible.

And it's exactly for these very reasons that I think C-z is more
important than "kill".  I think it's reasonable to assume that newbies
to debugging Emacs won't necessarily need to start with a hung Emacs
that already runs under GDB, so this corner case can be left in its
corner section.  I wouldn't recommend newbies to use "killall" anyway.

> It's good. Slightly more detail that I would have added (less is more in
> a brief tutorial).

Thanks.  Where to stop is a judgment call: too short descriptions risk
to leave the perplexed in their confused state.

> I would put back my short "run through".

It makes the section longer ;-)

Seriously, though: the few steps you described there are quite
possibly not what the user will need to do, so I think it would get in
the way.  And I'm not sure why it's important to mention "ppt", but
not a gazillion of other useful functions in .gdbinit.

> Also, the section on "pp" needs to mention that this prints to
> standard out (this is true right?).

Good point, I added that.  (No, it writes to stderr, but on GNU/Linux
you can redirect it to a file.)

> Probably, etc/DEBUG needs to be replaced with a section in the elisp
> manual.

Somebody already mentioned that.  I don't think I agree: when you
debug, you need the instructions be available on the simplest medium
possible, so a plain text file is better than Info.  What's more
important, a single file with a distinct name is easier found than a
section in a large manual.

> Which probably needs to be renamed (Programming Emacs Manual?)
> -- I noticed the section on modules going in the other day which isn't
> very lispy!

We have a section on writing Emacs primitives, had it for a long time.
In fact, the entire Appendix E there is full of non-Lispy stuff.  So
that ship sailed quite some time ago.  I won't argue about the name;
it's for the FSF to consider anyway, since they are selling it as a
book.

The C parts of the dynamic modules documentation will probably
relocate to the same appendix; what's now is just a preliminary
version (as the commit log message indicates), to let people who track
the development have something at their disposal.

Thanks.

Re: Debugging Emacs

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> Probably, etc/DEBUG needs to be replaced with a section in the elisp
>> manual.
>
> Somebody already mentioned that.  I don't think I agree: when you
> debug, you need the instructions be available on the simplest medium
> possible, so a plain text file is better than Info.  What's more
> important, a single file with a distinct name is easier found than a
> section in a large manual.

It would be very rare to have no working Emacs available to read an info
manual.

Perhaps a short summary in etc/DEBUG, with more complete description in
the manual?


-- 
-- Stephe

Re: Debugging Emacs

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Mon, 07 Dec 2015 12:18:43 -0600
> Cc: emacs-devel@gnu.org, nrichard@ulb.ac.be,
> 	Phillip Lord <phillip.lord@russet.org.uk>
> 
> Perhaps a short summary in etc/DEBUG, with more complete description in
> the manual?

etc/DEBUG is already short, so short, in fact, that making it an Info
document is not justified even by that measure.  I really don't see a
need to bother.

Re: Debugging Emacs

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:

>> Actually, it wasn't!
>> 
>> etc/DEBUG
>> 
>> has a section called "Getting Control to the Debugger". The section
>> BEFORE that mentions
>> 
>> kill -TSTP PID
>
> We are miscommunicating.  I didn't mean "kill -TSTP", I meant its
> equivalent C-z.  "kill -TSTP" is only needed when Emacs hangs or
> infloops while already running under GDB.  By contrast, the sub-thread
> to which I responded talked about ways to get control to GDB in
> general, where I think C-z is a much more important and much easier
> technique than "kill -TSTP".  Safer, too.

Perhaps I am being thick, but I tried C-z and AFAICT it does nothing. I
mean, where do I type C-z? In the debugged Emacs? In the Emacs running
gdb?



>> It's good. Slightly more detail that I would have added (less is more in
>> a brief tutorial).
>
> Thanks.  Where to stop is a judgment call: too short descriptions risk
> to leave the perplexed in their confused state.
>
>> I would put back my short "run through".
>
> It makes the section longer ;-)

Yeah, I know. "Hello World" is important though.


> Seriously, though: the few steps you described there are quite
> possibly not what the user will need to do, so I think it would get in
> the way.

I'd welcome simplification. Having a brief run though that anyone could
follow till they have a breakpointed Emacs would help. I'm no expert, so
need feedback on anything that makes it shorter.

> And I'm not sure why it's important to mention "ppt", but not a
> gazillion of other useful functions in .gdbinit.

It's not. I mention "pp" because I think it's really important. To
mention one useful function is not enough though, you need to mention
another so you can say there are many other functions and you should
read .gdbinit. I chose ppt because it seemed to make the point well (bad
pun!).

>> Also, the section on "pp" needs to mention that this prints to
>> standard out (this is true right?).
>
> Good point, I added that.  (No, it writes to stderr, but on GNU/Linux
> you can redirect it to a file.)

Ah, of course. Same window in gdb-many-windows!

>> Probably, etc/DEBUG needs to be replaced with a section in the elisp
>> manual.
>
> Somebody already mentioned that.  I don't think I agree: when you
> debug, you need the instructions be available on the simplest medium
> possible, so a plain text file is better than Info.  What's more
> important, a single file with a distinct name is easier found than a
> section in a large manual.

Unconvinced. The single large manual is also on the web and it's easier
to find there than as a file in etc/DEBUG. I tried searching for "Emacs
debug with GDB" and various other combinations before I found etc/DEBUG.
Which I found because you described it on Emacs-devel.

>
>> Which probably needs to be renamed (Programming Emacs Manual?)
>> -- I noticed the section on modules going in the other day which isn't
>> very lispy!
>
> We have a section on writing Emacs primitives, had it for a long time.
> In fact, the entire Appendix E there is full of non-Lispy stuff.  So
> that ship sailed quite some time ago.  I won't argue about the name;
> it's for the FSF to consider anyway, since they are selling it as a
> book.

I agree. I just mentioned it in passing!

Phil

Re: Debugging Emacs

[Eli Zaretskii]

> From: phillip.lord@russet.org.uk (Phillip Lord)
> Cc: <nrichard@ulb.ac.be>,  <emacs-devel@gnu.org>
> Date: Thu, 10 Dec 2015 22:36:32 +0000
> 
> > We are miscommunicating.  I didn't mean "kill -TSTP", I meant its
> > equivalent C-z.  "kill -TSTP" is only needed when Emacs hangs or
> > infloops while already running under GDB.  By contrast, the sub-thread
> > to which I responded talked about ways to get control to GDB in
> > general, where I think C-z is a much more important and much easier
> > technique than "kill -TSTP".  Safer, too.
> 
> Perhaps I am being thick, but I tried C-z and AFAICT it does nothing. I
> mean, where do I type C-z? In the debugged Emacs? In the Emacs running
> gdb?

Into the Emacs window, like DEBUG says.

> > Seriously, though: the few steps you described there are quite
> > possibly not what the user will need to do, so I think it would get in
> > the way.
> 
> I'd welcome simplification.

Alas, there is no simplification I could think of.

> Having a brief run though that anyone could follow till they have a
> breakpointed Emacs would help. I'm no expert, so need feedback on
> anything that makes it shorter.

It can only be longer, if we want it to be relevant.  The simplest
debugging scenarios are too diverse to allow a short introduction that
is useful.  See the "Sample Session" node in the GDB manual for what
such an introduction looks like.  We could point to that if you think
it will be useful.  Or we could have something similar (but specific
to Emacs) in DEBUG, but then it cannot be in the preamble, it should
be elsewhere, and the preamble could refer to it.

One other thing to keep in mind is that having documentation that is
too closely tied to the current source (e.g., quoting function and
variable names) is a certain maintenance burden, since functions and
variables are routinely renamed, moved to other places, and deleted as
part of development, and we then have yet another file to keep in sync
with that.  Not rocket science, just one more thing to consider when
deciding whether this is worth the hassle.

> > And I'm not sure why it's important to mention "ppt", but not a
> > gazillion of other useful functions in .gdbinit.
> 
> It's not. I mention "pp" because I think it's really important. To
> mention one useful function is not enough though, you need to mention
> another so you can say there are many other functions and you should
> read .gdbinit. I chose ppt because it seemed to make the point well (bad
> pun!).

Everything except "ppt" is still there, including "pp" and the
reference to a later section where other commands are described.

> >> Probably, etc/DEBUG needs to be replaced with a section in the elisp
> >> manual.
> >
> > Somebody already mentioned that.  I don't think I agree: when you
> > debug, you need the instructions be available on the simplest medium
> > possible, so a plain text file is better than Info.  What's more
> > important, a single file with a distinct name is easier found than a
> > section in a large manual.
> 
> Unconvinced. The single large manual is also on the web and it's easier
> to find there than as a file in etc/DEBUG. I tried searching for "Emacs
> debug with GDB" and various other combinations before I found etc/DEBUG.
> Which I found because you described it on Emacs-devel.

It's mentioned in CONTRIBUTE, FWIW.  That should be the first place
people look for this information.  I don't know how to advertise it
better, and I very much doubt having it in the manual will do the job:
look at how many questions get posted that are already in the manuals.

Re: Debugging Emacs

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:
>> Perhaps I am being thick, but I tried C-z and AFAICT it does nothing. I
>> mean, where do I type C-z? In the debugged Emacs? In the Emacs running
>> gdb?
>
> Into the Emacs window, like DEBUG says.

I can't get this to work (not when debugging Emacs inside another Emacs).

>> > Seriously, though: the few steps you described there are quite
>> > possibly not what the user will need to do, so I think it would get in
>> > the way.
>> 
>> I'd welcome simplification.
>
> Alas, there is no simplification I could think of.

Okay.



> One other thing to keep in mind is that having documentation that is
> too closely tied to the current source (e.g., quoting function and
> variable names) is a certain maintenance burden, since functions and
> variables are routinely renamed, moved to other places, and deleted as
> part of development, and we then have yet another file to keep in sync
> with that.  Not rocket science, just one more thing to consider when
> deciding whether this is worth the hassle.

This is also a reason why I thought adding a "break" function (which
does nothing and could be breakpointed by .gdbinit would be a good thing).


>> >> Probably, etc/DEBUG needs to be replaced with a section in the elisp
>> >> manual.
>> >
>> > Somebody already mentioned that.  I don't think I agree: when you
>> > debug, you need the instructions be available on the simplest medium
>> > possible, so a plain text file is better than Info.  What's more
>> > important, a single file with a distinct name is easier found than a
>> > section in a large manual.
>> 
>> Unconvinced. The single large manual is also on the web and it's easier
>> to find there than as a file in etc/DEBUG. I tried searching for "Emacs
>> debug with GDB" and various other combinations before I found etc/DEBUG.
>> Which I found because you described it on Emacs-devel.
>
> It's mentioned in CONTRIBUTE, FWIW.  That should be the first place
> people look for this information.  I don't know how to advertise it
> better, and I very much doubt having it in the manual will do the job:
> look at how many questions get posted that are already in the manuals.


The manual is difficult and people will always miss things. But I found
it hard to find out how to debug Emacs C than Emacs lisp -- not a
surprise, many fewer people do it. I looked in the web first. I guess
many people would do the same (esp. as this includes the manual).

Phil