gcc: Debugging Options
1
1 3.9 Options for Debugging Your Program
1 ======================================
1
1 To tell GCC to emit extra information for use by a debugger, in almost
1 all cases you need only to add '-g' to your other options.
1
1 GCC allows you to use '-g' with '-O'. The shortcuts taken by optimized
1 code may occasionally be surprising: some variables you declared may not
1 exist at all; flow of control may briefly move where you did not expect
1 it; some statements may not be executed because they compute constant
1 results or their values are already at hand; some statements may execute
1 in different places because they have been moved out of loops.
1 Nevertheless it is possible to debug optimized output. This makes it
1 reasonable to use the optimizer for programs that might have bugs.
1
1 If you are not using some other optimization option, consider using
1 '-Og' (⇒Optimize Options) with '-g'. With no '-O' option at all,
1 some compiler passes that collect information useful for debugging do
1 not run at all, so that '-Og' may result in a better debugging
1 experience.
1
1 '-g'
1 Produce debugging information in the operating system's native
1 format (stabs, COFF, XCOFF, or DWARF). GDB can work with this
1 debugging information.
1
1 On most systems that use stabs format, '-g' enables use of extra
1 debugging information that only GDB can use; this extra information
1 makes debugging work better in GDB but probably makes other
1 debuggers crash or refuse to read the program. If you want to
1 control for certain whether to generate the extra information, use
1 '-gstabs+', '-gstabs', '-gxcoff+', '-gxcoff', or '-gvms' (see
1 below).
1
1 '-ggdb'
1 Produce debugging information for use by GDB. This means to use
1 the most expressive format available (DWARF, stabs, or the native
1 format if neither of those are supported), including GDB extensions
1 if at all possible.
1
1 '-gdwarf'
1 '-gdwarf-VERSION'
1 Produce debugging information in DWARF format (if that is
1 supported). The value of VERSION may be either 2, 3, 4 or 5; the
1 default version for most targets is 4. DWARF Version 5 is only
1 experimental.
1
1 Note that with DWARF Version 2, some ports require and always use
1 some non-conflicting DWARF 3 extensions in the unwind tables.
1
1 Version 4 may require GDB 7.0 and '-fvar-tracking-assignments' for
1 maximum benefit.
1
1 GCC no longer supports DWARF Version 1, which is substantially
1 different than Version 2 and later. For historical reasons, some
1 other DWARF-related options such as '-fno-dwarf2-cfi-asm') retain a
1 reference to DWARF Version 2 in their names, but apply to all
1 currently-supported versions of DWARF.
1
1 '-gstabs'
1 Produce debugging information in stabs format (if that is
1 supported), without GDB extensions. This is the format used by DBX
1 on most BSD systems. On MIPS, Alpha and System V Release 4 systems
1 this option produces stabs debugging output that is not understood
1 by DBX. On System V Release 4 systems this option requires the GNU
1 assembler.
1
1 '-gstabs+'
1 Produce debugging information in stabs format (if that is
1 supported), using GNU extensions understood only by the GNU
1 debugger (GDB). The use of these extensions is likely to make
1 other debuggers crash or refuse to read the program.
1
1 '-gxcoff'
1 Produce debugging information in XCOFF format (if that is
1 supported). This is the format used by the DBX debugger on IBM
1 RS/6000 systems.
1
1 '-gxcoff+'
1 Produce debugging information in XCOFF format (if that is
1 supported), using GNU extensions understood only by the GNU
1 debugger (GDB). The use of these extensions is likely to make
1 other debuggers crash or refuse to read the program, and may cause
1 assemblers other than the GNU assembler (GAS) to fail with an
1 error.
1
1 '-gvms'
1 Produce debugging information in Alpha/VMS debug format (if that is
1 supported). This is the format used by DEBUG on Alpha/VMS systems.
1
1 '-gLEVEL'
1 '-ggdbLEVEL'
1 '-gstabsLEVEL'
1 '-gxcoffLEVEL'
1 '-gvmsLEVEL'
1 Request debugging information and also use LEVEL to specify how
1 much information. The default level is 2.
1
1 Level 0 produces no debug information at all. Thus, '-g0' negates
1 '-g'.
1
1 Level 1 produces minimal information, enough for making backtraces
1 in parts of the program that you don't plan to debug. This
1 includes descriptions of functions and external variables, and line
1 number tables, but no information about local variables.
1
1 Level 3 includes extra information, such as all the macro
1 definitions present in the program. Some debuggers support macro
1 expansion when you use '-g3'.
1
1 '-gdwarf' does not accept a concatenated debug level, to avoid
1 confusion with '-gdwarf-LEVEL'. Instead use an additional
1 '-gLEVEL' option to change the debug level for DWARF.
1
1 '-feliminate-unused-debug-symbols'
1 Produce debugging information in stabs format (if that is
1 supported), for only symbols that are actually used.
1
1 '-femit-class-debug-always'
1 Instead of emitting debugging information for a C++ class in only
1 one object file, emit it in all object files using the class. This
1 option should be used only with debuggers that are unable to handle
1 the way GCC normally emits debugging information for classes
1 because using this option increases the size of debugging
1 information by as much as a factor of two.
1
1 '-fno-merge-debug-strings'
1 Direct the linker to not merge together strings in the debugging
1 information that are identical in different object files. Merging
1 is not supported by all assemblers or linkers. Merging decreases
1 the size of the debug information in the output file at the cost of
1 increasing link processing time. Merging is enabled by default.
1
1 '-fdebug-prefix-map=OLD=NEW'
1 When compiling files residing in directory 'OLD', record debugging
1 information describing them as if the files resided in directory
1 'NEW' instead. This can be used to replace a build-time path with
1 an install-time path in the debug info. It can also be used to
1 change an absolute path to a relative path by using '.' for NEW.
1 This can give more reproducible builds, which are location
1 independent, but may require an extra command to tell GDB where to
1 find the source files. See also '-ffile-prefix-map'.
1
1 '-fvar-tracking'
1 Run variable tracking pass. It computes where variables are stored
1 at each position in code. Better debugging information is then
1 generated (if the debugging information format supports this
1 information).
1
1 It is enabled by default when compiling with optimization ('-Os',
1 '-O', '-O2', ...), debugging information ('-g') and the debug info
1 format supports it.
1
1 '-fvar-tracking-assignments'
1 Annotate assignments to user variables early in the compilation and
1 attempt to carry the annotations over throughout the compilation
1 all the way to the end, in an attempt to improve debug information
1 while optimizing. Use of '-gdwarf-4' is recommended along with it.
1
1 It can be enabled even if var-tracking is disabled, in which case
1 annotations are created and maintained, but discarded at the end.
1 By default, this flag is enabled together with '-fvar-tracking',
1 except when selective scheduling is enabled.
1
1 '-gsplit-dwarf'
1 Separate as much DWARF debugging information as possible into a
1 separate output file with the extension '.dwo'. This option allows
1 the build system to avoid linking files with debug information. To
1 be useful, this option requires a debugger capable of reading
1 '.dwo' files.
1
1 '-gpubnames'
1 Generate DWARF '.debug_pubnames' and '.debug_pubtypes' sections.
1
1 '-ggnu-pubnames'
1 Generate '.debug_pubnames' and '.debug_pubtypes' sections in a
1 format suitable for conversion into a GDB index. This option is
1 only useful with a linker that can produce GDB index version 7.
1
1 '-fdebug-types-section'
1 When using DWARF Version 4 or higher, type DIEs can be put into
1 their own '.debug_types' section instead of making them part of the
1 '.debug_info' section. It is more efficient to put them in a
1 separate comdat sections since the linker can then remove
1 duplicates. But not all DWARF consumers support '.debug_types'
1 sections yet and on some objects '.debug_types' produces larger
1 instead of smaller debugging information.
1
1 '-grecord-gcc-switches'
1 '-gno-record-gcc-switches'
1 This switch causes the command-line options used to invoke the
1 compiler that may affect code generation to be appended to the
1 DW_AT_producer attribute in DWARF debugging information. The
1 options are concatenated with spaces separating them from each
1 other and from the compiler version. It is enabled by default.
1 See also '-frecord-gcc-switches' for another way of storing
1 compiler options into the object file.
1
1 '-gstrict-dwarf'
1 Disallow using extensions of later DWARF standard version than
1 selected with '-gdwarf-VERSION'. On most targets using
1 non-conflicting DWARF extensions from later standard versions is
1 allowed.
1
1 '-gno-strict-dwarf'
1 Allow using extensions of later DWARF standard version than
1 selected with '-gdwarf-VERSION'.
1
1 '-gas-loc-support'
1 Inform the compiler that the assembler supports '.loc' directives.
1 It may then use them for the assembler to generate DWARF2+ line
1 number tables.
1
1 This is generally desirable, because assembler-generated
1 line-number tables are a lot more compact than those the compiler
1 can generate itself.
1
1 This option will be enabled by default if, at GCC configure time,
1 the assembler was found to support such directives.
1
1 '-gno-as-loc-support'
1 Force GCC to generate DWARF2+ line number tables internally, if
1 DWARF2+ line number tables are to be generated.
1
1 'gas-locview-support'
1 Inform the compiler that the assembler supports 'view' assignment
1 and reset assertion checking in '.loc' directives.
1
1 This option will be enabled by default if, at GCC configure time,
1 the assembler was found to support them.
1
1 'gno-as-locview-support'
1 Force GCC to assign view numbers internally, if
1 '-gvariable-location-views' are explicitly requested.
1
1 '-gcolumn-info'
1 '-gno-column-info'
1 Emit location column information into DWARF debugging information,
1 rather than just file and line. This option is enabled by default.
1
1 '-gstatement-frontiers'
1 '-gno-statement-frontiers'
1 This option causes GCC to create markers in the internal
1 representation at the beginning of statements, and to keep them
1 roughly in place throughout compilation, using them to guide the
1 output of 'is_stmt' markers in the line number table. This is
1 enabled by default when compiling with optimization ('-Os', '-O',
1 '-O2', ...), and outputting DWARF 2 debug information at the normal
1 level.
1
1 '-gvariable-location-views'
1 '-gvariable-location-views=incompat5'
1 '-gno-variable-location-views'
1 Augment variable location lists with progressive view numbers
1 implied from the line number table. This enables debug information
1 consumers to inspect state at certain points of the program, even
1 if no instructions associated with the corresponding source
1 locations are present at that point. If the assembler lacks
1 support for view numbers in line number tables, this will cause the
1 compiler to emit the line number table, which generally makes them
1 somewhat less compact. The augmented line number tables and
1 location lists are fully backward-compatible, so they can be
1 consumed by debug information consumers that are not aware of these
1 augmentations, but they won't derive any benefit from them either.
1
1 This is enabled by default when outputting DWARF 2 debug
1 information at the normal level, as long as there is assembler
1 support, '-fvar-tracking-assignments' is enabled and
1 '-gstrict-dwarf' is not. When assembler support is not available,
1 this may still be enabled, but it will force GCC to output internal
1 line number tables, and if '-ginternal-reset-location-views' is not
1 enabled, that will most certainly lead to silently mismatching
1 location views.
1
1 There is a proposed representation for view numbers that is not
1 backward compatible with the location list format introduced in
1 DWARF 5, that can be enabled with
1 '-gvariable-location-views=incompat5'. This option may be removed
1 in the future, is only provided as a reference implementation of
1 the proposed representation. Debug information consumers are not
1 expected to support this extended format, and they would be
1 rendered unable to decode location lists using it.
1
1 '-ginternal-reset-location-views'
1 '-gno-internal-reset-location-views'
1 Attempt to determine location views that can be omitted from
1 location view lists. This requires the compiler to have very
1 accurate insn length estimates, which isn't always the case, and it
1 may cause incorrect view lists to be generated silently when using
1 an assembler that does not support location view lists. The GNU
1 assembler will flag any such error as a 'view number mismatch'.
1 This is only enabled on ports that define a reliable estimation
1 function.
1
1 '-ginline-points'
1 '-gno-inline-points'
1 Generate extended debug information for inlined functions.
1 Location view tracking markers are inserted at inlined entry
1 points, so that address and view numbers can be computed and output
1 in debug information. This can be enabled independently of
1 location views, in which case the view numbers won't be output, but
1 it can only be enabled along with statement frontiers, and it is
1 only enabled by default if location views are enabled.
1
1 '-gz[=TYPE]'
1 Produce compressed debug sections in DWARF format, if that is
1 supported. If TYPE is not given, the default type depends on the
1 capabilities of the assembler and linker used. TYPE may be one of
1 'none' (don't compress debug sections), 'zlib' (use zlib
1 compression in ELF gABI format), or 'zlib-gnu' (use zlib
1 compression in traditional GNU format). If the linker doesn't
1 support writing compressed debug sections, the option is rejected.
1 Otherwise, if the assembler does not support them, '-gz' is
1 silently ignored when producing object files.
1
1 '-femit-struct-debug-baseonly'
1 Emit debug information for struct-like types only when the base
1 name of the compilation source file matches the base name of file
1 in which the struct is defined.
1
1 This option substantially reduces the size of debugging
1 information, but at significant potential loss in type information
1 to the debugger. See '-femit-struct-debug-reduced' for a less
1 aggressive option. See '-femit-struct-debug-detailed' for more
1 detailed control.
1
1 This option works only with DWARF debug output.
1
1 '-femit-struct-debug-reduced'
1 Emit debug information for struct-like types only when the base
1 name of the compilation source file matches the base name of file
1 in which the type is defined, unless the struct is a template or
1 defined in a system header.
1
1 This option significantly reduces the size of debugging
1 information, with some potential loss in type information to the
1 debugger. See '-femit-struct-debug-baseonly' for a more aggressive
1 option. See '-femit-struct-debug-detailed' for more detailed
1 control.
1
1 This option works only with DWARF debug output.
1
1 '-femit-struct-debug-detailed[=SPEC-LIST]'
1 Specify the struct-like types for which the compiler generates
1 debug information. The intent is to reduce duplicate struct debug
1 information between different object files within the same program.
1
1 This option is a detailed version of '-femit-struct-debug-reduced'
1 and '-femit-struct-debug-baseonly', which serves for most needs.
1
1 A specification has the syntax
1 ['dir:'|'ind:']['ord:'|'gen:']('any'|'sys'|'base'|'none')
1
1 The optional first word limits the specification to structs that
1 are used directly ('dir:') or used indirectly ('ind:'). A struct
1 type is used directly when it is the type of a variable, member.
1 Indirect uses arise through pointers to structs. That is, when use
1 of an incomplete struct is valid, the use is indirect. An example
1 is 'struct one direct; struct two * indirect;'.
1
1 The optional second word limits the specification to ordinary
1 structs ('ord:') or generic structs ('gen:'). Generic structs are
1 a bit complicated to explain. For C++, these are non-explicit
1 specializations of template classes, or non-template classes within
1 the above. Other programming languages have generics, but
1 '-femit-struct-debug-detailed' does not yet implement them.
1
1 The third word specifies the source files for those structs for
1 which the compiler should emit debug information. The values
1 'none' and 'any' have the normal meaning. The value 'base' means
1 that the base of name of the file in which the type declaration
1 appears must match the base of the name of the main compilation
1 file. In practice, this means that when compiling 'foo.c', debug
1 information is generated for types declared in that file and
1 'foo.h', but not other header files. The value 'sys' means those
1 types satisfying 'base' or declared in system or compiler headers.
1
1 You may need to experiment to determine the best settings for your
1 application.
1
1 The default is '-femit-struct-debug-detailed=all'.
1
1 This option works only with DWARF debug output.
1
1 '-fno-dwarf2-cfi-asm'
1 Emit DWARF unwind info as compiler generated '.eh_frame' section
1 instead of using GAS '.cfi_*' directives.
1
1 '-fno-eliminate-unused-debug-types'
1 Normally, when producing DWARF output, GCC avoids producing debug
1 symbol output for types that are nowhere used in the source file
1 being compiled. Sometimes it is useful to have GCC emit debugging
1 information for all types declared in a compilation unit,
1 regardless of whether or not they are actually used in that
1 compilation unit, for example if, in the debugger, you want to cast
1 a value to a type that is not actually used in your program (but is
1 declared). More often, however, this results in a significant
1 amount of wasted space.
1