Next:Options That Control Optimization, Previous:Options That Control Static Analysis, Up:GCC Command Options [Contents][Index]
To tell GCC to emit extra information for use by a debugger, in almostall cases you need only to add-g to your other options. Some debugformats can co-exist (like DWARF with CTF) when each of them is enabledexplicitly by adding the respective command line option to your other options.
GCC allows you to use-g with-O. The shortcuts taken by optimized code may occasionallybe surprising: some variables you declared may not existat all; flow of control may briefly move where you did not expect it;some statements may not be executed because they compute constantresults or their values are already at hand; some statements mayexecute in different places because they have been moved out of loops.Nevertheless it is possible to debug optimized output. This makesit reasonable to use the optimizer for programs that might have bugs.
If you are not using some other optimization option, considerusing-Og (seeOptions That Control Optimization) with-g.With no-O option at all, some compiler passes that collectinformation useful for debugging do not run at all, so that-Og may result in a better debugging experience.
-g ¶--debugProduce debugging information in the operating system’s native format(stabs, COFF, XCOFF, or DWARF). GDB can work with this debugginginformation.
On most systems that use stabs format,-g enables use of extradebugging information that only GDB can use; this extra informationmakes debugging work better in GDB but probably makes other debuggerscrash or refuse to read the program. If you want to control for certain whetherto generate the extra information, use-gvms (see below).
-ggdb ¶Produce debugging information for use by GDB. This means to use themost expressive format available (DWARF, stabs, or the native formatif neither of those are supported), including GDB extensions if at allpossible.
-gdwarf ¶-gdwarf-versionProduce debugging information in DWARF format (if that is supported).The value ofversion may be either 2, 3, 4 or 5; the defaultversion for most targets is 5 (with the exception of VxWorks, TPF andDarwin / macOS, which default to version 2, and AIX, which defaultsto version 4).
Note that with DWARF Version 2, some ports require and alwaysuse some non-conflicting DWARF 3 extensions in the unwind tables.
Version 4 may require GDB 7.0 and-fvar-tracking-assignmentsfor maximum benefit. Version 5 requires GDB 8.0 or higher.
GCC no longer supports DWARF Version 1, which is substantiallydifferent than Version 2 and later. For historical reasons, someother DWARF-related options such as-fno-dwarf2-cfi-asm) retain a reference to DWARF Version 2in their names, but apply to all currently-supported versions of DWARF.
-gbtf ¶Request BTF debug information. BTF is the default debugging format for theeBPF target. On other targets, like x86, BTF debug information can begenerated along with DWARF debug information when both of the debug formats areenabled explicitly via their respective command line options.
-gprune-btf ¶-gno-prune-btfPrune BTF information before emission. When pruning, only typeinformation for types used by global variables and file-scope functionswill be emitted. If compiling for the BPF target with BPF CO-REenabled, type information will also be emitted for types used in BPFCO-RE relocations. In addition, struct and union types which are onlyreferred to via pointers from members of other struct or union typesshall be pruned and replaced with BTF_KIND_FWD, as though those typeswere only present in the input as forward declarations.
This option substantially reduces the size of produced BTF information,but at significant loss in the amount of detailed type information.It is primarily useful when compiling for the BPF target, to minimizethe size of the resulting object, and to eliminate BTF informationwhich is not immediately relevant to the BPF program loading process.
This option is enabled by default for the BPF target when generatingBTF information.
-gctf ¶-gctflevelRequest CTF debug information and use level to specify how much CTF debuginformation should be produced. If-gctf is specifiedwithout a value for level, the default level of CTF debug information is 2.
CTF debug information can be generated along with DWARF debug information whenboth of the debug formats are enabled explicitly via their respective commandline options.
Level 0 produces no CTF debug information at all. Thus,-gctf0negates-gctf.
Level 1 produces CTF information for tracebacks only. This includes callsiteinformation, but does not include type information.
Level 2 produces type information for entities (functions, data objects etc.)at file-scope or global-scope only.
-gvms ¶Produce debugging information in Alpha/VMS debug format (if that issupported). This is the format used by DEBUG on Alpha/VMS systems.
-gcodeview ¶Produce debugging information in CodeView debug format (if that issupported). This is the format used by Microsoft Visual C++ onWindows.
-glevel-ggdblevel-gvmslevelRequest debugging information and also uselevel to specify howmuch information. The default level is 2.
Level 0 produces no debug information at all. Thus,-g0 negates-g.
Level 1 produces minimal information, enough for making backtraces inparts of the program that you don’t plan to debug. This includesdescriptions of functions and external variables, and line numbertables, but no information about local variables.
Level 3 includes extra information, such as all the macro definitionspresent in the program. Some debuggers support macro expansion whenyou use-g3.
If you use multiple-g options, with or without level numbers,the last such option is the one that is effective.
-gdwarf does not accept a concatenated debug level, to avoidconfusion with-gdwarf-level.Instead use an additional-glevel option to change thedebug level for DWARF.
-fno-eliminate-unused-debug-symbols ¶By default, no debug information is produced for symbols that are not actuallyused. Use this option if you want debug information for all symbols.
-femit-class-debug-always ¶Instead of emitting debugging information for a C++ class in only oneobject file, emit it in all object files using the class. This optionshould be used only with debuggers that are unable to handle the way GCCnormally emits debugging information for classes because using thisoption increases the size of debugging information by as much as afactor of two.
-fno-merge-debug-strings ¶Direct the linker to not merge together strings in the debugginginformation that are identical in different object files. Merging isnot supported by all assemblers or linkers. Merging decreases the sizeof the debug information in the output file at the cost of increasinglink processing time. Merging is enabled by default.
-fdebug-prefix-map=old=new ¶When compiling files residing in directoryold, recorddebugging information describing them as if the files resided indirectorynew instead. This can be used to replace abuild-time path with an install-time path in the debug info. It canalso be used to change an absolute path to a relative path by using. fornew. This can give more reproducible builds, whichare location independent, but may require an extra command to tell GDBwhere to find the source files. See also-ffile-prefix-mapand-fcanon-prefix-map.
-fvar-tracking ¶Run variable tracking pass. It computes where variables are stored at eachposition in code. Better debugging information is then generated(if the debugging information format supports this information).
It is enabled by default when compiling with optimization (-Os,-O,-O2, …), debugging information (-g) andthe debug info format supports it.
-fvar-tracking-assignments ¶Annotate assignments to user variables early in the compilation andattempt to carry the annotations over throughout the compilation all theway to the end, in an attempt to improve debug information whileoptimizing. Use of-gdwarf-4 is recommended along with it.
It can be enabled even if var-tracking is disabled, in which caseannotations are created and maintained, but discarded at the end.By default, this flag is enabled together with-fvar-tracking,except when selective scheduling is enabled.
-fvar-tracking-uninit ¶-fno-var-tracking-uninitPerform variable tracking and also mark uninitialized variables in thedebug information.This flag is enabled by default by-fvar-tracking; italso implies-fvar-tracking.To do variable tracking without marking uninitialized variables, use-fvar-tracking-fno-var-tracking-uninit.
-gsplit-dwarf ¶If DWARF debugging information is enabled, separate as much debugginginformation as possible into a separate output file with the extension.dwo. This option allows the build system to avoid linking files withdebug information. To be useful, this option requires a debugger capable ofreading.dwo files.
-gdwarf32 ¶-gdwarf64If DWARF debugging information is enabled, the-gdwarf32 selectsthe 32-bit DWARF format and the-gdwarf64 selects the 64-bitDWARF format. The default is target specific, on most targets it is-gdwarf32 though. The 32-bit DWARF format is smaller, butcan’t support more than 2GiB of debug information in any of the DWARFdebug information sections. The 64-bit DWARF format allows larger debuginformation and might not be well supported by all consumers yet.
-gdescribe-dies ¶Add description attributes to some DWARF DIEs that have no name attribute,such as artificial variables, external references and call siteparameter DIEs.
-gpubnames ¶Generate DWARF.debug_pubnames and.debug_pubtypes sections.
-ggnu-pubnames ¶Generate.debug_pubnames and.debug_pubtypes sections in a formatsuitable for conversion into a GDB index. This option is only usefulwith a linker that can produce GDB index version 7.
-gno-pubnames ¶Don’t generate DWARF.debug_pubnames and.debug_pubtypes sections.
-fdebug-types-section ¶When using DWARF Version 4 or higher, type DIEs can be put intotheir own.debug_types section instead of making them part of the.debug_info section. It is more efficient to put them in a separatecomdat section since the linker can then remove duplicates.But not all DWARF consumers support.debug_types sections yetand on some objects.debug_types produces larger instead of smallerdebugging information.
-grecord-gcc-switches ¶-gno-record-gcc-switchesThis switch causes the command-line options used to invoke thecompiler that may affect code generation to be appended to theDW_AT_producer attribute in DWARF debugging information. The optionsare concatenated with spaces separating them from each other and fromthe compiler version.It is enabled by default.See also-frecord-gcc-switches for anotherway of storing compiler options into the object file.
-gstrict-dwarf ¶Disallow using extensions of later DWARF standard version than selectedwith-gdwarf-version. On most targets using non-conflictingDWARF extensions from later standard versions is allowed.
-gno-strict-dwarf ¶Allow using extensions of later DWARF standard version than selected with-gdwarf-version.
-gas-loc-support ¶Inform the compiler that the assembler supports.loc directives.It may then use them for the assembler to generate DWARF2+ line numbertables.
This is generally desirable, because assembler-generated line-numbertables are a lot more compact than those the compiler can generateitself.
This option is enabled by default if, at GCC configure time, theassembler is found to support such directives.
-gno-as-loc-support ¶Force GCC to generate DWARF2+ line number tables internally, if DWARF2+line number tables are to be generated.
-gas-locview-support ¶Inform the compiler that the assembler supportsview assignmentand reset assertion checking in.loc directives.
This option is enabled by default if, at GCC configure time, theassembler is found to support them.
-gno-as-locview-support ¶Force GCC to assign view numbers internally, if-gvariable-location-views are explicitly requested.
-gcolumn-info ¶-gno-column-infoEmit location column information into DWARF debugging information, ratherthan just file and line.This option is enabled by default.
-gstatement-frontiers ¶-gno-statement-frontiersThis option causes GCC to create markers in the internal representationat the beginning of statements, and to keep them roughly in placethroughout compilation, using them to guide the output ofis_stmtmarkers in the line number table. This is enabled by default whencompiling with optimization (-Os,-O1,-O2,…), and outputting DWARF 2 debug information at the normal level.
-gvariable-location-views ¶-gvariable-location-views=incompat5-gno-variable-location-viewsAugment variable location lists with progressive view numbers impliedfrom the line number table. This enables debug information consumers toinspect state at certain points of the program, even if no instructionsassociated with the corresponding source locations are present at thatpoint. If the assembler lacks support for view numbers in line numbertables, this causes the compiler to emit the line number table,which generally makes them somewhat less compact. The augmented linenumber tables and location lists are fully backward-compatible, so theycan be consumed by debug information consumers that are not aware ofthese augmentations, but they won’t derive any benefit from them either.
This is enabled by default when outputting DWARF 2 debug information atthe normal level, as long as there is assembler support,-fvar-tracking-assignments is enabled and-gstrict-dwarf is not. When assembler support is notavailable, this may still be enabled, but it forces GCC to outputinternal line number tables, and if-ginternal-reset-location-views is not enabled, that mostcertainly leads to silently mismatching location views.
There is a proposed representation for view numbers that is not backwardcompatible with the location list format introduced in DWARF 5, that canbe enabled with-gvariable-location-views=incompat5. Thisoption may be removed in the future, is only provided as a referenceimplementation of the proposed representation. Debug informationconsumers are not expected to support this extended format, and theywould be rendered unable to decode location lists using it.
-ginternal-reset-location-views ¶-gno-internal-reset-location-viewsAttempt to determine location views that can be omitted from locationview lists. This requires the compiler to have very accurate instructionlength estimates, which isn’t always the case, and it may causeincorrect view lists to be generated silently when using an assemblerthat does not support location view lists. The GNU assembler flagsany such error as aview number mismatch. This is only enabledon ports that define a reliable estimation function.
-ginline-points ¶-gno-inline-pointsGenerate extended debug information for inlined functions. Locationview tracking markers are inserted at inlined entry points, so thataddress and view numbers can be computed and output in debuginformation. This can be enabled independently of location views, inwhich case the view numbers won’t be output, but it can only be enabledalong with statement frontiers, and it is only enabled by default iflocation views are enabled.
-gz[=type] ¶Produce compressed debug sections in DWARF format, if that is supported.Iftype is not given, the default type depends on the capabilitiesof the assembler and linker used.type may be one of‘none’ (don’t compress debug sections), ‘zlib’ (use zlibcompression in ELF gABI format), or ‘zstd’ (use zstdcompression in ELF gABI format). If the linker doesn’t support writingcompressed debug sections, the option is rejected. Otherwise, if theassembler does not support them,-gz is silently ignored whenproducing object files.
-femit-struct-debug-baseonly ¶Emit debug information for struct-like typesonly when the base name of the compilation source filematches the base name of file in which the struct is defined.
This option substantially reduces the size of debugging information,but at significant potential loss in type information to the debugger.See-femit-struct-debug-reduced for a less aggressive option.See-femit-struct-debug-detailed for more detailed control.
This option works only with DWARF debug output.
-femit-struct-debug-reduced ¶Emit debug information for struct-like typesonly when the base name of the compilation source filematches the base name of file in which the type is defined,unless the struct is a template or defined in a system header.
This option significantly reduces the size of debugging information,with some potential loss in type information to the debugger.See-femit-struct-debug-baseonly for a more aggressive option.See-femit-struct-debug-detailed for more detailed control.
This option works only with DWARF debug output.
-femit-struct-debug-detailed[=spec-list] ¶Specify the struct-like typesfor which the compiler generates debug information.The intent is to reduce duplicate struct debug informationbetween different object files within the same program.
This option is a detailed version of-femit-struct-debug-reduced and-femit-struct-debug-baseonly,which serves for most needs.
A specification has the syntax
[‘dir:’|‘ind:’][‘ord:’|‘gen:’](‘any’|‘sys’|‘base’|‘none’)
The optional first word limits the specification tostructs that are used directly (‘dir:’) or used indirectly (‘ind:’).A struct type is used directly when it is the type of a variable, member.Indirect uses arise through pointers to structs.That is, when use of an incomplete struct is valid, the use is indirect.An example is‘struct one direct; struct two * indirect;’.
The optional second word limits the specification toordinary structs (‘ord:’) or generic structs (‘gen:’).Generic structs are a bit complicated to explain.For C++, these are non-explicit specializations of template classes,or non-template classes within the above.Other programming languages have generics,but-femit-struct-debug-detailed does not yet implement them.
The third word specifies the source files for thosestructs for which the compiler should emit debug information.The values ‘none’ and ‘any’ have the normal meaning.The value ‘base’ means thatthe base of name of the file in which the type declaration appearsmust match the base of the name of the main compilation file.In practice, this means that when compilingfoo.c, debug informationis generated for types declared in that file andfoo.h,but not other header files.The value ‘sys’ means those types satisfying ‘base’or declared in system or compiler headers.
You may need to experiment to determine the best settings for your application.
The default is-femit-struct-debug-detailed=all.
This option works only with DWARF debug output.
-fno-dwarf2-cfi-asm ¶Emit DWARF unwind info as compiler generated.eh_frame sectioninstead of using GAS.cfi_* directives.
-fno-eliminate-unused-debug-types ¶Normally, when producing DWARF output, GCC avoids producing debug symboloutput for types that are nowhere used in the source file being compiled.Sometimes it is useful to have GCC emit debugginginformation for all types declared in a compilationunit, regardless of whether or not they are actually usedin that compilation unit, for exampleif, in the debugger, you want to cast a value to a type that isnot actually used in your program (but is declared). More often,however, this results in a significant amount of wasted space.
Next:Options That Control Optimization, Previous:Options That Control Static Analysis, Up:GCC Command Options [Contents][Index]