bug#13775: 24.3.50; Omissions in documentation for crash reporting

[Dmitry Gutov <dgutov@yandex.ru>]

On 21.02.2013 21:24, Eli Zaretskii wrote:
> I'm not sure your expectations can be met with any reasonable effort.

If you think that these complaints are not particularly important, feel 
free to close the bug.
Obviously, I've solved all items here for myself already.

> There's no way we can teach everybody the basics of GNU-style
> configure scripts, including how to discover the available switches
> and override compiler and linker options.  You need to learn that\

If by discovering switches you mean calling ./configure --help, then it 
wasn't my problem.
I've missed the --enable-checking switch, but that was later.

The ./configure --help output tells how to override switches in general, 
my complaint is about insufficient detail. Is the "Some influential 
environment variables" part provided by autoconf or somesuch? I haven't 
seen this specific message before.

> elsewhere.  In general, if you cannot figure out how to do something,
> just ask, and you _will_ be helped.

Thanks, I don't doubt that.

> Some answers below, because most of this info is available, you just
> need to know how to find it.
>
>> 1. Calling `xbacktrace' requires src/.gdbinit to be loaded. It
>> a) requires the user to run gdb exactly from src/ (not `gdb src/emacs'),
>
> The file etc/DEBUG tells you that at the beginning:
>
>    ** When you debug Emacs with GDB, you should start it in the directory
>    where the executable was made.  That directory has a .gdbinit file
>    that defines various "user-defined" commands for debugging Emacs.
>    (These commands are described below under "Examining Lisp object
>    values" and "Debugging Emacs Redisplay problems".)

Um, yes, I read that. Maybe I should've skipped this part of the 
complaint. But is this exact wording ("the directory where the 
executable was made") important? If it just said "./src", that would be 
more obvious.

>> b) requires them to modify the `auto-load safe-path', or that .gdbinit
>> is ignored.
>
> This "feature" entered GDB only recently.  Versions of GDB before 7.5
> don't need that, and will barf if you use this command.  I don't see
> any reasonable way of dealing with this without confusing newbies even
> more (while veteran GDB users already know how to negotiate this
> obstacle).

If the feature isn't considered for removal, this argument will become 
less and less important over time. And the odds of a newbie being 
confused by safe-path will approach 100%.

I'm not specifically asking to list the exact commands or ~/.gdbinit 
contents to work around safe-path. Maybe just mention the feature and, 
optionally, suggest consulting GDB manual, if that isn't obvious 
already? But specifying exactly what to do if GDB version is >= 7.5 
would also work.

>> 2. "Compile without optimizations" - how do I do that? `configure
>> --help' doesn't seem to show any pertinent options. ...but wait, it says
>> I can override the choices made by the script.
>
> Yes, it says near the end how to specify compiler switches.
>
>> a) Do I set the variable when calling `make', or do I have to re-run
>> ./configure? Not obvious, the answer is "the latter".
>
> Actually, both will work.

Not exactly.

'CFLAGS="-g3" ./configure' works.
'CFLAGS="-g3" make' doesn't.

'make CFLAGS="-g3"' does work, but AFAIK that's not the usual way of 
binding an environment variable value.

>> b) I don't know the choice the script made, how do I not break
>> anything by overriding it?
>
> You just need to know, or ask.  It is not reasonable to expect Emacs
> documentation to repeat the entire compiler manual, or large portions
> thereof.

I think "compile without optimizations" or "compile for debugging" is a 
sufficiently common special case to warrant listing the recommended 
command somewhere in etc/DEBUG. That will take a few lines at the most.

>> 3. In #13749 (which caused me to write this), Paul also suggests using
>> -DENABLE_CHECKING. If I'm not mistaken, this variable isn't documented
>> anywhere.
>
> As Andreas points out, this is in "./configure --help".

Indeed, thanks for that.