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

[David Carlton <carlton@math.stanford.edu>]

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