Re: [rfa/doc] correct info about best C++ compilers/debug formats

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Michael Elizabeth Chastain]

It's beautiful.  I tested it, too: I built gdb and 'makeinfo' worked fine.

Recommended for approval.

Michael C

===

2003-02-03  David Carlton  <carlton@math.stanford.edu>

	* gdb.texinfo (C@t{++}): Recommend DWARF2, then stabs+.
	(Variables): Recommend stabs+ and DWARF2.
	(C plus plus expressions): Correct info about
	compiler versions, debug formats.
	PR symtab/874.

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Eli Zaretskii]

On Mon, 3 Feb 2003, Michael Elizabeth Chastain wrote:

> I tested it, too: I built gdb and 'makeinfo' worked fine.

As long as we are testing, perhaps someone could find a moment and TeX 
the manual, to see that the additions typeset well.

Also, did you try to follow the external references, like this one:

   See @ref{Debugging Options,,Options
   for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC},
   for more information.

In my experience, references to other manuals tend to confuse people, and 
thus have a somewhat higher probability of being written incorrectly.  I 
cannot say I see anything wrong with this one, but I don't pretend to 
remember the order of the arguments by heart ;-)

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Michael Elizabeth Chastain]

Hi Eli,

> Let me explain myself: I'm grateful that you did _any_ testing at all; it 
> should have been my job, except that I don't have time to do anything 
> these days except read the patches and approve them.

We all do what we can and somehow the releases come out.

It looks like I need texinfo, tetex, and info in my baseline software.
I will go spruce up my baseline.

For chasing the cross-references, I can do this by hand for
a while.  And then maybe write testsuite/info.doc with some
'expect' automation, running on 'info' rather than gdb!

Michael C

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Michael Elizabeth Chastain]

The only testing I did was to build gdb (hey, it takes only 10 minutes)
and then look at the 'makeinfo' output in the log file.  I didn't even
read the generated info files, let alone chase references.

> As long as we are testing, perhaps someone could find a moment and TeX 
> the manual, to see that the additions typeset well.

This falls in my self-claimed charter of "gdb quality assurance".

I've added this to my todo list.

Can you give me a brain dump of how to QA the manuals: what software
I need to have, what procedures to follow, how to check the output,
things that often go wrong.

Michael C

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Eli Zaretskii]

On Tue, 4 Feb 2003, Michael Elizabeth Chastain wrote:

> The only testing I did was to build gdb (hey, it takes only 10 minutes)
> and then look at the 'makeinfo' output in the log file.  I didn't even
> read the generated info files, let alone chase references.

Let me explain myself: I'm grateful that you did _any_ testing at all; it 
should have been my job, except that I don't have time to do anything 
these days except read the patches and approve them.

So a big thanks is in order!

> This falls in my self-claimed charter of "gdb quality assurance".
> 
> I've added this to my todo list.

Thanks in advance!

> Can you give me a brain dump of how to QA the manuals: what software
> I need to have, what procedures to follow, how to check the output,
> things that often go wrong.

What I do (when I have time) is this:

  - do a "make info" and make sure makeinfo doesn't print any warnings
  - do a "make dvi" and make sure there are no overfull hbox warnings 
    from TeX that cite large (more than 10) margin overflow
  - if you can afford that, view the results of "make dvi" with a DVI 
    previewer (or say "make pdf" and use Acrobat or its workalike), where 
    the manual(s) were changed, and make sure the results look pleasantly
  - use any Info reader you fancy (preferably either Emacs or the 
    stand-alone reader from Texinfo) to display every node where changes 
    were made; press TAB to move to each menu item and cross-reference 
    that has been changed/added, and press RET to go to the target of 
    each of those menu items/cross-references, make sure RET places you
    at the right place and doesn't barf
  - while in the Info reader, type "i FOO RET" for each new/modified index 
    entry FOO, and see that it places you where you think it should
  - also while in the reader, find the new/modified index entries in the 
    Index sections and make sure there aren't multiple index entries for 
    the same topic.  These look like this:

	* foo::    About foo.
	* foo<1>:: Something else about foo.

    If you find such entries, it is usually best to disambiguate these 
    multiple entries like so:

        @cindex foo, the basics
        @cindex foo, and its relation to bar

    (you get the idea).

Again, thanks for doing any part of this.

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[David Carlton]

On Mon, 3 Feb 2003 14:08:22 -0600, Michael Elizabeth Chastain <mec@shout.net> said:
> Hi David,

>> Well, I wanted to include some sort of sentence that reassured users
>> that they probably didn't have to specify the debug format explicitly.

> How about:

>   Most configurations of @value{NGCC} emit either DWARF2 or stabs+
>   as their default debug format, so you usually don't need to specify a
>   debug format explicitly.

I can go with that.  I would assume that the + in 'stabs+' has to be
set off by @t, but TeXinfo doesn't complain; Eli, should I use stabs+
or stabs@t{+}?

Here's the next version of the patch; it changes this sentence, and
also replaces some uses of @samp{-gsomething} by @option{-gsomething},
which I assume is preferred.

David Carlton
carlton@math.stanford.edu

2003-02-03  David Carlton  <carlton@math.stanford.edu>

	* gdb.texinfo (C@t{++}): Recommend DWARF2, then stabs+.
	(Variables): Recommend stabs+ and DWARF2.
	(C plus plus expressions): Correct info about
	compiler versions, debug formats.
	PR symtab/874.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.145
diff -u -p -r1.145 gdb.texinfo
--- gdb.texinfo	1 Feb 2003 20:51:06 -0000	1.145
+++ gdb.texinfo	3 Feb 2003 20:13:22 -0000
@@ -4711,13 +4711,13 @@ No symbol "foo" in current context.
 
 To solve such problems, either recompile without optimizations, or use a
 different debug info format, if the compiler supports several such
-formats.  For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually
-supports the @samp{-gstabs} option.  @samp{-gstabs} produces debug info
-in a format that is superior to formats such as COFF.  You may be able
-to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for
-debug info.  See @ref{Debugging Options,,Options for Debugging Your
-Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
-information.
+formats.  For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler
+usually supports the @option{-gstabs+} option.  @option{-gstabs+}
+produces debug info in a format that is superior to formats such as
+COFF.  You may be able to use DWARF2 (@option{-gdwarf-2}), which is also
+an effective form for debug info.  See @ref{Debugging Options,,Options
+for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC},
+for more information.
 
 
 @node Arrays
@@ -7812,9 +7812,10 @@ effectively, you must compile your C@t{+
 C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
 compiler (@code{aCC}).
 
-For best results when using @sc{gnu} C@t{++}, use the stabs debugging
-format.  You can select that format explicitly with the @code{g++}
-command-line options @samp{-gstabs} or @samp{-gstabs+}.  See
+For best results when using @sc{gnu} C@t{++}, use the DWARF2 debugging
+format; if it doesn't work on your system, try the stabs@t{+} debugging
+format.  You can select those formats explicitly with the @code{g++}
+command-line options @option{-gdwarf-2} and @option{-gstabs+}.  See
 @ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
 CC, gcc.info, Using @sc{gnu} CC}, for more information.
 
@@ -8062,28 +8063,21 @@ and @samp{@{&"hi", &"there", &"fred"@}} 
 @cindex expressions in C@t{++}
 @value{GDBN} expression handling can interpret most C@t{++} expressions.
 
-@cindex C@t{++} support, not in @sc{coff}
-@cindex @sc{coff} versus C@t{++}
-@cindex C@t{++} and object formats
-@cindex object formats and C@t{++}
-@cindex a.out and C@t{++}
-@cindex @sc{ecoff} and C@t{++}
-@cindex @sc{xcoff} and C@t{++}
-@cindex @sc{elf}/stabs and C@t{++}
-@cindex @sc{elf}/@sc{dwarf} and C@t{++}
-@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
-@c periodically whether this has happened...
+@cindex debugging C@t{++} programs
+@cindex C@t{++} compilers
+@cindex debug formats and C@t{++}
+@cindex @value{NGCC} and C@t{++}
 @quotation
 @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
-proper compiler.  Typically, C@t{++} debugging depends on the use of
-additional debugging information in the symbol table, and thus requires
-special support.  In particular, if your compiler generates a.out, MIPS
-@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
-symbol table, these facilities are all available.  (With @sc{gnu} CC,
-you can use the @samp{-gstabs} option to request stabs debugging
-extensions explicitly.)  Where the object code format is standard
-@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++}
-support in @value{GDBN} does @emph{not} work.
+proper compiler and the proper debug format.  Currently, @value{GDBN}
+works best when debugging C@t{++} code that is compiled with
+@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
+@option{-gdwarf-2} or @option{-gstabs+}.  DWARF2 is preferred over
+stabs@t{+}.  Most configurations of @value{NGCC} emit either DWARF2 or
+stabs@t{+} as their default debug format, so you usually don't need to
+specify a debug format explicitly.  Other compilers and/or debug formats
+are likely to work badly or not at all when using @value{GDBN} to debug
+C@t{++} code.
 @end quotation
 
 @enumerate

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Eli Zaretskii]

On 3 Feb 2003, David Carlton wrote:

> I can go with that.  I would assume that the + in 'stabs+' has to be
> set off by @t, but TeXinfo doesn't complain; Eli, should I use stabs+
> or stabs@t{+}?

I'd use either @code{stabs+} or simply stabs+.  The @t{++} in C@t{++} is 
a kind of gimmick, since the C++ language name is a pun on a C operator
++.  There's no such pun in stabs+, AFAIK.

> Here's the next version of the patch; it changes this sentence, and
> also replaces some uses of @samp{-gsomething} by @option{-gsomething},
> which I assume is preferred.

Yes, @option is preferred once we require Texinfo 4.0 or later.

> +an effective form for debug info.  See @ref{Debugging Options,,Options
> +for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC},
> +for more information.

It is better to use "@xref{something}" rather than "See @ref{something}" 
at the beginning of a sentence, since the result will look better in Info 
(a single "*Note" instead of a "See *note").  Sorry I didn't catch this 
earlier.

Otherwise, this is fine; please go ahead and commit it.

Thanks.

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Andrew Cagney]

> Here's the next version of the patch; it changes this sentence, and
>> also replaces some uses of @samp{-gsomething} by @option{-gsomething},
>> which I assume is preferred.
> 
> 
> Yes, @option is preferred once we require Texinfo 4.0 or later.

We require texinfo 4.0 or later :-)

Andrew

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[David Carlton]

On Tue, 4 Feb 2003 08:06:25 +0200 (IST), Eli Zaretskii <eliz@is.elta.co.il> said:
> On 3 Feb 2003, David Carlton wrote:

>> I can go with that.  I would assume that the + in 'stabs+' has to be
>> set off by @t, but TeXinfo doesn't complain; Eli, should I use stabs+
>> or stabs@t{+}?

> I'd use either @code{stabs+} or simply stabs+.  The @t{++} in C@t{++} is 
> a kind of gimmick, since the C++ language name is a pun on a C operator
> ++.  There's no such pun in stabs+, AFAIK.

Great, I'll go with that.

>> +an effective form for debug info.  See @ref{Debugging Options,,Options
>> +for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC},
>> +for more information.

> It is better to use "@xref{something}" rather than "See @ref{something}" 
> at the beginning of a sentence, since the result will look better in Info 
> (a single "*Note" instead of a "See *note").  Sorry I didn't catch this 
> earlier.

Fixed.

Also, I did a grep through the GCC info files, and I saw a lot more
occurrences of 'DWARF 2' than 'DWARF2'.  So I went with 'DWARF 2', and
changed the only other occurrence in the manual accordingly.

> Otherwise, this is fine; please go ahead and commit it.

Thanks, committed; final patch is below.

David Carlton
carlton@math.stanford.edu

2003-02-04  David Carlton  <carlton@math.stanford.edu>

	* gdb.texinfo (C@t{++}): Recommend DWARF 2, then stabs+.
	(Variables): Recommend stabs+ and DWARF 2.
	(C plus plus expressions): Correct info about
	compiler versions, debug formats.
	(Contributors): Change 'DWARF2' to 'DWARF 2'.
	PR symtab/874.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.145
diff -u -p -r1.145 gdb.texinfo
--- gdb.texinfo	1 Feb 2003 20:51:06 -0000	1.145
+++ gdb.texinfo	4 Feb 2003 21:12:13 -0000
@@ -371,7 +371,7 @@ Henkel-Wallace, Rich Pixley, Steve Chamb
 David Johnson wrote the original COFF support; Pace Willison did
 the original support for encapsulated COFF.
 
-Brent Benson of Harris Computer Systems contributed DWARF2 support.
+Brent Benson of Harris Computer Systems contributed DWARF 2 support.
 
 Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
@@ -4711,13 +4711,12 @@ No symbol "foo" in current context.
 
 To solve such problems, either recompile without optimizations, or use a
 different debug info format, if the compiler supports several such
-formats.  For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually
-supports the @samp{-gstabs} option.  @samp{-gstabs} produces debug info
-in a format that is superior to formats such as COFF.  You may be able
-to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for
-debug info.  See @ref{Debugging Options,,Options for Debugging Your
-Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
-information.
+formats.  For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler
+usually supports the @option{-gstabs+} option.  @option{-gstabs+}
+produces debug info in a format that is superior to formats such as
+COFF.  You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
+an effective form for debug info.  @xref{Debugging Options,,Options
+for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}.
 
 
 @node Arrays
@@ -7812,11 +7811,12 @@ effectively, you must compile your C@t{+
 C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
 compiler (@code{aCC}).
 
-For best results when using @sc{gnu} C@t{++}, use the stabs debugging
-format.  You can select that format explicitly with the @code{g++}
-command-line options @samp{-gstabs} or @samp{-gstabs+}.  See
-@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
-CC, gcc.info, Using @sc{gnu} CC}, for more information.
+For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging
+format; if it doesn't work on your system, try the stabs+ debugging
+format.  You can select those formats explicitly with the @code{g++}
+command-line options @option{-gdwarf-2} and @option{-gstabs+}.
+@xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
+CC, gcc.info, Using @sc{gnu} CC}.
 
 @menu
 * C Operators::                 C and C@t{++} operators
@@ -8062,28 +8062,21 @@ and @samp{@{&"hi", &"there", &"fred"@}} 
 @cindex expressions in C@t{++}
 @value{GDBN} expression handling can interpret most C@t{++} expressions.
 
-@cindex C@t{++} support, not in @sc{coff}
-@cindex @sc{coff} versus C@t{++}
-@cindex C@t{++} and object formats
-@cindex object formats and C@t{++}
-@cindex a.out and C@t{++}
-@cindex @sc{ecoff} and C@t{++}
-@cindex @sc{xcoff} and C@t{++}
-@cindex @sc{elf}/stabs and C@t{++}
-@cindex @sc{elf}/@sc{dwarf} and C@t{++}
-@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
-@c periodically whether this has happened...
+@cindex debugging C@t{++} programs
+@cindex C@t{++} compilers
+@cindex debug formats and C@t{++}
+@cindex @value{NGCC} and C@t{++}
 @quotation
 @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
-proper compiler.  Typically, C@t{++} debugging depends on the use of
-additional debugging information in the symbol table, and thus requires
-special support.  In particular, if your compiler generates a.out, MIPS
-@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
-symbol table, these facilities are all available.  (With @sc{gnu} CC,
-you can use the @samp{-gstabs} option to request stabs debugging
-extensions explicitly.)  Where the object code format is standard
-@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++}
-support in @value{GDBN} does @emph{not} work.
+proper compiler and the proper debug format.  Currently, @value{GDBN}
+works best when debugging C@t{++} code that is compiled with
+@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
+@option{-gdwarf-2} or @option{-gstabs+}.  DWARF 2 is preferred over
+stabs+.  Most configurations of @value{NGCC} emit either DWARF 2 or
+stabs+ as their default debug format, so you usually don't need to
+specify a debug format explicitly.  Other compilers and/or debug formats
+are likely to work badly or not at all when using @value{GDBN} to debug
+C@t{++} code.
 @end quotation
 
 @enumerate

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Eli Zaretskii]

On 4 Feb 2003, David Carlton wrote:

> Also, I did a grep through the GCC info files, and I saw a lot more
> occurrences of 'DWARF 2' than 'DWARF2'.  So I went with 'DWARF 2', and
> changed the only other occurrence in the manual accordingly.

Great, thanks.

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[David Carlton]

On Mon, 3 Feb 2003 12:56:22 -0600, Michael Elizabeth Chastain <mec@shout.net> said:

> After fixing the doco, we can kill all the setup_xfail_format dwarf-1
> lines.  We can either add a test for dwarf-1 to "skip_cplus_tests",
> or we can just let the test suite do its job and report a lot of
> FAILs on dwarf-1.  I favor the latter.  But I would like to discuss
> this *after* fixing the docs.

Fair enough.

> Now the content:

>  @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
>  proper compiler and the proper debug format.  Currently, @value{GDBN}
>  works best when debugging C@t{++} code that is compiled with
>  @value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
>  @option{-gdwarf-2} or @option{-gstabs+}.  DWARF 2 is preferred over
>  stabs; newer versions of @value{NGCC} use DWARF 2 as the default
>  whenever possible.  Other compilers and/or debug formats are likely to
>  work badly or not at all when using @value{GDBN} to debugg C@t{++} code.

> The normal spelling is 'DWARF2' not 'DWARF 2'.

I wondered about this.  The standard doesn't give any guidance (it
says "DWARF Version 2", to me DWARF 2 looks much better, and the GCC
option is -gdwarf-2, not -gdwarf2.  On the other hand, there are more
web pages that refer to it as DWARF2 than web pages that refer to it
as DWARF 2.

> Also you usually want to say "stabs+", not "stabs".

I guess that makes sense.

> Also a typo on "debugg".

Thanks.

> The part about "newer versions of gcc use DWARF 2 as the default
> whenever possible" is vague and not accurate enough for doco (I
> think).

Well, I wanted to include some sort of sentence that reassured users
that they probably didn't have to specify the debug format explicitly.
Also, if they use a recent version of GCC, they'll probably get
the best working debug format by default: if GCC doesn't default to
DWARF 2, there's probably a good reason for that.

> Some more places need changing:

>   To solve such problems, either recompile without optimizations, or use a
>   different debug info format, if the compiler supports several such
>   formats.  For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually
>   supports the @samp{-gstabs} option.  @samp{-gstabs} produces debug info
>   in a format that is superior to formats such as COFF.  You may be able
>   to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for
>   debug info.  See @ref{Debugging Options,,Options for Debugging Your
>   Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
>   information.

> --> Change "-gstabs" to "-gstabs+" here.  In particular "-gstabs" is
>       miserable with C++ (I have tested it).

>   For best results when using @sc{gnu} C@t{++}, use the stabs debugging
>   format.  You can select that format explicitly with the @code{g++}
>   command-line options @samp{-gstabs} or @samp{-gstabs+}.  See
>   @ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
>   CC, gcc.info, Using @sc{gnu} CC}, for more information.

> --> Rewrite to say 'DWARF2'.

Thanks, I'll submit a revised patch including these.

David Carlton
carlton@math.stanford.edu

[rfa/doc] correct info about best C++ compilers/debug formats

[David Carlton]

As noted in PR symtab/874, the information in the manual about the
best debug formats for C++ is not only incorrect but actively
harmful.  Here's an attempt at a patch.  So:

* Eli: Is the TeXinfo okay?  What about the choice of cindex entries?
  When I actually looked at the index, I found that it generated three
  consecutive entries "C++ and ..." that all pointed at the same
  place; I'm tempted to get rid of the C++ and GCC entry, since that's
  really a special case of C++ and compilers.

* Daniel (and Michael): Is the content okay?  I decided to take a
  conservative approach, not promising support for compilers/debug
  formats that we don't intend to work on.

* Daniel, Michael: Once this goes in, should we get rid of the DWARF 1
  xfails in gdb.c++ and simply not run the C++ testsuite under DWARF
  1?

I'd like to apply this to 5.3 as well as mainline, on the slim chance
that 5.3.1 might happen, because the information in the doc now really
is bad.

David Carlton
carlton@math.stanford.edu

2003-02-03  David Carlton  <carlton@math.stanford.edu>

	* gdb.texinfo (C plus plus expressions): Correct info about
	compiler/debug formats for C++ debugging.  PR symtab/874.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.145
diff -u -p -r1.145 gdb.texinfo
--- gdb.texinfo	1 Feb 2003 20:51:06 -0000	1.145
+++ gdb.texinfo	3 Feb 2003 18:08:27 -0000
@@ -8062,28 +8062,22 @@ and @samp{@{&"hi", &"there", &"fred"@}} 
 @cindex expressions in C@t{++}
 @value{GDBN} expression handling can interpret most C@t{++} expressions.
 
-@cindex C@t{++} support, not in @sc{coff}
-@cindex @sc{coff} versus C@t{++}
-@cindex C@t{++} and object formats
-@cindex object formats and C@t{++}
-@cindex a.out and C@t{++}
-@cindex @sc{ecoff} and C@t{++}
-@cindex @sc{xcoff} and C@t{++}
+@cindex C@t{++} and debug formats
+@cindex debug formats and C@t{++}
 @cindex @sc{elf}/stabs and C@t{++}
 @cindex @sc{elf}/@sc{dwarf} and C@t{++}
-@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
-@c periodically whether this has happened...
+@cindex C@t{++} compilers
+@cindex C@t{++} and @value{NGCC}
+@cindex @value{NGCC} and C@t{++}
 @quotation
 @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
-proper compiler.  Typically, C@t{++} debugging depends on the use of
-additional debugging information in the symbol table, and thus requires
-special support.  In particular, if your compiler generates a.out, MIPS
-@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
-symbol table, these facilities are all available.  (With @sc{gnu} CC,
-you can use the @samp{-gstabs} option to request stabs debugging
-extensions explicitly.)  Where the object code format is standard
-@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++}
-support in @value{GDBN} does @emph{not} work.
+proper compiler and the proper debug format.  Currently, @value{GDBN}
+works best when debugging C@t{++} code that is compiled with
+@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
+@option{-gdwarf-2} or @option{-gstabs+}.  DWARF 2 is preferred over
+stabs; newer versions of @value{NGCC} use DWARF 2 as the default
+whenever possible.  Other compilers and/or debug formats are likely to
+work badly or not at all when using @value{GDBN} to debugg C@t{++} code.
 @end quotation
 
 @enumerate

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Daniel Jacobowitz]

On Mon, Feb 03, 2003 at 10:27:30AM -0800, David Carlton wrote:
> As noted in PR symtab/874, the information in the manual about the
> best debug formats for C++ is not only incorrect but actively
> harmful.  Here's an attempt at a patch.  So:
> 
> * Eli: Is the TeXinfo okay?  What about the choice of cindex entries?
>   When I actually looked at the index, I found that it generated three
>   consecutive entries "C++ and ..." that all pointed at the same
>   place; I'm tempted to get rid of the C++ and GCC entry, since that's
>   really a special case of C++ and compilers.
> 
> * Daniel (and Michael): Is the content okay?  I decided to take a
>   conservative approach, not promising support for compilers/debug
>   formats that we don't intend to work on.

I think so.

> * Daniel, Michael: Once this goes in, should we get rid of the DWARF 1
>   xfails in gdb.c++ and simply not run the C++ testsuite under DWARF
>   1?

I'm inclined to agree.  Michael?

> 
> I'd like to apply this to 5.3 as well as mainline, on the slim chance
> that 5.3.1 might happen, because the information in the doc now really
> is bad.
> 
> David Carlton
> carlton@math.stanford.edu
> 
> 2003-02-03  David Carlton  <carlton@math.stanford.edu>
> 
> 	* gdb.texinfo (C plus plus expressions): Correct info about
> 	compiler/debug formats for C++ debugging.  PR symtab/874.
> 
> Index: gdb.texinfo
> ===================================================================
> RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
> retrieving revision 1.145
> diff -u -p -r1.145 gdb.texinfo
> --- gdb.texinfo	1 Feb 2003 20:51:06 -0000	1.145
> +++ gdb.texinfo	3 Feb 2003 18:08:27 -0000
> @@ -8062,28 +8062,22 @@ and @samp{@{&"hi", &"there", &"fred"@}} 
>  @cindex expressions in C@t{++}
>  @value{GDBN} expression handling can interpret most C@t{++} expressions.
>  
> -@cindex C@t{++} support, not in @sc{coff}
> -@cindex @sc{coff} versus C@t{++}
> -@cindex C@t{++} and object formats
> -@cindex object formats and C@t{++}
> -@cindex a.out and C@t{++}
> -@cindex @sc{ecoff} and C@t{++}
> -@cindex @sc{xcoff} and C@t{++}
> +@cindex C@t{++} and debug formats
> +@cindex debug formats and C@t{++}
>  @cindex @sc{elf}/stabs and C@t{++}
>  @cindex @sc{elf}/@sc{dwarf} and C@t{++}
> -@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
> -@c periodically whether this has happened...
> +@cindex C@t{++} compilers
> +@cindex C@t{++} and @value{NGCC}
> +@cindex @value{NGCC} and C@t{++}
>  @quotation
>  @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
> -proper compiler.  Typically, C@t{++} debugging depends on the use of
> -additional debugging information in the symbol table, and thus requires
> -special support.  In particular, if your compiler generates a.out, MIPS
> -@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
> -symbol table, these facilities are all available.  (With @sc{gnu} CC,
> -you can use the @samp{-gstabs} option to request stabs debugging
> -extensions explicitly.)  Where the object code format is standard
> -@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++}
> -support in @value{GDBN} does @emph{not} work.
> +proper compiler and the proper debug format.  Currently, @value{GDBN}
> +works best when debugging C@t{++} code that is compiled with
> +@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
> +@option{-gdwarf-2} or @option{-gstabs+}.  DWARF 2 is preferred over
> +stabs; newer versions of @value{NGCC} use DWARF 2 as the default
> +whenever possible.  Other compilers and/or debug formats are likely to
> +work badly or not at all when using @value{GDBN} to debugg C@t{++} code.
>  @end quotation
>  
>  @enumerate
> 
> 

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Eli Zaretskii]

> From: David Carlton <carlton@math.stanford.edu>
> Date: 03 Feb 2003 10:27:30 -0800
> 
> * Eli: Is the TeXinfo okay?

Yes, except that there's a typo in the last sentence: "debugg".  (I
recommend "M-x ispell-region RET" after you change something in the
manuals.)

>   What about the choice of cindex entries?
>   When I actually looked at the index, I found that it generated three
>   consecutive entries "C++ and ..." that all pointed at the same
>   place

Right, it is not useful to have multiple index entries which all start
with the same string and point to the same place.

>   I'm tempted to get rid of the C++ and GCC entry, since that's
>   really a special case of C++ and compilers.

I suggest the following index entries:

  @cindex debugging C@t{++} programs
  @cindex C@t{++} compilers
  @cindex debug formats and C@t{++}
  @cindex @value{NGCC} and C@t{++}

Thanks!

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[David Carlton]

Here's a new version of the patch.  It fixes the 'debugg' typo,
replaces DWARF 2 with DWARF2, includes the index entries that Eli
suggested, and it updates the other two sections that Michael
mentioned.  I didn't remove the vague sentence that Michael disliked,
but I'll remove it if anybody else also dislikes it.

OK to commit?

David Carlton
carlton@math.stanford.edu

2003-02-03  David Carlton  <carlton@math.stanford.edu>

	* gdb.texinfo (C@t{++}): Recommend DWARF2, then stabs+.
	(Variables): Recommend stabs+ and DWARF2.
	(C plus plus expressions): Correct info about
	compiler versions, debug formats.
	PR symtab/874.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.145
diff -u -p -r1.145 gdb.texinfo
--- gdb.texinfo	1 Feb 2003 20:51:06 -0000	1.145
+++ gdb.texinfo	3 Feb 2003 20:05:52 -0000
@@ -4711,13 +4711,13 @@ No symbol "foo" in current context.
 
 To solve such problems, either recompile without optimizations, or use a
 different debug info format, if the compiler supports several such
-formats.  For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually
-supports the @samp{-gstabs} option.  @samp{-gstabs} produces debug info
-in a format that is superior to formats such as COFF.  You may be able
-to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for
-debug info.  See @ref{Debugging Options,,Options for Debugging Your
-Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
-information.
+formats.  For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler
+usually supports the @option{-gstabs+} option.  @option{-gstabs+}
+produces debug info in a format that is superior to formats such as
+COFF.  You may be able to use DWARF2 (@samp{-gdwarf-2}), which is also
+an effective form for debug info.  See @ref{Debugging Options,,Options
+for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC},
+for more information.
 
 
 @node Arrays
@@ -7812,9 +7812,10 @@ effectively, you must compile your C@t{+
 C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
 compiler (@code{aCC}).
 
-For best results when using @sc{gnu} C@t{++}, use the stabs debugging
-format.  You can select that format explicitly with the @code{g++}
-command-line options @samp{-gstabs} or @samp{-gstabs+}.  See
+For best results when using @sc{gnu} C@t{++}, use the DWARF2 debugging
+format; if it doesn't work on your system, try the stabs@t{+} debugging
+format.  You can select those formats explicitly with the @code{g++}
+command-line options @samp{-gdwarf-2} and @samp{-gstabs+}.  See
 @ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
 CC, gcc.info, Using @sc{gnu} CC}, for more information.
 
@@ -8062,28 +8063,19 @@ and @samp{@{&"hi", &"there", &"fred"@}} 
 @cindex expressions in C@t{++}
 @value{GDBN} expression handling can interpret most C@t{++} expressions.
 
-@cindex C@t{++} support, not in @sc{coff}
-@cindex @sc{coff} versus C@t{++}
-@cindex C@t{++} and object formats
-@cindex object formats and C@t{++}
-@cindex a.out and C@t{++}
-@cindex @sc{ecoff} and C@t{++}
-@cindex @sc{xcoff} and C@t{++}
-@cindex @sc{elf}/stabs and C@t{++}
-@cindex @sc{elf}/@sc{dwarf} and C@t{++}
-@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
-@c periodically whether this has happened...
+@cindex debugging C@t{++} programs
+@cindex C@t{++} compilers
+@cindex debug formats and C@t{++}
+@cindex @value{NGCC} and C@t{++}
 @quotation
 @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
-proper compiler.  Typically, C@t{++} debugging depends on the use of
-additional debugging information in the symbol table, and thus requires
-special support.  In particular, if your compiler generates a.out, MIPS
-@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
-symbol table, these facilities are all available.  (With @sc{gnu} CC,
-you can use the @samp{-gstabs} option to request stabs debugging
-extensions explicitly.)  Where the object code format is standard
-@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++}
-support in @value{GDBN} does @emph{not} work.
+proper compiler and the proper debug format.  Currently, @value{GDBN}
+works best when debugging C@t{++} code that is compiled with
+@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
+@option{-gdwarf-2} or @option{-gstabs+}.  DWARF2 is preferred over
+stabs@t{+}; newer versions of @value{NGCC} use DWARF2 as the default
+whenever possible.  Other compilers and/or debug formats are likely to
+work badly or not at all when using @value{GDBN} to debug C@t{++} code.
 @end quotation
 
 @enumerate

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Andrew Cagney]

> Here's a new version of the patch.  It fixes the 'debugg' typo,
> replaces DWARF 2 with DWARF2, includes the index entries that Eli
> suggested, and it updates the other two sections that Michael
> mentioned.  I didn't remove the vague sentence that Michael disliked,
> but I'll remove it if anybody else also dislikes it.

Just FYI, the dwarf v3 spec contains one `DWARF 2' and no `DWARF2's.

Andrew

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Eli Zaretskii]

On Mon, 3 Feb 2003, Andrew Cagney wrote:

> Just FYI, the dwarf v3 spec contains one `DWARF 2' and no `DWARF2's.

I don't really care how do we spell DWARF 2, as long as we do that 
consistently and as long as future support of DWARF 3 will spell DWARF 3 
the same way.

Perhaps also look at GCC docs and see if they spell it differently; I'd 
prefer to be consistent with them as well.

Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Eli Zaretskii]

On 3 Feb 2003, David Carlton wrote:

> Here's a new version of the patch.  It fixes the 'debugg' typo,
> replaces DWARF 2 with DWARF2, includes the index entries that Eli
> suggested, and it updates the other two sections that Michael
> mentioned.  I didn't remove the vague sentence that Michael disliked,
> but I'll remove it if anybody else also dislikes it.
> 
> OK to commit?

Fine with me.