From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 26520 invoked by alias); 10 Nov 2011 18:45:36 -0000 Received: (qmail 26510 invoked by uid 22791); 10 Nov 2011 18:45:34 -0000 X-SWARE-Spam-Status: No, hits=-7.5 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_HI,RP_MATCHES_RCVD,SPF_HELO_PASS,TW_GD X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 10 Nov 2011 18:45:19 +0000 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id pAAIjIes004311 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Thu, 10 Nov 2011 13:45:18 -0500 Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id pAAIjI2t023387; Thu, 10 Nov 2011 13:45:18 -0500 Received: from barimba (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id pAAIjGV6032223; Thu, 10 Nov 2011 13:45:17 -0500 From: Tom Tromey To: gdb-patches@sourceware.org Subject: RFA: manual updates for c++ Date: Thu, 10 Nov 2011 18:45:00 -0000 Message-ID: MIME-Version: 1.0 Content-Type: text/plain Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2011-11/txt/msg00290.txt.bz2 This needs a doc review. While looking at the manual, I noticed some outdated advice and some missing information about C++ debugging. This patch fixes the problems. I mostly consolidated compiler option advice into the Compilation node and made xrefs back to it. Both -gstabs+ and -gdwarf-2 are obsolete nowadays, and in general I think it is best to offer a bit of generic advice and a link to the GCC manual. The manual was never updated for ADL, wide characters, or support for using declarations. This patch adds that. Ok? Tom 2011-11-10 Tom Tromey * gdb.texinfo (Compilation): Don't mention -gdwarf-2. Link to GCC manual. (Variables): Don't mention -gdwarf-2. Link to Compilation node. (Macros): Add a footnote. (C): Remove paragraph about compiler options. (C Constants): Mention wide character and string constants. (C Plus Plus Expressions): Update compiler option advice. Mention using declarations. Mention ADL. Remove old HP compiler information. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index d2bdefa..1423b07 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1875,12 +1875,18 @@ expansion (@pxref{Macros}). Most compilers do not include information about preprocessor macros in the debugging information if you specify the @option{-g} flag alone, because this information is rather large. Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler, -provides macro information if you specify the options -@option{-gdwarf-2} and @option{-g3}; the former option requests -debugging information in the Dwarf 2 format, and the latter requests -``extra information''. In the future, we hope to find more compact -ways to represent macro information, so that it can be included with -@option{-g} alone. +provides macro information if you are using the DWARF debugging +format, and specify the option @option{-g3}. Starting with version +4.7, @value{NGCC} can emit macro information in a more compact format. + +@xref{Debugging Options,,Options for Debugging Your Program or GCC, +gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more +information on @value{NGCC} options affecting debug information. + +You will have the best debugging experience if you use the latest +version of the DWARF debugging format that your compiler supports. +DWARF is currently the most expressive and best supported debugging +format in @value{GDBN}. @need 2000 @node Starting @@ -7369,15 +7375,9 @@ 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 @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 GCC, gcc.info, Using the @sc{gnu} -Compiler Collection (GCC)}. -@xref{C, ,C and C@t{++}}, for more information about debug info formats -that are best suited to C@t{++} programs. +formats. @xref{Compilation}, for more information on choosing compiler +options. @xref{C, ,C and C@t{++}}, for more information about debug +info formats that are best suited to C@t{++} programs. If you ask to print an object whose contents are unknown to @value{GDBN}, e.g., because its data type is not completely specified @@ -10083,9 +10083,12 @@ $ cat sample.h $ @end smallexample -Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}. -We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the -compiler includes information about preprocessor macros in the debugging +Now, we compile the program using the @sc{gnu} C compiler, +@value{NGCC}. We pass the @option{-gdwarf-2} @footnote{This is the +minimum. Recent versions of @value{NGCC} support @option{-gdwarf-3} +@option{-gdwarf-4}; we recommend always choosing the most recent +version of DWARF} AND @option{-g3} flags to ensure the compiler +includes information about preprocessor macros in the debugging information. @smallexample @@ -12173,13 +12176,6 @@ effectively, you must compile your C@t{++} programs with a supported 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 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 GCC, -gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}. - @menu * C Operators:: C and C@t{++} operators * C Constants:: C and C@t{++} constants @@ -12389,6 +12385,11 @@ of the character's ordinal value; or of the form @samp{\@var{x}}, where @samp{@var{x}} is a predefined special character---for example, @samp{\n} for newline. +Wide character constants can be written by prefixing a character +constant with @samp{L}, as in C. For example, @samp{L'x'} is the wide +form of @samp{x}. The target wide character set is used when +computing the value of this constant (@pxref{Character Sets}). + @item String constants are a sequence of character constants surrounded by double quotes (@code{"}). Any valid character constant (as described @@ -12396,6 +12397,10 @@ above) may appear. Double quotes within the string must be preceded by a backslash, so for instance @samp{"a\"b'c"} is a string of five characters. +Wide string constants can be written by prefixing a string constant +with @samp{L}, as in C. The target wide character set is used when +computing the value of this constant (@pxref{Character Sets}). + @item Pointer constants are an integral value. You can also write pointers to constants using the C operator @samp{&}. @@ -12418,16 +12423,14 @@ and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. @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 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. +@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 the most recent version of @value{NGCC} possible. The DWARF +debugging format is preferred; @value{NGCC} defaults to this on most +popular platforms. Other compilers and/or debug formats are likely to +work badly or not at all when using @value{GDBN} to debug C@t{++} +code. @xref{Compilation}. @end quotation @enumerate @@ -12446,7 +12449,8 @@ count = aml->GetOriginal(x, y) While a member function is active (in the selected stack frame), your expressions have the same namespace available as the member function; that is, @value{GDBN} allows implicit references to the class instance -pointer @code{this} following the same rules as C@t{++}. +pointer @code{this} following the same rules as C@t{++}. @code{using} +declarations in the current scope are also respected by @value{GDBN}. @cindex call overloaded functions @cindex overloaded functions, calling @@ -12498,12 +12502,11 @@ necessary, for example in an expression like @samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows resolving name scope by reference to source files, in both C and C@t{++} debugging (@pxref{Variables, ,Program Variables}). -@end enumerate -In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports -calling virtual functions correctly, printing out virtual bases of -objects, calling functions in a base subobject, casting objects, and -invoking user-defined operators. +@item +@value{GDBN} performs argument-dependent lookup, following the C@t{++} +specification. +@end enumerate @node C Defaults @subsubsection C and C@t{++} Defaults