Re: [doc, dwarf] Update bit-rotten DWARF option documentation
On 01/20/2016 06:52 AM, Jason Merrill wrote: On 01/19/2016 11:31 PM, Sandra Loosemore wrote: -@option{-gdwarf-2} does not accept a concatenated debug level, because -GCC used to support an option @option{-gdwarf} that meant to generate -debug information in version 1 of the DWARF format (which is very -different from version 2), and it would have been too confusing. That -debug format is long obsolete, but the option cannot be changed now. I think we should retain some mention of DWARF 1 here, perhaps as an explanation of why {version} starts at 2. Ron Guilmette implemented the @command{protoize} and @command{unprotoize} -tools, the support for Dwarf symbolic debugging information, and much of +tools, the support for DWARF symbolic debugging information, and much of the support for System V Release 4. He has also worked heavily on the Let's clarify that rfg's implementation was of DWARF version 1. Thanks for the sanity check. I've committed the attached version of the patch, which addresses your comments. -Sandra 2016-01-20 Sandra Loosemoregcc/ * common.opt (feliminate-dwarf2-dups): Replace references to "DWARF 2" with just "DWARF". * config/ia64/ia64.opt (mdwarf2-asm): Likewise. * doc/extend.texi: Likewise. * doc/cpp.texi: Likewise. * doc/invoke.texi: Likewise. (Option Summary): Add -gdwarf to list of Debugging Options. (Debugging Options): Document -gdwarf. * doc/contrib.texi: Spell "DWARF" like that. Index: gcc/common.opt === --- gcc/common.opt (revision 232582) +++ gcc/common.opt (working copy) @@ -1234,7 +1234,7 @@ Perform early inlining. feliminate-dwarf2-dups Common Report Var(flag_eliminate_dwarf2_dups) -Perform DWARF2 duplicate elimination. +Perform DWARF duplicate elimination. fipa-sra Common Report Var(flag_ipa_sra) Init(0) Optimization Index: gcc/config/ia64/ia64.opt === --- gcc/config/ia64/ia64.opt (revision 232582) +++ gcc/config/ia64/ia64.opt (working copy) @@ -103,7 +103,7 @@ Do not inline square root. mdwarf2-asm Target Report Mask(DWARF2_ASM) -Enable Dwarf 2 line debug info via GNU as. +Enable DWARF line debug info via GNU as. mearly-stop-bits Target Report Mask(EARLY_STOP_BITS) Index: gcc/doc/extend.texi === --- gcc/doc/extend.texi (revision 232582) +++ gcc/doc/extend.texi (working copy) @@ -916,8 +916,8 @@ provided as built-in functions by GCC@. GCC can allocate complex automatic variables in a noncontiguous fashion; it's even possible for the real part to be in a register while -the imaginary part is on the stack (or vice versa). Only the DWARF 2 -debug info format can represent this, so use of DWARF 2 is recommended. +the imaginary part is on the stack (or vice versa). Only the DWARF +debug info format can represent this, so use of DWARF is recommended. If you are using the stabs debug info format, GCC describes a noncontiguous complex variable as if it were two separate variables of noncomplex type. If the variable's actual name is @code{foo}, the two fictitious @@ -1075,7 +1075,7 @@ the technical report. @end itemize Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} -are supported by the DWARF 2 debug information format. +are supported by the DWARF debug information format. @node Hex Floats @section Hex Floats @@ -1249,7 +1249,7 @@ is incomplete: Pragmas to control overflow and rounding behaviors are not implemented. @end itemize -Fixed-point types are supported by the DWARF 2 debug information format. +Fixed-point types are supported by the DWARF debug information format. @node Named Address Spaces @section Named Address Spaces Index: gcc/doc/invoke.texi === --- gcc/doc/invoke.texi (revision 232583) +++ gcc/doc/invoke.texi (working copy) @@ -316,7 +316,7 @@ Objective-C and Objective-C++ Dialects}. @item Debugging Options @xref{Debugging Options,,Options for Debugging Your Program}. -@gccoptlist{-g -g@var{level} -gcoff -gdwarf-@var{version} @gol +@gccoptlist{-g -g@var{level} -gcoff -gdwarf -gdwarf-@var{version} @gol -ggdb -grecord-gcc-switches -gno-record-gcc-switches @gol -gstabs -gstabs+ -gstrict-dwarf -gno-strict-dwarf @gol -gvms -gxcoff -gxcoff+ -gz@r{[}=@var{type}@r{]} @gol @@ -5727,7 +5727,7 @@ information useful for debugging do not @item -g @opindex g Produce debugging information in the operating system's native format -(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging +(stabs, COFF, XCOFF, or DWARF)@. GDB can work with this debugging information. On most systems that use stabs format, @option{-g} enables use of extra @@ -5741,12 +5741,13 @@ to generate the extra information, use @ @item -ggdb @opindex ggdb Produce debugging information for use by GDB@.
Re: [doc, dwarf] Update bit-rotten DWARF option documentation
On 01/19/2016 11:31 PM, Sandra Loosemore wrote: -@option{-gdwarf-2} does not accept a concatenated debug level, because -GCC used to support an option @option{-gdwarf} that meant to generate -debug information in version 1 of the DWARF format (which is very -different from version 2), and it would have been too confusing. That -debug format is long obsolete, but the option cannot be changed now. I think we should retain some mention of DWARF 1 here, perhaps as an explanation of why {version} starts at 2. Ron Guilmette implemented the @command{protoize} and @command{unprotoize} -tools, the support for Dwarf symbolic debugging information, and much of +tools, the support for DWARF symbolic debugging information, and much of the support for System V Release 4. He has also worked heavily on the Let's clarify that rfg's implementation was of DWARF version 1. Jason
[doc, dwarf] Update bit-rotten DWARF option documentation
I thought it was odd to see numerous references to "DWARF 2" in the manual and statements like "This option only works for DWARF 2", when GCC is now emitting DWARF version 4 by default. As far as I can tell from browsing dwarf2out.c, the options documented for "DWARF 2" actually do apply to all supported versions of DWARF, so we might as well just say "DWARF" throughout the documentation to avoid confusion. I also noticed that the generic -gdwarf option, without a specific version, was not mentioned in the manual except in a reference that said it used to exist. :-P I'm pretty sure this the result of the DWARF 2 specification being wildly different than the original DWARF 1, which hasn't been supported since GCC 3.3. Before any later versions of DWARF were added, saying "DWARF 2" did provide useful disambiguation information, but I think that's irrelevant now in documenting what the current version of GCC supports. DWARF maintainers, do you want to look this over for technical correctness? I'll commit this in a couple days if I don't hear any objections. -Sandra 2016-01-19 Sandra Loosemoregcc/ * common.opt (feliminate-dwarf2-dups): Replace references to "DWARF 2" with just "DWARF". * config/ia64/ia64.opt (mdwarf2-asm): Likewise. * doc/extend.texi: Likewise. * doc/cpp.texi: Likewise. * doc/invoke.texi: Likewise. (Option Summary): Add -gdwarf to list of Debugging Options. (Debugging Options): Document -gdwarf. * doc/contrib.texi: Spell "DWARF" like that. Index: gcc/common.opt === --- gcc/common.opt (revision 232582) +++ gcc/common.opt (working copy) @@ -1234,7 +1234,7 @@ Perform early inlining. feliminate-dwarf2-dups Common Report Var(flag_eliminate_dwarf2_dups) -Perform DWARF2 duplicate elimination. +Perform DWARF duplicate elimination. fipa-sra Common Report Var(flag_ipa_sra) Init(0) Optimization Index: gcc/config/ia64/ia64.opt === --- gcc/config/ia64/ia64.opt (revision 232582) +++ gcc/config/ia64/ia64.opt (working copy) @@ -103,7 +103,7 @@ Do not inline square root. mdwarf2-asm Target Report Mask(DWARF2_ASM) -Enable Dwarf 2 line debug info via GNU as. +Enable DWARF line debug info via GNU as. mearly-stop-bits Target Report Mask(EARLY_STOP_BITS) Index: gcc/doc/extend.texi === --- gcc/doc/extend.texi (revision 232582) +++ gcc/doc/extend.texi (working copy) @@ -916,8 +916,8 @@ provided as built-in functions by GCC@. GCC can allocate complex automatic variables in a noncontiguous fashion; it's even possible for the real part to be in a register while -the imaginary part is on the stack (or vice versa). Only the DWARF 2 -debug info format can represent this, so use of DWARF 2 is recommended. +the imaginary part is on the stack (or vice versa). Only the DWARF +debug info format can represent this, so use of DWARF is recommended. If you are using the stabs debug info format, GCC describes a noncontiguous complex variable as if it were two separate variables of noncomplex type. If the variable's actual name is @code{foo}, the two fictitious @@ -1075,7 +1075,7 @@ the technical report. @end itemize Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} -are supported by the DWARF 2 debug information format. +are supported by the DWARF debug information format. @node Hex Floats @section Hex Floats @@ -1249,7 +1249,7 @@ is incomplete: Pragmas to control overflow and rounding behaviors are not implemented. @end itemize -Fixed-point types are supported by the DWARF 2 debug information format. +Fixed-point types are supported by the DWARF debug information format. @node Named Address Spaces @section Named Address Spaces Index: gcc/doc/cpp.texi === --- gcc/doc/cpp.texi (revision 232582) +++ gcc/doc/cpp.texi (working copy) @@ -2382,7 +2382,7 @@ These macros are defined when the target and swap operations on operands 1, 2, 4, 8 or 16 bytes in length, respectively. @item __GCC_HAVE_DWARF2_CFI_ASM -This macro is defined when the compiler is emitting Dwarf2 CFI directives +This macro is defined when the compiler is emitting DWARF CFI directives to the assembler. When this is defined, it is possible to emit those same directives in inline assembly. Index: gcc/doc/invoke.texi === --- gcc/doc/invoke.texi (revision 232583) +++ gcc/doc/invoke.texi (working copy) @@ -316,7 +316,7 @@ Objective-C and Objective-C++ Dialects}. @item Debugging Options @xref{Debugging Options,,Options for Debugging Your Program}. -@gccoptlist{-g -g@var{level} -gcoff -gdwarf-@var{version} @gol +@gccoptlist{-g -g@var{level} -gcoff -gdwarf -gdwarf-@var{version} @gol -ggdb -grecord-gcc-switches