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

[Michael Elizabeth Chastain <mec at shout dot net>]

All right!

It's cool with me to fix this in gdb_5_3-branch as well as HEAD.

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.

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'.  Also you usually want
to say "stabs+", not "stabs".  Also a typo on "debugg".

I agree with the policy change that we prefer DWARF2 to stabs+.
The current doco prefers stabs+ in some places (see below).
Note well, however, that gdb currently has bugs that occur with
DWARF2 that do not occur with stabs+.  Check out my "compare by gdb"
tables for details.

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).
With gcc 3.2.1, stabs+ is the default on cygwin and darwin and about 90
other platforms.  Gory details in:

  http://sources.redhat.com/ml/gdb/2002-12/msg00128.html

So I want to just drop this sentence.

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

Michael C