From b0b662cc5653addf4f59bcd2300f11d9df2b6637 Mon Sep 17 00:00:00 2001 From: Sandra Loosemore Date: Mon, 18 Jan 2016 17:47:09 -0500 Subject: [PATCH] invoke.texi (Invoking GCC): Add new section to menu. 2016-01-18 Sandra Loosemore gcc/ * doc/invoke.texi (Invoking GCC): Add new section to menu. (Option Summary): Update to reflect new section and moved options. (C++ Dialect Options): Move -fstats to new section. (Debugging Options): Move all dump, statistics, and other GCC developer options to new section. Rewrite section introduction and re-order remaining options to put the more basic ones first. (Optimization Options): Move -fira-verbose and -flto-report* to new section. (Developer Options): New section incorporating moved options. * doc/cppopts.texi (-dM): Update cross-reference. From-SVN: r232541 --- gcc/ChangeLog | 13 + gcc/doc/cppopts.texi | 2 +- gcc/doc/invoke.texi | 11435 +++++++++++++++++++++-------------------- 3 files changed, 5748 insertions(+), 5702 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index ffb8c2a2bbf..de6e1ede674 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,16 @@ +2016-01-18 Sandra Loosemore + + * doc/invoke.texi (Invoking GCC): Add new section to menu. + (Option Summary): Update to reflect new section and moved options. + (C++ Dialect Options): Move -fstats to new section. + (Debugging Options): Move all dump, statistics, and other GCC + developer options to new section. Rewrite section introduction + and re-order remaining options to put the more basic ones first. + (Optimization Options): Move -fira-verbose and -flto-report* to + new section. + (Developer Options): New section incorporating moved options. + * doc/cppopts.texi (-dM): Update cross-reference. + 2016-01-18 Richard Henderson PR target/69176 diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi index f7142406498..c5f919a5cf2 100644 --- a/gcc/doc/cppopts.texi +++ b/gcc/doc/cppopts.texi @@ -710,7 +710,7 @@ will show all the predefined macros. If you use @option{-dM} without the @option{-E} option, @option{-dM} is interpreted as a synonym for @option{-fdump-rtl-mach}. -@xref{Debugging Options, , ,gcc}. +@xref{Developer Options, , ,gcc}. @item D @opindex dD diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 66861937d81..a1debf19074 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -138,7 +138,7 @@ only one of these two forms, whichever one is not the default. * Diagnostic Message Formatting Options:: Controlling how diagnostics should be formatted. * Warning Options:: How picky should the compiler be? -* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Debugging Options:: Producing debuggable code. * Optimize Options:: How much optimization? * Instrumentation Options:: Enabling profiling and extra run-time error checking. * Preprocessor Options:: Controlling header files and macro definitions. @@ -149,6 +149,8 @@ only one of these two forms, whichever one is not the default. Where to find the compiler executable files. * Code Gen Options:: Specifying conventions for function calls, data layout and register usage. +* Developer Options:: Printing GCC configuration info, statistics, and + debugging dumps. * Submodel Options:: Target-specific options, such as compiling for a specific processor variant. * Spec Files:: How to pass switches to sub-processes. @@ -199,7 +201,7 @@ in the following sections. -fno-optional-diags -fpermissive @gol -fno-pretty-templates @gol -frepo -fno-rtti -fsized-deallocation @gol --fstats -ftemplate-backtrace-limit=@var{n} @gol +-ftemplate-backtrace-limit=@var{n} @gol -ftemplate-depth=@var{n} @gol -fno-threadsafe-statics -fuse-cxa-atexit @gol -fno-weak -nostdinc++ @gol @@ -313,71 +315,18 @@ Objective-C and Objective-C++ Dialects}. -Wdeclaration-after-statement -Wpointer-sign} @item Debugging Options -@xref{Debugging Options,,Options for Debugging Your Program or GCC}. -@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol --fchecking -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol --fdisable-ipa-@var{pass_name} @gol --fdisable-rtl-@var{pass_name} @gol --fdisable-rtl-@var{pass-name}=@var{range-list} @gol --fdisable-tree-@var{pass_name} @gol --fdisable-tree-@var{pass-name}=@var{range-list} @gol --fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol --fdump-translation-unit@r{[}-@var{n}@r{]} @gol --fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol --fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol --fdump-passes @gol --fdump-statistics @gol --fdump-tree-all @gol --fdump-tree-original@r{[}-@var{n}@r{]} @gol --fdump-tree-optimized@r{[}-@var{n}@r{]} @gol --fdump-tree-cfg -fdump-tree-alias @gol --fdump-tree-ch @gol --fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol --fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol --fdump-tree-gimple@r{[}-raw@r{]} @gol --fdump-tree-dom@r{[}-@var{n}@r{]} @gol --fdump-tree-dse@r{[}-@var{n}@r{]} @gol --fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol --fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol --fdump-tree-backprop@r{[}-@var{n}@r{]} @gol --fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol --fdump-tree-nrv -fdump-tree-vect @gol --fdump-tree-sink @gol --fdump-tree-sra@r{[}-@var{n}@r{]} @gol --fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol --fdump-tree-fre@r{[}-@var{n}@r{]} @gol --fdump-tree-vtable-verify @gol --fdump-tree-vrp@r{[}-@var{n}@r{]} @gol --fdump-tree-split-paths@r{[}-@var{n}@r{]} @gol --fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol --fdump-final-insns=@var{file} @gol --fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol --feliminate-dwarf2-dups -fno-eliminate-unused-debug-types @gol --feliminate-unused-debug-symbols -femit-class-debug-always @gol --fenable-@var{kind}-@var{pass} @gol --fenable-@var{kind}-@var{pass}=@var{range-list} @gol --fdebug-types-section -fmem-report-wpa @gol --fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol --fopt-info @gol --fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol --fprofile-report @gol --frandom-seed=@var{string} -fsched-verbose=@var{n} @gol --fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol --fstack-usage -ftime-report -fvar-tracking @gol --fvar-tracking-assignments -fvar-tracking-assignments-toggle @gol --g -g@var{level} -gtoggle -gcoff -gdwarf-@var{version} @gol +@xref{Debugging Options,,Options for Debugging Your Program}. +@gccoptlist{-g -g@var{level} -gcoff -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 --fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol --fdebug-prefix-map=@var{old}=@var{new} @gol +-fdebug-prefix-map=@var{old}=@var{new} -fdebug-types-section @gol +-feliminate-dwarf2-dups -fno-eliminate-unused-debug-types @gol -femit-struct-debug-baseonly -femit-struct-debug-reduced @gol -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol --print-file-name=@var{library} -print-libgcc-file-name @gol --print-multi-directory -print-multi-lib -print-multi-os-directory @gol --print-prog-name=@var{program} -print-search-dirs -Q @gol --print-sysroot -print-sysroot-headers-suffix @gol --save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}} +-feliminate-unused-debug-symbols -femit-class-debug-always @gol +-fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol +-fvar-tracking -fvar-tracking-assignments} @item Optimization Options @xref{Optimize Options,,Options that Control Optimization}. @@ -407,14 +356,14 @@ Objective-C and Objective-C++ Dialects}. -fira-algorithm=@var{algorithm} @gol -fira-region=@var{region} -fira-hoist-pressure @gol -fira-loop-pressure -fno-ira-share-save-slots @gol --fno-ira-share-spill-slots -fira-verbose=@var{n} @gol +-fno-ira-share-spill-slots @gol -fisolate-erroneous-paths-dereference -fisolate-erroneous-paths-attribute @gol -fivopts -fkeep-inline-functions -fkeep-static-functions @gol -fkeep-static-consts -flive-range-shrinkage @gol -floop-block -floop-interchange -floop-strip-mine @gol -floop-unroll-and-jam -floop-nest-optimize @gol -floop-parallelize-all -flra-remat -flto -flto-compression-level @gol --flto-partition=@var{alg} -flto-report -flto-report-wpa -fmerge-all-constants @gol +-flto-partition=@var{alg} -fmerge-all-constants @gol -fmerge-constants -fmodulo-sched -fmodulo-sched-allow-regmoves @gol -fmove-loop-invariants -fno-branch-count-reg @gol -fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol @@ -548,6 +497,64 @@ Objective-C and Objective-C++ Dialects}. -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol -fstrict-volatile-bitfields -fsync-libcalls} +@item Developer Options +@xref{Developer Options,,GCC Developer Options} +@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol +-fchecking -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol +-fdisable-ipa-@var{pass_name} @gol +-fdisable-rtl-@var{pass_name} @gol +-fdisable-rtl-@var{pass-name}=@var{range-list} @gol +-fdisable-tree-@var{pass_name} @gol +-fdisable-tree-@var{pass-name}=@var{range-list} @gol +-fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol +-fdump-translation-unit@r{[}-@var{n}@r{]} @gol +-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol +-fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol +-fdump-passes @gol +-fdump-rtl-@var{pass} -fdump-rtl-@var{pass}=@var{filename} @gol +-fdump-statistics @gol +-fdump-tree-all @gol +-fdump-tree-original@r{[}-@var{n}@r{]} @gol +-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol +-fdump-tree-cfg -fdump-tree-alias @gol +-fdump-tree-ch @gol +-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol +-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol +-fdump-tree-gimple@r{[}-raw@r{]} @gol +-fdump-tree-dom@r{[}-@var{n}@r{]} @gol +-fdump-tree-dse@r{[}-@var{n}@r{]} @gol +-fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol +-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol +-fdump-tree-backprop@r{[}-@var{n}@r{]} @gol +-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol +-fdump-tree-nrv -fdump-tree-vect @gol +-fdump-tree-sink @gol +-fdump-tree-sra@r{[}-@var{n}@r{]} @gol +-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol +-fdump-tree-fre@r{[}-@var{n}@r{]} @gol +-fdump-tree-vtable-verify @gol +-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol +-fdump-tree-split-paths@r{[}-@var{n}@r{]} @gol +-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol +-fdump-final-insns=@var{file} @gol +-fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol +-fenable-@var{kind}-@var{pass} @gol +-fenable-@var{kind}-@var{pass}=@var{range-list} @gol +-fira-verbose=@var{n} @gol +-flto-report -flto-report-wpa -fmem-report-wpa @gol +-fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol +-fopt-info -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol +-fprofile-report @gol +-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol +-fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol +-fstats -fstack-usage -ftime-report @gol +-fvar-tracking-assignments-toggle -gtoggle @gol +-print-file-name=@var{library} -print-libgcc-file-name @gol +-print-multi-directory -print-multi-lib -print-multi-os-directory @gol +-print-prog-name=@var{program} -print-search-dirs -Q @gol +-print-sysroot -print-sysroot-headers-suffix @gol +-save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}} + @item Machine-Dependent Options @xref{Submodel Options,,Machine-Dependent Options}. @c This list is ordered alphanumerically by subsection name. @@ -2433,11 +2440,6 @@ to make deallocation faster. Enabled by default under @option{-std=c++14} and above. The flag @option{-Wsized-deallocation} warns about places that might want to add a definition. -@item -fstats -@opindex fstats -Emit statistics about front-end processing at the end of the compilation. -This information is generally only useful to the G++ development team. - @item -fstrict-enums @opindex fstrict-enums Allow the compiler to optimize using the assumption that a value of @@ -5694,12 +5696,28 @@ attribute. @end table @node Debugging Options -@section Options for Debugging Your Program or GCC +@section Options for Debugging Your Program @cindex options, debugging @cindex debugging information options -GCC has various special options that are used for debugging -either your program or GCC: +To tell GCC to emit extra information for use by a debugger, in almost +all cases you need only to add @option{-g} to your other options. + +GCC allows you to use @option{-g} with +@option{-O}. The shortcuts taken by optimized code may occasionally +be surprising: some variables you declared may not exist +at all; flow of control may briefly move where you did not expect it; +some statements may not be executed because they compute constant +results or their values are already at hand; some statements may +execute in different places because they have been moved out of loops. +Nevertheless it is possible to debug optimized output. This makes +it reasonable to use the optimizer for programs that might have bugs. + +If you are not using some other optimization option, consider +using @option{-Og} (@pxref{Optimize Options}) with @option{-g}. +With no @option{-O} option at all, some compiler passes that collect +information useful for debugging do not run at all, so that +@option{-Og} may result in a better debugging experience. @table @gcctabopt @item -g @@ -5716,28 +5734,6 @@ refuse to read the program. If you want to control for certain whether to generate the extra information, use @option{-gstabs+}, @option{-gstabs}, @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below). -GCC allows you to use @option{-g} with -@option{-O}. The shortcuts taken by optimized code may occasionally -produce surprising results: some variables you declared may not exist -at all; flow of control may briefly move where you did not expect it; -some statements may not be executed because they compute constant -results or their values are already at hand; some statements may -execute in different places because they have been moved out of loops. - -Nevertheless it proves possible to debug optimized output. This makes -it reasonable to use the optimizer for programs that might have bugs. - -The following options are useful when GCC is generated with the -capability for more than one debugging format. - -@item -gsplit-dwarf -@opindex gsplit-dwarf -Separate as much dwarf debugging information as possible into a -separate output file with the extension .dwo. This option allows -the build system to avoid linking files with debug information. To -be useful, this option requires a debugger capable of reading .dwo -files. - @item -ggdb @opindex ggdb Produce debugging information for use by GDB@. This means to use the @@ -5745,15 +5741,17 @@ most expressive format available (DWARF 2, stabs, or the native format if neither of those are supported), including GDB extensions if at all possible. -@item -gpubnames -@opindex gpubnames -Generate dwarf .debug_pubnames and .debug_pubtypes sections. +@item -gdwarf-@var{version} +@opindex gdwarf-@var{version} +Produce debugging information in DWARF format (if that is supported). +The value of @var{version} may be either 2, 3, 4 or 5; the default version +for most targets is 4. DWARF Version 5 is only experimental. -@item -ggnu-pubnames -@opindex ggnu-pubnames -Generate .debug_pubnames and .debug_pubtypes sections in a format -suitable for conversion into a GDB@ index. This option is only useful -with a linker that can produce GDB@ index version 7. +Note that with DWARF Version 2, some ports require and always +use some non-conflicting DWARF 3 extensions in the unwind tables. + +Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments} +for maximum benefit. @item -gstabs @opindex gstabs @@ -5763,31 +5761,6 @@ systems. On MIPS, Alpha and System V Release 4 systems this option produces stabs debugging output that is not understood by DBX or SDB@. On System V Release 4 systems this option requires the GNU assembler. -@item -feliminate-unused-debug-symbols -@opindex feliminate-unused-debug-symbols -Produce debugging information in stabs format (if that is supported), -for only symbols that are actually used. - -@item -femit-class-debug-always -@opindex femit-class-debug-always -Instead of emitting debugging information for a C++ class in only one -object file, emit it in all object files using the class. This option -should be used only with debuggers that are unable to handle the way GCC -normally emits debugging information for classes because using this -option increases the size of debugging information by as much as a -factor of two. - -@item -fdebug-types-section -@opindex fdebug-types-section -@opindex fno-debug-types-section -When using DWARF Version 4 or higher, type DIEs can be put into -their own @code{.debug_types} section instead of making them part of the -@code{.debug_info} section. It is more efficient to put them in a separate -comdat sections since the linker can then remove duplicates. -But not all DWARF consumers support @code{.debug_types} sections yet -and on some objects @code{.debug_types} produces larger instead of smaller -debugging information. - @item -gstabs+ @opindex gstabs+ Produce debugging information in stabs format (if that is supported), @@ -5814,55 +5787,6 @@ use of these extensions is likely to make other debuggers crash or refuse to read the program, and may cause assemblers other than the GNU assembler (GAS) to fail with an error. -@item -gdwarf-@var{version} -@opindex gdwarf-@var{version} -Produce debugging information in DWARF format (if that is supported). -The value of @var{version} may be either 2, 3, 4 or 5; the default version -for most targets is 4. DWARF Version 5 is only experimental. - -Note that with DWARF Version 2, some ports require and always -use some non-conflicting DWARF 3 extensions in the unwind tables. - -Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments} -for maximum benefit. - -@item -grecord-gcc-switches -@opindex grecord-gcc-switches -This switch causes the command-line options used to invoke the -compiler that may affect code generation to be appended to the -DW_AT_producer attribute in DWARF debugging information. The options -are concatenated with spaces separating them from each other and from -the compiler version. See also @option{-frecord-gcc-switches} for another -way of storing compiler options into the object file. This is the default. - -@item -gno-record-gcc-switches -@opindex gno-record-gcc-switches -Disallow appending command-line options to the DW_AT_producer attribute -in DWARF debugging information. - -@item -gstrict-dwarf -@opindex gstrict-dwarf -Disallow using extensions of later DWARF standard version than selected -with @option{-gdwarf-@var{version}}. On most targets using non-conflicting -DWARF extensions from later standard versions is allowed. - -@item -gno-strict-dwarf -@opindex gno-strict-dwarf -Allow using extensions of later DWARF standard version than selected with -@option{-gdwarf-@var{version}}. - -@item -gz@r{[}=@var{type}@r{]} -@opindex gz -Produce compressed debug sections in DWARF format, if that is supported. -If @var{type} is not given, the default type depends on the capabilities -of the assembler and linker used. @var{type} may be one of -@samp{none} (don't compress debug sections), @samp{zlib} (use zlib -compression in ELF gABI format), or @samp{zlib-gnu} (use zlib -compression in traditional GNU format). If the linker doesn't support -writing compressed debug sections, the option is rejected. Otherwise, -if the assembler does not support them, @option{-gz} is silently ignored -when producing object files. - @item -gvms @opindex gvms Produce debugging information in Alpha/VMS debug format (if that is @@ -5897,69 +5821,122 @@ debug format is long obsolete, but the option cannot be changed now. Instead use an additional @option{-g@var{level}} option to change the debug level for DWARF. -@item -gtoggle -@opindex gtoggle -Turn off generation of debug info, if leaving out this option -generates it, or turn it on at level 2 otherwise. The position of this -argument in the command line does not matter; it takes effect after all -other options are processed, and it does so only once, no matter how -many times it is given. This is mainly intended to be used with -@option{-fcompare-debug}. +@item -feliminate-unused-debug-symbols +@opindex feliminate-unused-debug-symbols +Produce debugging information in stabs format (if that is supported), +for only symbols that are actually used. -@item -fchecking -@opindex fchecking -@opindex fno-checking -Enable internal consistency checking. The default depends on -the compiler configuration. +@item -femit-class-debug-always +@opindex femit-class-debug-always +Instead of emitting debugging information for a C++ class in only one +object file, emit it in all object files using the class. This option +should be used only with debuggers that are unable to handle the way GCC +normally emits debugging information for classes because using this +option increases the size of debugging information by as much as a +factor of two. -@item -fdump-final-insns@r{[}=@var{file}@r{]} -@opindex fdump-final-insns -Dump the final internal representation (RTL) to @var{file}. If the -optional argument is omitted (or if @var{file} is @code{.}), the name -of the dump file is determined by appending @code{.gkd} to the -compilation output file name. +@item -fno-merge-debug-strings +@opindex fmerge-debug-strings +@opindex fno-merge-debug-strings +Direct the linker to not merge together strings in the debugging +information that are identical in different object files. Merging is +not supported by all assemblers or linkers. Merging decreases the size +of the debug information in the output file at the cost of increasing +link processing time. Merging is enabled by default. -@item -fcompare-debug@r{[}=@var{opts}@r{]} -@opindex fcompare-debug -@opindex fno-compare-debug -If no error occurs during compilation, run the compiler a second time, -adding @var{opts} and @option{-fcompare-debug-second} to the arguments -passed to the second compilation. Dump the final internal -representation in both compilations, and print an error if they differ. +@item -fdebug-prefix-map=@var{old}=@var{new} +@opindex fdebug-prefix-map +When compiling files in directory @file{@var{old}}, record debugging +information describing them as in @file{@var{new}} instead. -If the equal sign is omitted, the default @option{-gtoggle} is used. +@item -fvar-tracking +@opindex fvar-tracking +Run variable tracking pass. It computes where variables are stored at each +position in code. Better debugging information is then generated +(if the debugging information format supports this information). -The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty -and nonzero, implicitly enables @option{-fcompare-debug}. If -@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash, -then it is used for @var{opts}, otherwise the default @option{-gtoggle} -is used. +It is enabled by default when compiling with optimization (@option{-Os}, +@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and +the debug info format supports it. -@option{-fcompare-debug=}, with the equal sign but without @var{opts}, -is equivalent to @option{-fno-compare-debug}, which disables the dumping -of the final representation and the second compilation, preventing even -@env{GCC_COMPARE_DEBUG} from taking effect. +@item -fvar-tracking-assignments +@opindex fvar-tracking-assignments +@opindex fno-var-tracking-assignments +Annotate assignments to user variables early in the compilation and +attempt to carry the annotations over throughout the compilation all the +way to the end, in an attempt to improve debug information while +optimizing. Use of @option{-gdwarf-4} is recommended along with it. -To verify full coverage during @option{-fcompare-debug} testing, set -@env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden}, -which GCC rejects as an invalid option in any actual compilation -(rather than preprocessing, assembly or linking). To get just a -warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug -not overridden} will do. +It can be enabled even if var-tracking is disabled, in which case +annotations are created and maintained, but discarded at the end. +By default, this flag is enabled together with @option{-fvar-tracking}, +except when selective scheduling is enabled. -@item -fcompare-debug-second -@opindex fcompare-debug-second -This option is implicitly passed to the compiler for the second -compilation requested by @option{-fcompare-debug}, along with options to -silence warnings, and omitting other options that would cause -side-effect compiler outputs to files or to the standard output. Dump -files and preserved temporary files are renamed so as to contain the -@code{.gk} additional extension during the second compilation, to avoid -overwriting those generated by the first. +@item -gsplit-dwarf +@opindex gsplit-dwarf +Separate as much dwarf debugging information as possible into a +separate output file with the extension .dwo. This option allows +the build system to avoid linking files with debug information. To +be useful, this option requires a debugger capable of reading .dwo +files. -When this option is passed to the compiler driver, it causes the -@emph{first} compilation to be skipped, which makes it useful for little -other than debugging the compiler proper. +@item -gpubnames +@opindex gpubnames +Generate dwarf .debug_pubnames and .debug_pubtypes sections. + +@item -ggnu-pubnames +@opindex ggnu-pubnames +Generate .debug_pubnames and .debug_pubtypes sections in a format +suitable for conversion into a GDB@ index. This option is only useful +with a linker that can produce GDB@ index version 7. + +@item -fdebug-types-section +@opindex fdebug-types-section +@opindex fno-debug-types-section +When using DWARF Version 4 or higher, type DIEs can be put into +their own @code{.debug_types} section instead of making them part of the +@code{.debug_info} section. It is more efficient to put them in a separate +comdat sections since the linker can then remove duplicates. +But not all DWARF consumers support @code{.debug_types} sections yet +and on some objects @code{.debug_types} produces larger instead of smaller +debugging information. + +@item -grecord-gcc-switches +@opindex grecord-gcc-switches +This switch causes the command-line options used to invoke the +compiler that may affect code generation to be appended to the +DW_AT_producer attribute in DWARF debugging information. The options +are concatenated with spaces separating them from each other and from +the compiler version. See also @option{-frecord-gcc-switches} for another +way of storing compiler options into the object file. This is the default. + +@item -gno-record-gcc-switches +@opindex gno-record-gcc-switches +Disallow appending command-line options to the DW_AT_producer attribute +in DWARF debugging information. + +@item -gstrict-dwarf +@opindex gstrict-dwarf +Disallow using extensions of later DWARF standard version than selected +with @option{-gdwarf-@var{version}}. On most targets using non-conflicting +DWARF extensions from later standard versions is allowed. + +@item -gno-strict-dwarf +@opindex gno-strict-dwarf +Allow using extensions of later DWARF standard version than selected with +@option{-gdwarf-@var{version}}. + +@item -gz@r{[}=@var{type}@r{]} +@opindex gz +Produce compressed debug sections in DWARF format, if that is supported. +If @var{type} is not given, the default type depends on the capabilities +of the assembler and linker used. @var{type} may be one of +@samp{none} (don't compress debug sections), @samp{zlib} (use zlib +compression in ELF gABI format), or @samp{zlib-gnu} (use zlib +compression in traditional GNU format). If the linker doesn't support +writing compressed debug sections, the option is rejected. Otherwise, +if the assembler does not support them, @option{-gz} is silently ignored +when producing object files. @item -feliminate-dwarf2-dups @opindex feliminate-dwarf2-dups @@ -6042,6572 +6019,6628 @@ The default is @option{-femit-struct-debug-detailed=all}. This option works only with DWARF 2. -@item -fno-merge-debug-strings -@opindex fmerge-debug-strings -@opindex fno-merge-debug-strings -Direct the linker to not merge together strings in the debugging -information that are identical in different object files. Merging is -not supported by all assemblers or linkers. Merging decreases the size -of the debug information in the output file at the cost of increasing -link processing time. Merging is enabled by default. - -@item -fdebug-prefix-map=@var{old}=@var{new} -@opindex fdebug-prefix-map -When compiling files in directory @file{@var{old}}, record debugging -information describing them as in @file{@var{new}} instead. - @item -fno-dwarf2-cfi-asm @opindex fdwarf2-cfi-asm @opindex fno-dwarf2-cfi-asm Emit DWARF 2 unwind info as compiler generated @code{.eh_frame} section instead of using GAS @code{.cfi_*} directives. -@item -Q -@opindex Q -Makes the compiler print out each function name as it is compiled, and -print some statistics about each pass when it finishes. - -@item -ftime-report -@opindex ftime-report -Makes the compiler print some statistics about the time consumed by each -pass when it finishes. - -@item -fmem-report -@opindex fmem-report -Makes the compiler print some statistics about permanent memory -allocation when it finishes. +@item -fno-eliminate-unused-debug-types +@opindex feliminate-unused-debug-types +@opindex fno-eliminate-unused-debug-types +Normally, when producing DWARF 2 output, GCC avoids producing debug symbol +output for types that are nowhere used in the source file being compiled. +Sometimes it is useful to have GCC emit debugging +information for all types declared in a compilation +unit, regardless of whether or not they are actually used +in that compilation unit, for example +if, in the debugger, you want to cast a value to a type that is +not actually used in your program (but is declared). More often, +however, this results in a significant amount of wasted space. +@end table -@item -fmem-report-wpa -@opindex fmem-report-wpa -Makes the compiler print some statistics about permanent memory -allocation for the WPA phase only. +@node Optimize Options +@section Options That Control Optimization +@cindex optimize options +@cindex options, optimization -@item -fpre-ipa-mem-report -@opindex fpre-ipa-mem-report -@item -fpost-ipa-mem-report -@opindex fpost-ipa-mem-report -Makes the compiler print some statistics about permanent memory -allocation before or after interprocedural optimization. +These options control various sorts of optimizations. -@item -fprofile-report -@opindex fprofile-report -Makes the compiler print some statistics about consistency of the -(estimated) profile and effect of individual passes. +Without any optimization option, the compiler's goal is to reduce the +cost of compilation and to make debugging produce the expected +results. Statements are independent: if you stop the program with a +breakpoint between statements, you can then assign a new value to any +variable or change the program counter to any other statement in the +function and get exactly the results you expect from the source +code. -@item -fstack-usage -@opindex fstack-usage -Makes the compiler output stack usage information for the program, on a -per-function basis. The filename for the dump is made by appending -@file{.su} to the @var{auxname}. @var{auxname} is generated from the name of -the output file, if explicitly specified and it is not an executable, -otherwise it is the basename of the source file. An entry is made up -of three fields: +Turning on optimization flags makes the compiler attempt to improve +the performance and/or code size at the expense of compilation time +and possibly the ability to debug the program. -@itemize -@item -The name of the function. -@item -A number of bytes. -@item -One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}. -@end itemize +The compiler performs optimization based on the knowledge it has of the +program. Compiling multiple files at once to a single output file mode allows +the compiler to use information gained from all of the files when compiling +each of them. -The qualifier @code{static} means that the function manipulates the stack -statically: a fixed number of bytes are allocated for the frame on function -entry and released on function exit; no stack adjustments are otherwise made -in the function. The second field is this fixed number of bytes. +Not all optimizations are controlled directly by a flag. Only +optimizations that have a flag are listed in this section. -The qualifier @code{dynamic} means that the function manipulates the stack -dynamically: in addition to the static allocation described above, stack -adjustments are made in the body of the function, for example to push/pop -arguments around function calls. If the qualifier @code{bounded} is also -present, the amount of these adjustments is bounded at compile time and -the second field is an upper bound of the total amount of stack used by -the function. If it is not present, the amount of these adjustments is -not bounded at compile time and the second field only represents the -bounded part. +Most optimizations are only enabled if an @option{-O} level is set on +the command line. Otherwise they are disabled, even if individual +optimization flags are specified. -@item -fdbg-cnt-list -@opindex fdbg-cnt-list -Print the name and the counter upper bound for all debug counters. +Depending on the target and how GCC was configured, a slightly different +set of optimizations may be enabled at each @option{-O} level than +those listed here. You can invoke GCC with @option{-Q --help=optimizers} +to find out the exact set of optimizations that are enabled at each level. +@xref{Overall Options}, for examples. +@table @gcctabopt +@item -O +@itemx -O1 +@opindex O +@opindex O1 +Optimize. Optimizing compilation takes somewhat more time, and a lot +more memory for a large function. -@item -fdbg-cnt=@var{counter-value-list} -@opindex fdbg-cnt -Set the internal debug counter upper bound. @var{counter-value-list} -is a comma-separated list of @var{name}:@var{value} pairs -which sets the upper bound of each debug counter @var{name} to @var{value}. -All debug counters have the initial upper bound of @code{UINT_MAX}; -thus @code{dbg_cnt} returns true always unless the upper bound -is set by this option. -For example, with @option{-fdbg-cnt=dce:10,tail_call:0}, -@code{dbg_cnt(dce)} returns true only for first 10 invocations. - -@item -fenable-@var{kind}-@var{pass} -@itemx -fdisable-@var{kind}-@var{pass}=@var{range-list} -@opindex fdisable- -@opindex fenable- - -This is a set of options that are used to explicitly disable/enable -optimization passes. These options are intended for use for debugging GCC. -Compiler users should use regular options for enabling/disabling -passes instead. +With @option{-O}, the compiler tries to reduce code size and execution +time, without performing any optimizations that take a great deal of +compilation time. -@table @gcctabopt +@option{-O} turns on the following optimization flags: +@gccoptlist{ +-fauto-inc-dec @gol +-fbranch-count-reg @gol +-fcombine-stack-adjustments @gol +-fcompare-elim @gol +-fcprop-registers @gol +-fdce @gol +-fdefer-pop @gol +-fdelayed-branch @gol +-fdse @gol +-fforward-propagate @gol +-fguess-branch-probability @gol +-fif-conversion2 @gol +-fif-conversion @gol +-finline-functions-called-once @gol +-fipa-pure-const @gol +-fipa-profile @gol +-fipa-reference @gol +-fmerge-constants @gol +-fmove-loop-invariants @gol +-freorder-blocks @gol +-fshrink-wrap @gol +-fsplit-wide-types @gol +-fssa-backprop @gol +-fssa-phiopt @gol +-ftree-bit-ccp @gol +-ftree-ccp @gol +-ftree-ch @gol +-ftree-coalesce-vars @gol +-ftree-copy-prop @gol +-ftree-dce @gol +-ftree-dominator-opts @gol +-ftree-dse @gol +-ftree-forwprop @gol +-ftree-fre @gol +-ftree-phiprop @gol +-ftree-sink @gol +-ftree-slsr @gol +-ftree-sra @gol +-ftree-pta @gol +-ftree-ter @gol +-funit-at-a-time} -@item -fdisable-ipa-@var{pass} -Disable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is -statically invoked in the compiler multiple times, the pass name should be -appended with a sequential number starting from 1. +@option{-O} also turns on @option{-fomit-frame-pointer} on machines +where doing so does not interfere with debugging. -@item -fdisable-rtl-@var{pass} -@itemx -fdisable-rtl-@var{pass}=@var{range-list} -Disable RTL pass @var{pass}. @var{pass} is the pass name. If the same pass is -statically invoked in the compiler multiple times, the pass name should be -appended with a sequential number starting from 1. @var{range-list} is a -comma-separated list of function ranges or assembler names. Each range is a number -pair separated by a colon. The range is inclusive in both ends. If the range -is trivial, the number pair can be simplified as a single number. If the -function's call graph node's @var{uid} falls within one of the specified ranges, -the @var{pass} is disabled for that function. The @var{uid} is shown in the -function header of a dump file, and the pass names can be dumped by using -option @option{-fdump-passes}. +@item -O2 +@opindex O2 +Optimize even more. GCC performs nearly all supported optimizations +that do not involve a space-speed tradeoff. +As compared to @option{-O}, this option increases both compilation time +and the performance of the generated code. -@item -fdisable-tree-@var{pass} -@itemx -fdisable-tree-@var{pass}=@var{range-list} -Disable tree pass @var{pass}. See @option{-fdisable-rtl} for the description of -option arguments. +@option{-O2} turns on all optimization flags specified by @option{-O}. It +also turns on the following optimization flags: +@gccoptlist{-fthread-jumps @gol +-falign-functions -falign-jumps @gol +-falign-loops -falign-labels @gol +-fcaller-saves @gol +-fcrossjumping @gol +-fcse-follow-jumps -fcse-skip-blocks @gol +-fdelete-null-pointer-checks @gol +-fdevirtualize -fdevirtualize-speculatively @gol +-fexpensive-optimizations @gol +-fgcse -fgcse-lm @gol +-fhoist-adjacent-loads @gol +-finline-small-functions @gol +-findirect-inlining @gol +-fipa-cp @gol +-fipa-cp-alignment @gol +-fipa-sra @gol +-fipa-icf @gol +-fisolate-erroneous-paths-dereference @gol +-flra-remat @gol +-foptimize-sibling-calls @gol +-foptimize-strlen @gol +-fpartial-inlining @gol +-fpeephole2 @gol +-freorder-blocks-algorithm=stc @gol +-freorder-blocks-and-partition -freorder-functions @gol +-frerun-cse-after-loop @gol +-fsched-interblock -fsched-spec @gol +-fschedule-insns -fschedule-insns2 @gol +-fstrict-aliasing -fstrict-overflow @gol +-ftree-builtin-call-dce @gol +-ftree-switch-conversion -ftree-tail-merge @gol +-ftree-pre @gol +-ftree-vrp @gol +-fipa-ra} -@item -fenable-ipa-@var{pass} -Enable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is -statically invoked in the compiler multiple times, the pass name should be -appended with a sequential number starting from 1. +Please note the warning under @option{-fgcse} about +invoking @option{-O2} on programs that use computed gotos. -@item -fenable-rtl-@var{pass} -@itemx -fenable-rtl-@var{pass}=@var{range-list} -Enable RTL pass @var{pass}. See @option{-fdisable-rtl} for option argument -description and examples. +@item -O3 +@opindex O3 +Optimize yet more. @option{-O3} turns on all optimizations specified +by @option{-O2} and also turns on the @option{-finline-functions}, +@option{-funswitch-loops}, @option{-fpredictive-commoning}, +@option{-fgcse-after-reload}, @option{-ftree-loop-vectorize}, +@option{-ftree-loop-distribute-patterns}, @option{-fsplit-paths} +@option{-ftree-slp-vectorize}, @option{-fvect-cost-model}, +@option{-ftree-partial-pre} and @option{-fipa-cp-clone} options. -@item -fenable-tree-@var{pass} -@itemx -fenable-tree-@var{pass}=@var{range-list} -Enable tree pass @var{pass}. See @option{-fdisable-rtl} for the description -of option arguments. +@item -O0 +@opindex O0 +Reduce compilation time and make debugging produce the expected +results. This is the default. -@end table +@item -Os +@opindex Os +Optimize for size. @option{-Os} enables all @option{-O2} optimizations that +do not typically increase code size. It also performs further +optimizations designed to reduce code size. -Here are some examples showing uses of these options. +@option{-Os} disables the following optimization flags: +@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol +-falign-labels -freorder-blocks -freorder-blocks-algorithm=stc @gol +-freorder-blocks-and-partition -fprefetch-loop-arrays} -@smallexample +@item -Ofast +@opindex Ofast +Disregard strict standards compliance. @option{-Ofast} enables all +@option{-O3} optimizations. It also enables optimizations that are not +valid for all standard-compliant programs. +It turns on @option{-ffast-math} and the Fortran-specific +@option{-fno-protect-parens} and @option{-fstack-arrays}. -# disable ccp1 for all functions - -fdisable-tree-ccp1 -# disable complete unroll for function whose cgraph node uid is 1 - -fenable-tree-cunroll=1 -# disable gcse2 for functions at the following ranges [1,1], -# [300,400], and [400,1000] -# disable gcse2 for functions foo and foo2 - -fdisable-rtl-gcse2=foo,foo2 -# disable early inlining - -fdisable-tree-einline -# disable ipa inlining - -fdisable-ipa-inline -# enable tree full unroll - -fenable-tree-unroll +@item -Og +@opindex Og +Optimize debugging experience. @option{-Og} enables optimizations +that do not interfere with debugging. It should be the optimization +level of choice for the standard edit-compile-debug cycle, offering +a reasonable level of optimization while maintaining fast compilation +and a good debugging experience. +@end table -@end smallexample +If you use multiple @option{-O} options, with or without level numbers, +the last such option is the one that is effective. -@item -d@var{letters} -@itemx -fdump-rtl-@var{pass} -@itemx -fdump-rtl-@var{pass}=@var{filename} -@opindex d -@opindex fdump-rtl-@var{pass} -Says to make debugging dumps during compilation at times specified by -@var{letters}. This is used for debugging the RTL-based passes of the -compiler. The file names for most of the dumps are made by appending -a pass number and a word to the @var{dumpname}, and the files are -created in the directory of the output file. In case of -@option{=@var{filename}} option, the dump is output on the given file -instead of the pass numbered dump files. Note that the pass number is -assigned as passes are registered into the pass manager. Most passes -are registered in the order that they will execute and for these passes -the number corresponds to the pass execution order. However, passes -registered by plugins, passes specific to compilation targets, or -passes that are otherwise registered after all the other passes are -numbered higher than a pass named "final", even if they are executed -earlier. @var{dumpname} is generated from the name of the output -file if explicitly specified and not an executable, otherwise it is -the basename of the source file. These switches may have different -effects when @option{-E} is used for preprocessing. +Options of the form @option{-f@var{flag}} specify machine-independent +flags. Most flags have both positive and negative forms; the negative +form of @option{-ffoo} is @option{-fno-foo}. In the table +below, only one of the forms is listed---the one you typically +use. You can figure out the other form by either removing @samp{no-} +or adding it. -Debug dumps can be enabled with a @option{-fdump-rtl} switch or some -@option{-d} option @var{letters}. Here are the possible -letters for use in @var{pass} and @var{letters}, and their meanings: +The following options control specific optimizations. They are either +activated by @option{-O} options or are related to ones that are. You +can use the following flags in the rare cases when ``fine-tuning'' of +optimizations to be performed is desired. @table @gcctabopt +@item -fno-defer-pop +@opindex fno-defer-pop +Always pop the arguments to each function call as soon as that function +returns. For machines that must pop arguments after a function call, +the compiler normally lets arguments accumulate on the stack for several +function calls and pops them all at once. -@item -fdump-rtl-alignments -@opindex fdump-rtl-alignments -Dump after branch alignments have been computed. +Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -fdump-rtl-asmcons -@opindex fdump-rtl-asmcons -Dump after fixing rtl statements that have unsatisfied in/out constraints. +@item -fforward-propagate +@opindex fforward-propagate +Perform a forward propagation pass on RTL@. The pass tries to combine two +instructions and checks if the result can be simplified. If loop unrolling +is active, two passes are performed and the second is scheduled after +loop unrolling. -@item -fdump-rtl-auto_inc_dec -@opindex fdump-rtl-auto_inc_dec -Dump after auto-inc-dec discovery. This pass is only run on -architectures that have auto inc or auto dec instructions. - -@item -fdump-rtl-barriers -@opindex fdump-rtl-barriers -Dump after cleaning up the barrier instructions. - -@item -fdump-rtl-bbpart -@opindex fdump-rtl-bbpart -Dump after partitioning hot and cold basic blocks. +This option is enabled by default at optimization levels @option{-O}, +@option{-O2}, @option{-O3}, @option{-Os}. -@item -fdump-rtl-bbro -@opindex fdump-rtl-bbro -Dump after block reordering. +@item -ffp-contract=@var{style} +@opindex ffp-contract +@option{-ffp-contract=off} disables floating-point expression contraction. +@option{-ffp-contract=fast} enables floating-point expression contraction +such as forming of fused multiply-add operations if the target has +native support for them. +@option{-ffp-contract=on} enables floating-point expression contraction +if allowed by the language standard. This is currently not implemented +and treated equal to @option{-ffp-contract=off}. -@item -fdump-rtl-btl1 -@itemx -fdump-rtl-btl2 -@opindex fdump-rtl-btl2 -@opindex fdump-rtl-btl2 -@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping -after the two branch -target load optimization passes. +The default is @option{-ffp-contract=fast}. -@item -fdump-rtl-bypass -@opindex fdump-rtl-bypass -Dump after jump bypassing and control flow optimizations. +@item -fomit-frame-pointer +@opindex fomit-frame-pointer +Don't keep the frame pointer in a register for functions that +don't need one. This avoids the instructions to save, set up and +restore frame pointers; it also makes an extra register available +in many functions. @strong{It also makes debugging impossible on +some machines.} -@item -fdump-rtl-combine -@opindex fdump-rtl-combine -Dump after the RTL instruction combination pass. +On some machines, such as the VAX, this flag has no effect, because +the standard calling sequence automatically handles the frame pointer +and nothing is saved by pretending it doesn't exist. The +machine-description macro @code{FRAME_POINTER_REQUIRED} controls +whether a target machine supports this flag. @xref{Registers,,Register +Usage, gccint, GNU Compiler Collection (GCC) Internals}. -@item -fdump-rtl-compgotos -@opindex fdump-rtl-compgotos -Dump after duplicating the computed gotos. +The default setting (when not optimizing for +size) for 32-bit GNU/Linux x86 and 32-bit Darwin x86 targets is +@option{-fomit-frame-pointer}. You can configure GCC with the +@option{--enable-frame-pointer} configure option to change the default. -@item -fdump-rtl-ce1 -@itemx -fdump-rtl-ce2 -@itemx -fdump-rtl-ce3 -@opindex fdump-rtl-ce1 -@opindex fdump-rtl-ce2 -@opindex fdump-rtl-ce3 -@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and -@option{-fdump-rtl-ce3} enable dumping after the three -if conversion passes. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -fdump-rtl-cprop_hardreg -@opindex fdump-rtl-cprop_hardreg -Dump after hard register copy propagation. +@item -foptimize-sibling-calls +@opindex foptimize-sibling-calls +Optimize sibling and tail recursive calls. -@item -fdump-rtl-csa -@opindex fdump-rtl-csa -Dump after combining stack adjustments. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fdump-rtl-cse1 -@itemx -fdump-rtl-cse2 -@opindex fdump-rtl-cse1 -@opindex fdump-rtl-cse2 -@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after -the two common subexpression elimination passes. +@item -foptimize-strlen +@opindex foptimize-strlen +Optimize various standard C string functions (e.g. @code{strlen}, +@code{strchr} or @code{strcpy}) and +their @code{_FORTIFY_SOURCE} counterparts into faster alternatives. -@item -fdump-rtl-dce -@opindex fdump-rtl-dce -Dump after the standalone dead code elimination passes. +Enabled at levels @option{-O2}, @option{-O3}. -@item -fdump-rtl-dbr -@opindex fdump-rtl-dbr -Dump after delayed branch scheduling. +@item -fno-inline +@opindex fno-inline +Do not expand any functions inline apart from those marked with +the @code{always_inline} attribute. This is the default when not +optimizing. -@item -fdump-rtl-dce1 -@itemx -fdump-rtl-dce2 -@opindex fdump-rtl-dce1 -@opindex fdump-rtl-dce2 -@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after -the two dead store elimination passes. +Single functions can be exempted from inlining by marking them +with the @code{noinline} attribute. -@item -fdump-rtl-eh -@opindex fdump-rtl-eh -Dump after finalization of EH handling code. +@item -finline-small-functions +@opindex finline-small-functions +Integrate functions into their callers when their body is smaller than expected +function call code (so overall size of program gets smaller). The compiler +heuristically decides which functions are simple enough to be worth integrating +in this way. This inlining applies to all functions, even those not declared +inline. -@item -fdump-rtl-eh_ranges -@opindex fdump-rtl-eh_ranges -Dump after conversion of EH handling range regions. +Enabled at level @option{-O2}. -@item -fdump-rtl-expand -@opindex fdump-rtl-expand -Dump after RTL generation. +@item -findirect-inlining +@opindex findirect-inlining +Inline also indirect calls that are discovered to be known at compile +time thanks to previous inlining. This option has any effect only +when inlining itself is turned on by the @option{-finline-functions} +or @option{-finline-small-functions} options. -@item -fdump-rtl-fwprop1 -@itemx -fdump-rtl-fwprop2 -@opindex fdump-rtl-fwprop1 -@opindex fdump-rtl-fwprop2 -@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable -dumping after the two forward propagation passes. +Enabled at level @option{-O2}. -@item -fdump-rtl-gcse1 -@itemx -fdump-rtl-gcse2 -@opindex fdump-rtl-gcse1 -@opindex fdump-rtl-gcse2 -@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping -after global common subexpression elimination. +@item -finline-functions +@opindex finline-functions +Consider all functions for inlining, even if they are not declared inline. +The compiler heuristically decides which functions are worth integrating +in this way. -@item -fdump-rtl-init-regs -@opindex fdump-rtl-init-regs -Dump after the initialization of the registers. +If all calls to a given function are integrated, and the function is +declared @code{static}, then the function is normally not output as +assembler code in its own right. -@item -fdump-rtl-initvals -@opindex fdump-rtl-initvals -Dump after the computation of the initial value sets. +Enabled at level @option{-O3}. -@item -fdump-rtl-into_cfglayout -@opindex fdump-rtl-into_cfglayout -Dump after converting to cfglayout mode. +@item -finline-functions-called-once +@opindex finline-functions-called-once +Consider all @code{static} functions called once for inlining into their +caller even if they are not marked @code{inline}. If a call to a given +function is integrated, then the function is not output as assembler code +in its own right. -@item -fdump-rtl-ira -@opindex fdump-rtl-ira -Dump after iterated register allocation. +Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os}. -@item -fdump-rtl-jump -@opindex fdump-rtl-jump -Dump after the second jump optimization. +@item -fearly-inlining +@opindex fearly-inlining +Inline functions marked by @code{always_inline} and functions whose body seems +smaller than the function call overhead early before doing +@option{-fprofile-generate} instrumentation and real inlining pass. Doing so +makes profiling significantly cheaper and usually inlining faster on programs +having large chains of nested wrapper functions. -@item -fdump-rtl-loop2 -@opindex fdump-rtl-loop2 -@option{-fdump-rtl-loop2} enables dumping after the rtl -loop optimization passes. +Enabled by default. -@item -fdump-rtl-mach -@opindex fdump-rtl-mach -Dump after performing the machine dependent reorganization pass, if that -pass exists. +@item -fipa-sra +@opindex fipa-sra +Perform interprocedural scalar replacement of aggregates, removal of +unused parameters and replacement of parameters passed by reference +by parameters passed by value. -@item -fdump-rtl-mode_sw -@opindex fdump-rtl-mode_sw -Dump after removing redundant mode switches. +Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}. -@item -fdump-rtl-rnreg -@opindex fdump-rtl-rnreg -Dump after register renumbering. +@item -finline-limit=@var{n} +@opindex finline-limit +By default, GCC limits the size of functions that can be inlined. This flag +allows coarse control of this limit. @var{n} is the size of functions that +can be inlined in number of pseudo instructions. -@item -fdump-rtl-outof_cfglayout -@opindex fdump-rtl-outof_cfglayout -Dump after converting from cfglayout mode. +Inlining is actually controlled by a number of parameters, which may be +specified individually by using @option{--param @var{name}=@var{value}}. +The @option{-finline-limit=@var{n}} option sets some of these parameters +as follows: -@item -fdump-rtl-peephole2 -@opindex fdump-rtl-peephole2 -Dump after the peephole pass. +@table @gcctabopt +@item max-inline-insns-single +is set to @var{n}/2. +@item max-inline-insns-auto +is set to @var{n}/2. +@end table -@item -fdump-rtl-postreload -@opindex fdump-rtl-postreload -Dump after post-reload optimizations. +See below for a documentation of the individual +parameters controlling inlining and for the defaults of these parameters. -@item -fdump-rtl-pro_and_epilogue -@opindex fdump-rtl-pro_and_epilogue -Dump after generating the function prologues and epilogues. +@emph{Note:} there may be no value to @option{-finline-limit} that results +in default behavior. -@item -fdump-rtl-sched1 -@itemx -fdump-rtl-sched2 -@opindex fdump-rtl-sched1 -@opindex fdump-rtl-sched2 -@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping -after the basic block scheduling passes. +@emph{Note:} pseudo instruction represents, in this particular context, an +abstract measurement of function's size. In no way does it represent a count +of assembly instructions and as such its exact meaning might change from one +release to an another. -@item -fdump-rtl-ree -@opindex fdump-rtl-ree -Dump after sign/zero extension elimination. +@item -fno-keep-inline-dllexport +@opindex fno-keep-inline-dllexport +This is a more fine-grained version of @option{-fkeep-inline-functions}, +which applies only to functions that are declared using the @code{dllexport} +attribute or declspec (@xref{Function Attributes,,Declaring Attributes of +Functions}.) -@item -fdump-rtl-seqabstr -@opindex fdump-rtl-seqabstr -Dump after common sequence discovery. +@item -fkeep-inline-functions +@opindex fkeep-inline-functions +In C, emit @code{static} functions that are declared @code{inline} +into the object file, even if the function has been inlined into all +of its callers. This switch does not affect functions using the +@code{extern inline} extension in GNU C90@. In C++, emit any and all +inline functions into the object file. -@item -fdump-rtl-shorten -@opindex fdump-rtl-shorten -Dump after shortening branches. +@item -fkeep-static-functions +@opindex fkeep-static-functions +Emit @code{static} functions into the object file, even if the function +is never used. -@item -fdump-rtl-sibling -@opindex fdump-rtl-sibling -Dump after sibling call optimizations. +@item -fkeep-static-consts +@opindex fkeep-static-consts +Emit variables declared @code{static const} when optimization isn't turned +on, even if the variables aren't referenced. -@item -fdump-rtl-split1 -@itemx -fdump-rtl-split2 -@itemx -fdump-rtl-split3 -@itemx -fdump-rtl-split4 -@itemx -fdump-rtl-split5 -@opindex fdump-rtl-split1 -@opindex fdump-rtl-split2 -@opindex fdump-rtl-split3 -@opindex fdump-rtl-split4 -@opindex fdump-rtl-split5 -These options enable dumping after five rounds of -instruction splitting. +GCC enables this option by default. If you want to force the compiler to +check if a variable is referenced, regardless of whether or not +optimization is turned on, use the @option{-fno-keep-static-consts} option. -@item -fdump-rtl-sms -@opindex fdump-rtl-sms -Dump after modulo scheduling. This pass is only run on some -architectures. +@item -fmerge-constants +@opindex fmerge-constants +Attempt to merge identical constants (string constants and floating-point +constants) across compilation units. -@item -fdump-rtl-stack -@opindex fdump-rtl-stack -Dump after conversion from GCC's ``flat register file'' registers to the -x87's stack-like registers. This pass is only run on x86 variants. +This option is the default for optimized compilation if the assembler and +linker support it. Use @option{-fno-merge-constants} to inhibit this +behavior. -@item -fdump-rtl-subreg1 -@itemx -fdump-rtl-subreg2 -@opindex fdump-rtl-subreg1 -@opindex fdump-rtl-subreg2 -@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after -the two subreg expansion passes. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -fdump-rtl-unshare -@opindex fdump-rtl-unshare -Dump after all rtl has been unshared. +@item -fmerge-all-constants +@opindex fmerge-all-constants +Attempt to merge identical constants and identical variables. -@item -fdump-rtl-vartrack -@opindex fdump-rtl-vartrack -Dump after variable tracking. +This option implies @option{-fmerge-constants}. In addition to +@option{-fmerge-constants} this considers e.g.@: even constant initialized +arrays or initialized constant variables with integral or floating-point +types. Languages like C or C++ require each variable, including multiple +instances of the same variable in recursive calls, to have distinct locations, +so using this option results in non-conforming +behavior. -@item -fdump-rtl-vregs -@opindex fdump-rtl-vregs -Dump after converting virtual registers to hard registers. +@item -fmodulo-sched +@opindex fmodulo-sched +Perform swing modulo scheduling immediately before the first scheduling +pass. This pass looks at innermost loops and reorders their +instructions by overlapping different iterations. -@item -fdump-rtl-web -@opindex fdump-rtl-web -Dump after live range splitting. +@item -fmodulo-sched-allow-regmoves +@opindex fmodulo-sched-allow-regmoves +Perform more aggressive SMS-based modulo scheduling with register moves +allowed. By setting this flag certain anti-dependences edges are +deleted, which triggers the generation of reg-moves based on the +life-range analysis. This option is effective only with +@option{-fmodulo-sched} enabled. -@item -fdump-rtl-regclass -@itemx -fdump-rtl-subregs_of_mode_init -@itemx -fdump-rtl-subregs_of_mode_finish -@itemx -fdump-rtl-dfinit -@itemx -fdump-rtl-dfinish -@opindex fdump-rtl-regclass -@opindex fdump-rtl-subregs_of_mode_init -@opindex fdump-rtl-subregs_of_mode_finish -@opindex fdump-rtl-dfinit -@opindex fdump-rtl-dfinish -These dumps are defined but always produce empty files. +@item -fno-branch-count-reg +@opindex fno-branch-count-reg +Do not use ``decrement and branch'' instructions on a count register, +but instead generate a sequence of instructions that decrement a +register, compare it against zero, then branch based upon the result. +This option is only meaningful on architectures that support such +instructions, which include x86, PowerPC, IA-64 and S/390. -@item -da -@itemx -fdump-rtl-all -@opindex da -@opindex fdump-rtl-all -Produce all the dumps listed above. +Enabled by default at @option{-O1} and higher. -@item -dA -@opindex dA -Annotate the assembler output with miscellaneous debugging information. +The default is @option{-fbranch-count-reg}. -@item -dD -@opindex dD -Dump all macro definitions, at the end of preprocessing, in addition to -normal output. +@item -fno-function-cse +@opindex fno-function-cse +Do not put function addresses in registers; make each instruction that +calls a constant function contain the function's address explicitly. -@item -dH -@opindex dH -Produce a core dump whenever an error occurs. +This option results in less efficient code, but some strange hacks +that alter the assembler output may be confused by the optimizations +performed when this option is not used. -@item -dp -@opindex dp -Annotate the assembler output with a comment indicating which -pattern and alternative is used. The length of each instruction is -also printed. +The default is @option{-ffunction-cse} -@item -dP -@opindex dP -Dump the RTL in the assembler output as a comment before each instruction. -Also turns on @option{-dp} annotation. +@item -fno-zero-initialized-in-bss +@opindex fno-zero-initialized-in-bss +If the target supports a BSS section, GCC by default puts variables that +are initialized to zero into BSS@. This can save space in the resulting +code. -@item -dx -@opindex dx -Just generate RTL for a function instead of compiling it. Usually used -with @option{-fdump-rtl-expand}. -@end table +This option turns off this behavior because some programs explicitly +rely on variables going to the data section---e.g., so that the +resulting executable can find the beginning of that section and/or make +assumptions based on that. -@item -fdump-noaddr -@opindex fdump-noaddr -When doing debugging dumps, suppress address output. This makes it more -feasible to use diff on debugging dumps for compiler invocations with -different compiler binaries and/or different -text / bss / data / heap / stack / dso start locations. +The default is @option{-fzero-initialized-in-bss}. -@item -freport-bug -@opindex freport-bug -Collect and dump debug information into temporary file if ICE in C/C++ -compiler occured. +@item -fthread-jumps +@opindex fthread-jumps +Perform optimizations that check to see if a jump branches to a +location where another comparison subsumed by the first is found. If +so, the first branch is redirected to either the destination of the +second branch or a point immediately following it, depending on whether +the condition is known to be true or false. -@item -fdump-unnumbered -@opindex fdump-unnumbered -When doing debugging dumps, suppress instruction numbers and address output. -This makes it more feasible to use diff on debugging dumps for compiler -invocations with different options, in particular with and without -@option{-g}. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fdump-unnumbered-links -@opindex fdump-unnumbered-links -When doing debugging dumps (see @option{-d} option above), suppress -instruction numbers for the links to the previous and next instructions -in a sequence. +@item -fsplit-wide-types +@opindex fsplit-wide-types +When using a type that occupies multiple registers, such as @code{long +long} on a 32-bit system, split the registers apart and allocate them +independently. This normally generates better code for those types, +but may make debugging more difficult. -@item -fdump-translation-unit @r{(C++ only)} -@itemx -fdump-translation-unit-@var{options} @r{(C++ only)} -@opindex fdump-translation-unit -Dump a representation of the tree structure for the entire translation -unit to a file. The file name is made by appending @file{.tu} to the -source file name, and the file is created in the same directory as the -output file. If the @samp{-@var{options}} form is used, @var{options} -controls the details of the dump as described for the -@option{-fdump-tree} options. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, +@option{-Os}. -@item -fdump-class-hierarchy @r{(C++ only)} -@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)} -@opindex fdump-class-hierarchy -Dump a representation of each class's hierarchy and virtual function -table layout to a file. The file name is made by appending -@file{.class} to the source file name, and the file is created in the -same directory as the output file. If the @samp{-@var{options}} form -is used, @var{options} controls the details of the dump as described -for the @option{-fdump-tree} options. +@item -fcse-follow-jumps +@opindex fcse-follow-jumps +In common subexpression elimination (CSE), scan through jump instructions +when the target of the jump is not reached by any other path. For +example, when CSE encounters an @code{if} statement with an +@code{else} clause, CSE follows the jump when the condition +tested is false. -@item -fdump-ipa-@var{switch} -@opindex fdump-ipa -Control the dumping at various stages of inter-procedural analysis -language tree to a file. The file name is generated by appending a -switch specific suffix to the source file name, and the file is created -in the same directory as the output file. The following dumps are -possible: +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@table @samp -@item all -Enables all inter-procedural analysis dumps. +@item -fcse-skip-blocks +@opindex fcse-skip-blocks +This is similar to @option{-fcse-follow-jumps}, but causes CSE to +follow jumps that conditionally skip over blocks. When CSE +encounters a simple @code{if} statement with no else clause, +@option{-fcse-skip-blocks} causes CSE to follow the jump around the +body of the @code{if}. -@item cgraph -Dumps information about call-graph optimization, unused function removal, -and inlining decisions. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item inline -Dump after function inlining. +@item -frerun-cse-after-loop +@opindex frerun-cse-after-loop +Re-run common subexpression elimination after loop optimizations are +performed. -@end table +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fdump-passes -@opindex fdump-passes -Dump the list of optimization passes that are turned on and off by -the current command-line options. - -@item -fdump-statistics-@var{option} -@opindex fdump-statistics -Enable and control dumping of pass statistics in a separate file. The -file name is generated by appending a suffix ending in -@samp{.statistics} to the source file name, and the file is created in -the same directory as the output file. If the @samp{-@var{option}} -form is used, @samp{-stats} causes counters to be summed over the -whole compilation unit while @samp{-details} dumps every event as -the passes generate them. The default with no option is to sum -counters for each function compiled. - -@item -fdump-tree-@var{switch} -@itemx -fdump-tree-@var{switch}-@var{options} -@itemx -fdump-tree-@var{switch}-@var{options}=@var{filename} -@opindex fdump-tree -Control the dumping at various stages of processing the intermediate -language tree to a file. The file name is generated by appending a -switch-specific suffix to the source file name, and the file is -created in the same directory as the output file. In case of -@option{=@var{filename}} option, the dump is output on the given file -instead of the auto named dump files. If the @samp{-@var{options}} -form is used, @var{options} is a list of @samp{-} separated options -which control the details of the dump. Not all options are applicable -to all dumps; those that are not meaningful are ignored. The -following options are available +@item -fgcse +@opindex fgcse +Perform a global common subexpression elimination pass. +This pass also performs global constant and copy propagation. -@table @samp -@item address -Print the address of each node. Usually this is not meaningful as it -changes according to the environment and source file. Its primary use -is for tying up a dump file with a debug environment. -@item asmname -If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that -in the dump instead of @code{DECL_NAME}. Its primary use is ease of -use working backward from mangled names in the assembly file. -@item slim -When dumping front-end intermediate representations, inhibit dumping -of members of a scope or body of a function merely because that scope -has been reached. Only dump such items when they are directly reachable -by some other path. +@emph{Note:} When compiling a program using computed gotos, a GCC +extension, you may get better run-time performance if you disable +the global common subexpression elimination pass by adding +@option{-fno-gcse} to the command line. -When dumping pretty-printed trees, this option inhibits dumping the -bodies of control structures. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -When dumping RTL, print the RTL in slim (condensed) form instead of -the default LISP-like representation. -@item raw -Print a raw representation of the tree. By default, trees are -pretty-printed into a C-like representation. -@item details -Enable more detailed dumps (not honored by every dump option). Also -include information from the optimization passes. -@item stats -Enable dumping various statistics about the pass (not honored by every dump -option). -@item blocks -Enable showing basic block boundaries (disabled in raw dumps). -@item graph -For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}), -dump a representation of the control flow graph suitable for viewing with -GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in -the file is pretty-printed as a subgraph, so that GraphViz can render them -all in a single plot. +@item -fgcse-lm +@opindex fgcse-lm +When @option{-fgcse-lm} is enabled, global common subexpression elimination +attempts to move loads that are only killed by stores into themselves. This +allows a loop containing a load/store sequence to be changed to a load outside +the loop, and a copy/store within the loop. -This option currently only works for RTL dumps, and the RTL is always -dumped in slim form. -@item vops -Enable showing virtual operands for every statement. -@item lineno -Enable showing line numbers for statements. -@item uid -Enable showing the unique ID (@code{DECL_UID}) for each variable. -@item verbose -Enable showing the tree dump for each statement. -@item eh -Enable showing the EH region number holding each statement. -@item scev -Enable showing scalar evolution analysis details. -@item optimized -Enable showing optimization information (only available in certain -passes). -@item missed -Enable showing missed optimization information (only available in certain -passes). -@item note -Enable other detailed optimization information (only available in -certain passes). -@item =@var{filename} -Instead of an auto named dump file, output into the given file -name. The file names @file{stdout} and @file{stderr} are treated -specially and are considered already open standard streams. For -example, +Enabled by default when @option{-fgcse} is enabled. -@smallexample -gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump - -fdump-tree-pre=stderr file.c -@end smallexample +@item -fgcse-sm +@opindex fgcse-sm +When @option{-fgcse-sm} is enabled, a store motion pass is run after +global common subexpression elimination. This pass attempts to move +stores out of loops. When used in conjunction with @option{-fgcse-lm}, +loops containing a load/store sequence can be changed to a load before +the loop and a store after the loop. -outputs vectorizer dump into @file{foo.dump}, while the PRE dump is -output on to @file{stderr}. If two conflicting dump filenames are -given for the same pass, then the latter option overrides the earlier -one. +Not enabled at any optimization level. -@item split-paths -@opindex fdump-tree-split-paths -Dump each function after splitting paths to loop backedges. The file -name is made by appending @file{.split-paths} to the source file name. +@item -fgcse-las +@opindex fgcse-las +When @option{-fgcse-las} is enabled, the global common subexpression +elimination pass eliminates redundant loads that come after stores to the +same memory location (both partial and full redundancies). -@item all -Turn on all options, except @option{raw}, @option{slim}, @option{verbose} -and @option{lineno}. +Not enabled at any optimization level. -@item optall -Turn on all optimization options, i.e., @option{optimized}, -@option{missed}, and @option{note}. -@end table +@item -fgcse-after-reload +@opindex fgcse-after-reload +When @option{-fgcse-after-reload} is enabled, a redundant load elimination +pass is performed after reload. The purpose of this pass is to clean up +redundant spilling. -The following tree dumps are possible: -@table @samp +@item -faggressive-loop-optimizations +@opindex faggressive-loop-optimizations +This option tells the loop optimizer to use language constraints to +derive bounds for the number of iterations of a loop. This assumes that +loop code does not invoke undefined behavior by for example causing signed +integer overflows or out-of-bound array accesses. The bounds for the +number of iterations of a loop are used to guide loop unrolling and peeling +and loop exit test optimizations. +This option is enabled by default. -@item original -@opindex fdump-tree-original -Dump before any tree based optimization, to @file{@var{file}.original}. +@item -funsafe-loop-optimizations +@opindex funsafe-loop-optimizations +This option tells the loop optimizer to assume that loop indices do not +overflow, and that loops with nontrivial exit condition are not +infinite. This enables a wider range of loop optimizations even if +the loop optimizer itself cannot prove that these assumptions are valid. +If you use @option{-Wunsafe-loop-optimizations}, the compiler warns you +if it finds this kind of loop. -@item optimized -@opindex fdump-tree-optimized -Dump after all tree based optimization, to @file{@var{file}.optimized}. +@item -fcrossjumping +@opindex fcrossjumping +Perform cross-jumping transformation. +This transformation unifies equivalent code and saves code size. The +resulting code may or may not perform better than without cross-jumping. -@item gimple -@opindex fdump-tree-gimple -Dump each function before and after the gimplification pass to a file. The -file name is made by appending @file{.gimple} to the source file name. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item cfg -@opindex fdump-tree-cfg -Dump the control flow graph of each function to a file. The file name is -made by appending @file{.cfg} to the source file name. +@item -fauto-inc-dec +@opindex fauto-inc-dec +Combine increments or decrements of addresses with memory accesses. +This pass is always skipped on architectures that do not have +instructions to support this. Enabled by default at @option{-O} and +higher on architectures that support this. -@item ch -@opindex fdump-tree-ch -Dump each function after copying loop headers. The file name is made by -appending @file{.ch} to the source file name. +@item -fdce +@opindex fdce +Perform dead code elimination (DCE) on RTL@. +Enabled by default at @option{-O} and higher. -@item ssa -@opindex fdump-tree-ssa -Dump SSA related information to a file. The file name is made by appending -@file{.ssa} to the source file name. +@item -fdse +@opindex fdse +Perform dead store elimination (DSE) on RTL@. +Enabled by default at @option{-O} and higher. -@item alias -@opindex fdump-tree-alias -Dump aliasing information for each function. The file name is made by -appending @file{.alias} to the source file name. +@item -fif-conversion +@opindex fif-conversion +Attempt to transform conditional jumps into branch-less equivalents. This +includes use of conditional moves, min, max, set flags and abs instructions, and +some tricks doable by standard arithmetics. The use of conditional execution +on chips where it is available is controlled by @option{-fif-conversion2}. -@item ccp -@opindex fdump-tree-ccp -Dump each function after CCP@. The file name is made by appending -@file{.ccp} to the source file name. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item storeccp -@opindex fdump-tree-storeccp -Dump each function after STORE-CCP@. The file name is made by appending -@file{.storeccp} to the source file name. +@item -fif-conversion2 +@opindex fif-conversion2 +Use conditional execution (where available) to transform conditional jumps into +branch-less equivalents. -@item pre -@opindex fdump-tree-pre -Dump trees after partial redundancy elimination. The file name is made -by appending @file{.pre} to the source file name. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item fre -@opindex fdump-tree-fre -Dump trees after full redundancy elimination. The file name is made -by appending @file{.fre} to the source file name. +@item -fdeclone-ctor-dtor +@opindex fdeclone-ctor-dtor +The C++ ABI requires multiple entry points for constructors and +destructors: one for a base subobject, one for a complete object, and +one for a virtual destructor that calls operator delete afterwards. +For a hierarchy with virtual bases, the base and complete variants are +clones, which means two copies of the function. With this option, the +base and complete variants are changed to be thunks that call a common +implementation. -@item copyprop -@opindex fdump-tree-copyprop -Dump trees after copy propagation. The file name is made -by appending @file{.copyprop} to the source file name. +Enabled by @option{-Os}. -@item store_copyprop -@opindex fdump-tree-store_copyprop -Dump trees after store copy-propagation. The file name is made -by appending @file{.store_copyprop} to the source file name. - -@item dce -@opindex fdump-tree-dce -Dump each function after dead code elimination. The file name is made by -appending @file{.dce} to the source file name. - -@item sra -@opindex fdump-tree-sra -Dump each function after performing scalar replacement of aggregates. The -file name is made by appending @file{.sra} to the source file name. - -@item sink -@opindex fdump-tree-sink -Dump each function after performing code sinking. The file name is made -by appending @file{.sink} to the source file name. +@item -fdelete-null-pointer-checks +@opindex fdelete-null-pointer-checks +Assume that programs cannot safely dereference null pointers, and that +no code or data element resides at address zero. +This option enables simple constant +folding optimizations at all optimization levels. In addition, other +optimization passes in GCC use this flag to control global dataflow +analyses that eliminate useless checks for null pointers; these assume +that a memory access to address zero always results in a trap, so +that if a pointer is checked after it has already been dereferenced, +it cannot be null. -@item dom -@opindex fdump-tree-dom -Dump each function after applying dominator tree optimizations. The file -name is made by appending @file{.dom} to the source file name. +Note however that in some environments this assumption is not true. +Use @option{-fno-delete-null-pointer-checks} to disable this optimization +for programs that depend on that behavior. -@item dse -@opindex fdump-tree-dse -Dump each function after applying dead store elimination. The file -name is made by appending @file{.dse} to the source file name. +This option is enabled by default on most targets. On Nios II ELF, it +defaults to off. On AVR and CR16, this option is completely disabled. -@item phiopt -@opindex fdump-tree-phiopt -Dump each function after optimizing PHI nodes into straightline code. The file -name is made by appending @file{.phiopt} to the source file name. +Passes that use the dataflow information +are enabled independently at different optimization levels. -@item backprop -@opindex fdump-tree-backprop -Dump each function after back-propagating use information up the definition -chain. The file name is made by appending @file{.backprop} to the -source file name. +@item -fdevirtualize +@opindex fdevirtualize +Attempt to convert calls to virtual functions to direct calls. This +is done both within a procedure and interprocedurally as part of +indirect inlining (@option{-findirect-inlining}) and interprocedural constant +propagation (@option{-fipa-cp}). +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item forwprop -@opindex fdump-tree-forwprop -Dump each function after forward propagating single use variables. The file -name is made by appending @file{.forwprop} to the source file name. +@item -fdevirtualize-speculatively +@opindex fdevirtualize-speculatively +Attempt to convert calls to virtual functions to speculative direct calls. +Based on the analysis of the type inheritance graph, determine for a given call +the set of likely targets. If the set is small, preferably of size 1, change +the call into a conditional deciding between direct and indirect calls. The +speculative calls enable more optimizations, such as inlining. When they seem +useless after further optimization, they are converted back into original form. -@item nrv -@opindex fdump-tree-nrv -Dump each function after applying the named return value optimization on -generic trees. The file name is made by appending @file{.nrv} to the source -file name. +@item -fdevirtualize-at-ltrans +@opindex fdevirtualize-at-ltrans +Stream extra information needed for aggressive devirtualization when running +the link-time optimizer in local transformation mode. +This option enables more devirtualization but +significantly increases the size of streamed data. For this reason it is +disabled by default. -@item vect -@opindex fdump-tree-vect -Dump each function after applying vectorization of loops. The file name is -made by appending @file{.vect} to the source file name. +@item -fexpensive-optimizations +@opindex fexpensive-optimizations +Perform a number of minor optimizations that are relatively expensive. -@item slp -@opindex fdump-tree-slp -Dump each function after applying vectorization of basic blocks. The file name -is made by appending @file{.slp} to the source file name. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item vrp -@opindex fdump-tree-vrp -Dump each function after Value Range Propagation (VRP). The file name -is made by appending @file{.vrp} to the source file name. +@item -free +@opindex free +Attempt to remove redundant extension instructions. This is especially +helpful for the x86-64 architecture, which implicitly zero-extends in 64-bit +registers after writing to their lower 32-bit half. -@item oaccdevlow -@opindex fdump-tree-oaccdevlow -Dump each function after applying device-specific OpenACC transformations. -The file name is made by appending @file{.oaccdevlow} to the source file name. +Enabled for Alpha, AArch64 and x86 at levels @option{-O2}, +@option{-O3}, @option{-Os}. -@item all -@opindex fdump-tree-all -Enable all the available tree dumps with the flags provided in this option. -@end table +@item -fno-lifetime-dse +@opindex fno-lifetime-dse +In C++ the value of an object is only affected by changes within its +lifetime: when the constructor begins, the object has an indeterminate +value, and any changes during the lifetime of the object are dead when +the object is destroyed. Normally dead store elimination will take +advantage of this; if your code relies on the value of the object +storage persisting beyond the lifetime of the object, you can use this +flag to disable this optimization. -@item -fopt-info -@itemx -fopt-info-@var{options} -@itemx -fopt-info-@var{options}=@var{filename} -@opindex fopt-info -Controls optimization dumps from various optimization passes. If the -@samp{-@var{options}} form is used, @var{options} is a list of -@samp{-} separated option keywords to select the dump details and -optimizations. +@item -flive-range-shrinkage +@opindex flive-range-shrinkage +Attempt to decrease register pressure through register live range +shrinkage. This is helpful for fast processors with small or moderate +size register sets. -The @var{options} can be divided into two groups: options describing the -verbosity of the dump, and options describing which optimizations -should be included. The options from both the groups can be freely -mixed as they are non-overlapping. However, in case of any conflicts, -the later options override the earlier options on the command -line. +@item -fira-algorithm=@var{algorithm} +@opindex fira-algorithm +Use the specified coloring algorithm for the integrated register +allocator. The @var{algorithm} argument can be @samp{priority}, which +specifies Chow's priority coloring, or @samp{CB}, which specifies +Chaitin-Briggs coloring. Chaitin-Briggs coloring is not implemented +for all architectures, but for those targets that do support it, it is +the default because it generates better code. -The following options control the dump verbosity: +@item -fira-region=@var{region} +@opindex fira-region +Use specified regions for the integrated register allocator. The +@var{region} argument should be one of the following: @table @samp -@item optimized -Print information when an optimization is successfully applied. It is -up to a pass to decide which information is relevant. For example, the -vectorizer passes print the source location of loops which are -successfully vectorized. -@item missed -Print information about missed optimizations. Individual passes -control which information to include in the output. -@item note -Print verbose information about optimizations, such as certain -transformations, more detailed messages about decisions etc. + @item all -Print detailed optimization information. This includes -@samp{optimized}, @samp{missed}, and @samp{note}. -@end table +Use all loops as register allocation regions. +This can give the best results for machines with a small and/or +irregular register set. -One or more of the following option keywords can be used to describe a -group of optimizations: +@item mixed +Use all loops except for loops with small register pressure +as the regions. This value usually gives +the best results in most cases and for most architectures, +and is enabled by default when compiling with optimization for speed +(@option{-O}, @option{-O2}, @dots{}). + +@item one +Use all functions as a single region. +This typically results in the smallest code size, and is enabled by default for +@option{-Os} or @option{-O0}. -@table @samp -@item ipa -Enable dumps from all interprocedural optimizations. -@item loop -Enable dumps from all loop optimizations. -@item inline -Enable dumps from all inlining optimizations. -@item vec -Enable dumps from all vectorization optimizations. -@item optall -Enable dumps from all optimizations. This is a superset of -the optimization groups listed above. @end table -If @var{options} is -omitted, it defaults to @samp{optimized-optall}, which means to dump all -info about successful optimizations from all the passes. +@item -fira-hoist-pressure +@opindex fira-hoist-pressure +Use IRA to evaluate register pressure in the code hoisting pass for +decisions to hoist expressions. This option usually results in smaller +code, but it can slow the compiler down. -If the @var{filename} is provided, then the dumps from all the -applicable optimizations are concatenated into the @var{filename}. -Otherwise the dump is output onto @file{stderr}. Though multiple -@option{-fopt-info} options are accepted, only one of them can include -a @var{filename}. If other filenames are provided then all but the -first such option are ignored. +This option is enabled at level @option{-Os} for all targets. -Note that the output @var{filename} is overwritten -in case of multiple translation units. If a combined output from -multiple translation units is desired, @file{stderr} should be used -instead. +@item -fira-loop-pressure +@opindex fira-loop-pressure +Use IRA to evaluate register pressure in loops for decisions to move +loop invariants. This option usually results in generation +of faster and smaller code on machines with large register files (>= 32 +registers), but it can slow the compiler down. -In the following example, the optimization info is output to -@file{stderr}: +This option is enabled at level @option{-O3} for some targets. -@smallexample -gcc -O3 -fopt-info -@end smallexample +@item -fno-ira-share-save-slots +@opindex fno-ira-share-save-slots +Disable sharing of stack slots used for saving call-used hard +registers living through a call. Each hard register gets a +separate stack slot, and as a result function stack frames are +larger. -This example: -@smallexample -gcc -O3 -fopt-info-missed=missed.all -@end smallexample +@item -fno-ira-share-spill-slots +@opindex fno-ira-share-spill-slots +Disable sharing of stack slots allocated for pseudo-registers. Each +pseudo-register that does not get a hard register gets a separate +stack slot, and as a result function stack frames are larger. -@noindent -outputs missed optimization report from all the passes into -@file{missed.all}, and this one: +@item -flra-remat +@opindex flra-remat +Enable CFG-sensitive rematerialization in LRA. Instead of loading +values of spilled pseudos, LRA tries to rematerialize (recalculate) +values if it is profitable. -@smallexample -gcc -O2 -ftree-vectorize -fopt-info-vec-missed -@end smallexample +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@noindent -prints information about missed optimization opportunities from -vectorization passes on @file{stderr}. -Note that @option{-fopt-info-vec-missed} is equivalent to -@option{-fopt-info-missed-vec}. - -As another example, -@smallexample -gcc -O3 -fopt-info-inline-optimized-missed=inline.txt -@end smallexample +@item -fdelayed-branch +@opindex fdelayed-branch +If supported for the target machine, attempt to reorder instructions +to exploit instruction slots available after delayed branch +instructions. -@noindent -outputs information about missed optimizations as well as -optimized locations from all the inlining passes into -@file{inline.txt}. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -Finally, consider: +@item -fschedule-insns +@opindex fschedule-insns +If supported for the target machine, attempt to reorder instructions to +eliminate execution stalls due to required data being unavailable. This +helps machines that have slow floating point or memory load instructions +by allowing other instructions to be issued until the result of the load +or floating-point instruction is required. -@smallexample -gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt -@end smallexample +Enabled at levels @option{-O2}, @option{-O3}. -@noindent -Here the two output filenames @file{vec.miss} and @file{loop.opt} are -in conflict since only one output file is allowed. In this case, only -the first option takes effect and the subsequent options are -ignored. Thus only @file{vec.miss} is produced which contains -dumps from the vectorizer about missed opportunities. +@item -fschedule-insns2 +@opindex fschedule-insns2 +Similar to @option{-fschedule-insns}, but requests an additional pass of +instruction scheduling after register allocation has been done. This is +especially useful on machines with a relatively small number of +registers and where memory load instructions take more than one cycle. -@item -frandom-seed=@var{string} -@opindex frandom-seed -This option provides a seed that GCC uses in place of -random numbers in generating certain symbol names -that have to be different in every compiled file. It is also used to -place unique stamps in coverage data files and the object files that -produce them. You can use the @option{-frandom-seed} option to produce -reproducibly identical object files. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -The @var{string} can either be a number (decimal, octal or hex) or an -arbitrary string (in which case it's converted to a number by -computing CRC32). +@item -fno-sched-interblock +@opindex fno-sched-interblock +Don't schedule instructions across basic blocks. This is normally +enabled by default when scheduling before register allocation, i.e.@: +with @option{-fschedule-insns} or at @option{-O2} or higher. -The @var{string} should be different for every file you compile. +@item -fno-sched-spec +@opindex fno-sched-spec +Don't allow speculative motion of non-load instructions. This is normally +enabled by default when scheduling before register allocation, i.e.@: +with @option{-fschedule-insns} or at @option{-O2} or higher. -@item -fsched-verbose=@var{n} -@opindex fsched-verbose -On targets that use instruction scheduling, this option controls the -amount of debugging output the scheduler prints to the dump files. +@item -fsched-pressure +@opindex fsched-pressure +Enable register pressure sensitive insn scheduling before register +allocation. This only makes sense when scheduling before register +allocation is enabled, i.e.@: with @option{-fschedule-insns} or at +@option{-O2} or higher. Usage of this option can improve the +generated code and decrease its size by preventing register pressure +increase above the number of available hard registers and subsequent +spills in register allocation. -For @var{n} greater than zero, @option{-fsched-verbose} outputs the -same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}. -For @var{n} greater than one, it also output basic block probabilities, -detailed ready list information and unit/insn info. For @var{n} greater -than two, it includes RTL at abort point, control-flow and regions info. -And for @var{n} over four, @option{-fsched-verbose} also includes -dependence info. +@item -fsched-spec-load +@opindex fsched-spec-load +Allow speculative motion of some load instructions. This only makes +sense when scheduling before register allocation, i.e.@: with +@option{-fschedule-insns} or at @option{-O2} or higher. -@item -save-temps -@itemx -save-temps=cwd -@opindex save-temps -Store the usual ``temporary'' intermediate files permanently; place them -in the current directory and name them based on the source file. Thus, -compiling @file{foo.c} with @option{-c -save-temps} produces files -@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a -preprocessed @file{foo.i} output file even though the compiler now -normally uses an integrated preprocessor. +@item -fsched-spec-load-dangerous +@opindex fsched-spec-load-dangerous +Allow speculative motion of more load instructions. This only makes +sense when scheduling before register allocation, i.e.@: with +@option{-fschedule-insns} or at @option{-O2} or higher. -When used in combination with the @option{-x} command-line option, -@option{-save-temps} is sensible enough to avoid over writing an -input source file with the same extension as an intermediate file. -The corresponding intermediate file may be obtained by renaming the -source file before using @option{-save-temps}. +@item -fsched-stalled-insns +@itemx -fsched-stalled-insns=@var{n} +@opindex fsched-stalled-insns +Define how many insns (if any) can be moved prematurely from the queue +of stalled insns into the ready list during the second scheduling pass. +@option{-fno-sched-stalled-insns} means that no insns are moved +prematurely, @option{-fsched-stalled-insns=0} means there is no limit +on how many queued insns can be moved prematurely. +@option{-fsched-stalled-insns} without a value is equivalent to +@option{-fsched-stalled-insns=1}. -If you invoke GCC in parallel, compiling several different source -files that share a common base name in different subdirectories or the -same source file compiled for multiple output destinations, it is -likely that the different parallel compilers will interfere with each -other, and overwrite the temporary files. For instance: +@item -fsched-stalled-insns-dep +@itemx -fsched-stalled-insns-dep=@var{n} +@opindex fsched-stalled-insns-dep +Define how many insn groups (cycles) are examined for a dependency +on a stalled insn that is a candidate for premature removal from the queue +of stalled insns. This has an effect only during the second scheduling pass, +and only if @option{-fsched-stalled-insns} is used. +@option{-fno-sched-stalled-insns-dep} is equivalent to +@option{-fsched-stalled-insns-dep=0}. +@option{-fsched-stalled-insns-dep} without a value is equivalent to +@option{-fsched-stalled-insns-dep=1}. -@smallexample -gcc -save-temps -o outdir1/foo.o indir1/foo.c& -gcc -save-temps -o outdir2/foo.o indir2/foo.c& -@end smallexample +@item -fsched2-use-superblocks +@opindex fsched2-use-superblocks +When scheduling after register allocation, use superblock scheduling. +This allows motion across basic block boundaries, +resulting in faster schedules. This option is experimental, as not all machine +descriptions used by GCC model the CPU closely enough to avoid unreliable +results from the algorithm. -may result in @file{foo.i} and @file{foo.o} being written to -simultaneously by both compilers. +This only makes sense when scheduling after register allocation, i.e.@: with +@option{-fschedule-insns2} or at @option{-O2} or higher. -@item -save-temps=obj -@opindex save-temps=obj -Store the usual ``temporary'' intermediate files permanently. If the -@option{-o} option is used, the temporary files are based on the -object file. If the @option{-o} option is not used, the -@option{-save-temps=obj} switch behaves like @option{-save-temps}. +@item -fsched-group-heuristic +@opindex fsched-group-heuristic +Enable the group heuristic in the scheduler. This heuristic favors +the instruction that belongs to a schedule group. This is enabled +by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns} +or @option{-fschedule-insns2} or at @option{-O2} or higher. -For example: +@item -fsched-critical-path-heuristic +@opindex fsched-critical-path-heuristic +Enable the critical-path heuristic in the scheduler. This heuristic favors +instructions on the critical path. This is enabled by default when +scheduling is enabled, i.e.@: with @option{-fschedule-insns} +or @option{-fschedule-insns2} or at @option{-O2} or higher. -@smallexample -gcc -save-temps=obj -c foo.c -gcc -save-temps=obj -c bar.c -o dir/xbar.o -gcc -save-temps=obj foobar.c -o dir2/yfoobar -@end smallexample +@item -fsched-spec-insn-heuristic +@opindex fsched-spec-insn-heuristic +Enable the speculative instruction heuristic in the scheduler. This +heuristic favors speculative instructions with greater dependency weakness. +This is enabled by default when scheduling is enabled, i.e.@: +with @option{-fschedule-insns} or @option{-fschedule-insns2} +or at @option{-O2} or higher. -@noindent -creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i}, -@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and -@file{dir2/yfoobar.o}. +@item -fsched-rank-heuristic +@opindex fsched-rank-heuristic +Enable the rank heuristic in the scheduler. This heuristic favors +the instruction belonging to a basic block with greater size or frequency. +This is enabled by default when scheduling is enabled, i.e.@: +with @option{-fschedule-insns} or @option{-fschedule-insns2} or +at @option{-O2} or higher. -@item -time@r{[}=@var{file}@r{]} -@opindex time -Report the CPU time taken by each subprocess in the compilation -sequence. For C source files, this is the compiler proper and assembler -(plus the linker if linking is done). +@item -fsched-last-insn-heuristic +@opindex fsched-last-insn-heuristic +Enable the last-instruction heuristic in the scheduler. This heuristic +favors the instruction that is less dependent on the last instruction +scheduled. This is enabled by default when scheduling is enabled, +i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or +at @option{-O2} or higher. -Without the specification of an output file, the output looks like this: +@item -fsched-dep-count-heuristic +@opindex fsched-dep-count-heuristic +Enable the dependent-count heuristic in the scheduler. This heuristic +favors the instruction that has more instructions depending on it. +This is enabled by default when scheduling is enabled, i.e.@: +with @option{-fschedule-insns} or @option{-fschedule-insns2} or +at @option{-O2} or higher. -@smallexample -# cc1 0.12 0.01 -# as 0.00 0.01 -@end smallexample +@item -freschedule-modulo-scheduled-loops +@opindex freschedule-modulo-scheduled-loops +Modulo scheduling is performed before traditional scheduling. If a loop +is modulo scheduled, later scheduling passes may change its schedule. +Use this option to control that behavior. -The first number on each line is the ``user time'', that is time spent -executing the program itself. The second number is ``system time'', -time spent executing operating system routines on behalf of the program. -Both numbers are in seconds. +@item -fselective-scheduling +@opindex fselective-scheduling +Schedule instructions using selective scheduling algorithm. Selective +scheduling runs instead of the first scheduler pass. -With the specification of an output file, the output is appended to the -named file, and it looks like this: +@item -fselective-scheduling2 +@opindex fselective-scheduling2 +Schedule instructions using selective scheduling algorithm. Selective +scheduling runs instead of the second scheduler pass. -@smallexample -0.12 0.01 cc1 @var{options} -0.00 0.01 as @var{options} -@end smallexample +@item -fsel-sched-pipelining +@opindex fsel-sched-pipelining +Enable software pipelining of innermost loops during selective scheduling. +This option has no effect unless one of @option{-fselective-scheduling} or +@option{-fselective-scheduling2} is turned on. -The ``user time'' and the ``system time'' are moved before the program -name, and the options passed to the program are displayed, so that one -can later tell what file was being compiled, and with which options. +@item -fsel-sched-pipelining-outer-loops +@opindex fsel-sched-pipelining-outer-loops +When pipelining loops during selective scheduling, also pipeline outer loops. +This option has no effect unless @option{-fsel-sched-pipelining} is turned on. -@item -fvar-tracking -@opindex fvar-tracking -Run variable tracking pass. It computes where variables are stored at each -position 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 (@option{-Os}, -@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and -the debug info format supports it. +@item -fsemantic-interposition +@opindex fsemantic-interposition +Some object formats, like ELF, allow interposing of symbols by the +dynamic linker. +This means that for symbols exported from the DSO, the compiler cannot perform +interprocedural propagation, inlining and other optimizations in anticipation +that the function or variable in question may change. While this feature is +useful, for example, to rewrite memory allocation functions by a debugging +implementation, it is expensive in the terms of code quality. +With @option{-fno-semantic-interposition} the compiler assumes that +if interposition happens for functions the overwriting function will have +precisely the same semantics (and side effects). +Similarly if interposition happens +for variables, the constructor of the variable will be the same. The flag +has no effect for functions explicitly declared inline +(where it is never allowed for interposition to change semantics) +and for symbols explicitly declared weak. -@item -fvar-tracking-assignments -@opindex fvar-tracking-assignments -@opindex fno-var-tracking-assignments -Annotate assignments to user variables early in the compilation and -attempt to carry the annotations over throughout the compilation all the -way to the end, in an attempt to improve debug information while -optimizing. Use of @option{-gdwarf-4} is recommended along with it. +@item -fshrink-wrap +@opindex fshrink-wrap +Emit function prologues only before parts of the function that need it, +rather than at the top of the function. This flag is enabled by default at +@option{-O} and higher. -It can be enabled even if var-tracking is disabled, in which case -annotations are created and maintained, but discarded at the end. -By default, this flag is enabled together with @option{-fvar-tracking}, -except when selective scheduling is enabled. +@item -fcaller-saves +@opindex fcaller-saves +Enable allocation of values to registers that are clobbered by +function calls, by emitting extra instructions to save and restore the +registers around such calls. Such allocation is done only when it +seems to result in better code. -@item -fvar-tracking-assignments-toggle -@opindex fvar-tracking-assignments-toggle -@opindex fno-var-tracking-assignments-toggle -Toggle @option{-fvar-tracking-assignments}, in the same way that -@option{-gtoggle} toggles @option{-g}. +This option is always enabled by default on certain machines, usually +those which have no call-preserved registers to use instead. -@item -print-file-name=@var{library} -@opindex print-file-name -Print the full absolute name of the library file @var{library} that -would be used when linking---and don't do anything else. With this -option, GCC does not compile or link anything; it just prints the -file name. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -print-multi-directory -@opindex print-multi-directory -Print the directory name corresponding to the multilib selected by any -other switches present in the command line. This directory is supposed -to exist in @env{GCC_EXEC_PREFIX}. +@item -fcombine-stack-adjustments +@opindex fcombine-stack-adjustments +Tracks stack adjustments (pushes and pops) and stack memory references +and then tries to find ways to combine them. -@item -print-multi-lib -@opindex print-multi-lib -Print the mapping from multilib directory names to compiler switches -that enable them. The directory name is separated from the switches by -@samp{;}, and each switch starts with an @samp{@@} instead of the -@samp{-}, without spaces between multiple switches. This is supposed to -ease shell processing. +Enabled by default at @option{-O1} and higher. -@item -print-multi-os-directory -@opindex print-multi-os-directory -Print the path to OS libraries for the selected -multilib, relative to some @file{lib} subdirectory. If OS libraries are -present in the @file{lib} subdirectory and no multilibs are used, this is -usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}} -sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or -@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}} -subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}. +@item -fipa-ra +@opindex fipa-ra +Use caller save registers for allocation if those registers are not used by +any called function. In that case it is not necessary to save and restore +them around calls. This is only possible if called functions are part of +same compilation unit as current function and they are compiled before it. -@item -print-multiarch -@opindex print-multiarch -Print the path to OS libraries for the selected multiarch, -relative to some @file{lib} subdirectory. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -print-prog-name=@var{program} -@opindex print-prog-name -Like @option{-print-file-name}, but searches for a program such as @command{cpp}. +@item -fconserve-stack +@opindex fconserve-stack +Attempt to minimize stack usage. The compiler attempts to use less +stack space, even if that makes the program slower. This option +implies setting the @option{large-stack-frame} parameter to 100 +and the @option{large-stack-frame-growth} parameter to 400. -@item -print-libgcc-file-name -@opindex print-libgcc-file-name -Same as @option{-print-file-name=libgcc.a}. +@item -ftree-reassoc +@opindex ftree-reassoc +Perform reassociation on trees. This flag is enabled by default +at @option{-O} and higher. -This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs} -but you do want to link with @file{libgcc.a}. You can do: +@item -ftree-pre +@opindex ftree-pre +Perform partial redundancy elimination (PRE) on trees. This flag is +enabled by default at @option{-O2} and @option{-O3}. -@smallexample -gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` -@end smallexample +@item -ftree-partial-pre +@opindex ftree-partial-pre +Make partial redundancy elimination (PRE) more aggressive. This flag is +enabled by default at @option{-O3}. -@item -print-search-dirs -@opindex print-search-dirs -Print the name of the configured installation directory and a list of -program and library directories @command{gcc} searches---and don't do anything else. +@item -ftree-forwprop +@opindex ftree-forwprop +Perform forward propagation on trees. This flag is enabled by default +at @option{-O} and higher. -This is useful when @command{gcc} prints the error message -@samp{installation problem, cannot exec cpp0: No such file or directory}. -To resolve this you either need to put @file{cpp0} and the other compiler -components where @command{gcc} expects to find them, or you can set the environment -variable @env{GCC_EXEC_PREFIX} to the directory where you installed them. -Don't forget the trailing @samp{/}. -@xref{Environment Variables}. +@item -ftree-fre +@opindex ftree-fre +Perform full redundancy elimination (FRE) on trees. The difference +between FRE and PRE is that FRE only considers expressions +that are computed on all paths leading to the redundant computation. +This analysis is faster than PRE, though it exposes fewer redundancies. +This flag is enabled by default at @option{-O} and higher. -@item -print-sysroot -@opindex print-sysroot -Print the target sysroot directory that is used during -compilation. This is the target sysroot specified either at configure -time or using the @option{--sysroot} option, possibly with an extra -suffix that depends on compilation options. If no target sysroot is -specified, the option prints nothing. +@item -ftree-phiprop +@opindex ftree-phiprop +Perform hoisting of loads from conditional pointers on trees. This +pass is enabled by default at @option{-O} and higher. -@item -print-sysroot-headers-suffix -@opindex print-sysroot-headers-suffix -Print the suffix added to the target sysroot when searching for -headers, or give an error if the compiler is not configured with such -a suffix---and don't do anything else. +@item -fhoist-adjacent-loads +@opindex fhoist-adjacent-loads +Speculatively hoist loads from both branches of an if-then-else if the +loads are from adjacent locations in the same structure and the target +architecture has a conditional move instruction. This flag is enabled +by default at @option{-O2} and higher. -@item -dumpmachine -@opindex dumpmachine -Print the compiler's target machine (for example, -@samp{i686-pc-linux-gnu})---and don't do anything else. +@item -ftree-copy-prop +@opindex ftree-copy-prop +Perform copy propagation on trees. This pass eliminates unnecessary +copy operations. This flag is enabled by default at @option{-O} and +higher. -@item -dumpversion -@opindex dumpversion -Print the compiler version (for example, @code{3.0})---and don't do -anything else. +@item -fipa-pure-const +@opindex fipa-pure-const +Discover which functions are pure or constant. +Enabled by default at @option{-O} and higher. -@item -dumpspecs -@opindex dumpspecs -Print the compiler's built-in specs---and don't do anything else. (This -is used when GCC itself is being built.) @xref{Spec Files}. +@item -fipa-reference +@opindex fipa-reference +Discover which static variables do not escape the +compilation unit. +Enabled by default at @option{-O} and higher. -@item -fno-eliminate-unused-debug-types -@opindex feliminate-unused-debug-types -@opindex fno-eliminate-unused-debug-types -Normally, when producing DWARF 2 output, GCC avoids producing debug symbol -output for types that are nowhere used in the source file being compiled. -Sometimes it is useful to have GCC emit debugging -information for all types declared in a compilation -unit, regardless of whether or not they are actually used -in that compilation unit, for example -if, in the debugger, you want to cast a value to a type that is -not actually used in your program (but is declared). More often, -however, this results in a significant amount of wasted space. -@end table +@item -fipa-pta +@opindex fipa-pta +Perform interprocedural pointer analysis and interprocedural modification +and reference analysis. This option can cause excessive memory and +compile-time usage on large compilation units. It is not enabled by +default at any optimization level. -@node Optimize Options -@section Options That Control Optimization -@cindex optimize options -@cindex options, optimization +@item -fipa-profile +@opindex fipa-profile +Perform interprocedural profile propagation. The functions called only from +cold functions are marked as cold. Also functions executed once (such as +@code{cold}, @code{noreturn}, static constructors or destructors) are identified. Cold +functions and loop less parts of functions executed once are then optimized for +size. +Enabled by default at @option{-O} and higher. -These options control various sorts of optimizations. +@item -fipa-cp +@opindex fipa-cp +Perform interprocedural constant propagation. +This optimization analyzes the program to determine when values passed +to functions are constants and then optimizes accordingly. +This optimization can substantially increase performance +if the application has constants passed to functions. +This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}. -Without any optimization option, the compiler's goal is to reduce the -cost of compilation and to make debugging produce the expected -results. Statements are independent: if you stop the program with a -breakpoint between statements, you can then assign a new value to any -variable or change the program counter to any other statement in the -function and get exactly the results you expect from the source -code. +@item -fipa-cp-clone +@opindex fipa-cp-clone +Perform function cloning to make interprocedural constant propagation stronger. +When enabled, interprocedural constant propagation performs function cloning +when externally visible function can be called with constant arguments. +Because this optimization can create multiple copies of functions, +it may significantly increase code size +(see @option{--param ipcp-unit-growth=@var{value}}). +This flag is enabled by default at @option{-O3}. -Turning on optimization flags makes the compiler attempt to improve -the performance and/or code size at the expense of compilation time -and possibly the ability to debug the program. +@item -fipa-cp-alignment +@opindex -fipa-cp-alignment +When enabled, this optimization propagates alignment of function +parameters to support better vectorization and string operations. -The compiler performs optimization based on the knowledge it has of the -program. Compiling multiple files at once to a single output file mode allows -the compiler to use information gained from all of the files when compiling -each of them. +This flag is enabled by default at @option{-O2} and @option{-Os}. It +requires that @option{-fipa-cp} is enabled. -Not all optimizations are controlled directly by a flag. Only -optimizations that have a flag are listed in this section. +@item -fipa-icf +@opindex fipa-icf +Perform Identical Code Folding for functions and read-only variables. +The optimization reduces code size and may disturb unwind stacks by replacing +a function by equivalent one with a different name. The optimization works +more effectively with link time optimization enabled. -Most optimizations are only enabled if an @option{-O} level is set on -the command line. Otherwise they are disabled, even if individual -optimization flags are specified. +Nevertheless the behavior is similar to Gold Linker ICF optimization, GCC ICF +works on different levels and thus the optimizations are not same - there are +equivalences that are found only by GCC and equivalences found only by Gold. -Depending on the target and how GCC was configured, a slightly different -set of optimizations may be enabled at each @option{-O} level than -those listed here. You can invoke GCC with @option{-Q --help=optimizers} -to find out the exact set of optimizations that are enabled at each level. -@xref{Overall Options}, for examples. +This flag is enabled by default at @option{-O2} and @option{-Os}. -@table @gcctabopt -@item -O -@itemx -O1 -@opindex O -@opindex O1 -Optimize. Optimizing compilation takes somewhat more time, and a lot -more memory for a large function. +@item -fisolate-erroneous-paths-dereference +@opindex fisolate-erroneous-paths-dereference +Detect paths that trigger erroneous or undefined behavior due to +dereferencing a null pointer. Isolate those paths from the main control +flow and turn the statement with erroneous or undefined behavior into a trap. +This flag is enabled by default at @option{-O2} and higher and depends on +@option{-fdelete-null-pointer-checks} also being enabled. -With @option{-O}, the compiler tries to reduce code size and execution -time, without performing any optimizations that take a great deal of -compilation time. +@item -fisolate-erroneous-paths-attribute +@opindex fisolate-erroneous-paths-attribute +Detect paths that trigger erroneous or undefined behavior due a null value +being used in a way forbidden by a @code{returns_nonnull} or @code{nonnull} +attribute. Isolate those paths from the main control flow and turn the +statement with erroneous or undefined behavior into a trap. This is not +currently enabled, but may be enabled by @option{-O2} in the future. -@option{-O} turns on the following optimization flags: -@gccoptlist{ --fauto-inc-dec @gol --fbranch-count-reg @gol --fcombine-stack-adjustments @gol --fcompare-elim @gol --fcprop-registers @gol --fdce @gol --fdefer-pop @gol --fdelayed-branch @gol --fdse @gol --fforward-propagate @gol --fguess-branch-probability @gol --fif-conversion2 @gol --fif-conversion @gol --finline-functions-called-once @gol --fipa-pure-const @gol --fipa-profile @gol --fipa-reference @gol --fmerge-constants @gol --fmove-loop-invariants @gol --freorder-blocks @gol --fshrink-wrap @gol --fsplit-wide-types @gol --fssa-backprop @gol --fssa-phiopt @gol --ftree-bit-ccp @gol --ftree-ccp @gol --ftree-ch @gol --ftree-coalesce-vars @gol --ftree-copy-prop @gol --ftree-dce @gol --ftree-dominator-opts @gol --ftree-dse @gol --ftree-forwprop @gol --ftree-fre @gol --ftree-phiprop @gol --ftree-sink @gol --ftree-slsr @gol --ftree-sra @gol --ftree-pta @gol --ftree-ter @gol --funit-at-a-time} +@item -ftree-sink +@opindex ftree-sink +Perform forward store motion on trees. This flag is +enabled by default at @option{-O} and higher. -@option{-O} also turns on @option{-fomit-frame-pointer} on machines -where doing so does not interfere with debugging. +@item -ftree-bit-ccp +@opindex ftree-bit-ccp +Perform sparse conditional bit constant propagation on trees and propagate +pointer alignment information. +This pass only operates on local scalar variables and is enabled by default +at @option{-O} and higher. It requires that @option{-ftree-ccp} is enabled. -@item -O2 -@opindex O2 -Optimize even more. GCC performs nearly all supported optimizations -that do not involve a space-speed tradeoff. -As compared to @option{-O}, this option increases both compilation time -and the performance of the generated code. +@item -ftree-ccp +@opindex ftree-ccp +Perform sparse conditional constant propagation (CCP) on trees. This +pass only operates on local scalar variables and is enabled by default +at @option{-O} and higher. -@option{-O2} turns on all optimization flags specified by @option{-O}. It -also turns on the following optimization flags: -@gccoptlist{-fthread-jumps @gol --falign-functions -falign-jumps @gol --falign-loops -falign-labels @gol --fcaller-saves @gol --fcrossjumping @gol --fcse-follow-jumps -fcse-skip-blocks @gol --fdelete-null-pointer-checks @gol --fdevirtualize -fdevirtualize-speculatively @gol --fexpensive-optimizations @gol --fgcse -fgcse-lm @gol --fhoist-adjacent-loads @gol --finline-small-functions @gol --findirect-inlining @gol --fipa-cp @gol --fipa-cp-alignment @gol --fipa-sra @gol --fipa-icf @gol --fisolate-erroneous-paths-dereference @gol --flra-remat @gol --foptimize-sibling-calls @gol --foptimize-strlen @gol --fpartial-inlining @gol --fpeephole2 @gol --freorder-blocks-algorithm=stc @gol --freorder-blocks-and-partition -freorder-functions @gol --frerun-cse-after-loop @gol --fsched-interblock -fsched-spec @gol --fschedule-insns -fschedule-insns2 @gol --fstrict-aliasing -fstrict-overflow @gol --ftree-builtin-call-dce @gol --ftree-switch-conversion -ftree-tail-merge @gol --ftree-pre @gol --ftree-vrp @gol --fipa-ra} +@item -fssa-backprop +@opindex fssa-backprop +Propagate information about uses of a value up the definition chain +in order to simplify the definitions. For example, this pass strips +sign operations if the sign of a value never matters. The flag is +enabled by default at @option{-O} and higher. -Please note the warning under @option{-fgcse} about -invoking @option{-O2} on programs that use computed gotos. +@item -fssa-phiopt +@opindex fssa-phiopt +Perform pattern matching on SSA PHI nodes to optimize conditional +code. This pass is enabled by default at @option{-O} and higher. -@item -O3 -@opindex O3 -Optimize yet more. @option{-O3} turns on all optimizations specified -by @option{-O2} and also turns on the @option{-finline-functions}, -@option{-funswitch-loops}, @option{-fpredictive-commoning}, -@option{-fgcse-after-reload}, @option{-ftree-loop-vectorize}, -@option{-ftree-loop-distribute-patterns}, @option{-fsplit-paths} -@option{-ftree-slp-vectorize}, @option{-fvect-cost-model}, -@option{-ftree-partial-pre} and @option{-fipa-cp-clone} options. +@item -ftree-switch-conversion +@opindex ftree-switch-conversion +Perform conversion of simple initializations in a switch to +initializations from a scalar array. This flag is enabled by default +at @option{-O2} and higher. -@item -O0 -@opindex O0 -Reduce compilation time and make debugging produce the expected -results. This is the default. +@item -ftree-tail-merge +@opindex ftree-tail-merge +Look for identical code sequences. When found, replace one with a jump to the +other. This optimization is known as tail merging or cross jumping. This flag +is enabled by default at @option{-O2} and higher. The compilation time +in this pass can +be limited using @option{max-tail-merge-comparisons} parameter and +@option{max-tail-merge-iterations} parameter. -@item -Os -@opindex Os -Optimize for size. @option{-Os} enables all @option{-O2} optimizations that -do not typically increase code size. It also performs further -optimizations designed to reduce code size. +@item -ftree-dce +@opindex ftree-dce +Perform dead code elimination (DCE) on trees. This flag is enabled by +default at @option{-O} and higher. -@option{-Os} disables the following optimization flags: -@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol --falign-labels -freorder-blocks -freorder-blocks-algorithm=stc @gol --freorder-blocks-and-partition -fprefetch-loop-arrays} +@item -ftree-builtin-call-dce +@opindex ftree-builtin-call-dce +Perform conditional dead code elimination (DCE) for calls to built-in functions +that may set @code{errno} but are otherwise side-effect free. This flag is +enabled by default at @option{-O2} and higher if @option{-Os} is not also +specified. -@item -Ofast -@opindex Ofast -Disregard strict standards compliance. @option{-Ofast} enables all -@option{-O3} optimizations. It also enables optimizations that are not -valid for all standard-compliant programs. -It turns on @option{-ffast-math} and the Fortran-specific -@option{-fno-protect-parens} and @option{-fstack-arrays}. +@item -ftree-dominator-opts +@opindex ftree-dominator-opts +Perform a variety of simple scalar cleanups (constant/copy +propagation, redundancy elimination, range propagation and expression +simplification) based on a dominator tree traversal. This also +performs jump threading (to reduce jumps to jumps). This flag is +enabled by default at @option{-O} and higher. -@item -Og -@opindex Og -Optimize debugging experience. @option{-Og} enables optimizations -that do not interfere with debugging. It should be the optimization -level of choice for the standard edit-compile-debug cycle, offering -a reasonable level of optimization while maintaining fast compilation -and a good debugging experience. -@end table +@item -ftree-dse +@opindex ftree-dse +Perform dead store elimination (DSE) on trees. A dead store is a store into +a memory location that is later overwritten by another store without +any intervening loads. In this case the earlier store can be deleted. This +flag is enabled by default at @option{-O} and higher. -If you use multiple @option{-O} options, with or without level numbers, -the last such option is the one that is effective. +@item -ftree-ch +@opindex ftree-ch +Perform loop header copying on trees. This is beneficial since it increases +effectiveness of code motion optimizations. It also saves one jump. This flag +is enabled by default at @option{-O} and higher. It is not enabled +for @option{-Os}, since it usually increases code size. -Options of the form @option{-f@var{flag}} specify machine-independent -flags. Most flags have both positive and negative forms; the negative -form of @option{-ffoo} is @option{-fno-foo}. In the table -below, only one of the forms is listed---the one you typically -use. You can figure out the other form by either removing @samp{no-} -or adding it. +@item -ftree-loop-optimize +@opindex ftree-loop-optimize +Perform loop optimizations on trees. This flag is enabled by default +at @option{-O} and higher. -The following options control specific optimizations. They are either -activated by @option{-O} options or are related to ones that are. You -can use the following flags in the rare cases when ``fine-tuning'' of -optimizations to be performed is desired. - -@table @gcctabopt -@item -fno-defer-pop -@opindex fno-defer-pop -Always pop the arguments to each function call as soon as that function -returns. For machines that must pop arguments after a function call, -the compiler normally lets arguments accumulate on the stack for several -function calls and pops them all at once. +@item -ftree-loop-linear +@itemx -floop-interchange +@itemx -floop-strip-mine +@itemx -floop-block +@itemx -floop-unroll-and-jam +@opindex ftree-loop-linear +@opindex floop-interchange +@opindex floop-strip-mine +@opindex floop-block +@opindex floop-unroll-and-jam +Perform loop nest optimizations. Same as +@option{-floop-nest-optimize}. To use this code transformation, GCC has +to be configured with @option{--with-isl} to enable the Graphite loop +transformation infrastructure. -Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item -fgraphite-identity +@opindex fgraphite-identity +Enable the identity transformation for graphite. For every SCoP we generate +the polyhedral representation and transform it back to gimple. Using +@option{-fgraphite-identity} we can check the costs or benefits of the +GIMPLE -> GRAPHITE -> GIMPLE transformation. Some minimal optimizations +are also performed by the code generator isl, like index splitting and +dead code elimination in loops. -@item -fforward-propagate -@opindex fforward-propagate -Perform a forward propagation pass on RTL@. The pass tries to combine two -instructions and checks if the result can be simplified. If loop unrolling -is active, two passes are performed and the second is scheduled after -loop unrolling. +@item -floop-nest-optimize +@opindex floop-nest-optimize +Enable the isl based loop nest optimizer. This is a generic loop nest +optimizer based on the Pluto optimization algorithms. It calculates a loop +structure optimized for data-locality and parallelism. This option +is experimental. -This option is enabled by default at optimization levels @option{-O}, -@option{-O2}, @option{-O3}, @option{-Os}. +@item -floop-parallelize-all +@opindex floop-parallelize-all +Use the Graphite data dependence analysis to identify loops that can +be parallelized. Parallelize all the loops that can be analyzed to +not contain loop carried dependences without checking that it is +profitable to parallelize the loops. -@item -ffp-contract=@var{style} -@opindex ffp-contract -@option{-ffp-contract=off} disables floating-point expression contraction. -@option{-ffp-contract=fast} enables floating-point expression contraction -such as forming of fused multiply-add operations if the target has -native support for them. -@option{-ffp-contract=on} enables floating-point expression contraction -if allowed by the language standard. This is currently not implemented -and treated equal to @option{-ffp-contract=off}. +@item -ftree-coalesce-vars +@opindex ftree-coalesce-vars +While transforming the program out of the SSA representation, attempt to +reduce copying by coalescing versions of different user-defined +variables, instead of just compiler temporaries. This may severely +limit the ability to debug an optimized program compiled with +@option{-fno-var-tracking-assignments}. In the negated form, this flag +prevents SSA coalescing of user variables. This option is enabled by +default if optimization is enabled, and it does very little otherwise. -The default is @option{-ffp-contract=fast}. +@item -ftree-loop-if-convert +@opindex ftree-loop-if-convert +Attempt to transform conditional jumps in the innermost loops to +branch-less equivalents. The intent is to remove control-flow from +the innermost loops in order to improve the ability of the +vectorization pass to handle these loops. This is enabled by default +if vectorization is enabled. -@item -fomit-frame-pointer -@opindex fomit-frame-pointer -Don't keep the frame pointer in a register for functions that -don't need one. This avoids the instructions to save, set up and -restore frame pointers; it also makes an extra register available -in many functions. @strong{It also makes debugging impossible on -some machines.} +@item -ftree-loop-if-convert-stores +@opindex ftree-loop-if-convert-stores +Attempt to also if-convert conditional jumps containing memory writes. +This transformation can be unsafe for multi-threaded programs as it +transforms conditional memory writes into unconditional memory writes. +For example, +@smallexample +for (i = 0; i < N; i++) + if (cond) + A[i] = expr; +@end smallexample +is transformed to +@smallexample +for (i = 0; i < N; i++) + A[i] = cond ? expr : A[i]; +@end smallexample +potentially producing data races. -On some machines, such as the VAX, this flag has no effect, because -the standard calling sequence automatically handles the frame pointer -and nothing is saved by pretending it doesn't exist. The -machine-description macro @code{FRAME_POINTER_REQUIRED} controls -whether a target machine supports this flag. @xref{Registers,,Register -Usage, gccint, GNU Compiler Collection (GCC) Internals}. +@item -ftree-loop-distribution +@opindex ftree-loop-distribution +Perform loop distribution. This flag can improve cache performance on +big loop bodies and allow further loop optimizations, like +parallelization or vectorization, to take place. For example, the loop +@smallexample +DO I = 1, N + A(I) = B(I) + C + D(I) = E(I) * F +ENDDO +@end smallexample +is transformed to +@smallexample +DO I = 1, N + A(I) = B(I) + C +ENDDO +DO I = 1, N + D(I) = E(I) * F +ENDDO +@end smallexample -The default setting (when not optimizing for -size) for 32-bit GNU/Linux x86 and 32-bit Darwin x86 targets is -@option{-fomit-frame-pointer}. You can configure GCC with the -@option{--enable-frame-pointer} configure option to change the default. +@item -ftree-loop-distribute-patterns +@opindex ftree-loop-distribute-patterns +Perform loop distribution of patterns that can be code generated with +calls to a library. This flag is enabled by default at @option{-O3}. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +This pass distributes the initialization loops and generates a call to +memset zero. For example, the loop +@smallexample +DO I = 1, N + A(I) = 0 + B(I) = A(I) + I +ENDDO +@end smallexample +is transformed to +@smallexample +DO I = 1, N + A(I) = 0 +ENDDO +DO I = 1, N + B(I) = A(I) + I +ENDDO +@end smallexample +and the initialization loop is transformed into a call to memset zero. -@item -foptimize-sibling-calls -@opindex foptimize-sibling-calls -Optimize sibling and tail recursive calls. +@item -ftree-loop-im +@opindex ftree-loop-im +Perform loop invariant motion on trees. This pass moves only invariants that +are hard to handle at RTL level (function calls, operations that expand to +nontrivial sequences of insns). With @option{-funswitch-loops} it also moves +operands of conditions that are invariant out of the loop, so that we can use +just trivial invariantness analysis in loop unswitching. The pass also includes +store motion. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -ftree-loop-ivcanon +@opindex ftree-loop-ivcanon +Create a canonical counter for number of iterations in loops for which +determining number of iterations requires complicated analysis. Later +optimizations then may determine the number easily. Useful especially +in connection with unrolling. -@item -foptimize-strlen -@opindex foptimize-strlen -Optimize various standard C string functions (e.g. @code{strlen}, -@code{strchr} or @code{strcpy}) and -their @code{_FORTIFY_SOURCE} counterparts into faster alternatives. +@item -fivopts +@opindex fivopts +Perform induction variable optimizations (strength reduction, induction +variable merging and induction variable elimination) on trees. -Enabled at levels @option{-O2}, @option{-O3}. +@item -ftree-parallelize-loops=n +@opindex ftree-parallelize-loops +Parallelize loops, i.e., split their iteration space to run in n threads. +This is only possible for loops whose iterations are independent +and can be arbitrarily reordered. The optimization is only +profitable on multiprocessor machines, for loops that are CPU-intensive, +rather than constrained e.g.@: by memory bandwidth. This option +implies @option{-pthread}, and thus is only supported on targets +that have support for @option{-pthread}. -@item -fno-inline -@opindex fno-inline -Do not expand any functions inline apart from those marked with -the @code{always_inline} attribute. This is the default when not -optimizing. +@item -ftree-pta +@opindex ftree-pta +Perform function-local points-to analysis on trees. This flag is +enabled by default at @option{-O} and higher. -Single functions can be exempted from inlining by marking them -with the @code{noinline} attribute. +@item -ftree-sra +@opindex ftree-sra +Perform scalar replacement of aggregates. This pass replaces structure +references with scalars to prevent committing structures to memory too +early. This flag is enabled by default at @option{-O} and higher. -@item -finline-small-functions -@opindex finline-small-functions -Integrate functions into their callers when their body is smaller than expected -function call code (so overall size of program gets smaller). The compiler -heuristically decides which functions are simple enough to be worth integrating -in this way. This inlining applies to all functions, even those not declared -inline. +@item -ftree-ter +@opindex ftree-ter +Perform temporary expression replacement during the SSA->normal phase. Single +use/single def temporaries are replaced at their use location with their +defining expression. This results in non-GIMPLE code, but gives the expanders +much more complex trees to work on resulting in better RTL generation. This is +enabled by default at @option{-O} and higher. -Enabled at level @option{-O2}. +@item -ftree-slsr +@opindex ftree-slsr +Perform straight-line strength reduction on trees. This recognizes related +expressions involving multiplications and replaces them by less expensive +calculations when possible. This is enabled by default at @option{-O} and +higher. -@item -findirect-inlining -@opindex findirect-inlining -Inline also indirect calls that are discovered to be known at compile -time thanks to previous inlining. This option has any effect only -when inlining itself is turned on by the @option{-finline-functions} -or @option{-finline-small-functions} options. +@item -ftree-vectorize +@opindex ftree-vectorize +Perform vectorization on trees. This flag enables @option{-ftree-loop-vectorize} +and @option{-ftree-slp-vectorize} if not explicitly specified. -Enabled at level @option{-O2}. +@item -ftree-loop-vectorize +@opindex ftree-loop-vectorize +Perform loop vectorization on trees. This flag is enabled by default at +@option{-O3} and when @option{-ftree-vectorize} is enabled. -@item -finline-functions -@opindex finline-functions -Consider all functions for inlining, even if they are not declared inline. -The compiler heuristically decides which functions are worth integrating -in this way. +@item -ftree-slp-vectorize +@opindex ftree-slp-vectorize +Perform basic block vectorization on trees. This flag is enabled by default at +@option{-O3} and when @option{-ftree-vectorize} is enabled. -If all calls to a given function are integrated, and the function is -declared @code{static}, then the function is normally not output as -assembler code in its own right. +@item -fvect-cost-model=@var{model} +@opindex fvect-cost-model +Alter the cost model used for vectorization. The @var{model} argument +should be one of @samp{unlimited}, @samp{dynamic} or @samp{cheap}. +With the @samp{unlimited} model the vectorized code-path is assumed +to be profitable while with the @samp{dynamic} model a runtime check +guards the vectorized code-path to enable it only for iteration +counts that will likely execute faster than when executing the original +scalar loop. The @samp{cheap} model disables vectorization of +loops where doing so would be cost prohibitive for example due to +required runtime checks for data dependence or alignment but otherwise +is equal to the @samp{dynamic} model. +The default cost model depends on other optimization flags and is +either @samp{dynamic} or @samp{cheap}. -Enabled at level @option{-O3}. +@item -fsimd-cost-model=@var{model} +@opindex fsimd-cost-model +Alter the cost model used for vectorization of loops marked with the OpenMP +or Cilk Plus simd directive. The @var{model} argument should be one of +@samp{unlimited}, @samp{dynamic}, @samp{cheap}. All values of @var{model} +have the same meaning as described in @option{-fvect-cost-model} and by +default a cost model defined with @option{-fvect-cost-model} is used. -@item -finline-functions-called-once -@opindex finline-functions-called-once -Consider all @code{static} functions called once for inlining into their -caller even if they are not marked @code{inline}. If a call to a given -function is integrated, then the function is not output as assembler code -in its own right. +@item -ftree-vrp +@opindex ftree-vrp +Perform Value Range Propagation on trees. This is similar to the +constant propagation pass, but instead of values, ranges of values are +propagated. This allows the optimizers to remove unnecessary range +checks like array bound checks and null pointer checks. This is +enabled by default at @option{-O2} and higher. Null pointer check +elimination is only done if @option{-fdelete-null-pointer-checks} is +enabled. -Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os}. +@item -fsplit-paths +@opindex fsplit-paths +Split paths leading to loop backedges. This can improve dead code +elimination and common subexpression elimination. This is enabled by +default at @option{-O2} and above. -@item -fearly-inlining -@opindex fearly-inlining -Inline functions marked by @code{always_inline} and functions whose body seems -smaller than the function call overhead early before doing -@option{-fprofile-generate} instrumentation and real inlining pass. Doing so -makes profiling significantly cheaper and usually inlining faster on programs -having large chains of nested wrapper functions. +@item -fsplit-ivs-in-unroller +@opindex fsplit-ivs-in-unroller +Enables expression of values of induction variables in later iterations +of the unrolled loop using the value in the first iteration. This breaks +long dependency chains, thus improving efficiency of the scheduling passes. -Enabled by default. +A combination of @option{-fweb} and CSE is often sufficient to obtain the +same effect. However, that is not reliable in cases where the loop body +is more complicated than a single basic block. It also does not work at all +on some architectures due to restrictions in the CSE pass. -@item -fipa-sra -@opindex fipa-sra -Perform interprocedural scalar replacement of aggregates, removal of -unused parameters and replacement of parameters passed by reference -by parameters passed by value. +This optimization is enabled by default. -Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}. +@item -fvariable-expansion-in-unroller +@opindex fvariable-expansion-in-unroller +With this option, the compiler creates multiple copies of some +local variables when unrolling a loop, which can result in superior code. -@item -finline-limit=@var{n} -@opindex finline-limit -By default, GCC limits the size of functions that can be inlined. This flag -allows coarse control of this limit. @var{n} is the size of functions that -can be inlined in number of pseudo instructions. +@item -fpartial-inlining +@opindex fpartial-inlining +Inline parts of functions. This option has any effect only +when inlining itself is turned on by the @option{-finline-functions} +or @option{-finline-small-functions} options. -Inlining is actually controlled by a number of parameters, which may be -specified individually by using @option{--param @var{name}=@var{value}}. -The @option{-finline-limit=@var{n}} option sets some of these parameters -as follows: +Enabled at level @option{-O2}. -@table @gcctabopt -@item max-inline-insns-single -is set to @var{n}/2. -@item max-inline-insns-auto -is set to @var{n}/2. -@end table +@item -fpredictive-commoning +@opindex fpredictive-commoning +Perform predictive commoning optimization, i.e., reusing computations +(especially memory loads and stores) performed in previous +iterations of loops. -See below for a documentation of the individual -parameters controlling inlining and for the defaults of these parameters. +This option is enabled at level @option{-O3}. -@emph{Note:} there may be no value to @option{-finline-limit} that results -in default behavior. +@item -fprefetch-loop-arrays +@opindex fprefetch-loop-arrays +If supported by the target machine, generate instructions to prefetch +memory to improve the performance of loops that access large arrays. -@emph{Note:} pseudo instruction represents, in this particular context, an -abstract measurement of function's size. In no way does it represent a count -of assembly instructions and as such its exact meaning might change from one -release to an another. +This option may generate better or worse code; results are highly +dependent on the structure of loops within the source code. -@item -fno-keep-inline-dllexport -@opindex fno-keep-inline-dllexport -This is a more fine-grained version of @option{-fkeep-inline-functions}, -which applies only to functions that are declared using the @code{dllexport} -attribute or declspec (@xref{Function Attributes,,Declaring Attributes of -Functions}.) +Disabled at level @option{-Os}. -@item -fkeep-inline-functions -@opindex fkeep-inline-functions -In C, emit @code{static} functions that are declared @code{inline} -into the object file, even if the function has been inlined into all -of its callers. This switch does not affect functions using the -@code{extern inline} extension in GNU C90@. In C++, emit any and all -inline functions into the object file. +@item -fno-peephole +@itemx -fno-peephole2 +@opindex fno-peephole +@opindex fno-peephole2 +Disable any machine-specific peephole optimizations. The difference +between @option{-fno-peephole} and @option{-fno-peephole2} is in how they +are implemented in the compiler; some targets use one, some use the +other, a few use both. -@item -fkeep-static-functions -@opindex fkeep-static-functions -Emit @code{static} functions into the object file, even if the function -is never used. +@option{-fpeephole} is enabled by default. +@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fkeep-static-consts -@opindex fkeep-static-consts -Emit variables declared @code{static const} when optimization isn't turned -on, even if the variables aren't referenced. +@item -fno-guess-branch-probability +@opindex fno-guess-branch-probability +Do not guess branch probabilities using heuristics. -GCC enables this option by default. If you want to force the compiler to -check if a variable is referenced, regardless of whether or not -optimization is turned on, use the @option{-fno-keep-static-consts} option. +GCC uses heuristics to guess branch probabilities if they are +not provided by profiling feedback (@option{-fprofile-arcs}). These +heuristics are based on the control flow graph. If some branch probabilities +are specified by @code{__builtin_expect}, then the heuristics are +used to guess branch probabilities for the rest of the control flow graph, +taking the @code{__builtin_expect} info into account. The interactions +between the heuristics and @code{__builtin_expect} can be complex, and in +some cases, it may be useful to disable the heuristics so that the effects +of @code{__builtin_expect} are easier to understand. -@item -fmerge-constants -@opindex fmerge-constants -Attempt to merge identical constants (string constants and floating-point -constants) across compilation units. +The default is @option{-fguess-branch-probability} at levels +@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -This option is the default for optimized compilation if the assembler and -linker support it. Use @option{-fno-merge-constants} to inhibit this -behavior. +@item -freorder-blocks +@opindex freorder-blocks +Reorder basic blocks in the compiled function in order to reduce number of +taken branches and improve code locality. Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -fmerge-all-constants -@opindex fmerge-all-constants -Attempt to merge identical constants and identical variables. - -This option implies @option{-fmerge-constants}. In addition to -@option{-fmerge-constants} this considers e.g.@: even constant initialized -arrays or initialized constant variables with integral or floating-point -types. Languages like C or C++ require each variable, including multiple -instances of the same variable in recursive calls, to have distinct locations, -so using this option results in non-conforming -behavior. +@item -freorder-blocks-algorithm=@var{algorithm} +@opindex freorder-blocks-algorithm +Use the specified algorithm for basic block reordering. The +@var{algorithm} argument can be @samp{simple}, which does not increase +code size (except sometimes due to secondary effects like alignment), +or @samp{stc}, the ``software trace cache'' algorithm, which tries to +put all often executed code together, minimizing the number of branches +executed by making extra copies of code. -@item -fmodulo-sched -@opindex fmodulo-sched -Perform swing modulo scheduling immediately before the first scheduling -pass. This pass looks at innermost loops and reorders their -instructions by overlapping different iterations. +The default is @samp{simple} at levels @option{-O}, @option{-Os}, and +@samp{stc} at levels @option{-O2}, @option{-O3}. -@item -fmodulo-sched-allow-regmoves -@opindex fmodulo-sched-allow-regmoves -Perform more aggressive SMS-based modulo scheduling with register moves -allowed. By setting this flag certain anti-dependences edges are -deleted, which triggers the generation of reg-moves based on the -life-range analysis. This option is effective only with -@option{-fmodulo-sched} enabled. +@item -freorder-blocks-and-partition +@opindex freorder-blocks-and-partition +In addition to reordering basic blocks in the compiled function, in order +to reduce number of taken branches, partitions hot and cold basic blocks +into separate sections of the assembly and .o files, to improve +paging and cache locality performance. -@item -fno-branch-count-reg -@opindex fno-branch-count-reg -Do not use ``decrement and branch'' instructions on a count register, -but instead generate a sequence of instructions that decrement a -register, compare it against zero, then branch based upon the result. -This option is only meaningful on architectures that support such -instructions, which include x86, PowerPC, IA-64 and S/390. +This optimization is automatically turned off in the presence of +exception handling, for linkonce sections, for functions with a user-defined +section attribute and on any architecture that does not support named +sections. -Enabled by default at @option{-O1} and higher. +Enabled for x86 at levels @option{-O2}, @option{-O3}. -The default is @option{-fbranch-count-reg}. +@item -freorder-functions +@opindex freorder-functions +Reorder functions in the object file in order to +improve code locality. This is implemented by using special +subsections @code{.text.hot} for most frequently executed functions and +@code{.text.unlikely} for unlikely executed functions. Reordering is done by +the linker so object file format must support named sections and linker must +place them in a reasonable way. -@item -fno-function-cse -@opindex fno-function-cse -Do not put function addresses in registers; make each instruction that -calls a constant function contain the function's address explicitly. +Also profile feedback must be available to make this option effective. See +@option{-fprofile-arcs} for details. -This option results in less efficient code, but some strange hacks -that alter the assembler output may be confused by the optimizations -performed when this option is not used. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -The default is @option{-ffunction-cse} +@item -fstrict-aliasing +@opindex fstrict-aliasing +Allow the compiler to assume the strictest aliasing rules applicable to +the language being compiled. For C (and C++), this activates +optimizations based on the type of expressions. In particular, an +object of one type is assumed never to reside at the same address as an +object of a different type, unless the types are almost the same. For +example, an @code{unsigned int} can alias an @code{int}, but not a +@code{void*} or a @code{double}. A character type may alias any other +type. -@item -fno-zero-initialized-in-bss -@opindex fno-zero-initialized-in-bss -If the target supports a BSS section, GCC by default puts variables that -are initialized to zero into BSS@. This can save space in the resulting -code. +@anchor{Type-punning}Pay special attention to code like this: +@smallexample +union a_union @{ + int i; + double d; +@}; -This option turns off this behavior because some programs explicitly -rely on variables going to the data section---e.g., so that the -resulting executable can find the beginning of that section and/or make -assumptions based on that. +int f() @{ + union a_union t; + t.d = 3.0; + return t.i; +@} +@end smallexample +The practice of reading from a different union member than the one most +recently written to (called ``type-punning'') is common. Even with +@option{-fstrict-aliasing}, type-punning is allowed, provided the memory +is accessed through the union type. So, the code above works as +expected. @xref{Structures unions enumerations and bit-fields +implementation}. However, this code might not: +@smallexample +int f() @{ + union a_union t; + int* ip; + t.d = 3.0; + ip = &t.i; + return *ip; +@} +@end smallexample -The default is @option{-fzero-initialized-in-bss}. +Similarly, access by taking the address, casting the resulting pointer +and dereferencing the result has undefined behavior, even if the cast +uses a union type, e.g.: +@smallexample +int f() @{ + double d = 3.0; + return ((union a_union *) &d)->i; +@} +@end smallexample -@item -fthread-jumps -@opindex fthread-jumps -Perform optimizations that check to see if a jump branches to a -location where another comparison subsumed by the first is found. If -so, the first branch is redirected to either the destination of the -second branch or a point immediately following it, depending on whether -the condition is known to be true or false. +The @option{-fstrict-aliasing} option is enabled at levels +@option{-O2}, @option{-O3}, @option{-Os}. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -fstrict-overflow +@opindex fstrict-overflow +Allow the compiler to assume strict signed overflow rules, depending +on the language being compiled. For C (and C++) this means that +overflow when doing arithmetic with signed numbers is undefined, which +means that the compiler may assume that it does not happen. This +permits various optimizations. For example, the compiler assumes +that an expression like @code{i + 10 > i} is always true for +signed @code{i}. This assumption is only valid if signed overflow is +undefined, as the expression is false if @code{i + 10} overflows when +using twos complement arithmetic. When this option is in effect any +attempt to determine whether an operation on signed numbers +overflows must be written carefully to not actually involve overflow. -@item -fsplit-wide-types -@opindex fsplit-wide-types -When using a type that occupies multiple registers, such as @code{long -long} on a 32-bit system, split the registers apart and allocate them -independently. This normally generates better code for those types, -but may make debugging more difficult. +This option also allows the compiler to assume strict pointer +semantics: given a pointer to an object, if adding an offset to that +pointer does not produce a pointer to the same object, the addition is +undefined. This permits the compiler to conclude that @code{p + u > +p} is always true for a pointer @code{p} and unsigned integer +@code{u}. This assumption is only valid because pointer wraparound is +undefined, as the expression is false if @code{p + u} overflows using +twos complement arithmetic. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, -@option{-Os}. +See also the @option{-fwrapv} option. Using @option{-fwrapv} means +that integer signed overflow is fully defined: it wraps. When +@option{-fwrapv} is used, there is no difference between +@option{-fstrict-overflow} and @option{-fno-strict-overflow} for +integers. With @option{-fwrapv} certain types of overflow are +permitted. For example, if the compiler gets an overflow when doing +arithmetic on constants, the overflowed value can still be used with +@option{-fwrapv}, but not otherwise. -@item -fcse-follow-jumps -@opindex fcse-follow-jumps -In common subexpression elimination (CSE), scan through jump instructions -when the target of the jump is not reached by any other path. For -example, when CSE encounters an @code{if} statement with an -@code{else} clause, CSE follows the jump when the condition -tested is false. +The @option{-fstrict-overflow} option is enabled at levels +@option{-O2}, @option{-O3}, @option{-Os}. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -falign-functions +@itemx -falign-functions=@var{n} +@opindex falign-functions +Align the start of functions to the next power-of-two greater than +@var{n}, skipping up to @var{n} bytes. For instance, +@option{-falign-functions=32} aligns functions to the next 32-byte +boundary, but @option{-falign-functions=24} aligns to the next +32-byte boundary only if this can be done by skipping 23 bytes or less. -@item -fcse-skip-blocks -@opindex fcse-skip-blocks -This is similar to @option{-fcse-follow-jumps}, but causes CSE to -follow jumps that conditionally skip over blocks. When CSE -encounters a simple @code{if} statement with no else clause, -@option{-fcse-skip-blocks} causes CSE to follow the jump around the -body of the @code{if}. +@option{-fno-align-functions} and @option{-falign-functions=1} are +equivalent and mean that functions are not aligned. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +Some assemblers only support this flag when @var{n} is a power of two; +in that case, it is rounded up. -@item -frerun-cse-after-loop -@opindex frerun-cse-after-loop -Re-run common subexpression elimination after loop optimizations are -performed. +If @var{n} is not specified or is zero, use a machine-dependent default. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +Enabled at levels @option{-O2}, @option{-O3}. -@item -fgcse -@opindex fgcse -Perform a global common subexpression elimination pass. -This pass also performs global constant and copy propagation. +@item -falign-labels +@itemx -falign-labels=@var{n} +@opindex falign-labels +Align all branch targets to a power-of-two boundary, skipping up to +@var{n} bytes like @option{-falign-functions}. This option can easily +make code slower, because it must insert dummy operations for when the +branch target is reached in the usual flow of the code. -@emph{Note:} When compiling a program using computed gotos, a GCC -extension, you may get better run-time performance if you disable -the global common subexpression elimination pass by adding -@option{-fno-gcse} to the command line. +@option{-fno-align-labels} and @option{-falign-labels=1} are +equivalent and mean that labels are not aligned. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +If @option{-falign-loops} or @option{-falign-jumps} are applicable and +are greater than this value, then their values are used instead. -@item -fgcse-lm -@opindex fgcse-lm -When @option{-fgcse-lm} is enabled, global common subexpression elimination -attempts to move loads that are only killed by stores into themselves. This -allows a loop containing a load/store sequence to be changed to a load outside -the loop, and a copy/store within the loop. +If @var{n} is not specified or is zero, use a machine-dependent default +which is very likely to be @samp{1}, meaning no alignment. -Enabled by default when @option{-fgcse} is enabled. +Enabled at levels @option{-O2}, @option{-O3}. -@item -fgcse-sm -@opindex fgcse-sm -When @option{-fgcse-sm} is enabled, a store motion pass is run after -global common subexpression elimination. This pass attempts to move -stores out of loops. When used in conjunction with @option{-fgcse-lm}, -loops containing a load/store sequence can be changed to a load before -the loop and a store after the loop. +@item -falign-loops +@itemx -falign-loops=@var{n} +@opindex falign-loops +Align loops to a power-of-two boundary, skipping up to @var{n} bytes +like @option{-falign-functions}. If the loops are +executed many times, this makes up for any execution of the dummy +operations. -Not enabled at any optimization level. +@option{-fno-align-loops} and @option{-falign-loops=1} are +equivalent and mean that loops are not aligned. -@item -fgcse-las -@opindex fgcse-las -When @option{-fgcse-las} is enabled, the global common subexpression -elimination pass eliminates redundant loads that come after stores to the -same memory location (both partial and full redundancies). +If @var{n} is not specified or is zero, use a machine-dependent default. -Not enabled at any optimization level. +Enabled at levels @option{-O2}, @option{-O3}. -@item -fgcse-after-reload -@opindex fgcse-after-reload -When @option{-fgcse-after-reload} is enabled, a redundant load elimination -pass is performed after reload. The purpose of this pass is to clean up -redundant spilling. +@item -falign-jumps +@itemx -falign-jumps=@var{n} +@opindex falign-jumps +Align branch targets to a power-of-two boundary, for branch targets +where the targets can only be reached by jumping, skipping up to @var{n} +bytes like @option{-falign-functions}. In this case, no dummy operations +need be executed. -@item -faggressive-loop-optimizations -@opindex faggressive-loop-optimizations -This option tells the loop optimizer to use language constraints to -derive bounds for the number of iterations of a loop. This assumes that -loop code does not invoke undefined behavior by for example causing signed -integer overflows or out-of-bound array accesses. The bounds for the -number of iterations of a loop are used to guide loop unrolling and peeling -and loop exit test optimizations. -This option is enabled by default. +@option{-fno-align-jumps} and @option{-falign-jumps=1} are +equivalent and mean that loops are not aligned. -@item -funsafe-loop-optimizations -@opindex funsafe-loop-optimizations -This option tells the loop optimizer to assume that loop indices do not -overflow, and that loops with nontrivial exit condition are not -infinite. This enables a wider range of loop optimizations even if -the loop optimizer itself cannot prove that these assumptions are valid. -If you use @option{-Wunsafe-loop-optimizations}, the compiler warns you -if it finds this kind of loop. +If @var{n} is not specified or is zero, use a machine-dependent default. -@item -fcrossjumping -@opindex fcrossjumping -Perform cross-jumping transformation. -This transformation unifies equivalent code and saves code size. The -resulting code may or may not perform better than without cross-jumping. +Enabled at levels @option{-O2}, @option{-O3}. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -funit-at-a-time +@opindex funit-at-a-time +This option is left for compatibility reasons. @option{-funit-at-a-time} +has no effect, while @option{-fno-unit-at-a-time} implies +@option{-fno-toplevel-reorder} and @option{-fno-section-anchors}. -@item -fauto-inc-dec -@opindex fauto-inc-dec -Combine increments or decrements of addresses with memory accesses. -This pass is always skipped on architectures that do not have -instructions to support this. Enabled by default at @option{-O} and -higher on architectures that support this. +Enabled by default. -@item -fdce -@opindex fdce -Perform dead code elimination (DCE) on RTL@. -Enabled by default at @option{-O} and higher. +@item -fno-toplevel-reorder +@opindex fno-toplevel-reorder +Do not reorder top-level functions, variables, and @code{asm} +statements. Output them in the same order that they appear in the +input file. When this option is used, unreferenced static variables +are not removed. This option is intended to support existing code +that relies on a particular ordering. For new code, it is better to +use attributes when possible. -@item -fdse -@opindex fdse -Perform dead store elimination (DSE) on RTL@. -Enabled by default at @option{-O} and higher. +Enabled at level @option{-O0}. When disabled explicitly, it also implies +@option{-fno-section-anchors}, which is otherwise enabled at @option{-O0} on some +targets. -@item -fif-conversion -@opindex fif-conversion -Attempt to transform conditional jumps into branch-less equivalents. This -includes use of conditional moves, min, max, set flags and abs instructions, and -some tricks doable by standard arithmetics. The use of conditional execution -on chips where it is available is controlled by @option{-fif-conversion2}. +@item -fweb +@opindex fweb +Constructs webs as commonly used for register allocation purposes and assign +each web individual pseudo register. This allows the register allocation pass +to operate on pseudos directly, but also strengthens several other optimization +passes, such as CSE, loop optimizer and trivial dead code remover. It can, +however, make debugging impossible, since variables no longer stay in a +``home register''. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +Enabled by default with @option{-funroll-loops}. -@item -fif-conversion2 -@opindex fif-conversion2 -Use conditional execution (where available) to transform conditional jumps into -branch-less equivalents. +@item -fwhole-program +@opindex fwhole-program +Assume that the current compilation unit represents the whole program being +compiled. All public functions and variables with the exception of @code{main} +and those merged by attribute @code{externally_visible} become static functions +and in effect are optimized more aggressively by interprocedural optimizers. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +This option should not be used in combination with @option{-flto}. +Instead relying on a linker plugin should provide safer and more precise +information. -@item -fdeclone-ctor-dtor -@opindex fdeclone-ctor-dtor -The C++ ABI requires multiple entry points for constructors and -destructors: one for a base subobject, one for a complete object, and -one for a virtual destructor that calls operator delete afterwards. -For a hierarchy with virtual bases, the base and complete variants are -clones, which means two copies of the function. With this option, the -base and complete variants are changed to be thunks that call a common -implementation. +@item -flto[=@var{n}] +@opindex flto +This option runs the standard link-time optimizer. When invoked +with source code, it generates GIMPLE (one of GCC's internal +representations) and writes it to special ELF sections in the object +file. When the object files are linked together, all the function +bodies are read from these ELF sections and instantiated as if they +had been part of the same translation unit. -Enabled by @option{-Os}. +To use the link-time optimizer, @option{-flto} and optimization +options should be specified at compile time and during the final link. +For example: -@item -fdelete-null-pointer-checks -@opindex fdelete-null-pointer-checks -Assume that programs cannot safely dereference null pointers, and that -no code or data element resides at address zero. -This option enables simple constant -folding optimizations at all optimization levels. In addition, other -optimization passes in GCC use this flag to control global dataflow -analyses that eliminate useless checks for null pointers; these assume -that a memory access to address zero always results in a trap, so -that if a pointer is checked after it has already been dereferenced, -it cannot be null. +@smallexample +gcc -c -O2 -flto foo.c +gcc -c -O2 -flto bar.c +gcc -o myprog -flto -O2 foo.o bar.o +@end smallexample -Note however that in some environments this assumption is not true. -Use @option{-fno-delete-null-pointer-checks} to disable this optimization -for programs that depend on that behavior. +The first two invocations to GCC save a bytecode representation +of GIMPLE into special ELF sections inside @file{foo.o} and +@file{bar.o}. The final invocation reads the GIMPLE bytecode from +@file{foo.o} and @file{bar.o}, merges the two files into a single +internal image, and compiles the result as usual. Since both +@file{foo.o} and @file{bar.o} are merged into a single image, this +causes all the interprocedural analyses and optimizations in GCC to +work across the two files as if they were a single one. This means, +for example, that the inliner is able to inline functions in +@file{bar.o} into functions in @file{foo.o} and vice-versa. -This option is enabled by default on most targets. On Nios II ELF, it -defaults to off. On AVR and CR16, this option is completely disabled. +Another (simpler) way to enable link-time optimization is: -Passes that use the dataflow information -are enabled independently at different optimization levels. +@smallexample +gcc -o myprog -flto -O2 foo.c bar.c +@end smallexample -@item -fdevirtualize -@opindex fdevirtualize -Attempt to convert calls to virtual functions to direct calls. This -is done both within a procedure and interprocedurally as part of -indirect inlining (@option{-findirect-inlining}) and interprocedural constant -propagation (@option{-fipa-cp}). -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +The above generates bytecode for @file{foo.c} and @file{bar.c}, +merges them together into a single GIMPLE representation and optimizes +them as usual to produce @file{myprog}. -@item -fdevirtualize-speculatively -@opindex fdevirtualize-speculatively -Attempt to convert calls to virtual functions to speculative direct calls. -Based on the analysis of the type inheritance graph, determine for a given call -the set of likely targets. If the set is small, preferably of size 1, change -the call into a conditional deciding between direct and indirect calls. The -speculative calls enable more optimizations, such as inlining. When they seem -useless after further optimization, they are converted back into original form. +The only important thing to keep in mind is that to enable link-time +optimizations you need to use the GCC driver to perform the link-step. +GCC then automatically performs link-time optimization if any of the +objects involved were compiled with the @option{-flto} command-line option. +You generally +should specify the optimization options to be used for link-time +optimization though GCC tries to be clever at guessing an +optimization level to use from the options used at compile-time +if you fail to specify one at link-time. You can always override +the automatic decision to do link-time optimization at link-time +by passing @option{-fno-lto} to the link command. -@item -fdevirtualize-at-ltrans -@opindex fdevirtualize-at-ltrans -Stream extra information needed for aggressive devirtualization when running -the link-time optimizer in local transformation mode. -This option enables more devirtualization but -significantly increases the size of streamed data. For this reason it is -disabled by default. +To make whole program optimization effective, it is necessary to make +certain whole program assumptions. The compiler needs to know +what functions and variables can be accessed by libraries and runtime +outside of the link-time optimized unit. When supported by the linker, +the linker plugin (see @option{-fuse-linker-plugin}) passes information +to the compiler about used and externally visible symbols. When +the linker plugin is not available, @option{-fwhole-program} should be +used to allow the compiler to make these assumptions, which leads +to more aggressive optimization decisions. -@item -fexpensive-optimizations -@opindex fexpensive-optimizations -Perform a number of minor optimizations that are relatively expensive. +When @option{-fuse-linker-plugin} is not enabled then, when a file is +compiled with @option{-flto}, the generated object file is larger than +a regular object file because it contains GIMPLE bytecodes and the usual +final code (see @option{-ffat-lto-objects}. This means that +object files with LTO information can be linked as normal object +files; if @option{-fno-lto} is passed to the linker, no +interprocedural optimizations are applied. Note that when +@option{-fno-fat-lto-objects} is enabled the compile-stage is faster +but you cannot perform a regular, non-LTO link on them. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +Additionally, the optimization flags used to compile individual files +are not necessarily related to those used at link time. For instance, -@item -free -@opindex free -Attempt to remove redundant extension instructions. This is especially -helpful for the x86-64 architecture, which implicitly zero-extends in 64-bit -registers after writing to their lower 32-bit half. +@smallexample +gcc -c -O0 -ffat-lto-objects -flto foo.c +gcc -c -O0 -ffat-lto-objects -flto bar.c +gcc -o myprog -O3 foo.o bar.o +@end smallexample -Enabled for Alpha, AArch64 and x86 at levels @option{-O2}, -@option{-O3}, @option{-Os}. +This produces individual object files with unoptimized assembler +code, but the resulting binary @file{myprog} is optimized at +@option{-O3}. If, instead, the final binary is generated with +@option{-fno-lto}, then @file{myprog} is not optimized. -@item -fno-lifetime-dse -@opindex fno-lifetime-dse -In C++ the value of an object is only affected by changes within its -lifetime: when the constructor begins, the object has an indeterminate -value, and any changes during the lifetime of the object are dead when -the object is destroyed. Normally dead store elimination will take -advantage of this; if your code relies on the value of the object -storage persisting beyond the lifetime of the object, you can use this -flag to disable this optimization. +When producing the final binary, GCC only +applies link-time optimizations to those files that contain bytecode. +Therefore, you can mix and match object files and libraries with +GIMPLE bytecodes and final object code. GCC automatically selects +which files to optimize in LTO mode and which files to link without +further processing. -@item -flive-range-shrinkage -@opindex flive-range-shrinkage -Attempt to decrease register pressure through register live range -shrinkage. This is helpful for fast processors with small or moderate -size register sets. +There are some code generation flags preserved by GCC when +generating bytecodes, as they need to be used during the final link +stage. Generally options specified at link-time override those +specified at compile-time. -@item -fira-algorithm=@var{algorithm} -@opindex fira-algorithm -Use the specified coloring algorithm for the integrated register -allocator. The @var{algorithm} argument can be @samp{priority}, which -specifies Chow's priority coloring, or @samp{CB}, which specifies -Chaitin-Briggs coloring. Chaitin-Briggs coloring is not implemented -for all architectures, but for those targets that do support it, it is -the default because it generates better code. +If you do not specify an optimization level option @option{-O} at +link-time then GCC computes one based on the optimization levels +used when compiling the object files. The highest optimization +level wins here. -@item -fira-region=@var{region} -@opindex fira-region -Use specified regions for the integrated register allocator. The -@var{region} argument should be one of the following: +Currently, the following options and their setting are take from +the first object file that explicitely specified it: +@option{-fPIC}, @option{-fpic}, @option{-fpie}, @option{-fcommon}, +@option{-fexceptions}, @option{-fnon-call-exceptions}, @option{-fgnu-tm} +and all the @option{-m} target flags. -@table @samp +Certain ABI changing flags are required to match in all compilation-units +and trying to override this at link-time with a conflicting value +is ignored. This includes options such as @option{-freg-struct-return} +and @option{-fpcc-struct-return}. -@item all -Use all loops as register allocation regions. -This can give the best results for machines with a small and/or -irregular register set. +Other options such as @option{-ffp-contract}, @option{-fno-strict-overflow}, +@option{-fwrapv}, @option{-fno-trapv} or @option{-fno-strict-aliasing} +are passed through to the link stage and merged conservatively for +conflicting translation units. Specifically +@option{-fno-strict-overflow}, @option{-fwrapv} and @option{-fno-trapv} take +precedence and for example @option{-ffp-contract=off} takes precedence +over @option{-ffp-contract=fast}. You can override them at linke-time. -@item mixed -Use all loops except for loops with small register pressure -as the regions. This value usually gives -the best results in most cases and for most architectures, -and is enabled by default when compiling with optimization for speed -(@option{-O}, @option{-O2}, @dots{}). +It is recommended that you compile all the files participating in the +same link with the same options and also specify those options at +link time. -@item one -Use all functions as a single region. -This typically results in the smallest code size, and is enabled by default for -@option{-Os} or @option{-O0}. +If LTO encounters objects with C linkage declared with incompatible +types in separate translation units to be linked together (undefined +behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be +issued. The behavior is still undefined at run time. Similar +diagnostics may be raised for other languages. -@end table +Another feature of LTO is that it is possible to apply interprocedural +optimizations on files written in different languages: -@item -fira-hoist-pressure -@opindex fira-hoist-pressure -Use IRA to evaluate register pressure in the code hoisting pass for -decisions to hoist expressions. This option usually results in smaller -code, but it can slow the compiler down. +@smallexample +gcc -c -flto foo.c +g++ -c -flto bar.cc +gfortran -c -flto baz.f90 +g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran +@end smallexample -This option is enabled at level @option{-Os} for all targets. +Notice that the final link is done with @command{g++} to get the C++ +runtime libraries and @option{-lgfortran} is added to get the Fortran +runtime libraries. In general, when mixing languages in LTO mode, you +should use the same link command options as when mixing languages in a +regular (non-LTO) compilation. -@item -fira-loop-pressure -@opindex fira-loop-pressure -Use IRA to evaluate register pressure in loops for decisions to move -loop invariants. This option usually results in generation -of faster and smaller code on machines with large register files (>= 32 -registers), but it can slow the compiler down. +If object files containing GIMPLE bytecode are stored in a library archive, say +@file{libfoo.a}, it is possible to extract and use them in an LTO link if you +are using a linker with plugin support. To create static libraries suitable +for LTO, use @command{gcc-ar} and @command{gcc-ranlib} instead of @command{ar} +and @command{ranlib}; +to show the symbols of object files with GIMPLE bytecode, use +@command{gcc-nm}. Those commands require that @command{ar}, @command{ranlib} +and @command{nm} have been compiled with plugin support. At link time, use the the +flag @option{-fuse-linker-plugin} to ensure that the library participates in +the LTO optimization process: -This option is enabled at level @option{-O3} for some targets. +@smallexample +gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo +@end smallexample -@item -fno-ira-share-save-slots -@opindex fno-ira-share-save-slots -Disable sharing of stack slots used for saving call-used hard -registers living through a call. Each hard register gets a -separate stack slot, and as a result function stack frames are -larger. +With the linker plugin enabled, the linker extracts the needed +GIMPLE files from @file{libfoo.a} and passes them on to the running GCC +to make them part of the aggregated GIMPLE image to be optimized. -@item -fno-ira-share-spill-slots -@opindex fno-ira-share-spill-slots -Disable sharing of stack slots allocated for pseudo-registers. Each -pseudo-register that does not get a hard register gets a separate -stack slot, and as a result function stack frames are larger. +If you are not using a linker with plugin support and/or do not +enable the linker plugin, then the objects inside @file{libfoo.a} +are extracted and linked as usual, but they do not participate +in the LTO optimization process. In order to make a static library suitable +for both LTO optimization and usual linkage, compile its object files with +@option{-flto} @option{-ffat-lto-objects}. -@item -fira-verbose=@var{n} -@opindex fira-verbose -Control the verbosity of the dump file for the integrated register allocator. -The default value is 5. If the value @var{n} is greater or equal to 10, -the dump output is sent to stderr using the same format as @var{n} minus 10. +Link-time optimizations do not require the presence of the whole program to +operate. If the program does not require any symbols to be exported, it is +possible to combine @option{-flto} and @option{-fwhole-program} to allow +the interprocedural optimizers to use more aggressive assumptions which may +lead to improved optimization opportunities. +Use of @option{-fwhole-program} is not needed when linker plugin is +active (see @option{-fuse-linker-plugin}). -@item -flra-remat -@opindex flra-remat -Enable CFG-sensitive rematerialization in LRA. Instead of loading -values of spilled pseudos, LRA tries to rematerialize (recalculate) -values if it is profitable. +The current implementation of LTO makes no +attempt to generate bytecode that is portable between different +types of hosts. The bytecode files are versioned and there is a +strict version check, so bytecode files generated in one version of +GCC do not work with an older or newer version of GCC. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +Link-time optimization does not work well with generation of debugging +information. Combining @option{-flto} with +@option{-g} is currently experimental and expected to produce unexpected +results. -@item -fdelayed-branch -@opindex fdelayed-branch -If supported for the target machine, attempt to reorder instructions -to exploit instruction slots available after delayed branch -instructions. +If you specify the optional @var{n}, the optimization and code +generation done at link time is executed in parallel using @var{n} +parallel jobs by utilizing an installed @command{make} program. The +environment variable @env{MAKE} may be used to override the program +used. The default value for @var{n} is 1. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +You can also specify @option{-flto=jobserver} to use GNU make's +job server mode to determine the number of parallel jobs. This +is useful when the Makefile calling GCC is already executing in parallel. +You must prepend a @samp{+} to the command recipe in the parent Makefile +for this to work. This option likely only works if @env{MAKE} is +GNU make. -@item -fschedule-insns -@opindex fschedule-insns -If supported for the target machine, attempt to reorder instructions to -eliminate execution stalls due to required data being unavailable. This -helps machines that have slow floating point or memory load instructions -by allowing other instructions to be issued until the result of the load -or floating-point instruction is required. +@item -flto-partition=@var{alg} +@opindex flto-partition +Specify the partitioning algorithm used by the link-time optimizer. +The value is either @samp{1to1} to specify a partitioning mirroring +the original source files or @samp{balanced} to specify partitioning +into equally sized chunks (whenever possible) or @samp{max} to create +new partition for every symbol where possible. Specifying @samp{none} +as an algorithm disables partitioning and streaming completely. +The default value is @samp{balanced}. While @samp{1to1} can be used +as an workaround for various code ordering issues, the @samp{max} +partitioning is intended for internal testing only. +The value @samp{one} specifies that exactly one partition should be +used while the value @samp{none} bypasses partitioning and executes +the link-time optimization step directly from the WPA phase. -Enabled at levels @option{-O2}, @option{-O3}. +@item -flto-odr-type-merging +@opindex flto-odr-type-merging +Enable streaming of mangled types names of C++ types and their unification +at linktime. This increases size of LTO object files, but enable +diagnostics about One Definition Rule violations. -@item -fschedule-insns2 -@opindex fschedule-insns2 -Similar to @option{-fschedule-insns}, but requests an additional pass of -instruction scheduling after register allocation has been done. This is -especially useful on machines with a relatively small number of -registers and where memory load instructions take more than one cycle. +@item -flto-compression-level=@var{n} +@opindex flto-compression-level +This option specifies the level of compression used for intermediate +language written to LTO object files, and is only meaningful in +conjunction with LTO mode (@option{-flto}). Valid +values are 0 (no compression) to 9 (maximum compression). Values +outside this range are clamped to either 0 or 9. If the option is not +given, a default balanced compression setting is used. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -fuse-linker-plugin +@opindex fuse-linker-plugin +Enables the use of a linker plugin during link-time optimization. This +option relies on plugin support in the linker, which is available in gold +or in GNU ld 2.21 or newer. -@item -fno-sched-interblock -@opindex fno-sched-interblock -Don't schedule instructions across basic blocks. This is normally -enabled by default when scheduling before register allocation, i.e.@: -with @option{-fschedule-insns} or at @option{-O2} or higher. +This option enables the extraction of object files with GIMPLE bytecode out +of library archives. This improves the quality of optimization by exposing +more code to the link-time optimizer. This information specifies what +symbols can be accessed externally (by non-LTO object or during dynamic +linking). Resulting code quality improvements on binaries (and shared +libraries that use hidden visibility) are similar to @option{-fwhole-program}. +See @option{-flto} for a description of the effect of this flag and how to +use it. -@item -fno-sched-spec -@opindex fno-sched-spec -Don't allow speculative motion of non-load instructions. This is normally -enabled by default when scheduling before register allocation, i.e.@: -with @option{-fschedule-insns} or at @option{-O2} or higher. +This option is enabled by default when LTO support in GCC is enabled +and GCC was configured for use with +a linker supporting plugins (GNU ld 2.21 or newer or gold). -@item -fsched-pressure -@opindex fsched-pressure -Enable register pressure sensitive insn scheduling before register -allocation. This only makes sense when scheduling before register -allocation is enabled, i.e.@: with @option{-fschedule-insns} or at -@option{-O2} or higher. Usage of this option can improve the -generated code and decrease its size by preventing register pressure -increase above the number of available hard registers and subsequent -spills in register allocation. +@item -ffat-lto-objects +@opindex ffat-lto-objects +Fat LTO objects are object files that contain both the intermediate language +and the object code. This makes them usable for both LTO linking and normal +linking. This option is effective only when compiling with @option{-flto} +and is ignored at link time. -@item -fsched-spec-load -@opindex fsched-spec-load -Allow speculative motion of some load instructions. This only makes -sense when scheduling before register allocation, i.e.@: with -@option{-fschedule-insns} or at @option{-O2} or higher. +@option{-fno-fat-lto-objects} improves compilation time over plain LTO, but +requires the complete toolchain to be aware of LTO. It requires a linker with +linker plugin support for basic functionality. Additionally, +@command{nm}, @command{ar} and @command{ranlib} +need to support linker plugins to allow a full-featured build environment +(capable of building static libraries etc). GCC provides the @command{gcc-ar}, +@command{gcc-nm}, @command{gcc-ranlib} wrappers to pass the right options +to these tools. With non fat LTO makefiles need to be modified to use them. -@item -fsched-spec-load-dangerous -@opindex fsched-spec-load-dangerous -Allow speculative motion of more load instructions. This only makes -sense when scheduling before register allocation, i.e.@: with -@option{-fschedule-insns} or at @option{-O2} or higher. +The default is @option{-fno-fat-lto-objects} on targets with linker plugin +support. -@item -fsched-stalled-insns -@itemx -fsched-stalled-insns=@var{n} -@opindex fsched-stalled-insns -Define how many insns (if any) can be moved prematurely from the queue -of stalled insns into the ready list during the second scheduling pass. -@option{-fno-sched-stalled-insns} means that no insns are moved -prematurely, @option{-fsched-stalled-insns=0} means there is no limit -on how many queued insns can be moved prematurely. -@option{-fsched-stalled-insns} without a value is equivalent to -@option{-fsched-stalled-insns=1}. +@item -fcompare-elim +@opindex fcompare-elim +After register allocation and post-register allocation instruction splitting, +identify arithmetic instructions that compute processor flags similar to a +comparison operation based on that arithmetic. If possible, eliminate the +explicit comparison operation. -@item -fsched-stalled-insns-dep -@itemx -fsched-stalled-insns-dep=@var{n} -@opindex fsched-stalled-insns-dep -Define how many insn groups (cycles) are examined for a dependency -on a stalled insn that is a candidate for premature removal from the queue -of stalled insns. This has an effect only during the second scheduling pass, -and only if @option{-fsched-stalled-insns} is used. -@option{-fno-sched-stalled-insns-dep} is equivalent to -@option{-fsched-stalled-insns-dep=0}. -@option{-fsched-stalled-insns-dep} without a value is equivalent to -@option{-fsched-stalled-insns-dep=1}. +This pass only applies to certain targets that cannot explicitly represent +the comparison operation before register allocation is complete. -@item -fsched2-use-superblocks -@opindex fsched2-use-superblocks -When scheduling after register allocation, use superblock scheduling. -This allows motion across basic block boundaries, -resulting in faster schedules. This option is experimental, as not all machine -descriptions used by GCC model the CPU closely enough to avoid unreliable -results from the algorithm. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -This only makes sense when scheduling after register allocation, i.e.@: with -@option{-fschedule-insns2} or at @option{-O2} or higher. +@item -fcprop-registers +@opindex fcprop-registers +After register allocation and post-register allocation instruction splitting, +perform a copy-propagation pass to try to reduce scheduling dependencies +and occasionally eliminate the copy. -@item -fsched-group-heuristic -@opindex fsched-group-heuristic -Enable the group heuristic in the scheduler. This heuristic favors -the instruction that belongs to a schedule group. This is enabled -by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns} -or @option{-fschedule-insns2} or at @option{-O2} or higher. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. -@item -fsched-critical-path-heuristic -@opindex fsched-critical-path-heuristic -Enable the critical-path heuristic in the scheduler. This heuristic favors -instructions on the critical path. This is enabled by default when -scheduling is enabled, i.e.@: with @option{-fschedule-insns} -or @option{-fschedule-insns2} or at @option{-O2} or higher. +@item -fprofile-correction +@opindex fprofile-correction +Profiles collected using an instrumented binary for multi-threaded programs may +be inconsistent due to missed counter updates. When this option is specified, +GCC uses heuristics to correct or smooth out such inconsistencies. By +default, GCC emits an error message when an inconsistent profile is detected. -@item -fsched-spec-insn-heuristic -@opindex fsched-spec-insn-heuristic -Enable the speculative instruction heuristic in the scheduler. This -heuristic favors speculative instructions with greater dependency weakness. -This is enabled by default when scheduling is enabled, i.e.@: -with @option{-fschedule-insns} or @option{-fschedule-insns2} -or at @option{-O2} or higher. - -@item -fsched-rank-heuristic -@opindex fsched-rank-heuristic -Enable the rank heuristic in the scheduler. This heuristic favors -the instruction belonging to a basic block with greater size or frequency. -This is enabled by default when scheduling is enabled, i.e.@: -with @option{-fschedule-insns} or @option{-fschedule-insns2} or -at @option{-O2} or higher. +@item -fprofile-use +@itemx -fprofile-use=@var{path} +@opindex fprofile-use +Enable profile feedback-directed optimizations, +and the following optimizations +which are generally profitable only with profile feedback available: +@option{-fbranch-probabilities}, @option{-fvpt}, +@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, +@option{-ftree-vectorize}, and @option{ftree-loop-distribute-patterns}. -@item -fsched-last-insn-heuristic -@opindex fsched-last-insn-heuristic -Enable the last-instruction heuristic in the scheduler. This heuristic -favors the instruction that is less dependent on the last instruction -scheduled. This is enabled by default when scheduling is enabled, -i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or -at @option{-O2} or higher. +Before you can use this option, you must first generate profiling information. +@xref{Optimize Options}, for information about the @option{-fprofile-generate} +option. -@item -fsched-dep-count-heuristic -@opindex fsched-dep-count-heuristic -Enable the dependent-count heuristic in the scheduler. This heuristic -favors the instruction that has more instructions depending on it. -This is enabled by default when scheduling is enabled, i.e.@: -with @option{-fschedule-insns} or @option{-fschedule-insns2} or -at @option{-O2} or higher. +By default, GCC emits an error message if the feedback profiles do not +match the source code. This error can be turned into a warning by using +@option{-Wcoverage-mismatch}. Note this may result in poorly optimized +code. -@item -freschedule-modulo-scheduled-loops -@opindex freschedule-modulo-scheduled-loops -Modulo scheduling is performed before traditional scheduling. If a loop -is modulo scheduled, later scheduling passes may change its schedule. -Use this option to control that behavior. +If @var{path} is specified, GCC looks at the @var{path} to find +the profile feedback data files. See @option{-fprofile-dir}. -@item -fselective-scheduling -@opindex fselective-scheduling -Schedule instructions using selective scheduling algorithm. Selective -scheduling runs instead of the first scheduler pass. +@item -fauto-profile +@itemx -fauto-profile=@var{path} +@opindex fauto-profile +Enable sampling-based feedback-directed optimizations, +and the following optimizations +which are generally profitable only with profile feedback available: +@option{-fbranch-probabilities}, @option{-fvpt}, +@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, +@option{-ftree-vectorize}, +@option{-finline-functions}, @option{-fipa-cp}, @option{-fipa-cp-clone}, +@option{-fpredictive-commoning}, @option{-funswitch-loops}, +@option{-fgcse-after-reload}, and @option{-ftree-loop-distribute-patterns}. -@item -fselective-scheduling2 -@opindex fselective-scheduling2 -Schedule instructions using selective scheduling algorithm. Selective -scheduling runs instead of the second scheduler pass. +@var{path} is the name of a file containing AutoFDO profile information. +If omitted, it defaults to @file{fbdata.afdo} in the current directory. -@item -fsel-sched-pipelining -@opindex fsel-sched-pipelining -Enable software pipelining of innermost loops during selective scheduling. -This option has no effect unless one of @option{-fselective-scheduling} or -@option{-fselective-scheduling2} is turned on. +Producing an AutoFDO profile data file requires running your program +with the @command{perf} utility on a supported GNU/Linux target system. +For more information, see @uref{https://perf.wiki.kernel.org/}. -@item -fsel-sched-pipelining-outer-loops -@opindex fsel-sched-pipelining-outer-loops -When pipelining loops during selective scheduling, also pipeline outer loops. -This option has no effect unless @option{-fsel-sched-pipelining} is turned on. +E.g. +@smallexample +perf record -e br_inst_retired:near_taken -b -o perf.data \ + -- your_program +@end smallexample -@item -fsemantic-interposition -@opindex fsemantic-interposition -Some object formats, like ELF, allow interposing of symbols by the -dynamic linker. -This means that for symbols exported from the DSO, the compiler cannot perform -interprocedural propagation, inlining and other optimizations in anticipation -that the function or variable in question may change. While this feature is -useful, for example, to rewrite memory allocation functions by a debugging -implementation, it is expensive in the terms of code quality. -With @option{-fno-semantic-interposition} the compiler assumes that -if interposition happens for functions the overwriting function will have -precisely the same semantics (and side effects). -Similarly if interposition happens -for variables, the constructor of the variable will be the same. The flag -has no effect for functions explicitly declared inline -(where it is never allowed for interposition to change semantics) -and for symbols explicitly declared weak. +Then use the @command{create_gcov} tool to convert the raw profile data +to a format that can be used by GCC.@ You must also supply the +unstripped binary for your program to this tool. +See @uref{https://github.com/google/autofdo}. -@item -fshrink-wrap -@opindex fshrink-wrap -Emit function prologues only before parts of the function that need it, -rather than at the top of the function. This flag is enabled by default at -@option{-O} and higher. +E.g. +@smallexample +create_gcov --binary=your_program.unstripped --profile=perf.data \ + --gcov=profile.afdo +@end smallexample +@end table -@item -fcaller-saves -@opindex fcaller-saves -Enable allocation of values to registers that are clobbered by -function calls, by emitting extra instructions to save and restore the -registers around such calls. Such allocation is done only when it -seems to result in better code. +The following options control compiler behavior regarding floating-point +arithmetic. These options trade off between speed and +correctness. All must be specifically enabled. -This option is always enabled by default on certain machines, usually -those which have no call-preserved registers to use instead. +@table @gcctabopt +@item -ffloat-store +@opindex ffloat-store +Do not store floating-point variables in registers, and inhibit other +options that might change whether a floating-point value is taken from a +register or memory. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@cindex floating-point precision +This option prevents undesirable excess precision on machines such as +the 68000 where the floating registers (of the 68881) keep more +precision than a @code{double} is supposed to have. Similarly for the +x86 architecture. For most programs, the excess precision does only +good, but a few programs rely on the precise definition of IEEE floating +point. Use @option{-ffloat-store} for such programs, after modifying +them to store all pertinent intermediate computations into variables. -@item -fcombine-stack-adjustments -@opindex fcombine-stack-adjustments -Tracks stack adjustments (pushes and pops) and stack memory references -and then tries to find ways to combine them. +@item -fexcess-precision=@var{style} +@opindex fexcess-precision +This option allows further control over excess precision on machines +where floating-point registers have more precision than the IEEE +@code{float} and @code{double} types and the processor does not +support operations rounding to those types. By default, +@option{-fexcess-precision=fast} is in effect; this means that +operations are carried out in the precision of the registers and that +it is unpredictable when rounding to the types specified in the source +code takes place. When compiling C, if +@option{-fexcess-precision=standard} is specified then excess +precision follows the rules specified in ISO C99; in particular, +both casts and assignments cause values to be rounded to their +semantic types (whereas @option{-ffloat-store} only affects +assignments). This option is enabled by default for C if a strict +conformance option such as @option{-std=c99} is used. -Enabled by default at @option{-O1} and higher. +@opindex mfpmath +@option{-fexcess-precision=standard} is not implemented for languages +other than C, and has no effect if +@option{-funsafe-math-optimizations} or @option{-ffast-math} is +specified. On the x86, it also has no effect if @option{-mfpmath=sse} +or @option{-mfpmath=sse+387} is specified; in the former case, IEEE +semantics apply without excess precision, and in the latter, rounding +is unpredictable. -@item -fipa-ra -@opindex fipa-ra -Use caller save registers for allocation if those registers are not used by -any called function. In that case it is not necessary to save and restore -them around calls. This is only possible if called functions are part of -same compilation unit as current function and they are compiled before it. +@item -ffast-math +@opindex ffast-math +Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, +@option{-ffinite-math-only}, @option{-fno-rounding-math}, +@option{-fno-signaling-nans} and @option{-fcx-limited-range}. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. -@item -fconserve-stack -@opindex fconserve-stack -Attempt to minimize stack usage. The compiler attempts to use less -stack space, even if that makes the program slower. This option -implies setting the @option{large-stack-frame} parameter to 100 -and the @option{large-stack-frame-growth} parameter to 400. +This option is not turned on by any @option{-O} option besides +@option{-Ofast} since it can result in incorrect output for programs +that depend on an exact implementation of IEEE or ISO rules/specifications +for math functions. It may, however, yield faster code for programs +that do not require the guarantees of these specifications. -@item -ftree-reassoc -@opindex ftree-reassoc -Perform reassociation on trees. This flag is enabled by default -at @option{-O} and higher. +@item -fno-math-errno +@opindex fno-math-errno +Do not set @code{errno} after calling math functions that are executed +with a single instruction, e.g., @code{sqrt}. A program that relies on +IEEE exceptions for math error handling may want to use this flag +for speed while maintaining IEEE arithmetic compatibility. -@item -ftree-pre -@opindex ftree-pre -Perform partial redundancy elimination (PRE) on trees. This flag is -enabled by default at @option{-O2} and @option{-O3}. +This option is not turned on by any @option{-O} option since +it can result in incorrect output for programs that depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. It may, however, yield faster code for programs +that do not require the guarantees of these specifications. -@item -ftree-partial-pre -@opindex ftree-partial-pre -Make partial redundancy elimination (PRE) more aggressive. This flag is -enabled by default at @option{-O3}. +The default is @option{-fmath-errno}. -@item -ftree-forwprop -@opindex ftree-forwprop -Perform forward propagation on trees. This flag is enabled by default -at @option{-O} and higher. +On Darwin systems, the math library never sets @code{errno}. There is +therefore no reason for the compiler to consider the possibility that +it might, and @option{-fno-math-errno} is the default. -@item -ftree-fre -@opindex ftree-fre -Perform full redundancy elimination (FRE) on trees. The difference -between FRE and PRE is that FRE only considers expressions -that are computed on all paths leading to the redundant computation. -This analysis is faster than PRE, though it exposes fewer redundancies. -This flag is enabled by default at @option{-O} and higher. +@item -funsafe-math-optimizations +@opindex funsafe-math-optimizations -@item -ftree-phiprop -@opindex ftree-phiprop -Perform hoisting of loads from conditional pointers on trees. This -pass is enabled by default at @option{-O} and higher. +Allow optimizations for floating-point arithmetic that (a) assume +that arguments and results are valid and (b) may violate IEEE or +ANSI standards. When used at link-time, it may include libraries +or startup files that change the default FPU control word or other +similar optimizations. -@item -fhoist-adjacent-loads -@opindex fhoist-adjacent-loads -Speculatively hoist loads from both branches of an if-then-else if the -loads are from adjacent locations in the same structure and the target -architecture has a conditional move instruction. This flag is enabled -by default at @option{-O2} and higher. +This option is not turned on by any @option{-O} option since +it can result in incorrect output for programs that depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. It may, however, yield faster code for programs +that do not require the guarantees of these specifications. +Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math}, +@option{-fassociative-math} and @option{-freciprocal-math}. -@item -ftree-copy-prop -@opindex ftree-copy-prop -Perform copy propagation on trees. This pass eliminates unnecessary -copy operations. This flag is enabled by default at @option{-O} and -higher. +The default is @option{-fno-unsafe-math-optimizations}. -@item -fipa-pure-const -@opindex fipa-pure-const -Discover which functions are pure or constant. -Enabled by default at @option{-O} and higher. +@item -fassociative-math +@opindex fassociative-math -@item -fipa-reference -@opindex fipa-reference -Discover which static variables do not escape the -compilation unit. -Enabled by default at @option{-O} and higher. +Allow re-association of operands in series of floating-point operations. +This violates the ISO C and C++ language standard by possibly changing +computation result. NOTE: re-ordering may change the sign of zero as +well as ignore NaNs and inhibit or create underflow or overflow (and +thus cannot be used on code that relies on rounding behavior like +@code{(x + 2**52) - 2**52}. May also reorder floating-point comparisons +and thus may not be used when ordered comparisons are required. +This option requires that both @option{-fno-signed-zeros} and +@option{-fno-trapping-math} be in effect. Moreover, it doesn't make +much sense with @option{-frounding-math}. For Fortran the option +is automatically enabled when both @option{-fno-signed-zeros} and +@option{-fno-trapping-math} are in effect. -@item -fipa-pta -@opindex fipa-pta -Perform interprocedural pointer analysis and interprocedural modification -and reference analysis. This option can cause excessive memory and -compile-time usage on large compilation units. It is not enabled by -default at any optimization level. +The default is @option{-fno-associative-math}. -@item -fipa-profile -@opindex fipa-profile -Perform interprocedural profile propagation. The functions called only from -cold functions are marked as cold. Also functions executed once (such as -@code{cold}, @code{noreturn}, static constructors or destructors) are identified. Cold -functions and loop less parts of functions executed once are then optimized for -size. -Enabled by default at @option{-O} and higher. +@item -freciprocal-math +@opindex freciprocal-math -@item -fipa-cp -@opindex fipa-cp -Perform interprocedural constant propagation. -This optimization analyzes the program to determine when values passed -to functions are constants and then optimizes accordingly. -This optimization can substantially increase performance -if the application has constants passed to functions. -This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}. +Allow the reciprocal of a value to be used instead of dividing by +the value if this enables optimizations. For example @code{x / y} +can be replaced with @code{x * (1/y)}, which is useful if @code{(1/y)} +is subject to common subexpression elimination. Note that this loses +precision and increases the number of flops operating on the value. -@item -fipa-cp-clone -@opindex fipa-cp-clone -Perform function cloning to make interprocedural constant propagation stronger. -When enabled, interprocedural constant propagation performs function cloning -when externally visible function can be called with constant arguments. -Because this optimization can create multiple copies of functions, -it may significantly increase code size -(see @option{--param ipcp-unit-growth=@var{value}}). -This flag is enabled by default at @option{-O3}. +The default is @option{-fno-reciprocal-math}. -@item -fipa-cp-alignment -@opindex -fipa-cp-alignment -When enabled, this optimization propagates alignment of function -parameters to support better vectorization and string operations. +@item -ffinite-math-only +@opindex ffinite-math-only +Allow optimizations for floating-point arithmetic that assume +that arguments and results are not NaNs or +-Infs. -This flag is enabled by default at @option{-O2} and @option{-Os}. It -requires that @option{-fipa-cp} is enabled. +This option is not turned on by any @option{-O} option since +it can result in incorrect output for programs that depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. It may, however, yield faster code for programs +that do not require the guarantees of these specifications. -@item -fipa-icf -@opindex fipa-icf -Perform Identical Code Folding for functions and read-only variables. -The optimization reduces code size and may disturb unwind stacks by replacing -a function by equivalent one with a different name. The optimization works -more effectively with link time optimization enabled. +The default is @option{-fno-finite-math-only}. -Nevertheless the behavior is similar to Gold Linker ICF optimization, GCC ICF -works on different levels and thus the optimizations are not same - there are -equivalences that are found only by GCC and equivalences found only by Gold. +@item -fno-signed-zeros +@opindex fno-signed-zeros +Allow optimizations for floating-point arithmetic that ignore the +signedness of zero. IEEE arithmetic specifies the behavior of +distinct +0.0 and @minus{}0.0 values, which then prohibits simplification +of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}). +This option implies that the sign of a zero result isn't significant. -This flag is enabled by default at @option{-O2} and @option{-Os}. +The default is @option{-fsigned-zeros}. -@item -fisolate-erroneous-paths-dereference -@opindex fisolate-erroneous-paths-dereference -Detect paths that trigger erroneous or undefined behavior due to -dereferencing a null pointer. Isolate those paths from the main control -flow and turn the statement with erroneous or undefined behavior into a trap. -This flag is enabled by default at @option{-O2} and higher and depends on -@option{-fdelete-null-pointer-checks} also being enabled. +@item -fno-trapping-math +@opindex fno-trapping-math +Compile code assuming that floating-point operations cannot generate +user-visible traps. These traps include division by zero, overflow, +underflow, inexact result and invalid operation. This option requires +that @option{-fno-signaling-nans} be in effect. Setting this option may +allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example. -@item -fisolate-erroneous-paths-attribute -@opindex fisolate-erroneous-paths-attribute -Detect paths that trigger erroneous or undefined behavior due a null value -being used in a way forbidden by a @code{returns_nonnull} or @code{nonnull} -attribute. Isolate those paths from the main control flow and turn the -statement with erroneous or undefined behavior into a trap. This is not -currently enabled, but may be enabled by @option{-O2} in the future. +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs that depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. -@item -ftree-sink -@opindex ftree-sink -Perform forward store motion on trees. This flag is -enabled by default at @option{-O} and higher. +The default is @option{-ftrapping-math}. -@item -ftree-bit-ccp -@opindex ftree-bit-ccp -Perform sparse conditional bit constant propagation on trees and propagate -pointer alignment information. -This pass only operates on local scalar variables and is enabled by default -at @option{-O} and higher. It requires that @option{-ftree-ccp} is enabled. +@item -frounding-math +@opindex frounding-math +Disable transformations and optimizations that assume default floating-point +rounding behavior. This is round-to-zero for all floating point +to integer conversions, and round-to-nearest for all other arithmetic +truncations. This option should be specified for programs that change +the FP rounding mode dynamically, or that may be executed with a +non-default rounding mode. This option disables constant folding of +floating-point expressions at compile time (which may be affected by +rounding mode) and arithmetic transformations that are unsafe in the +presence of sign-dependent rounding modes. -@item -ftree-ccp -@opindex ftree-ccp -Perform sparse conditional constant propagation (CCP) on trees. This -pass only operates on local scalar variables and is enabled by default -at @option{-O} and higher. +The default is @option{-fno-rounding-math}. -@item -fssa-backprop -@opindex fssa-backprop -Propagate information about uses of a value up the definition chain -in order to simplify the definitions. For example, this pass strips -sign operations if the sign of a value never matters. The flag is -enabled by default at @option{-O} and higher. +This option is experimental and does not currently guarantee to +disable all GCC optimizations that are affected by rounding mode. +Future versions of GCC may provide finer control of this setting +using C99's @code{FENV_ACCESS} pragma. This command-line option +will be used to specify the default state for @code{FENV_ACCESS}. -@item -fssa-phiopt -@opindex fssa-phiopt -Perform pattern matching on SSA PHI nodes to optimize conditional -code. This pass is enabled by default at @option{-O} and higher. +@item -fsignaling-nans +@opindex fsignaling-nans +Compile code assuming that IEEE signaling NaNs may generate user-visible +traps during floating-point operations. Setting this option disables +optimizations that may change the number of exceptions visible with +signaling NaNs. This option implies @option{-ftrapping-math}. -@item -ftree-switch-conversion -@opindex ftree-switch-conversion -Perform conversion of simple initializations in a switch to -initializations from a scalar array. This flag is enabled by default -at @option{-O2} and higher. +This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to +be defined. -@item -ftree-tail-merge -@opindex ftree-tail-merge -Look for identical code sequences. When found, replace one with a jump to the -other. This optimization is known as tail merging or cross jumping. This flag -is enabled by default at @option{-O2} and higher. The compilation time -in this pass can -be limited using @option{max-tail-merge-comparisons} parameter and -@option{max-tail-merge-iterations} parameter. +The default is @option{-fno-signaling-nans}. -@item -ftree-dce -@opindex ftree-dce -Perform dead code elimination (DCE) on trees. This flag is enabled by -default at @option{-O} and higher. +This option is experimental and does not currently guarantee to +disable all GCC optimizations that affect signaling NaN behavior. -@item -ftree-builtin-call-dce -@opindex ftree-builtin-call-dce -Perform conditional dead code elimination (DCE) for calls to built-in functions -that may set @code{errno} but are otherwise side-effect free. This flag is -enabled by default at @option{-O2} and higher if @option{-Os} is not also -specified. +@item -fsingle-precision-constant +@opindex fsingle-precision-constant +Treat floating-point constants as single precision instead of +implicitly converting them to double-precision constants. -@item -ftree-dominator-opts -@opindex ftree-dominator-opts -Perform a variety of simple scalar cleanups (constant/copy -propagation, redundancy elimination, range propagation and expression -simplification) based on a dominator tree traversal. This also -performs jump threading (to reduce jumps to jumps). This flag is -enabled by default at @option{-O} and higher. +@item -fcx-limited-range +@opindex fcx-limited-range +When enabled, this option states that a range reduction step is not +needed when performing complex division. Also, there is no checking +whether the result of a complex multiplication or division is @code{NaN ++ I*NaN}, with an attempt to rescue the situation in that case. The +default is @option{-fno-cx-limited-range}, but is enabled by +@option{-ffast-math}. -@item -ftree-dse -@opindex ftree-dse -Perform dead store elimination (DSE) on trees. A dead store is a store into -a memory location that is later overwritten by another store without -any intervening loads. In this case the earlier store can be deleted. This -flag is enabled by default at @option{-O} and higher. +This option controls the default setting of the ISO C99 +@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to +all languages. -@item -ftree-ch -@opindex ftree-ch -Perform loop header copying on trees. This is beneficial since it increases -effectiveness of code motion optimizations. It also saves one jump. This flag -is enabled by default at @option{-O} and higher. It is not enabled -for @option{-Os}, since it usually increases code size. +@item -fcx-fortran-rules +@opindex fcx-fortran-rules +Complex multiplication and division follow Fortran rules. Range +reduction is done as part of complex division, but there is no checking +whether the result of a complex multiplication or division is @code{NaN ++ I*NaN}, with an attempt to rescue the situation in that case. -@item -ftree-loop-optimize -@opindex ftree-loop-optimize -Perform loop optimizations on trees. This flag is enabled by default -at @option{-O} and higher. - -@item -ftree-loop-linear -@itemx -floop-interchange -@itemx -floop-strip-mine -@itemx -floop-block -@itemx -floop-unroll-and-jam -@opindex ftree-loop-linear -@opindex floop-interchange -@opindex floop-strip-mine -@opindex floop-block -@opindex floop-unroll-and-jam -Perform loop nest optimizations. Same as -@option{-floop-nest-optimize}. To use this code transformation, GCC has -to be configured with @option{--with-isl} to enable the Graphite loop -transformation infrastructure. +The default is @option{-fno-cx-fortran-rules}. -@item -fgraphite-identity -@opindex fgraphite-identity -Enable the identity transformation for graphite. For every SCoP we generate -the polyhedral representation and transform it back to gimple. Using -@option{-fgraphite-identity} we can check the costs or benefits of the -GIMPLE -> GRAPHITE -> GIMPLE transformation. Some minimal optimizations -are also performed by the code generator isl, like index splitting and -dead code elimination in loops. +@end table -@item -floop-nest-optimize -@opindex floop-nest-optimize -Enable the isl based loop nest optimizer. This is a generic loop nest -optimizer based on the Pluto optimization algorithms. It calculates a loop -structure optimized for data-locality and parallelism. This option -is experimental. +The following options control optimizations that may improve +performance, but are not enabled by any @option{-O} options. This +section includes experimental options that may produce broken code. -@item -floop-parallelize-all -@opindex floop-parallelize-all -Use the Graphite data dependence analysis to identify loops that can -be parallelized. Parallelize all the loops that can be analyzed to -not contain loop carried dependences without checking that it is -profitable to parallelize the loops. +@table @gcctabopt +@item -fbranch-probabilities +@opindex fbranch-probabilities +After running a program compiled with @option{-fprofile-arcs} +(@pxref{Instrumentation Options}), +you can compile it a second time using +@option{-fbranch-probabilities}, to improve optimizations based on +the number of times each branch was taken. When a program +compiled with @option{-fprofile-arcs} exits, it saves arc execution +counts to a file called @file{@var{sourcename}.gcda} for each source +file. The information in this data file is very dependent on the +structure of the generated code, so you must use the same source code +and the same optimization options for both compilations. -@item -ftree-coalesce-vars -@opindex ftree-coalesce-vars -While transforming the program out of the SSA representation, attempt to -reduce copying by coalescing versions of different user-defined -variables, instead of just compiler temporaries. This may severely -limit the ability to debug an optimized program compiled with -@option{-fno-var-tracking-assignments}. In the negated form, this flag -prevents SSA coalescing of user variables. This option is enabled by -default if optimization is enabled, and it does very little otherwise. +With @option{-fbranch-probabilities}, GCC puts a +@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. +These can be used to improve optimization. Currently, they are only +used in one place: in @file{reorg.c}, instead of guessing which path a +branch is most likely to take, the @samp{REG_BR_PROB} values are used to +exactly determine which path is taken more often. -@item -ftree-loop-if-convert -@opindex ftree-loop-if-convert -Attempt to transform conditional jumps in the innermost loops to -branch-less equivalents. The intent is to remove control-flow from -the innermost loops in order to improve the ability of the -vectorization pass to handle these loops. This is enabled by default -if vectorization is enabled. +@item -fprofile-values +@opindex fprofile-values +If combined with @option{-fprofile-arcs}, it adds code so that some +data about values of expressions in the program is gathered. -@item -ftree-loop-if-convert-stores -@opindex ftree-loop-if-convert-stores -Attempt to also if-convert conditional jumps containing memory writes. -This transformation can be unsafe for multi-threaded programs as it -transforms conditional memory writes into unconditional memory writes. -For example, -@smallexample -for (i = 0; i < N; i++) - if (cond) - A[i] = expr; -@end smallexample -is transformed to -@smallexample -for (i = 0; i < N; i++) - A[i] = cond ? expr : A[i]; -@end smallexample -potentially producing data races. +With @option{-fbranch-probabilities}, it reads back the data gathered +from profiling values of expressions for usage in optimizations. -@item -ftree-loop-distribution -@opindex ftree-loop-distribution -Perform loop distribution. This flag can improve cache performance on -big loop bodies and allow further loop optimizations, like -parallelization or vectorization, to take place. For example, the loop -@smallexample -DO I = 1, N - A(I) = B(I) + C - D(I) = E(I) * F -ENDDO -@end smallexample -is transformed to -@smallexample -DO I = 1, N - A(I) = B(I) + C -ENDDO -DO I = 1, N - D(I) = E(I) * F -ENDDO -@end smallexample +Enabled with @option{-fprofile-generate} and @option{-fprofile-use}. -@item -ftree-loop-distribute-patterns -@opindex ftree-loop-distribute-patterns -Perform loop distribution of patterns that can be code generated with -calls to a library. This flag is enabled by default at @option{-O3}. +@item -fprofile-reorder-functions +@opindex fprofile-reorder-functions +Function reordering based on profile instrumentation collects +first time of execution of a function and orders these functions +in ascending order. -This pass distributes the initialization loops and generates a call to -memset zero. For example, the loop -@smallexample -DO I = 1, N - A(I) = 0 - B(I) = A(I) + I -ENDDO -@end smallexample -is transformed to -@smallexample -DO I = 1, N - A(I) = 0 -ENDDO -DO I = 1, N - B(I) = A(I) + I -ENDDO -@end smallexample -and the initialization loop is transformed into a call to memset zero. +Enabled with @option{-fprofile-use}. -@item -ftree-loop-im -@opindex ftree-loop-im -Perform loop invariant motion on trees. This pass moves only invariants that -are hard to handle at RTL level (function calls, operations that expand to -nontrivial sequences of insns). With @option{-funswitch-loops} it also moves -operands of conditions that are invariant out of the loop, so that we can use -just trivial invariantness analysis in loop unswitching. The pass also includes -store motion. +@item -fvpt +@opindex fvpt +If combined with @option{-fprofile-arcs}, this option instructs the compiler +to add code to gather information about values of expressions. -@item -ftree-loop-ivcanon -@opindex ftree-loop-ivcanon -Create a canonical counter for number of iterations in loops for which -determining number of iterations requires complicated analysis. Later -optimizations then may determine the number easily. Useful especially -in connection with unrolling. +With @option{-fbranch-probabilities}, it reads back the data gathered +and actually performs the optimizations based on them. +Currently the optimizations include specialization of division operations +using the knowledge about the value of the denominator. -@item -fivopts -@opindex fivopts -Perform induction variable optimizations (strength reduction, induction -variable merging and induction variable elimination) on trees. +@item -frename-registers +@opindex frename-registers +Attempt to avoid false dependencies in scheduled code by making use +of registers left over after register allocation. This optimization +most benefits processors with lots of registers. Depending on the +debug information format adopted by the target, however, it can +make debugging impossible, since variables no longer stay in +a ``home register''. -@item -ftree-parallelize-loops=n -@opindex ftree-parallelize-loops -Parallelize loops, i.e., split their iteration space to run in n threads. -This is only possible for loops whose iterations are independent -and can be arbitrarily reordered. The optimization is only -profitable on multiprocessor machines, for loops that are CPU-intensive, -rather than constrained e.g.@: by memory bandwidth. This option -implies @option{-pthread}, and thus is only supported on targets -that have support for @option{-pthread}. +Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}. -@item -ftree-pta -@opindex ftree-pta -Perform function-local points-to analysis on trees. This flag is -enabled by default at @option{-O} and higher. +@item -fschedule-fusion +@opindex fschedule-fusion +Performs a target dependent pass over the instruction stream to schedule +instructions of same type together because target machine can execute them +more efficiently if they are adjacent to each other in the instruction flow. -@item -ftree-sra -@opindex ftree-sra -Perform scalar replacement of aggregates. This pass replaces structure -references with scalars to prevent committing structures to memory too -early. This flag is enabled by default at @option{-O} and higher. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -ftree-ter -@opindex ftree-ter -Perform temporary expression replacement during the SSA->normal phase. Single -use/single def temporaries are replaced at their use location with their -defining expression. This results in non-GIMPLE code, but gives the expanders -much more complex trees to work on resulting in better RTL generation. This is -enabled by default at @option{-O} and higher. +@item -ftracer +@opindex ftracer +Perform tail duplication to enlarge superblock size. This transformation +simplifies the control flow of the function allowing other optimizations to do +a better job. -@item -ftree-slsr -@opindex ftree-slsr -Perform straight-line strength reduction on trees. This recognizes related -expressions involving multiplications and replaces them by less expensive -calculations when possible. This is enabled by default at @option{-O} and -higher. +Enabled with @option{-fprofile-use}. -@item -ftree-vectorize -@opindex ftree-vectorize -Perform vectorization on trees. This flag enables @option{-ftree-loop-vectorize} -and @option{-ftree-slp-vectorize} if not explicitly specified. +@item -funroll-loops +@opindex funroll-loops +Unroll loops whose number of iterations can be determined at compile time or +upon entry to the loop. @option{-funroll-loops} implies +@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}. +It also turns on complete loop peeling (i.e.@: complete removal of loops with +a small constant number of iterations). This option makes code larger, and may +or may not make it run faster. -@item -ftree-loop-vectorize -@opindex ftree-loop-vectorize -Perform loop vectorization on trees. This flag is enabled by default at -@option{-O3} and when @option{-ftree-vectorize} is enabled. +Enabled with @option{-fprofile-use}. -@item -ftree-slp-vectorize -@opindex ftree-slp-vectorize -Perform basic block vectorization on trees. This flag is enabled by default at -@option{-O3} and when @option{-ftree-vectorize} is enabled. +@item -funroll-all-loops +@opindex funroll-all-loops +Unroll all loops, even if their number of iterations is uncertain when +the loop is entered. This usually makes programs run more slowly. +@option{-funroll-all-loops} implies the same options as +@option{-funroll-loops}. -@item -fvect-cost-model=@var{model} -@opindex fvect-cost-model -Alter the cost model used for vectorization. The @var{model} argument -should be one of @samp{unlimited}, @samp{dynamic} or @samp{cheap}. -With the @samp{unlimited} model the vectorized code-path is assumed -to be profitable while with the @samp{dynamic} model a runtime check -guards the vectorized code-path to enable it only for iteration -counts that will likely execute faster than when executing the original -scalar loop. The @samp{cheap} model disables vectorization of -loops where doing so would be cost prohibitive for example due to -required runtime checks for data dependence or alignment but otherwise -is equal to the @samp{dynamic} model. -The default cost model depends on other optimization flags and is -either @samp{dynamic} or @samp{cheap}. - -@item -fsimd-cost-model=@var{model} -@opindex fsimd-cost-model -Alter the cost model used for vectorization of loops marked with the OpenMP -or Cilk Plus simd directive. The @var{model} argument should be one of -@samp{unlimited}, @samp{dynamic}, @samp{cheap}. All values of @var{model} -have the same meaning as described in @option{-fvect-cost-model} and by -default a cost model defined with @option{-fvect-cost-model} is used. - -@item -ftree-vrp -@opindex ftree-vrp -Perform Value Range Propagation on trees. This is similar to the -constant propagation pass, but instead of values, ranges of values are -propagated. This allows the optimizers to remove unnecessary range -checks like array bound checks and null pointer checks. This is -enabled by default at @option{-O2} and higher. Null pointer check -elimination is only done if @option{-fdelete-null-pointer-checks} is -enabled. +@item -fpeel-loops +@opindex fpeel-loops +Peels loops for which there is enough information that they do not +roll much (from profile feedback). It also turns on complete loop peeling +(i.e.@: complete removal of loops with small constant number of iterations). -@item -fsplit-paths -@opindex fsplit-paths -Split paths leading to loop backedges. This can improve dead code -elimination and common subexpression elimination. This is enabled by -default at @option{-O2} and above. +Enabled with @option{-fprofile-use}. -@item -fsplit-ivs-in-unroller -@opindex fsplit-ivs-in-unroller -Enables expression of values of induction variables in later iterations -of the unrolled loop using the value in the first iteration. This breaks -long dependency chains, thus improving efficiency of the scheduling passes. +@item -fmove-loop-invariants +@opindex fmove-loop-invariants +Enables the loop invariant motion pass in the RTL loop optimizer. Enabled +at level @option{-O1} -A combination of @option{-fweb} and CSE is often sufficient to obtain the -same effect. However, that is not reliable in cases where the loop body -is more complicated than a single basic block. It also does not work at all -on some architectures due to restrictions in the CSE pass. +@item -funswitch-loops +@opindex funswitch-loops +Move branches with loop invariant conditions out of the loop, with duplicates +of the loop on both branches (modified according to result of the condition). -This optimization is enabled by default. +@item -ffunction-sections +@itemx -fdata-sections +@opindex ffunction-sections +@opindex fdata-sections +Place each function or data item into its own section in the output +file if the target supports arbitrary sections. The name of the +function or the name of the data item determines the section's name +in the output file. -@item -fvariable-expansion-in-unroller -@opindex fvariable-expansion-in-unroller -With this option, the compiler creates multiple copies of some -local variables when unrolling a loop, which can result in superior code. +Use these options on systems where the linker can perform optimizations +to improve locality of reference in the instruction space. Most systems +using the ELF object format and SPARC processors running Solaris 2 have +linkers with such optimizations. AIX may have these optimizations in +the future. -@item -fpartial-inlining -@opindex fpartial-inlining -Inline parts of functions. This option has any effect only -when inlining itself is turned on by the @option{-finline-functions} -or @option{-finline-small-functions} options. +Only use these options when there are significant benefits from doing +so. When you specify these options, the assembler and linker +create larger object and executable files and are also slower. +You cannot use @command{gprof} on all systems if you +specify this option, and you may have problems with debugging if +you specify both this option and @option{-g}. -Enabled at level @option{-O2}. +@item -fbranch-target-load-optimize +@opindex fbranch-target-load-optimize +Perform branch target register load optimization before prologue / epilogue +threading. +The use of target registers can typically be exposed only during reload, +thus hoisting loads out of loops and doing inter-block scheduling needs +a separate optimization pass. -@item -fpredictive-commoning -@opindex fpredictive-commoning -Perform predictive commoning optimization, i.e., reusing computations -(especially memory loads and stores) performed in previous -iterations of loops. +@item -fbranch-target-load-optimize2 +@opindex fbranch-target-load-optimize2 +Perform branch target register load optimization after prologue / epilogue +threading. -This option is enabled at level @option{-O3}. +@item -fbtr-bb-exclusive +@opindex fbtr-bb-exclusive +When performing branch target register load optimization, don't reuse +branch target registers within any basic block. -@item -fprefetch-loop-arrays -@opindex fprefetch-loop-arrays -If supported by the target machine, generate instructions to prefetch -memory to improve the performance of loops that access large arrays. +@item -fstdarg-opt +@opindex fstdarg-opt +Optimize the prologue of variadic argument functions with respect to usage of +those arguments. -This option may generate better or worse code; results are highly -dependent on the structure of loops within the source code. +@item -fsection-anchors +@opindex fsection-anchors +Try to reduce the number of symbolic address calculations by using +shared ``anchor'' symbols to address nearby objects. This transformation +can help to reduce the number of GOT entries and GOT accesses on some +targets. -Disabled at level @option{-Os}. +For example, the implementation of the following function @code{foo}: -@item -fno-peephole -@itemx -fno-peephole2 -@opindex fno-peephole -@opindex fno-peephole2 -Disable any machine-specific peephole optimizations. The difference -between @option{-fno-peephole} and @option{-fno-peephole2} is in how they -are implemented in the compiler; some targets use one, some use the -other, a few use both. +@smallexample +static int a, b, c; +int foo (void) @{ return a + b + c; @} +@end smallexample -@option{-fpeephole} is enabled by default. -@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@noindent +usually calculates the addresses of all three variables, but if you +compile it with @option{-fsection-anchors}, it accesses the variables +from a common anchor point instead. The effect is similar to the +following pseudocode (which isn't valid C): -@item -fno-guess-branch-probability -@opindex fno-guess-branch-probability -Do not guess branch probabilities using heuristics. +@smallexample +int foo (void) +@{ + register int *xr = &x; + return xr[&a - &x] + xr[&b - &x] + xr[&c - &x]; +@} +@end smallexample -GCC uses heuristics to guess branch probabilities if they are -not provided by profiling feedback (@option{-fprofile-arcs}). These -heuristics are based on the control flow graph. If some branch probabilities -are specified by @code{__builtin_expect}, then the heuristics are -used to guess branch probabilities for the rest of the control flow graph, -taking the @code{__builtin_expect} info into account. The interactions -between the heuristics and @code{__builtin_expect} can be complex, and in -some cases, it may be useful to disable the heuristics so that the effects -of @code{__builtin_expect} are easier to understand. +Not all targets support this option. -The default is @option{-fguess-branch-probability} at levels -@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item --param @var{name}=@var{value} +@opindex param +In some places, GCC uses various constants to control the amount of +optimization that is done. For example, GCC does not inline functions +that contain more than a certain number of instructions. You can +control some of these constants on the command line using the +@option{--param} option. -@item -freorder-blocks -@opindex freorder-blocks -Reorder basic blocks in the compiled function in order to reduce number of -taken branches and improve code locality. +The names of specific parameters, and the meaning of the values, are +tied to the internals of the compiler, and are subject to change +without notice in future releases. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +In each case, the @var{value} is an integer. The allowable choices for +@var{name} are: -@item -freorder-blocks-algorithm=@var{algorithm} -@opindex freorder-blocks-algorithm -Use the specified algorithm for basic block reordering. The -@var{algorithm} argument can be @samp{simple}, which does not increase -code size (except sometimes due to secondary effects like alignment), -or @samp{stc}, the ``software trace cache'' algorithm, which tries to -put all often executed code together, minimizing the number of branches -executed by making extra copies of code. +@table @gcctabopt +@item predictable-branch-outcome +When branch is predicted to be taken with probability lower than this threshold +(in percent), then it is considered well predictable. The default is 10. -The default is @samp{simple} at levels @option{-O}, @option{-Os}, and -@samp{stc} at levels @option{-O2}, @option{-O3}. +@item max-rtl-if-conversion-insns +RTL if-conversion tries to remove conditional branches around a block and +replace them with conditionally executed instructions. This parameter +gives the maximum number of instructions in a block which should be +considered for if-conversion. The default is 10, though the compiler will +also use other heuristics to decide whether if-conversion is likely to be +profitable. -@item -freorder-blocks-and-partition -@opindex freorder-blocks-and-partition -In addition to reordering basic blocks in the compiled function, in order -to reduce number of taken branches, partitions hot and cold basic blocks -into separate sections of the assembly and .o files, to improve -paging and cache locality performance. +@item max-crossjump-edges +The maximum number of incoming edges to consider for cross-jumping. +The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in +the number of edges incoming to each block. Increasing values mean +more aggressive optimization, making the compilation time increase with +probably small improvement in executable size. -This optimization is automatically turned off in the presence of -exception handling, for linkonce sections, for functions with a user-defined -section attribute and on any architecture that does not support named -sections. +@item min-crossjump-insns +The minimum number of instructions that must be matched at the end +of two blocks before cross-jumping is performed on them. This +value is ignored in the case where all instructions in the block being +cross-jumped from are matched. The default value is 5. -Enabled for x86 at levels @option{-O2}, @option{-O3}. +@item max-grow-copy-bb-insns +The maximum code size expansion factor when copying basic blocks +instead of jumping. The expansion is relative to a jump instruction. +The default value is 8. -@item -freorder-functions -@opindex freorder-functions -Reorder functions in the object file in order to -improve code locality. This is implemented by using special -subsections @code{.text.hot} for most frequently executed functions and -@code{.text.unlikely} for unlikely executed functions. Reordering is done by -the linker so object file format must support named sections and linker must -place them in a reasonable way. +@item max-goto-duplication-insns +The maximum number of instructions to duplicate to a block that jumps +to a computed goto. To avoid @math{O(N^2)} behavior in a number of +passes, GCC factors computed gotos early in the compilation process, +and unfactors them as late as possible. Only computed jumps at the +end of a basic blocks with no more than max-goto-duplication-insns are +unfactored. The default value is 8. -Also profile feedback must be available to make this option effective. See -@option{-fprofile-arcs} for details. +@item max-delay-slot-insn-search +The maximum number of instructions to consider when looking for an +instruction to fill a delay slot. If more than this arbitrary number of +instructions are searched, the time savings from filling the delay slot +are minimal, so stop searching. Increasing values mean more +aggressive optimization, making the compilation time increase with probably +small improvement in execution time. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. - -@item -fstrict-aliasing -@opindex fstrict-aliasing -Allow the compiler to assume the strictest aliasing rules applicable to -the language being compiled. For C (and C++), this activates -optimizations based on the type of expressions. In particular, an -object of one type is assumed never to reside at the same address as an -object of a different type, unless the types are almost the same. For -example, an @code{unsigned int} can alias an @code{int}, but not a -@code{void*} or a @code{double}. A character type may alias any other -type. +@item max-delay-slot-live-search +When trying to fill delay slots, the maximum number of instructions to +consider when searching for a block with valid live register +information. Increasing this arbitrarily chosen value means more +aggressive optimization, increasing the compilation time. This parameter +should be removed when the delay slot code is rewritten to maintain the +control-flow graph. -@anchor{Type-punning}Pay special attention to code like this: -@smallexample -union a_union @{ - int i; - double d; -@}; +@item max-gcse-memory +The approximate maximum amount of memory that can be allocated in +order to perform the global common subexpression elimination +optimization. If more memory than specified is required, the +optimization is not done. -int f() @{ - union a_union t; - t.d = 3.0; - return t.i; -@} -@end smallexample -The practice of reading from a different union member than the one most -recently written to (called ``type-punning'') is common. Even with -@option{-fstrict-aliasing}, type-punning is allowed, provided the memory -is accessed through the union type. So, the code above works as -expected. @xref{Structures unions enumerations and bit-fields -implementation}. However, this code might not: -@smallexample -int f() @{ - union a_union t; - int* ip; - t.d = 3.0; - ip = &t.i; - return *ip; -@} -@end smallexample +@item max-gcse-insertion-ratio +If the ratio of expression insertions to deletions is larger than this value +for any expression, then RTL PRE inserts or removes the expression and thus +leaves partially redundant computations in the instruction stream. The default value is 20. -Similarly, access by taking the address, casting the resulting pointer -and dereferencing the result has undefined behavior, even if the cast -uses a union type, e.g.: -@smallexample -int f() @{ - double d = 3.0; - return ((union a_union *) &d)->i; -@} -@end smallexample +@item max-pending-list-length +The maximum number of pending dependencies scheduling allows +before flushing the current state and starting over. Large functions +with few branches or calls can create excessively large lists which +needlessly consume memory and resources. -The @option{-fstrict-aliasing} option is enabled at levels -@option{-O2}, @option{-O3}, @option{-Os}. +@item max-modulo-backtrack-attempts +The maximum number of backtrack attempts the scheduler should make +when modulo scheduling a loop. Larger values can exponentially increase +compilation time. -@item -fstrict-overflow -@opindex fstrict-overflow -Allow the compiler to assume strict signed overflow rules, depending -on the language being compiled. For C (and C++) this means that -overflow when doing arithmetic with signed numbers is undefined, which -means that the compiler may assume that it does not happen. This -permits various optimizations. For example, the compiler assumes -that an expression like @code{i + 10 > i} is always true for -signed @code{i}. This assumption is only valid if signed overflow is -undefined, as the expression is false if @code{i + 10} overflows when -using twos complement arithmetic. When this option is in effect any -attempt to determine whether an operation on signed numbers -overflows must be written carefully to not actually involve overflow. +@item max-inline-insns-single +Several parameters control the tree inliner used in GCC@. +This number sets the maximum number of instructions (counted in GCC's +internal representation) in a single function that the tree inliner +considers for inlining. This only affects functions declared +inline and methods implemented in a class declaration (C++). +The default value is 400. -This option also allows the compiler to assume strict pointer -semantics: given a pointer to an object, if adding an offset to that -pointer does not produce a pointer to the same object, the addition is -undefined. This permits the compiler to conclude that @code{p + u > -p} is always true for a pointer @code{p} and unsigned integer -@code{u}. This assumption is only valid because pointer wraparound is -undefined, as the expression is false if @code{p + u} overflows using -twos complement arithmetic. +@item max-inline-insns-auto +When you use @option{-finline-functions} (included in @option{-O3}), +a lot of functions that would otherwise not be considered for inlining +by the compiler are investigated. To those functions, a different +(more restrictive) limit compared to functions declared inline can +be applied. +The default value is 40. -See also the @option{-fwrapv} option. Using @option{-fwrapv} means -that integer signed overflow is fully defined: it wraps. When -@option{-fwrapv} is used, there is no difference between -@option{-fstrict-overflow} and @option{-fno-strict-overflow} for -integers. With @option{-fwrapv} certain types of overflow are -permitted. For example, if the compiler gets an overflow when doing -arithmetic on constants, the overflowed value can still be used with -@option{-fwrapv}, but not otherwise. +@item inline-min-speedup +When estimated performance improvement of caller + callee runtime exceeds this +threshold (in precent), the function can be inlined regardless the limit on +@option{--param max-inline-insns-single} and @option{--param +max-inline-insns-auto}. -The @option{-fstrict-overflow} option is enabled at levels -@option{-O2}, @option{-O3}, @option{-Os}. +@item large-function-insns +The limit specifying really large functions. For functions larger than this +limit after inlining, inlining is constrained by +@option{--param large-function-growth}. This parameter is useful primarily +to avoid extreme compilation time caused by non-linear algorithms used by the +back end. +The default value is 2700. -@item -falign-functions -@itemx -falign-functions=@var{n} -@opindex falign-functions -Align the start of functions to the next power-of-two greater than -@var{n}, skipping up to @var{n} bytes. For instance, -@option{-falign-functions=32} aligns functions to the next 32-byte -boundary, but @option{-falign-functions=24} aligns to the next -32-byte boundary only if this can be done by skipping 23 bytes or less. +@item large-function-growth +Specifies maximal growth of large function caused by inlining in percents. +The default value is 100 which limits large function growth to 2.0 times +the original size. -@option{-fno-align-functions} and @option{-falign-functions=1} are -equivalent and mean that functions are not aligned. +@item large-unit-insns +The limit specifying large translation unit. Growth caused by inlining of +units larger than this limit is limited by @option{--param inline-unit-growth}. +For small units this might be too tight. +For example, consider a unit consisting of function A +that is inline and B that just calls A three times. If B is small relative to +A, the growth of unit is 300\% and yet such inlining is very sane. For very +large units consisting of small inlineable functions, however, the overall unit +growth limit is needed to avoid exponential explosion of code size. Thus for +smaller units, the size is increased to @option{--param large-unit-insns} +before applying @option{--param inline-unit-growth}. The default is 10000. -Some assemblers only support this flag when @var{n} is a power of two; -in that case, it is rounded up. +@item inline-unit-growth +Specifies maximal overall growth of the compilation unit caused by inlining. +The default value is 20 which limits unit growth to 1.2 times the original +size. Cold functions (either marked cold via an attribute or by profile +feedback) are not accounted into the unit size. -If @var{n} is not specified or is zero, use a machine-dependent default. +@item ipcp-unit-growth +Specifies maximal overall growth of the compilation unit caused by +interprocedural constant propagation. The default value is 10 which limits +unit growth to 1.1 times the original size. -Enabled at levels @option{-O2}, @option{-O3}. +@item large-stack-frame +The limit specifying large stack frames. While inlining the algorithm is trying +to not grow past this limit too much. The default value is 256 bytes. -@item -falign-labels -@itemx -falign-labels=@var{n} -@opindex falign-labels -Align all branch targets to a power-of-two boundary, skipping up to -@var{n} bytes like @option{-falign-functions}. This option can easily -make code slower, because it must insert dummy operations for when the -branch target is reached in the usual flow of the code. +@item large-stack-frame-growth +Specifies maximal growth of large stack frames caused by inlining in percents. +The default value is 1000 which limits large stack frame growth to 11 times +the original size. -@option{-fno-align-labels} and @option{-falign-labels=1} are -equivalent and mean that labels are not aligned. +@item max-inline-insns-recursive +@itemx max-inline-insns-recursive-auto +Specifies the maximum number of instructions an out-of-line copy of a +self-recursive inline +function can grow into by performing recursive inlining. -If @option{-falign-loops} or @option{-falign-jumps} are applicable and -are greater than this value, then their values are used instead. +@option{--param max-inline-insns-recursive} applies to functions +declared inline. +For functions not declared inline, recursive inlining +happens only when @option{-finline-functions} (included in @option{-O3}) is +enabled; @option{--param max-inline-insns-recursive-auto} applies instead. The +default value is 450. -If @var{n} is not specified or is zero, use a machine-dependent default -which is very likely to be @samp{1}, meaning no alignment. +@item max-inline-recursive-depth +@itemx max-inline-recursive-depth-auto +Specifies the maximum recursion depth used for recursive inlining. -Enabled at levels @option{-O2}, @option{-O3}. +@option{--param max-inline-recursive-depth} applies to functions +declared inline. For functions not declared inline, recursive inlining +happens only when @option{-finline-functions} (included in @option{-O3}) is +enabled; @option{--param max-inline-recursive-depth-auto} applies instead. The +default value is 8. -@item -falign-loops -@itemx -falign-loops=@var{n} -@opindex falign-loops -Align loops to a power-of-two boundary, skipping up to @var{n} bytes -like @option{-falign-functions}. If the loops are -executed many times, this makes up for any execution of the dummy -operations. +@item min-inline-recursive-probability +Recursive inlining is profitable only for function having deep recursion +in average and can hurt for function having little recursion depth by +increasing the prologue size or complexity of function body to other +optimizers. -@option{-fno-align-loops} and @option{-falign-loops=1} are -equivalent and mean that loops are not aligned. +When profile feedback is available (see @option{-fprofile-generate}) the actual +recursion depth can be guessed from probability that function recurses via a +given call expression. This parameter limits inlining only to call expressions +whose probability exceeds the given threshold (in percents). +The default value is 10. -If @var{n} is not specified or is zero, use a machine-dependent default. +@item early-inlining-insns +Specify growth that the early inliner can make. In effect it increases +the amount of inlining for code having a large abstraction penalty. +The default value is 14. -Enabled at levels @option{-O2}, @option{-O3}. +@item max-early-inliner-iterations +Limit of iterations of the early inliner. This basically bounds +the number of nested indirect calls the early inliner can resolve. +Deeper chains are still handled by late inlining. -@item -falign-jumps -@itemx -falign-jumps=@var{n} -@opindex falign-jumps -Align branch targets to a power-of-two boundary, for branch targets -where the targets can only be reached by jumping, skipping up to @var{n} -bytes like @option{-falign-functions}. In this case, no dummy operations -need be executed. +@item comdat-sharing-probability +Probability (in percent) that C++ inline function with comdat visibility +are shared across multiple compilation units. The default value is 20. -@option{-fno-align-jumps} and @option{-falign-jumps=1} are -equivalent and mean that loops are not aligned. +@item profile-func-internal-id +A parameter to control whether to use function internal id in profile +database lookup. If the value is 0, the compiler uses an id that +is based on function assembler name and filename, which makes old profile +data more tolerant to source changes such as function reordering etc. +The default value is 0. -If @var{n} is not specified or is zero, use a machine-dependent default. +@item min-vect-loop-bound +The minimum number of iterations under which loops are not vectorized +when @option{-ftree-vectorize} is used. The number of iterations after +vectorization needs to be greater than the value specified by this option +to allow vectorization. The default value is 0. -Enabled at levels @option{-O2}, @option{-O3}. +@item gcse-cost-distance-ratio +Scaling factor in calculation of maximum distance an expression +can be moved by GCSE optimizations. This is currently supported only in the +code hoisting pass. The bigger the ratio, the more aggressive code hoisting +is with simple expressions, i.e., the expressions that have cost +less than @option{gcse-unrestricted-cost}. Specifying 0 disables +hoisting of simple expressions. The default value is 10. -@item -funit-at-a-time -@opindex funit-at-a-time -This option is left for compatibility reasons. @option{-funit-at-a-time} -has no effect, while @option{-fno-unit-at-a-time} implies -@option{-fno-toplevel-reorder} and @option{-fno-section-anchors}. +@item gcse-unrestricted-cost +Cost, roughly measured as the cost of a single typical machine +instruction, at which GCSE optimizations do not constrain +the distance an expression can travel. This is currently +supported only in the code hoisting pass. The lesser the cost, +the more aggressive code hoisting is. Specifying 0 +allows all expressions to travel unrestricted distances. +The default value is 3. -Enabled by default. +@item max-hoist-depth +The depth of search in the dominator tree for expressions to hoist. +This is used to avoid quadratic behavior in hoisting algorithm. +The value of 0 does not limit on the search, but may slow down compilation +of huge functions. The default value is 30. -@item -fno-toplevel-reorder -@opindex fno-toplevel-reorder -Do not reorder top-level functions, variables, and @code{asm} -statements. Output them in the same order that they appear in the -input file. When this option is used, unreferenced static variables -are not removed. This option is intended to support existing code -that relies on a particular ordering. For new code, it is better to -use attributes when possible. +@item max-tail-merge-comparisons +The maximum amount of similar bbs to compare a bb with. This is used to +avoid quadratic behavior in tree tail merging. The default value is 10. -Enabled at level @option{-O0}. When disabled explicitly, it also implies -@option{-fno-section-anchors}, which is otherwise enabled at @option{-O0} on some -targets. +@item max-tail-merge-iterations +The maximum amount of iterations of the pass over the function. This is used to +limit compilation time in tree tail merging. The default value is 2. -@item -fweb -@opindex fweb -Constructs webs as commonly used for register allocation purposes and assign -each web individual pseudo register. This allows the register allocation pass -to operate on pseudos directly, but also strengthens several other optimization -passes, such as CSE, loop optimizer and trivial dead code remover. It can, -however, make debugging impossible, since variables no longer stay in a -``home register''. +@item max-unrolled-insns +The maximum number of instructions that a loop may have to be unrolled. +If a loop is unrolled, this parameter also determines how many times +the loop code is unrolled. -Enabled by default with @option{-funroll-loops}. +@item max-average-unrolled-insns +The maximum number of instructions biased by probabilities of their execution +that a loop may have to be unrolled. If a loop is unrolled, +this parameter also determines how many times the loop code is unrolled. -@item -fwhole-program -@opindex fwhole-program -Assume that the current compilation unit represents the whole program being -compiled. All public functions and variables with the exception of @code{main} -and those merged by attribute @code{externally_visible} become static functions -and in effect are optimized more aggressively by interprocedural optimizers. +@item max-unroll-times +The maximum number of unrollings of a single loop. -This option should not be used in combination with @option{-flto}. -Instead relying on a linker plugin should provide safer and more precise -information. +@item max-peeled-insns +The maximum number of instructions that a loop may have to be peeled. +If a loop is peeled, this parameter also determines how many times +the loop code is peeled. -@item -flto[=@var{n}] -@opindex flto -This option runs the standard link-time optimizer. When invoked -with source code, it generates GIMPLE (one of GCC's internal -representations) and writes it to special ELF sections in the object -file. When the object files are linked together, all the function -bodies are read from these ELF sections and instantiated as if they -had been part of the same translation unit. +@item max-peel-times +The maximum number of peelings of a single loop. -To use the link-time optimizer, @option{-flto} and optimization -options should be specified at compile time and during the final link. -For example: +@item max-peel-branches +The maximum number of branches on the hot path through the peeled sequence. -@smallexample -gcc -c -O2 -flto foo.c -gcc -c -O2 -flto bar.c -gcc -o myprog -flto -O2 foo.o bar.o -@end smallexample +@item max-completely-peeled-insns +The maximum number of insns of a completely peeled loop. -The first two invocations to GCC save a bytecode representation -of GIMPLE into special ELF sections inside @file{foo.o} and -@file{bar.o}. The final invocation reads the GIMPLE bytecode from -@file{foo.o} and @file{bar.o}, merges the two files into a single -internal image, and compiles the result as usual. Since both -@file{foo.o} and @file{bar.o} are merged into a single image, this -causes all the interprocedural analyses and optimizations in GCC to -work across the two files as if they were a single one. This means, -for example, that the inliner is able to inline functions in -@file{bar.o} into functions in @file{foo.o} and vice-versa. +@item max-completely-peel-times +The maximum number of iterations of a loop to be suitable for complete peeling. -Another (simpler) way to enable link-time optimization is: +@item max-completely-peel-loop-nest-depth +The maximum depth of a loop nest suitable for complete peeling. -@smallexample -gcc -o myprog -flto -O2 foo.c bar.c -@end smallexample +@item max-unswitch-insns +The maximum number of insns of an unswitched loop. -The above generates bytecode for @file{foo.c} and @file{bar.c}, -merges them together into a single GIMPLE representation and optimizes -them as usual to produce @file{myprog}. +@item max-unswitch-level +The maximum number of branches unswitched in a single loop. -The only important thing to keep in mind is that to enable link-time -optimizations you need to use the GCC driver to perform the link-step. -GCC then automatically performs link-time optimization if any of the -objects involved were compiled with the @option{-flto} command-line option. -You generally -should specify the optimization options to be used for link-time -optimization though GCC tries to be clever at guessing an -optimization level to use from the options used at compile-time -if you fail to specify one at link-time. You can always override -the automatic decision to do link-time optimization at link-time -by passing @option{-fno-lto} to the link command. +@item lim-expensive +The minimum cost of an expensive expression in the loop invariant motion. -To make whole program optimization effective, it is necessary to make -certain whole program assumptions. The compiler needs to know -what functions and variables can be accessed by libraries and runtime -outside of the link-time optimized unit. When supported by the linker, -the linker plugin (see @option{-fuse-linker-plugin}) passes information -to the compiler about used and externally visible symbols. When -the linker plugin is not available, @option{-fwhole-program} should be -used to allow the compiler to make these assumptions, which leads -to more aggressive optimization decisions. +@item iv-consider-all-candidates-bound +Bound on number of candidates for induction variables, below which +all candidates are considered for each use in induction variable +optimizations. If there are more candidates than this, +only the most relevant ones are considered to avoid quadratic time complexity. -When @option{-fuse-linker-plugin} is not enabled then, when a file is -compiled with @option{-flto}, the generated object file is larger than -a regular object file because it contains GIMPLE bytecodes and the usual -final code (see @option{-ffat-lto-objects}. This means that -object files with LTO information can be linked as normal object -files; if @option{-fno-lto} is passed to the linker, no -interprocedural optimizations are applied. Note that when -@option{-fno-fat-lto-objects} is enabled the compile-stage is faster -but you cannot perform a regular, non-LTO link on them. +@item iv-max-considered-uses +The induction variable optimizations give up on loops that contain more +induction variable uses. -Additionally, the optimization flags used to compile individual files -are not necessarily related to those used at link time. For instance, +@item iv-always-prune-cand-set-bound +If the number of candidates in the set is smaller than this value, +always try to remove unnecessary ivs from the set +when adding a new one. -@smallexample -gcc -c -O0 -ffat-lto-objects -flto foo.c -gcc -c -O0 -ffat-lto-objects -flto bar.c -gcc -o myprog -O3 foo.o bar.o -@end smallexample +@item scev-max-expr-size +Bound on size of expressions used in the scalar evolutions analyzer. +Large expressions slow the analyzer. -This produces individual object files with unoptimized assembler -code, but the resulting binary @file{myprog} is optimized at -@option{-O3}. If, instead, the final binary is generated with -@option{-fno-lto}, then @file{myprog} is not optimized. +@item scev-max-expr-complexity +Bound on the complexity of the expressions in the scalar evolutions analyzer. +Complex expressions slow the analyzer. -When producing the final binary, GCC only -applies link-time optimizations to those files that contain bytecode. -Therefore, you can mix and match object files and libraries with -GIMPLE bytecodes and final object code. GCC automatically selects -which files to optimize in LTO mode and which files to link without -further processing. +@item vect-max-version-for-alignment-checks +The maximum number of run-time checks that can be performed when +doing loop versioning for alignment in the vectorizer. -There are some code generation flags preserved by GCC when -generating bytecodes, as they need to be used during the final link -stage. Generally options specified at link-time override those -specified at compile-time. +@item vect-max-version-for-alias-checks +The maximum number of run-time checks that can be performed when +doing loop versioning for alias in the vectorizer. -If you do not specify an optimization level option @option{-O} at -link-time then GCC computes one based on the optimization levels -used when compiling the object files. The highest optimization -level wins here. +@item vect-max-peeling-for-alignment +The maximum number of loop peels to enhance access alignment +for vectorizer. Value -1 means 'no limit'. -Currently, the following options and their setting are take from -the first object file that explicitely specified it: -@option{-fPIC}, @option{-fpic}, @option{-fpie}, @option{-fcommon}, -@option{-fexceptions}, @option{-fnon-call-exceptions}, @option{-fgnu-tm} -and all the @option{-m} target flags. +@item max-iterations-to-track +The maximum number of iterations of a loop the brute-force algorithm +for analysis of the number of iterations of the loop tries to evaluate. -Certain ABI changing flags are required to match in all compilation-units -and trying to override this at link-time with a conflicting value -is ignored. This includes options such as @option{-freg-struct-return} -and @option{-fpcc-struct-return}. +@item hot-bb-count-ws-permille +A basic block profile count is considered hot if it contributes to +the given permillage (i.e. 0...1000) of the entire profiled execution. -Other options such as @option{-ffp-contract}, @option{-fno-strict-overflow}, -@option{-fwrapv}, @option{-fno-trapv} or @option{-fno-strict-aliasing} -are passed through to the link stage and merged conservatively for -conflicting translation units. Specifically -@option{-fno-strict-overflow}, @option{-fwrapv} and @option{-fno-trapv} take -precedence and for example @option{-ffp-contract=off} takes precedence -over @option{-ffp-contract=fast}. You can override them at linke-time. +@item hot-bb-frequency-fraction +Select fraction of the entry block frequency of executions of basic block in +function given basic block needs to have to be considered hot. -It is recommended that you compile all the files participating in the -same link with the same options and also specify those options at -link time. +@item max-predicted-iterations +The maximum number of loop iterations we predict statically. This is useful +in cases where a function contains a single loop with known bound and +another loop with unknown bound. +The known number of iterations is predicted correctly, while +the unknown number of iterations average to roughly 10. This means that the +loop without bounds appears artificially cold relative to the other one. -If LTO encounters objects with C linkage declared with incompatible -types in separate translation units to be linked together (undefined -behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be -issued. The behavior is still undefined at run time. Similar -diagnostics may be raised for other languages. +@item builtin-expect-probability +Control the probability of the expression having the specified value. This +parameter takes a percentage (i.e. 0 ... 100) as input. +The default probability of 90 is obtained empirically. -Another feature of LTO is that it is possible to apply interprocedural -optimizations on files written in different languages: +@item align-threshold -@smallexample -gcc -c -flto foo.c -g++ -c -flto bar.cc -gfortran -c -flto baz.f90 -g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran -@end smallexample +Select fraction of the maximal frequency of executions of a basic block in +a function to align the basic block. -Notice that the final link is done with @command{g++} to get the C++ -runtime libraries and @option{-lgfortran} is added to get the Fortran -runtime libraries. In general, when mixing languages in LTO mode, you -should use the same link command options as when mixing languages in a -regular (non-LTO) compilation. +@item align-loop-iterations -If object files containing GIMPLE bytecode are stored in a library archive, say -@file{libfoo.a}, it is possible to extract and use them in an LTO link if you -are using a linker with plugin support. To create static libraries suitable -for LTO, use @command{gcc-ar} and @command{gcc-ranlib} instead of @command{ar} -and @command{ranlib}; -to show the symbols of object files with GIMPLE bytecode, use -@command{gcc-nm}. Those commands require that @command{ar}, @command{ranlib} -and @command{nm} have been compiled with plugin support. At link time, use the the -flag @option{-fuse-linker-plugin} to ensure that the library participates in -the LTO optimization process: +A loop expected to iterate at least the selected number of iterations is +aligned. -@smallexample -gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo -@end smallexample +@item tracer-dynamic-coverage +@itemx tracer-dynamic-coverage-feedback -With the linker plugin enabled, the linker extracts the needed -GIMPLE files from @file{libfoo.a} and passes them on to the running GCC -to make them part of the aggregated GIMPLE image to be optimized. +This value is used to limit superblock formation once the given percentage of +executed instructions is covered. This limits unnecessary code size +expansion. -If you are not using a linker with plugin support and/or do not -enable the linker plugin, then the objects inside @file{libfoo.a} -are extracted and linked as usual, but they do not participate -in the LTO optimization process. In order to make a static library suitable -for both LTO optimization and usual linkage, compile its object files with -@option{-flto} @option{-ffat-lto-objects}. +The @option{tracer-dynamic-coverage-feedback} parameter +is used only when profile +feedback is available. The real profiles (as opposed to statically estimated +ones) are much less balanced allowing the threshold to be larger value. -Link-time optimizations do not require the presence of the whole program to -operate. If the program does not require any symbols to be exported, it is -possible to combine @option{-flto} and @option{-fwhole-program} to allow -the interprocedural optimizers to use more aggressive assumptions which may -lead to improved optimization opportunities. -Use of @option{-fwhole-program} is not needed when linker plugin is -active (see @option{-fuse-linker-plugin}). +@item tracer-max-code-growth +Stop tail duplication once code growth has reached given percentage. This is +a rather artificial limit, as most of the duplicates are eliminated later in +cross jumping, so it may be set to much higher values than is the desired code +growth. -The current implementation of LTO makes no -attempt to generate bytecode that is portable between different -types of hosts. The bytecode files are versioned and there is a -strict version check, so bytecode files generated in one version of -GCC do not work with an older or newer version of GCC. +@item tracer-min-branch-ratio -Link-time optimization does not work well with generation of debugging -information. Combining @option{-flto} with -@option{-g} is currently experimental and expected to produce unexpected -results. +Stop reverse growth when the reverse probability of best edge is less than this +threshold (in percent). -If you specify the optional @var{n}, the optimization and code -generation done at link time is executed in parallel using @var{n} -parallel jobs by utilizing an installed @command{make} program. The -environment variable @env{MAKE} may be used to override the program -used. The default value for @var{n} is 1. +@item tracer-min-branch-ratio +@itemx tracer-min-branch-ratio-feedback -You can also specify @option{-flto=jobserver} to use GNU make's -job server mode to determine the number of parallel jobs. This -is useful when the Makefile calling GCC is already executing in parallel. -You must prepend a @samp{+} to the command recipe in the parent Makefile -for this to work. This option likely only works if @env{MAKE} is -GNU make. +Stop forward growth if the best edge has probability lower than this +threshold. -@item -flto-partition=@var{alg} -@opindex flto-partition -Specify the partitioning algorithm used by the link-time optimizer. -The value is either @samp{1to1} to specify a partitioning mirroring -the original source files or @samp{balanced} to specify partitioning -into equally sized chunks (whenever possible) or @samp{max} to create -new partition for every symbol where possible. Specifying @samp{none} -as an algorithm disables partitioning and streaming completely. -The default value is @samp{balanced}. While @samp{1to1} can be used -as an workaround for various code ordering issues, the @samp{max} -partitioning is intended for internal testing only. -The value @samp{one} specifies that exactly one partition should be -used while the value @samp{none} bypasses partitioning and executes -the link-time optimization step directly from the WPA phase. +Similarly to @option{tracer-dynamic-coverage} two values are present, one for +compilation for profile feedback and one for compilation without. The value +for compilation with profile feedback needs to be more conservative (higher) in +order to make tracer effective. -@item -flto-odr-type-merging -@opindex flto-odr-type-merging -Enable streaming of mangled types names of C++ types and their unification -at linktime. This increases size of LTO object files, but enable -diagnostics about One Definition Rule violations. +@item max-cse-path-length -@item -flto-compression-level=@var{n} -@opindex flto-compression-level -This option specifies the level of compression used for intermediate -language written to LTO object files, and is only meaningful in -conjunction with LTO mode (@option{-flto}). Valid -values are 0 (no compression) to 9 (maximum compression). Values -outside this range are clamped to either 0 or 9. If the option is not -given, a default balanced compression setting is used. +The maximum number of basic blocks on path that CSE considers. +The default is 10. -@item -flto-report -@opindex flto-report -Prints a report with internal details on the workings of the link-time -optimizer. The contents of this report vary from version to version. -It is meant to be useful to GCC developers when processing object -files in LTO mode (via @option{-flto}). +@item max-cse-insns +The maximum number of instructions CSE processes before flushing. +The default is 1000. -Disabled by default. +@item ggc-min-expand -@item -flto-report-wpa -@opindex flto-report-wpa -Like @option{-flto-report}, but only print for the WPA phase of Link -Time Optimization. +GCC uses a garbage collector to manage its own memory allocation. This +parameter specifies the minimum percentage by which the garbage +collector's heap should be allowed to expand between collections. +Tuning this may improve compilation speed; it has no effect on code +generation. -@item -fuse-linker-plugin -@opindex fuse-linker-plugin -Enables the use of a linker plugin during link-time optimization. This -option relies on plugin support in the linker, which is available in gold -or in GNU ld 2.21 or newer. +The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when +RAM >= 1GB@. If @code{getrlimit} is available, the notion of ``RAM'' is +the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If +GCC is not able to calculate RAM on a particular platform, the lower +bound of 30% is used. Setting this parameter and +@option{ggc-min-heapsize} to zero causes a full collection to occur at +every opportunity. This is extremely slow, but can be useful for +debugging. -This option enables the extraction of object files with GIMPLE bytecode out -of library archives. This improves the quality of optimization by exposing -more code to the link-time optimizer. This information specifies what -symbols can be accessed externally (by non-LTO object or during dynamic -linking). Resulting code quality improvements on binaries (and shared -libraries that use hidden visibility) are similar to @option{-fwhole-program}. -See @option{-flto} for a description of the effect of this flag and how to -use it. +@item ggc-min-heapsize -This option is enabled by default when LTO support in GCC is enabled -and GCC was configured for use with -a linker supporting plugins (GNU ld 2.21 or newer or gold). +Minimum size of the garbage collector's heap before it begins bothering +to collect garbage. The first collection occurs after the heap expands +by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again, +tuning this may improve compilation speed, and has no effect on code +generation. -@item -ffat-lto-objects -@opindex ffat-lto-objects -Fat LTO objects are object files that contain both the intermediate language -and the object code. This makes them usable for both LTO linking and normal -linking. This option is effective only when compiling with @option{-flto} -and is ignored at link time. +The default is the smaller of RAM/8, RLIMIT_RSS, or a limit that +tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but +with a lower bound of 4096 (four megabytes) and an upper bound of +131072 (128 megabytes). If GCC is not able to calculate RAM on a +particular platform, the lower bound is used. Setting this parameter +very large effectively disables garbage collection. Setting this +parameter and @option{ggc-min-expand} to zero causes a full collection +to occur at every opportunity. -@option{-fno-fat-lto-objects} improves compilation time over plain LTO, but -requires the complete toolchain to be aware of LTO. It requires a linker with -linker plugin support for basic functionality. Additionally, -@command{nm}, @command{ar} and @command{ranlib} -need to support linker plugins to allow a full-featured build environment -(capable of building static libraries etc). GCC provides the @command{gcc-ar}, -@command{gcc-nm}, @command{gcc-ranlib} wrappers to pass the right options -to these tools. With non fat LTO makefiles need to be modified to use them. +@item max-reload-search-insns +The maximum number of instruction reload should look backward for equivalent +register. Increasing values mean more aggressive optimization, making the +compilation time increase with probably slightly better performance. +The default value is 100. -The default is @option{-fno-fat-lto-objects} on targets with linker plugin -support. +@item max-cselib-memory-locations +The maximum number of memory locations cselib should take into account. +Increasing values mean more aggressive optimization, making the compilation time +increase with probably slightly better performance. The default value is 500. -@item -fcompare-elim -@opindex fcompare-elim -After register allocation and post-register allocation instruction splitting, -identify arithmetic instructions that compute processor flags similar to a -comparison operation based on that arithmetic. If possible, eliminate the -explicit comparison operation. +@item reorder-blocks-duplicate +@itemx reorder-blocks-duplicate-feedback -This pass only applies to certain targets that cannot explicitly represent -the comparison operation before register allocation is complete. +Used by the basic block reordering pass to decide whether to use unconditional +branch or duplicate the code on its destination. Code is duplicated when its +estimated size is smaller than this value multiplied by the estimated size of +unconditional jump in the hot spots of the program. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +The @option{reorder-block-duplicate-feedback} parameter +is used only when profile +feedback is available. It may be set to higher values than +@option{reorder-block-duplicate} since information about the hot spots is more +accurate. -@item -fcprop-registers -@opindex fcprop-registers -After register allocation and post-register allocation instruction splitting, -perform a copy-propagation pass to try to reduce scheduling dependencies -and occasionally eliminate the copy. +@item max-sched-ready-insns +The maximum number of instructions ready to be issued the scheduler should +consider at any given time during the first scheduling pass. Increasing +values mean more thorough searches, making the compilation time increase +with probably little benefit. The default value is 100. -Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item max-sched-region-blocks +The maximum number of blocks in a region to be considered for +interblock scheduling. The default value is 10. -@item -fprofile-correction -@opindex fprofile-correction -Profiles collected using an instrumented binary for multi-threaded programs may -be inconsistent due to missed counter updates. When this option is specified, -GCC uses heuristics to correct or smooth out such inconsistencies. By -default, GCC emits an error message when an inconsistent profile is detected. +@item max-pipeline-region-blocks +The maximum number of blocks in a region to be considered for +pipelining in the selective scheduler. The default value is 15. -@item -fprofile-use -@itemx -fprofile-use=@var{path} -@opindex fprofile-use -Enable profile feedback-directed optimizations, -and the following optimizations -which are generally profitable only with profile feedback available: -@option{-fbranch-probabilities}, @option{-fvpt}, -@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, -@option{-ftree-vectorize}, and @option{ftree-loop-distribute-patterns}. - -Before you can use this option, you must first generate profiling information. -@xref{Optimize Options}, for information about the @option{-fprofile-generate} -option. +@item max-sched-region-insns +The maximum number of insns in a region to be considered for +interblock scheduling. The default value is 100. -By default, GCC emits an error message if the feedback profiles do not -match the source code. This error can be turned into a warning by using -@option{-Wcoverage-mismatch}. Note this may result in poorly optimized -code. +@item max-pipeline-region-insns +The maximum number of insns in a region to be considered for +pipelining in the selective scheduler. The default value is 200. -If @var{path} is specified, GCC looks at the @var{path} to find -the profile feedback data files. See @option{-fprofile-dir}. +@item min-spec-prob +The minimum probability (in percents) of reaching a source block +for interblock speculative scheduling. The default value is 40. -@item -fauto-profile -@itemx -fauto-profile=@var{path} -@opindex fauto-profile -Enable sampling-based feedback-directed optimizations, -and the following optimizations -which are generally profitable only with profile feedback available: -@option{-fbranch-probabilities}, @option{-fvpt}, -@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, -@option{-ftree-vectorize}, -@option{-finline-functions}, @option{-fipa-cp}, @option{-fipa-cp-clone}, -@option{-fpredictive-commoning}, @option{-funswitch-loops}, -@option{-fgcse-after-reload}, and @option{-ftree-loop-distribute-patterns}. +@item max-sched-extend-regions-iters +The maximum number of iterations through CFG to extend regions. +A value of 0 (the default) disables region extensions. -@var{path} is the name of a file containing AutoFDO profile information. -If omitted, it defaults to @file{fbdata.afdo} in the current directory. +@item max-sched-insn-conflict-delay +The maximum conflict delay for an insn to be considered for speculative motion. +The default value is 3. -Producing an AutoFDO profile data file requires running your program -with the @command{perf} utility on a supported GNU/Linux target system. -For more information, see @uref{https://perf.wiki.kernel.org/}. +@item sched-spec-prob-cutoff +The minimal probability of speculation success (in percents), so that +speculative insns are scheduled. +The default value is 40. -E.g. -@smallexample -perf record -e br_inst_retired:near_taken -b -o perf.data \ - -- your_program -@end smallexample +@item sched-spec-state-edge-prob-cutoff +The minimum probability an edge must have for the scheduler to save its +state across it. +The default value is 10. -Then use the @command{create_gcov} tool to convert the raw profile data -to a format that can be used by GCC.@ You must also supply the -unstripped binary for your program to this tool. -See @uref{https://github.com/google/autofdo}. +@item sched-mem-true-dep-cost +Minimal distance (in CPU cycles) between store and load targeting same +memory locations. The default value is 1. -E.g. -@smallexample -create_gcov --binary=your_program.unstripped --profile=perf.data \ - --gcov=profile.afdo -@end smallexample -@end table +@item selsched-max-lookahead +The maximum size of the lookahead window of selective scheduling. It is a +depth of search for available instructions. +The default value is 50. -The following options control compiler behavior regarding floating-point -arithmetic. These options trade off between speed and -correctness. All must be specifically enabled. +@item selsched-max-sched-times +The maximum number of times that an instruction is scheduled during +selective scheduling. This is the limit on the number of iterations +through which the instruction may be pipelined. The default value is 2. -@table @gcctabopt -@item -ffloat-store -@opindex ffloat-store -Do not store floating-point variables in registers, and inhibit other -options that might change whether a floating-point value is taken from a -register or memory. +@item selsched-max-insns-to-rename +The maximum number of best instructions in the ready list that are considered +for renaming in the selective scheduler. The default value is 2. -@cindex floating-point precision -This option prevents undesirable excess precision on machines such as -the 68000 where the floating registers (of the 68881) keep more -precision than a @code{double} is supposed to have. Similarly for the -x86 architecture. For most programs, the excess precision does only -good, but a few programs rely on the precise definition of IEEE floating -point. Use @option{-ffloat-store} for such programs, after modifying -them to store all pertinent intermediate computations into variables. +@item sms-min-sc +The minimum value of stage count that swing modulo scheduler +generates. The default value is 2. -@item -fexcess-precision=@var{style} -@opindex fexcess-precision -This option allows further control over excess precision on machines -where floating-point registers have more precision than the IEEE -@code{float} and @code{double} types and the processor does not -support operations rounding to those types. By default, -@option{-fexcess-precision=fast} is in effect; this means that -operations are carried out in the precision of the registers and that -it is unpredictable when rounding to the types specified in the source -code takes place. When compiling C, if -@option{-fexcess-precision=standard} is specified then excess -precision follows the rules specified in ISO C99; in particular, -both casts and assignments cause values to be rounded to their -semantic types (whereas @option{-ffloat-store} only affects -assignments). This option is enabled by default for C if a strict -conformance option such as @option{-std=c99} is used. +@item max-last-value-rtl +The maximum size measured as number of RTLs that can be recorded in an expression +in combiner for a pseudo register as last known value of that register. The default +is 10000. -@opindex mfpmath -@option{-fexcess-precision=standard} is not implemented for languages -other than C, and has no effect if -@option{-funsafe-math-optimizations} or @option{-ffast-math} is -specified. On the x86, it also has no effect if @option{-mfpmath=sse} -or @option{-mfpmath=sse+387} is specified; in the former case, IEEE -semantics apply without excess precision, and in the latter, rounding -is unpredictable. +@item max-combine-insns +The maximum number of instructions the RTL combiner tries to combine. +The default value is 2 at @option{-Og} and 4 otherwise. -@item -ffast-math -@opindex ffast-math -Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, -@option{-ffinite-math-only}, @option{-fno-rounding-math}, -@option{-fno-signaling-nans} and @option{-fcx-limited-range}. +@item integer-share-limit +Small integer constants can use a shared data structure, reducing the +compiler's memory usage and increasing its speed. This sets the maximum +value of a shared integer constant. The default value is 256. -This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. +@item ssp-buffer-size +The minimum size of buffers (i.e.@: arrays) that receive stack smashing +protection when @option{-fstack-protection} is used. -This option is not turned on by any @option{-O} option besides -@option{-Ofast} since it can result in incorrect output for programs -that depend on an exact implementation of IEEE or ISO rules/specifications -for math functions. It may, however, yield faster code for programs -that do not require the guarantees of these specifications. +@item min-size-for-stack-sharing +The minimum size of variables taking part in stack slot sharing when not +optimizing. The default value is 32. -@item -fno-math-errno -@opindex fno-math-errno -Do not set @code{errno} after calling math functions that are executed -with a single instruction, e.g., @code{sqrt}. A program that relies on -IEEE exceptions for math error handling may want to use this flag -for speed while maintaining IEEE arithmetic compatibility. +@item max-jump-thread-duplication-stmts +Maximum number of statements allowed in a block that needs to be +duplicated when threading jumps. -This option is not turned on by any @option{-O} option since -it can result in incorrect output for programs that depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. It may, however, yield faster code for programs -that do not require the guarantees of these specifications. +@item max-fields-for-field-sensitive +Maximum number of fields in a structure treated in +a field sensitive manner during pointer analysis. The default is zero +for @option{-O0} and @option{-O1}, +and 100 for @option{-Os}, @option{-O2}, and @option{-O3}. -The default is @option{-fmath-errno}. +@item prefetch-latency +Estimate on average number of instructions that are executed before +prefetch finishes. The distance prefetched ahead is proportional +to this constant. Increasing this number may also lead to less +streams being prefetched (see @option{simultaneous-prefetches}). -On Darwin systems, the math library never sets @code{errno}. There is -therefore no reason for the compiler to consider the possibility that -it might, and @option{-fno-math-errno} is the default. +@item simultaneous-prefetches +Maximum number of prefetches that can run at the same time. -@item -funsafe-math-optimizations -@opindex funsafe-math-optimizations +@item l1-cache-line-size +The size of cache line in L1 cache, in bytes. -Allow optimizations for floating-point arithmetic that (a) assume -that arguments and results are valid and (b) may violate IEEE or -ANSI standards. When used at link-time, it may include libraries -or startup files that change the default FPU control word or other -similar optimizations. +@item l1-cache-size +The size of L1 cache, in kilobytes. -This option is not turned on by any @option{-O} option since -it can result in incorrect output for programs that depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. It may, however, yield faster code for programs -that do not require the guarantees of these specifications. -Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math}, -@option{-fassociative-math} and @option{-freciprocal-math}. +@item l2-cache-size +The size of L2 cache, in kilobytes. -The default is @option{-fno-unsafe-math-optimizations}. +@item min-insn-to-prefetch-ratio +The minimum ratio between the number of instructions and the +number of prefetches to enable prefetching in a loop. -@item -fassociative-math -@opindex fassociative-math +@item prefetch-min-insn-to-mem-ratio +The minimum ratio between the number of instructions and the +number of memory references to enable prefetching in a loop. -Allow re-association of operands in series of floating-point operations. -This violates the ISO C and C++ language standard by possibly changing -computation result. NOTE: re-ordering may change the sign of zero as -well as ignore NaNs and inhibit or create underflow or overflow (and -thus cannot be used on code that relies on rounding behavior like -@code{(x + 2**52) - 2**52}. May also reorder floating-point comparisons -and thus may not be used when ordered comparisons are required. -This option requires that both @option{-fno-signed-zeros} and -@option{-fno-trapping-math} be in effect. Moreover, it doesn't make -much sense with @option{-frounding-math}. For Fortran the option -is automatically enabled when both @option{-fno-signed-zeros} and -@option{-fno-trapping-math} are in effect. +@item use-canonical-types +Whether the compiler should use the ``canonical'' type system. By +default, this should always be 1, which uses a more efficient internal +mechanism for comparing types in C++ and Objective-C++. However, if +bugs in the canonical type system are causing compilation failures, +set this value to 0 to disable canonical types. -The default is @option{-fno-associative-math}. +@item switch-conversion-max-branch-ratio +Switch initialization conversion refuses to create arrays that are +bigger than @option{switch-conversion-max-branch-ratio} times the number of +branches in the switch. -@item -freciprocal-math -@opindex freciprocal-math +@item max-partial-antic-length +Maximum length of the partial antic set computed during the tree +partial redundancy elimination optimization (@option{-ftree-pre}) when +optimizing at @option{-O3} and above. For some sorts of source code +the enhanced partial redundancy elimination optimization can run away, +consuming all of the memory available on the host machine. This +parameter sets a limit on the length of the sets that are computed, +which prevents the runaway behavior. Setting a value of 0 for +this parameter allows an unlimited set length. -Allow the reciprocal of a value to be used instead of dividing by -the value if this enables optimizations. For example @code{x / y} -can be replaced with @code{x * (1/y)}, which is useful if @code{(1/y)} -is subject to common subexpression elimination. Note that this loses -precision and increases the number of flops operating on the value. +@item sccvn-max-scc-size +Maximum size of a strongly connected component (SCC) during SCCVN +processing. If this limit is hit, SCCVN processing for the whole +function is not done and optimizations depending on it are +disabled. The default maximum SCC size is 10000. -The default is @option{-fno-reciprocal-math}. - -@item -ffinite-math-only -@opindex ffinite-math-only -Allow optimizations for floating-point arithmetic that assume -that arguments and results are not NaNs or +-Infs. +@item sccvn-max-alias-queries-per-access +Maximum number of alias-oracle queries we perform when looking for +redundancies for loads and stores. If this limit is hit the search +is aborted and the load or store is not considered redundant. The +number of queries is algorithmically limited to the number of +stores on all paths from the load to the function entry. +The default maxmimum number of queries is 1000. -This option is not turned on by any @option{-O} option since -it can result in incorrect output for programs that depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. It may, however, yield faster code for programs -that do not require the guarantees of these specifications. +@item ira-max-loops-num +IRA uses regional register allocation by default. If a function +contains more loops than the number given by this parameter, only at most +the given number of the most frequently-executed loops form regions +for regional register allocation. The default value of the +parameter is 100. -The default is @option{-fno-finite-math-only}. +@item ira-max-conflict-table-size +Although IRA uses a sophisticated algorithm to compress the conflict +table, the table can still require excessive amounts of memory for +huge functions. If the conflict table for a function could be more +than the size in MB given by this parameter, the register allocator +instead uses a faster, simpler, and lower-quality +algorithm that does not require building a pseudo-register conflict table. +The default value of the parameter is 2000. -@item -fno-signed-zeros -@opindex fno-signed-zeros -Allow optimizations for floating-point arithmetic that ignore the -signedness of zero. IEEE arithmetic specifies the behavior of -distinct +0.0 and @minus{}0.0 values, which then prohibits simplification -of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}). -This option implies that the sign of a zero result isn't significant. +@item ira-loop-reserved-regs +IRA can be used to evaluate more accurate register pressure in loops +for decisions to move loop invariants (see @option{-O3}). The number +of available registers reserved for some other purposes is given +by this parameter. The default value of the parameter is 2, which is +the minimal number of registers needed by typical instructions. +This value is the best found from numerous experiments. -The default is @option{-fsigned-zeros}. +@item lra-inheritance-ebb-probability-cutoff +LRA tries to reuse values reloaded in registers in subsequent insns. +This optimization is called inheritance. EBB is used as a region to +do this optimization. The parameter defines a minimal fall-through +edge probability in percentage used to add BB to inheritance EBB in +LRA. The default value of the parameter is 40. The value was chosen +from numerous runs of SPEC2000 on x86-64. -@item -fno-trapping-math -@opindex fno-trapping-math -Compile code assuming that floating-point operations cannot generate -user-visible traps. These traps include division by zero, overflow, -underflow, inexact result and invalid operation. This option requires -that @option{-fno-signaling-nans} be in effect. Setting this option may -allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example. +@item loop-invariant-max-bbs-in-loop +Loop invariant motion can be very expensive, both in compilation time and +in amount of needed compile-time memory, with very large loops. Loops +with more basic blocks than this parameter won't have loop invariant +motion optimization performed on them. The default value of the +parameter is 1000 for @option{-O1} and 10000 for @option{-O2} and above. -This option should never be turned on by any @option{-O} option since -it can result in incorrect output for programs that depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. +@item loop-max-datarefs-for-datadeps +Building data dapendencies is expensive for very large loops. This +parameter limits the number of data references in loops that are +considered for data dependence analysis. These large loops are no +handled by the optimizations using loop data dependencies. +The default value is 1000. -The default is @option{-ftrapping-math}. +@item max-vartrack-size +Sets a maximum number of hash table slots to use during variable +tracking dataflow analysis of any function. If this limit is exceeded +with variable tracking at assignments enabled, analysis for that +function is retried without it, after removing all debug insns from +the function. If the limit is exceeded even without debug insns, var +tracking analysis is completely disabled for the function. Setting +the parameter to zero makes it unlimited. -@item -frounding-math -@opindex frounding-math -Disable transformations and optimizations that assume default floating-point -rounding behavior. This is round-to-zero for all floating point -to integer conversions, and round-to-nearest for all other arithmetic -truncations. This option should be specified for programs that change -the FP rounding mode dynamically, or that may be executed with a -non-default rounding mode. This option disables constant folding of -floating-point expressions at compile time (which may be affected by -rounding mode) and arithmetic transformations that are unsafe in the -presence of sign-dependent rounding modes. +@item max-vartrack-expr-depth +Sets a maximum number of recursion levels when attempting to map +variable names or debug temporaries to value expressions. This trades +compilation time for more complete debug information. If this is set too +low, value expressions that are available and could be represented in +debug information may end up not being used; setting this higher may +enable the compiler to find more complex debug expressions, but compile +time and memory use may grow. The default is 12. -The default is @option{-fno-rounding-math}. +@item min-nondebug-insn-uid +Use uids starting at this parameter for nondebug insns. The range below +the parameter is reserved exclusively for debug insns created by +@option{-fvar-tracking-assignments}, but debug insns may get +(non-overlapping) uids above it if the reserved range is exhausted. -This option is experimental and does not currently guarantee to -disable all GCC optimizations that are affected by rounding mode. -Future versions of GCC may provide finer control of this setting -using C99's @code{FENV_ACCESS} pragma. This command-line option -will be used to specify the default state for @code{FENV_ACCESS}. +@item ipa-sra-ptr-growth-factor +IPA-SRA replaces a pointer to an aggregate with one or more new +parameters only when their cumulative size is less or equal to +@option{ipa-sra-ptr-growth-factor} times the size of the original +pointer parameter. -@item -fsignaling-nans -@opindex fsignaling-nans -Compile code assuming that IEEE signaling NaNs may generate user-visible -traps during floating-point operations. Setting this option disables -optimizations that may change the number of exceptions visible with -signaling NaNs. This option implies @option{-ftrapping-math}. +@item sra-max-scalarization-size-Ospeed +@item sra-max-scalarization-size-Osize +The two Scalar Reduction of Aggregates passes (SRA and IPA-SRA) aim to +replace scalar parts of aggregates with uses of independent scalar +variables. These parameters control the maximum size, in storage units, +of aggregate which is considered for replacement when compiling for +speed +(@option{sra-max-scalarization-size-Ospeed}) or size +(@option{sra-max-scalarization-size-Osize}) respectively. -This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to -be defined. +@item tm-max-aggregate-size +When making copies of thread-local variables in a transaction, this +parameter specifies the size in bytes after which variables are +saved with the logging functions as opposed to save/restore code +sequence pairs. This option only applies when using +@option{-fgnu-tm}. -The default is @option{-fno-signaling-nans}. +@item graphite-max-nb-scop-params +To avoid exponential effects in the Graphite loop transforms, the +number of parameters in a Static Control Part (SCoP) is bounded. The +default value is 10 parameters. A variable whose value is unknown at +compilation time and defined outside a SCoP is a parameter of the SCoP. -This option is experimental and does not currently guarantee to -disable all GCC optimizations that affect signaling NaN behavior. +@item graphite-max-bbs-per-function +To avoid exponential effects in the detection of SCoPs, the size of +the functions analyzed by Graphite is bounded. The default value is +100 basic blocks. -@item -fsingle-precision-constant -@opindex fsingle-precision-constant -Treat floating-point constants as single precision instead of -implicitly converting them to double-precision constants. +@item loop-block-tile-size +Loop blocking or strip mining transforms, enabled with +@option{-floop-block} or @option{-floop-strip-mine}, strip mine each +loop in the loop nest by a given number of iterations. The strip +length can be changed using the @option{loop-block-tile-size} +parameter. The default value is 51 iterations. -@item -fcx-limited-range -@opindex fcx-limited-range -When enabled, this option states that a range reduction step is not -needed when performing complex division. Also, there is no checking -whether the result of a complex multiplication or division is @code{NaN -+ I*NaN}, with an attempt to rescue the situation in that case. The -default is @option{-fno-cx-limited-range}, but is enabled by -@option{-ffast-math}. +@item loop-unroll-jam-size +Specify the unroll factor for the @option{-floop-unroll-and-jam} option. The +default value is 4. -This option controls the default setting of the ISO C99 -@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to -all languages. +@item loop-unroll-jam-depth +Specify the dimension to be unrolled (counting from the most inner loop) +for the @option{-floop-unroll-and-jam}. The default value is 2. -@item -fcx-fortran-rules -@opindex fcx-fortran-rules -Complex multiplication and division follow Fortran rules. Range -reduction is done as part of complex division, but there is no checking -whether the result of a complex multiplication or division is @code{NaN -+ I*NaN}, with an attempt to rescue the situation in that case. +@item ipa-cp-value-list-size +IPA-CP attempts to track all possible values and types passed to a function's +parameter in order to propagate them and perform devirtualization. +@option{ipa-cp-value-list-size} is the maximum number of values and types it +stores per one formal parameter of a function. -The default is @option{-fno-cx-fortran-rules}. +@item ipa-cp-eval-threshold +IPA-CP calculates its own score of cloning profitability heuristics +and performs those cloning opportunities with scores that exceed +@option{ipa-cp-eval-threshold}. -@end table +@item ipa-cp-recursion-penalty +Percentage penalty the recursive functions will receive when they +are evaluated for cloning. -The following options control optimizations that may improve -performance, but are not enabled by any @option{-O} options. This -section includes experimental options that may produce broken code. +@item ipa-cp-single-call-penalty +Percentage penalty functions containg a single call to another +function will receive when they are evaluated for cloning. -@table @gcctabopt -@item -fbranch-probabilities -@opindex fbranch-probabilities -After running a program compiled with @option{-fprofile-arcs} -(@pxref{Instrumentation Options}), -you can compile it a second time using -@option{-fbranch-probabilities}, to improve optimizations based on -the number of times each branch was taken. When a program -compiled with @option{-fprofile-arcs} exits, it saves arc execution -counts to a file called @file{@var{sourcename}.gcda} for each source -file. The information in this data file is very dependent on the -structure of the generated code, so you must use the same source code -and the same optimization options for both compilations. -With @option{-fbranch-probabilities}, GCC puts a -@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. -These can be used to improve optimization. Currently, they are only -used in one place: in @file{reorg.c}, instead of guessing which path a -branch is most likely to take, the @samp{REG_BR_PROB} values are used to -exactly determine which path is taken more often. +@item ipa-max-agg-items +IPA-CP is also capable to propagate a number of scalar values passed +in an aggregate. @option{ipa-max-agg-items} controls the maximum +number of such values per one parameter. -@item -fprofile-values -@opindex fprofile-values -If combined with @option{-fprofile-arcs}, it adds code so that some -data about values of expressions in the program is gathered. +@item ipa-cp-loop-hint-bonus +When IPA-CP determines that a cloning candidate would make the number +of iterations of a loop known, it adds a bonus of +@option{ipa-cp-loop-hint-bonus} to the profitability score of +the candidate. -With @option{-fbranch-probabilities}, it reads back the data gathered -from profiling values of expressions for usage in optimizations. +@item ipa-cp-array-index-hint-bonus +When IPA-CP determines that a cloning candidate would make the index of +an array access known, it adds a bonus of +@option{ipa-cp-array-index-hint-bonus} to the profitability +score of the candidate. -Enabled with @option{-fprofile-generate} and @option{-fprofile-use}. +@item ipa-max-aa-steps +During its analysis of function bodies, IPA-CP employs alias analysis +in order to track values pointed to by function parameters. In order +not spend too much time analyzing huge functions, it gives up and +consider all memory clobbered after examining +@option{ipa-max-aa-steps} statements modifying memory. -@item -fprofile-reorder-functions -@opindex fprofile-reorder-functions -Function reordering based on profile instrumentation collects -first time of execution of a function and orders these functions -in ascending order. +@item lto-partitions +Specify desired number of partitions produced during WHOPR compilation. +The number of partitions should exceed the number of CPUs used for compilation. +The default value is 32. -Enabled with @option{-fprofile-use}. +@item lto-minpartition +Size of minimal partition for WHOPR (in estimated instructions). +This prevents expenses of splitting very small programs into too many +partitions. -@item -fvpt -@opindex fvpt -If combined with @option{-fprofile-arcs}, this option instructs the compiler -to add code to gather information about values of expressions. +@item cxx-max-namespaces-for-diagnostic-help +The maximum number of namespaces to consult for suggestions when C++ +name lookup fails for an identifier. The default is 1000. -With @option{-fbranch-probabilities}, it reads back the data gathered -and actually performs the optimizations based on them. -Currently the optimizations include specialization of division operations -using the knowledge about the value of the denominator. +@item sink-frequency-threshold +The maximum relative execution frequency (in percents) of the target block +relative to a statement's original block to allow statement sinking of a +statement. Larger numbers result in more aggressive statement sinking. +The default value is 75. A small positive adjustment is applied for +statements with memory operands as those are even more profitable so sink. -@item -frename-registers -@opindex frename-registers -Attempt to avoid false dependencies in scheduled code by making use -of registers left over after register allocation. This optimization -most benefits processors with lots of registers. Depending on the -debug information format adopted by the target, however, it can -make debugging impossible, since variables no longer stay in -a ``home register''. +@item max-stores-to-sink +The maximum number of conditional stores paires that can be sunk. Set to 0 +if either vectorization (@option{-ftree-vectorize}) or if-conversion +(@option{-ftree-loop-if-convert}) is disabled. The default is 2. -Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}. +@item allow-store-data-races +Allow optimizers to introduce new data races on stores. +Set to 1 to allow, otherwise to 0. This option is enabled by default +at optimization level @option{-Ofast}. -@item -fschedule-fusion -@opindex fschedule-fusion -Performs a target dependent pass over the instruction stream to schedule -instructions of same type together because target machine can execute them -more efficiently if they are adjacent to each other in the instruction flow. +@item case-values-threshold +The smallest number of different values for which it is best to use a +jump-table instead of a tree of conditional branches. If the value is +0, use the default for the machine. The default is 0. -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item tree-reassoc-width +Set the maximum number of instructions executed in parallel in +reassociated tree. This parameter overrides target dependent +heuristics used by default if has non zero value. -@item -ftracer -@opindex ftracer -Perform tail duplication to enlarge superblock size. This transformation -simplifies the control flow of the function allowing other optimizations to do -a better job. +@item sched-pressure-algorithm +Choose between the two available implementations of +@option{-fsched-pressure}. Algorithm 1 is the original implementation +and is the more likely to prevent instructions from being reordered. +Algorithm 2 was designed to be a compromise between the relatively +conservative approach taken by algorithm 1 and the rather aggressive +approach taken by the default scheduler. It relies more heavily on +having a regular register file and accurate register pressure classes. +See @file{haifa-sched.c} in the GCC sources for more details. -Enabled with @option{-fprofile-use}. +The default choice depends on the target. -@item -funroll-loops -@opindex funroll-loops -Unroll loops whose number of iterations can be determined at compile time or -upon entry to the loop. @option{-funroll-loops} implies -@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}. -It also turns on complete loop peeling (i.e.@: complete removal of loops with -a small constant number of iterations). This option makes code larger, and may -or may not make it run faster. +@item max-slsr-cand-scan +Set the maximum number of existing candidates that are considered when +seeking a basis for a new straight-line strength reduction candidate. -Enabled with @option{-fprofile-use}. +@item asan-globals +Enable buffer overflow detection for global objects. This kind +of protection is enabled by default if you are using +@option{-fsanitize=address} option. +To disable global objects protection use @option{--param asan-globals=0}. -@item -funroll-all-loops -@opindex funroll-all-loops -Unroll all loops, even if their number of iterations is uncertain when -the loop is entered. This usually makes programs run more slowly. -@option{-funroll-all-loops} implies the same options as -@option{-funroll-loops}. +@item asan-stack +Enable buffer overflow detection for stack objects. This kind of +protection is enabled by default when using @option{-fsanitize=address}. +To disable stack protection use @option{--param asan-stack=0} option. -@item -fpeel-loops -@opindex fpeel-loops -Peels loops for which there is enough information that they do not -roll much (from profile feedback). It also turns on complete loop peeling -(i.e.@: complete removal of loops with small constant number of iterations). +@item asan-instrument-reads +Enable buffer overflow detection for memory reads. This kind of +protection is enabled by default when using @option{-fsanitize=address}. +To disable memory reads protection use +@option{--param asan-instrument-reads=0}. -Enabled with @option{-fprofile-use}. +@item asan-instrument-writes +Enable buffer overflow detection for memory writes. This kind of +protection is enabled by default when using @option{-fsanitize=address}. +To disable memory writes protection use +@option{--param asan-instrument-writes=0} option. -@item -fmove-loop-invariants -@opindex fmove-loop-invariants -Enables the loop invariant motion pass in the RTL loop optimizer. Enabled -at level @option{-O1} +@item asan-memintrin +Enable detection for built-in functions. This kind of protection +is enabled by default when using @option{-fsanitize=address}. +To disable built-in functions protection use +@option{--param asan-memintrin=0}. -@item -funswitch-loops -@opindex funswitch-loops -Move branches with loop invariant conditions out of the loop, with duplicates -of the loop on both branches (modified according to result of the condition). +@item asan-use-after-return +Enable detection of use-after-return. This kind of protection +is enabled by default when using @option{-fsanitize=address} option. +To disable use-after-return detection use +@option{--param asan-use-after-return=0}. -@item -ffunction-sections -@itemx -fdata-sections -@opindex ffunction-sections -@opindex fdata-sections -Place each function or data item into its own section in the output -file if the target supports arbitrary sections. The name of the -function or the name of the data item determines the section's name -in the output file. +@item asan-instrumentation-with-call-threshold +If number of memory accesses in function being instrumented +is greater or equal to this number, use callbacks instead of inline checks. +E.g. to disable inline code use +@option{--param asan-instrumentation-with-call-threshold=0}. -Use these options on systems where the linker can perform optimizations -to improve locality of reference in the instruction space. Most systems -using the ELF object format and SPARC processors running Solaris 2 have -linkers with such optimizations. AIX may have these optimizations in -the future. +@item chkp-max-ctor-size +Static constructors generated by Pointer Bounds Checker may become very +large and significantly increase compile time at optimization level +@option{-O1} and higher. This parameter is a maximum nubmer of statements +in a single generated constructor. Default value is 5000. -Only use these options when there are significant benefits from doing -so. When you specify these options, the assembler and linker -create larger object and executable files and are also slower. -You cannot use @command{gprof} on all systems if you -specify this option, and you may have problems with debugging if -you specify both this option and @option{-g}. +@item max-fsm-thread-path-insns +Maximum number of instructions to copy when duplicating blocks on a +finite state automaton jump thread path. The default is 100. -@item -fbranch-target-load-optimize -@opindex fbranch-target-load-optimize -Perform branch target register load optimization before prologue / epilogue -threading. -The use of target registers can typically be exposed only during reload, -thus hoisting loads out of loops and doing inter-block scheduling needs -a separate optimization pass. +@item max-fsm-thread-length +Maximum number of basic blocks on a finite state automaton jump thread +path. The default is 10. -@item -fbranch-target-load-optimize2 -@opindex fbranch-target-load-optimize2 -Perform branch target register load optimization after prologue / epilogue -threading. +@item max-fsm-thread-paths +Maximum number of new jump thread paths to create for a finite state +automaton. The default is 50. -@item -fbtr-bb-exclusive -@opindex fbtr-bb-exclusive -When performing branch target register load optimization, don't reuse -branch target registers within any basic block. +@item parloops-chunk-size +Chunk size of omp schedule for loops parallelized by parloops. The default +is 0. -@item -fstdarg-opt -@opindex fstdarg-opt -Optimize the prologue of variadic argument functions with respect to usage of -those arguments. +@item parloops-schedule +Schedule type of omp schedule for loops parallelized by parloops (static, +dynamic, guided, auto, runtime). The default is static. -@item -fsection-anchors -@opindex fsection-anchors -Try to reduce the number of symbolic address calculations by using -shared ``anchor'' symbols to address nearby objects. This transformation -can help to reduce the number of GOT entries and GOT accesses on some -targets. +@item max-ssa-name-query-depth +Maximum depth of recursion when querying properties of SSA names in things +like fold routines. One level of recursion corresponds to following a +use-def chain. +@end table +@end table -For example, the implementation of the following function @code{foo}: +@node Instrumentation Options +@section Program Instrumentation Options +@cindex instrumentation options +@cindex program instrumentation options +@cindex run-time error checking options +@cindex profiling options +@cindex options, program instrumentation +@cindex options, run-time error checking +@cindex options, profiling -@smallexample -static int a, b, c; -int foo (void) @{ return a + b + c; @} -@end smallexample +GCC supports a number of command-line options that control adding +run-time instrumentation to the code it normally generates. +For example, one purpose of instrumentation is collect profiling +statistics for use in finding program hot spots, code coverage +analysis, or profile-guided optimizations. +Another class of program instrumentation is adding run-time checking +to detect programming errors like invalid pointer +dereferences or out-of-bounds array accesses, as well as deliberately +hostile attacks such as stack smashing or C++ vtable hijacking. +There is also a general hook which can be used to implement other +forms of tracing or function-level instrumentation for debug or +program analysis purposes. -@noindent -usually calculates the addresses of all three variables, but if you -compile it with @option{-fsection-anchors}, it accesses the variables -from a common anchor point instead. The effect is similar to the -following pseudocode (which isn't valid C): +@table @gcctabopt +@cindex @command{prof} +@item -p +@opindex p +Generate extra code to write profile information suitable for the +analysis program @command{prof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. -@smallexample -int foo (void) -@{ - register int *xr = &x; - return xr[&a - &x] + xr[&b - &x] + xr[&c - &x]; -@} -@end smallexample +@cindex @command{gprof} +@item -pg +@opindex pg +Generate extra code to write profile information suitable for the +analysis program @command{gprof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. -Not all targets support this option. +@item -fprofile-arcs +@opindex fprofile-arcs +Add code so that program flow @dfn{arcs} are instrumented. During +execution the program records how many times each branch and call is +executed and how many times it is taken or returns. When the compiled +program exits it saves this data to a file called +@file{@var{auxname}.gcda} for each source file. The data may be used for +profile-directed optimizations (@option{-fbranch-probabilities}), or for +test coverage analysis (@option{-ftest-coverage}). Each object file's +@var{auxname} is generated from the name of the output file, if +explicitly specified and it is not the final executable, otherwise it is +the basename of the source file. In both cases any suffix is removed +(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or +@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}). +@xref{Cross-profiling}. -@item --param @var{name}=@var{value} -@opindex param -In some places, GCC uses various constants to control the amount of -optimization that is done. For example, GCC does not inline functions -that contain more than a certain number of instructions. You can -control some of these constants on the command line using the -@option{--param} option. +@cindex @command{gcov} +@item --coverage +@opindex coverage -The names of specific parameters, and the meaning of the values, are -tied to the internals of the compiler, and are subject to change -without notice in future releases. +This option is used to compile and link code instrumented for coverage +analysis. The option is a synonym for @option{-fprofile-arcs} +@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when +linking). See the documentation for those options for more details. -In each case, the @var{value} is an integer. The allowable choices for -@var{name} are: +@itemize -@table @gcctabopt -@item predictable-branch-outcome -When branch is predicted to be taken with probability lower than this threshold -(in percent), then it is considered well predictable. The default is 10. +@item +Compile the source files with @option{-fprofile-arcs} plus optimization +and code generation options. For test coverage analysis, use the +additional @option{-ftest-coverage} option. You do not need to profile +every source file in a program. -@item max-rtl-if-conversion-insns -RTL if-conversion tries to remove conditional branches around a block and -replace them with conditionally executed instructions. This parameter -gives the maximum number of instructions in a block which should be -considered for if-conversion. The default is 10, though the compiler will -also use other heuristics to decide whether if-conversion is likely to be -profitable. +@item +Link your object files with @option{-lgcov} or @option{-fprofile-arcs} +(the latter implies the former). -@item max-crossjump-edges -The maximum number of incoming edges to consider for cross-jumping. -The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in -the number of edges incoming to each block. Increasing values mean -more aggressive optimization, making the compilation time increase with -probably small improvement in executable size. +@item +Run the program on a representative workload to generate the arc profile +information. This may be repeated any number of times. You can run +concurrent instances of your program, and provided that the file system +supports locking, the data files will be correctly updated. Also +@code{fork} calls are detected and correctly handled (double counting +will not happen). -@item min-crossjump-insns -The minimum number of instructions that must be matched at the end -of two blocks before cross-jumping is performed on them. This -value is ignored in the case where all instructions in the block being -cross-jumped from are matched. The default value is 5. +@item +For profile-directed optimizations, compile the source files again with +the same optimization and code generation options plus +@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that +Control Optimization}). -@item max-grow-copy-bb-insns -The maximum code size expansion factor when copying basic blocks -instead of jumping. The expansion is relative to a jump instruction. -The default value is 8. +@item +For test coverage analysis, use @command{gcov} to produce human readable +information from the @file{.gcno} and @file{.gcda} files. Refer to the +@command{gcov} documentation for further information. -@item max-goto-duplication-insns -The maximum number of instructions to duplicate to a block that jumps -to a computed goto. To avoid @math{O(N^2)} behavior in a number of -passes, GCC factors computed gotos early in the compilation process, -and unfactors them as late as possible. Only computed jumps at the -end of a basic blocks with no more than max-goto-duplication-insns are -unfactored. The default value is 8. +@end itemize -@item max-delay-slot-insn-search -The maximum number of instructions to consider when looking for an -instruction to fill a delay slot. If more than this arbitrary number of -instructions are searched, the time savings from filling the delay slot -are minimal, so stop searching. Increasing values mean more -aggressive optimization, making the compilation time increase with probably -small improvement in execution time. +With @option{-fprofile-arcs}, for each function of your program GCC +creates a program flow graph, then finds a spanning tree for the graph. +Only arcs that are not on the spanning tree have to be instrumented: the +compiler adds code to count the number of times that these arcs are +executed. When an arc is the only exit or only entrance to a block, the +instrumentation code can be added to the block; otherwise, a new basic +block must be created to hold the instrumentation code. -@item max-delay-slot-live-search -When trying to fill delay slots, the maximum number of instructions to -consider when searching for a block with valid live register -information. Increasing this arbitrarily chosen value means more -aggressive optimization, increasing the compilation time. This parameter -should be removed when the delay slot code is rewritten to maintain the -control-flow graph. +@need 2000 +@item -ftest-coverage +@opindex ftest-coverage +Produce a notes file that the @command{gcov} code-coverage utility +(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to +show program coverage. Each source file's note file is called +@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option +above for a description of @var{auxname} and instructions on how to +generate test coverage data. Coverage data matches the source files +more closely if you do not optimize. -@item max-gcse-memory -The approximate maximum amount of memory that can be allocated in -order to perform the global common subexpression elimination -optimization. If more memory than specified is required, the -optimization is not done. +@item -fprofile-dir=@var{path} +@opindex fprofile-dir -@item max-gcse-insertion-ratio -If the ratio of expression insertions to deletions is larger than this value -for any expression, then RTL PRE inserts or removes the expression and thus -leaves partially redundant computations in the instruction stream. The default value is 20. +Set the directory to search for the profile data files in to @var{path}. +This option affects only the profile data generated by +@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs} +and used by @option{-fprofile-use} and @option{-fbranch-probabilities} +and its related options. Both absolute and relative paths can be used. +By default, GCC uses the current directory as @var{path}, thus the +profile data file appears in the same directory as the object file. -@item max-pending-list-length -The maximum number of pending dependencies scheduling allows -before flushing the current state and starting over. Large functions -with few branches or calls can create excessively large lists which -needlessly consume memory and resources. +@item -fprofile-generate +@itemx -fprofile-generate=@var{path} +@opindex fprofile-generate -@item max-modulo-backtrack-attempts -The maximum number of backtrack attempts the scheduler should make -when modulo scheduling a loop. Larger values can exponentially increase -compilation time. +Enable options usually used for instrumenting application to produce +profile useful for later recompilation with profile feedback based +optimization. You must use @option{-fprofile-generate} both when +compiling and when linking your program. -@item max-inline-insns-single -Several parameters control the tree inliner used in GCC@. -This number sets the maximum number of instructions (counted in GCC's -internal representation) in a single function that the tree inliner -considers for inlining. This only affects functions declared -inline and methods implemented in a class declaration (C++). -The default value is 400. +The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}. -@item max-inline-insns-auto -When you use @option{-finline-functions} (included in @option{-O3}), -a lot of functions that would otherwise not be considered for inlining -by the compiler are investigated. To those functions, a different -(more restrictive) limit compared to functions declared inline can -be applied. -The default value is 40. +If @var{path} is specified, GCC looks at the @var{path} to find +the profile feedback data files. See @option{-fprofile-dir}. -@item inline-min-speedup -When estimated performance improvement of caller + callee runtime exceeds this -threshold (in precent), the function can be inlined regardless the limit on -@option{--param max-inline-insns-single} and @option{--param -max-inline-insns-auto}. +To optimize the program based on the collected profile information, use +@option{-fprofile-use}. @xref{Optimize Options}, for more information. -@item large-function-insns -The limit specifying really large functions. For functions larger than this -limit after inlining, inlining is constrained by -@option{--param large-function-growth}. This parameter is useful primarily -to avoid extreme compilation time caused by non-linear algorithms used by the -back end. -The default value is 2700. +@item -fsanitize=address +@opindex fsanitize=address +Enable AddressSanitizer, a fast memory error detector. +Memory access instructions are instrumented to detect +out-of-bounds and use-after-free bugs. +See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for +more details. The run-time behavior can be influenced using the +@env{ASAN_OPTIONS} environment variable. When set to @code{help=1}, +the available options are shown at startup of the instrumended program. See +@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags} +for a list of supported options. -@item large-function-growth -Specifies maximal growth of large function caused by inlining in percents. -The default value is 100 which limits large function growth to 2.0 times -the original size. +@item -fsanitize=kernel-address +@opindex fsanitize=kernel-address +Enable AddressSanitizer for Linux kernel. +See @uref{https://github.com/google/kasan/wiki} for more details. -@item large-unit-insns -The limit specifying large translation unit. Growth caused by inlining of -units larger than this limit is limited by @option{--param inline-unit-growth}. -For small units this might be too tight. -For example, consider a unit consisting of function A -that is inline and B that just calls A three times. If B is small relative to -A, the growth of unit is 300\% and yet such inlining is very sane. For very -large units consisting of small inlineable functions, however, the overall unit -growth limit is needed to avoid exponential explosion of code size. Thus for -smaller units, the size is increased to @option{--param large-unit-insns} -before applying @option{--param inline-unit-growth}. The default is 10000. +@item -fsanitize=thread +@opindex fsanitize=thread +Enable ThreadSanitizer, a fast data race detector. +Memory access instructions are instrumented to detect +data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more +details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS} +environment variable; see +@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of +supported options. -@item inline-unit-growth -Specifies maximal overall growth of the compilation unit caused by inlining. -The default value is 20 which limits unit growth to 1.2 times the original -size. Cold functions (either marked cold via an attribute or by profile -feedback) are not accounted into the unit size. +@item -fsanitize=leak +@opindex fsanitize=leak +Enable LeakSanitizer, a memory leak detector. +This option only matters for linking of executables and if neither +@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that +case the executable is linked against a library that overrides @code{malloc} +and other allocator functions. See +@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more +details. The run-time behavior can be influenced using the +@env{LSAN_OPTIONS} environment variable. -@item ipcp-unit-growth -Specifies maximal overall growth of the compilation unit caused by -interprocedural constant propagation. The default value is 10 which limits -unit growth to 1.1 times the original size. - -@item large-stack-frame -The limit specifying large stack frames. While inlining the algorithm is trying -to not grow past this limit too much. The default value is 256 bytes. - -@item large-stack-frame-growth -Specifies maximal growth of large stack frames caused by inlining in percents. -The default value is 1000 which limits large stack frame growth to 11 times -the original size. +@item -fsanitize=undefined +@opindex fsanitize=undefined +Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. +Various computations are instrumented to detect undefined behavior +at runtime. Current suboptions are: -@item max-inline-insns-recursive -@itemx max-inline-insns-recursive-auto -Specifies the maximum number of instructions an out-of-line copy of a -self-recursive inline -function can grow into by performing recursive inlining. +@table @gcctabopt -@option{--param max-inline-insns-recursive} applies to functions -declared inline. -For functions not declared inline, recursive inlining -happens only when @option{-finline-functions} (included in @option{-O3}) is -enabled; @option{--param max-inline-insns-recursive-auto} applies instead. The -default value is 450. +@item -fsanitize=shift +@opindex fsanitize=shift +This option enables checking that the result of a shift operation is +not undefined. Note that what exactly is considered undefined differs +slightly between C and C++, as well as between ISO C90 and C99, etc. -@item max-inline-recursive-depth -@itemx max-inline-recursive-depth-auto -Specifies the maximum recursion depth used for recursive inlining. +@item -fsanitize=integer-divide-by-zero +@opindex fsanitize=integer-divide-by-zero +Detect integer division by zero as well as @code{INT_MIN / -1} division. -@option{--param max-inline-recursive-depth} applies to functions -declared inline. For functions not declared inline, recursive inlining -happens only when @option{-finline-functions} (included in @option{-O3}) is -enabled; @option{--param max-inline-recursive-depth-auto} applies instead. The -default value is 8. +@item -fsanitize=unreachable +@opindex fsanitize=unreachable +With this option, the compiler turns the @code{__builtin_unreachable} +call into a diagnostics message call instead. When reaching the +@code{__builtin_unreachable} call, the behavior is undefined. -@item min-inline-recursive-probability -Recursive inlining is profitable only for function having deep recursion -in average and can hurt for function having little recursion depth by -increasing the prologue size or complexity of function body to other -optimizers. +@item -fsanitize=vla-bound +@opindex fsanitize=vla-bound +This option instructs the compiler to check that the size of a variable +length array is positive. -When profile feedback is available (see @option{-fprofile-generate}) the actual -recursion depth can be guessed from probability that function recurses via a -given call expression. This parameter limits inlining only to call expressions -whose probability exceeds the given threshold (in percents). -The default value is 10. +@item -fsanitize=null +@opindex fsanitize=null +This option enables pointer checking. Particularly, the application +built with this option turned on will issue an error message when it +tries to dereference a NULL pointer, or if a reference (possibly an +rvalue reference) is bound to a NULL pointer, or if a method is invoked +on an object pointed by a NULL pointer. -@item early-inlining-insns -Specify growth that the early inliner can make. In effect it increases -the amount of inlining for code having a large abstraction penalty. -The default value is 14. +@item -fsanitize=return +@opindex fsanitize=return +This option enables return statement checking. Programs +built with this option turned on will issue an error message +when the end of a non-void function is reached without actually +returning a value. This option works in C++ only. -@item max-early-inliner-iterations -Limit of iterations of the early inliner. This basically bounds -the number of nested indirect calls the early inliner can resolve. -Deeper chains are still handled by late inlining. +@item -fsanitize=signed-integer-overflow +@opindex fsanitize=signed-integer-overflow +This option enables signed integer overflow checking. We check that +the result of @code{+}, @code{*}, and both unary and binary @code{-} +does not overflow in the signed arithmetics. Note, integer promotion +rules must be taken into account. That is, the following is not an +overflow: +@smallexample +signed char a = SCHAR_MAX; +a++; +@end smallexample -@item comdat-sharing-probability -Probability (in percent) that C++ inline function with comdat visibility -are shared across multiple compilation units. The default value is 20. +@item -fsanitize=bounds +@opindex fsanitize=bounds +This option enables instrumentation of array bounds. Various out of bounds +accesses are detected. Flexible array members, flexible array member-like +arrays, and initializers of variables with static storage are not instrumented. -@item profile-func-internal-id -A parameter to control whether to use function internal id in profile -database lookup. If the value is 0, the compiler uses an id that -is based on function assembler name and filename, which makes old profile -data more tolerant to source changes such as function reordering etc. -The default value is 0. +@item -fsanitize=bounds-strict +@opindex fsanitize=bounds-strict +This option enables strict instrumentation of array bounds. Most out of bounds +accesses are detected, including flexible array members and flexible array +member-like arrays. Initializers of variables with static storage are not +instrumented. -@item min-vect-loop-bound -The minimum number of iterations under which loops are not vectorized -when @option{-ftree-vectorize} is used. The number of iterations after -vectorization needs to be greater than the value specified by this option -to allow vectorization. The default value is 0. +@item -fsanitize=alignment +@opindex fsanitize=alignment -@item gcse-cost-distance-ratio -Scaling factor in calculation of maximum distance an expression -can be moved by GCSE optimizations. This is currently supported only in the -code hoisting pass. The bigger the ratio, the more aggressive code hoisting -is with simple expressions, i.e., the expressions that have cost -less than @option{gcse-unrestricted-cost}. Specifying 0 disables -hoisting of simple expressions. The default value is 10. +This option enables checking of alignment of pointers when they are +dereferenced, or when a reference is bound to insufficiently aligned target, +or when a method or constructor is invoked on insufficiently aligned object. -@item gcse-unrestricted-cost -Cost, roughly measured as the cost of a single typical machine -instruction, at which GCSE optimizations do not constrain -the distance an expression can travel. This is currently -supported only in the code hoisting pass. The lesser the cost, -the more aggressive code hoisting is. Specifying 0 -allows all expressions to travel unrestricted distances. -The default value is 3. +@item -fsanitize=object-size +@opindex fsanitize=object-size +This option enables instrumentation of memory references using the +@code{__builtin_object_size} function. Various out of bounds pointer +accesses are detected. -@item max-hoist-depth -The depth of search in the dominator tree for expressions to hoist. -This is used to avoid quadratic behavior in hoisting algorithm. -The value of 0 does not limit on the search, but may slow down compilation -of huge functions. The default value is 30. +@item -fsanitize=float-divide-by-zero +@opindex fsanitize=float-divide-by-zero +Detect floating-point division by zero. Unlike other similar options, +@option{-fsanitize=float-divide-by-zero} is not enabled by +@option{-fsanitize=undefined}, since floating-point division by zero can +be a legitimate way of obtaining infinities and NaNs. -@item max-tail-merge-comparisons -The maximum amount of similar bbs to compare a bb with. This is used to -avoid quadratic behavior in tree tail merging. The default value is 10. +@item -fsanitize=float-cast-overflow +@opindex fsanitize=float-cast-overflow +This option enables floating-point type to integer conversion checking. +We check that the result of the conversion does not overflow. +Unlike other similar options, @option{-fsanitize=float-cast-overflow} is +not enabled by @option{-fsanitize=undefined}. +This option does not work well with @code{FE_INVALID} exceptions enabled. -@item max-tail-merge-iterations -The maximum amount of iterations of the pass over the function. This is used to -limit compilation time in tree tail merging. The default value is 2. +@item -fsanitize=nonnull-attribute +@opindex fsanitize=nonnull-attribute -@item max-unrolled-insns -The maximum number of instructions that a loop may have to be unrolled. -If a loop is unrolled, this parameter also determines how many times -the loop code is unrolled. +This option enables instrumentation of calls, checking whether null values +are not passed to arguments marked as requiring a non-null value by the +@code{nonnull} function attribute. -@item max-average-unrolled-insns -The maximum number of instructions biased by probabilities of their execution -that a loop may have to be unrolled. If a loop is unrolled, -this parameter also determines how many times the loop code is unrolled. +@item -fsanitize=returns-nonnull-attribute +@opindex fsanitize=returns-nonnull-attribute -@item max-unroll-times -The maximum number of unrollings of a single loop. +This option enables instrumentation of return statements in functions +marked with @code{returns_nonnull} function attribute, to detect returning +of null values from such functions. -@item max-peeled-insns -The maximum number of instructions that a loop may have to be peeled. -If a loop is peeled, this parameter also determines how many times -the loop code is peeled. +@item -fsanitize=bool +@opindex fsanitize=bool -@item max-peel-times -The maximum number of peelings of a single loop. +This option enables instrumentation of loads from bool. If a value other +than 0/1 is loaded, a run-time error is issued. -@item max-peel-branches -The maximum number of branches on the hot path through the peeled sequence. +@item -fsanitize=enum +@opindex fsanitize=enum -@item max-completely-peeled-insns -The maximum number of insns of a completely peeled loop. +This option enables instrumentation of loads from an enum type. If +a value outside the range of values for the enum type is loaded, +a run-time error is issued. -@item max-completely-peel-times -The maximum number of iterations of a loop to be suitable for complete peeling. +@item -fsanitize=vptr +@opindex fsanitize=vptr -@item max-completely-peel-loop-nest-depth -The maximum depth of a loop nest suitable for complete peeling. +This option enables instrumentation of C++ member function calls, member +accesses and some conversions between pointers to base and derived classes, +to verify the referenced object has the correct dynamic type. -@item max-unswitch-insns -The maximum number of insns of an unswitched loop. +@end table -@item max-unswitch-level -The maximum number of branches unswitched in a single loop. +While @option{-ftrapv} causes traps for signed overflows to be emitted, +@option{-fsanitize=undefined} gives a diagnostic message. +This currently works only for the C family of languages. -@item lim-expensive -The minimum cost of an expensive expression in the loop invariant motion. +@item -fno-sanitize=all +@opindex fno-sanitize=all -@item iv-consider-all-candidates-bound -Bound on number of candidates for induction variables, below which -all candidates are considered for each use in induction variable -optimizations. If there are more candidates than this, -only the most relevant ones are considered to avoid quadratic time complexity. +This option disables all previously enabled sanitizers. +@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used +together. -@item iv-max-considered-uses -The induction variable optimizations give up on loops that contain more -induction variable uses. +@item -fasan-shadow-offset=@var{number} +@opindex fasan-shadow-offset +This option forces GCC to use custom shadow offset in AddressSanitizer checks. +It is useful for experimenting with different shadow memory layouts in +Kernel AddressSanitizer. -@item iv-always-prune-cand-set-bound -If the number of candidates in the set is smaller than this value, -always try to remove unnecessary ivs from the set -when adding a new one. +@item -fsanitize-sections=@var{s1},@var{s2},... +@opindex fsanitize-sections +Sanitize global variables in selected user-defined sections. @var{si} may +contain wildcards. -@item scev-max-expr-size -Bound on size of expressions used in the scalar evolutions analyzer. -Large expressions slow the analyzer. - -@item scev-max-expr-complexity -Bound on the complexity of the expressions in the scalar evolutions analyzer. -Complex expressions slow the analyzer. - -@item vect-max-version-for-alignment-checks -The maximum number of run-time checks that can be performed when -doing loop versioning for alignment in the vectorizer. +@item -fsanitize-recover@r{[}=@var{opts}@r{]} +@opindex fsanitize-recover +@opindex fno-sanitize-recover +@option{-fsanitize-recover=} controls error recovery mode for sanitizers +mentioned in comma-separated list of @var{opts}. Enabling this option +for a sanitizer component causes it to attempt to continue +running the program as if no error happened. This means multiple +runtime errors can be reported in a single program run, and the exit +code of the program may indicate success even when errors +have been reported. The @option{-fno-sanitize-recover=} option +can be used to alter +this behavior: only the first detected error is reported +and program then exits with a non-zero exit code. -@item vect-max-version-for-alias-checks -The maximum number of run-time checks that can be performed when -doing loop versioning for alias in the vectorizer. +Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions +except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}), +@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero}, +@option{-fsanitize=kernel-address} and @option{-fsanitize=address}. +For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address}, +for which this feature is experimental. +@option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also +accepted, the former enables recovery for all sanitizers that support it, +the latter disables recovery for all sanitizers that support it. -@item vect-max-peeling-for-alignment -The maximum number of loop peels to enhance access alignment -for vectorizer. Value -1 means 'no limit'. +Syntax without explicit @var{opts} parameter is deprecated. It is equivalent to +@smallexample +-fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero +@end smallexample +@noindent +Similarly @option{-fno-sanitize-recover} is equivalent to +@smallexample +-fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero +@end smallexample -@item max-iterations-to-track -The maximum number of iterations of a loop the brute-force algorithm -for analysis of the number of iterations of the loop tries to evaluate. +@item -fsanitize-undefined-trap-on-error +@opindex fsanitize-undefined-trap-on-error +The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to +report undefined behavior using @code{__builtin_trap} rather than +a @code{libubsan} library routine. The advantage of this is that the +@code{libubsan} library is not needed and is not linked in, so this +is usable even in freestanding environments. -@item hot-bb-count-ws-permille -A basic block profile count is considered hot if it contributes to -the given permillage (i.e. 0...1000) of the entire profiled execution. +@item -fsanitize-coverage=trace-pc +@opindex fsanitize-coverage=trace-pc +Enable coverage-guided fuzzing code instrumentation. +Inserts call to __sanitizer_cov_trace_pc into every basic block. -@item hot-bb-frequency-fraction -Select fraction of the entry block frequency of executions of basic block in -function given basic block needs to have to be considered hot. +@item -fbounds-check +@opindex fbounds-check +For front ends that support it, generate additional code to check that +indices used to access arrays are within the declared range. This is +currently only supported by the Java and Fortran front ends, where +this option defaults to true and false respectively. -@item max-predicted-iterations -The maximum number of loop iterations we predict statically. This is useful -in cases where a function contains a single loop with known bound and -another loop with unknown bound. -The known number of iterations is predicted correctly, while -the unknown number of iterations average to roughly 10. This means that the -loop without bounds appears artificially cold relative to the other one. +@item -fcheck-pointer-bounds +@opindex fcheck-pointer-bounds +@opindex fno-check-pointer-bounds +@cindex Pointer Bounds Checker options +Enable Pointer Bounds Checker instrumentation. Each memory reference +is instrumented with checks of the pointer used for memory access against +bounds associated with that pointer. -@item builtin-expect-probability -Control the probability of the expression having the specified value. This -parameter takes a percentage (i.e. 0 ... 100) as input. -The default probability of 90 is obtained empirically. +Currently there +is only an implementation for Intel MPX available, thus x86 target +and @option{-mmpx} are required to enable this feature. +MPX-based instrumentation requires +a runtime library to enable MPX in hardware and handle bounds +violation signals. By default when @option{-fcheck-pointer-bounds} +and @option{-mmpx} options are used to link a program, the GCC driver +links against the @file{libmpx} runtime library and @file{libmpxwrappers} +library. It also passes '-z bndplt' to a linker in case it supports this +option (which is checked on libmpx configuration). Note that old versions +of linker may ignore option. Gold linker doesn't support '-z bndplt' +option. With no '-z bndplt' support in linker all calls to dynamic libraries +lose passed bounds reducing overall protection level. It's highly +recommended to use linker with '-z bndplt' support. In case such linker +is not available it is adviced to always use @option{-static-libmpxwrappers} +for better protection level or use @option{-static} to completely avoid +external calls to dynamic libraries. MPX-based instrumentation +may be used for debugging and also may be included in production code +to increase program security. Depending on usage, you may +have different requirements for the runtime library. The current version +of the MPX runtime library is more oriented for use as a debugging +tool. MPX runtime library usage implies @option{-lpthread}. See +also @option{-static-libmpx}. The runtime library behavior can be +influenced using various @env{CHKP_RT_*} environment variables. See +@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler} +for more details. -@item align-threshold +Generated instrumentation may be controlled by various +@option{-fchkp-*} options and by the @code{bnd_variable_size} +structure field attribute (@pxref{Type Attributes}) and +@code{bnd_legacy}, and @code{bnd_instrument} function attributes +(@pxref{Function Attributes}). GCC also provides a number of built-in +functions for controlling the Pointer Bounds Checker. @xref{Pointer +Bounds Checker builtins}, for more information. -Select fraction of the maximal frequency of executions of a basic block in -a function to align the basic block. +@item -fchkp-check-incomplete-type +@opindex fchkp-check-incomplete-type +@opindex fno-chkp-check-incomplete-type +Generate pointer bounds checks for variables with incomplete type. +Enabled by default. -@item align-loop-iterations +@item -fchkp-narrow-bounds +@opindex fchkp-narrow-bounds +@opindex fno-chkp-narrow-bounds +Controls bounds used by Pointer Bounds Checker for pointers to object +fields. If narrowing is enabled then field bounds are used. Otherwise +object bounds are used. See also @option{-fchkp-narrow-to-innermost-array} +and @option{-fchkp-first-field-has-own-bounds}. Enabled by default. -A loop expected to iterate at least the selected number of iterations is -aligned. +@item -fchkp-first-field-has-own-bounds +@opindex fchkp-first-field-has-own-bounds +@opindex fno-chkp-first-field-has-own-bounds +Forces Pointer Bounds Checker to use narrowed bounds for the address of the +first field in the structure. By default a pointer to the first field has +the same bounds as a pointer to the whole structure. -@item tracer-dynamic-coverage -@itemx tracer-dynamic-coverage-feedback +@item -fchkp-narrow-to-innermost-array +@opindex fchkp-narrow-to-innermost-array +@opindex fno-chkp-narrow-to-innermost-array +Forces Pointer Bounds Checker to use bounds of the innermost arrays in +case of nested static array access. By default this option is disabled and +bounds of the outermost array are used. -This value is used to limit superblock formation once the given percentage of -executed instructions is covered. This limits unnecessary code size -expansion. +@item -fchkp-optimize +@opindex fchkp-optimize +@opindex fno-chkp-optimize +Enables Pointer Bounds Checker optimizations. Enabled by default at +optimization levels @option{-O}, @option{-O2}, @option{-O3}. -The @option{tracer-dynamic-coverage-feedback} parameter -is used only when profile -feedback is available. The real profiles (as opposed to statically estimated -ones) are much less balanced allowing the threshold to be larger value. +@item -fchkp-use-fast-string-functions +@opindex fchkp-use-fast-string-functions +@opindex fno-chkp-use-fast-string-functions +Enables use of @code{*_nobnd} versions of string functions (not copying bounds) +by Pointer Bounds Checker. Disabled by default. -@item tracer-max-code-growth -Stop tail duplication once code growth has reached given percentage. This is -a rather artificial limit, as most of the duplicates are eliminated later in -cross jumping, so it may be set to much higher values than is the desired code -growth. +@item -fchkp-use-nochk-string-functions +@opindex fchkp-use-nochk-string-functions +@opindex fno-chkp-use-nochk-string-functions +Enables use of @code{*_nochk} versions of string functions (not checking bounds) +by Pointer Bounds Checker. Disabled by default. -@item tracer-min-branch-ratio +@item -fchkp-use-static-bounds +@opindex fchkp-use-static-bounds +@opindex fno-chkp-use-static-bounds +Allow Pointer Bounds Checker to generate static bounds holding +bounds of static variables. Enabled by default. -Stop reverse growth when the reverse probability of best edge is less than this -threshold (in percent). +@item -fchkp-use-static-const-bounds +@opindex fchkp-use-static-const-bounds +@opindex fno-chkp-use-static-const-bounds +Use statically-initialized bounds for constant bounds instead of +generating them each time they are required. By default enabled when +@option{-fchkp-use-static-bounds} is enabled. -@item tracer-min-branch-ratio -@itemx tracer-min-branch-ratio-feedback +@item -fchkp-treat-zero-dynamic-size-as-infinite +@opindex fchkp-treat-zero-dynamic-size-as-infinite +@opindex fno-chkp-treat-zero-dynamic-size-as-infinite +With this option, objects with incomplete type whose +dynamically-obtained size is zero are treated as having infinite size +instead by Pointer Bounds +Checker. This option may be helpful if a program is linked with a library +missing size information for some symbols. Disabled by default. -Stop forward growth if the best edge has probability lower than this -threshold. +@item -fchkp-check-read +@opindex fchkp-check-read +@opindex fno-chkp-check-read +Instructs Pointer Bounds Checker to generate checks for all read +accesses to memory. Enabled by default. -Similarly to @option{tracer-dynamic-coverage} two values are present, one for -compilation for profile feedback and one for compilation without. The value -for compilation with profile feedback needs to be more conservative (higher) in -order to make tracer effective. +@item -fchkp-check-write +@opindex fchkp-check-write +@opindex fno-chkp-check-write +Instructs Pointer Bounds Checker to generate checks for all write +accesses to memory. Enabled by default. -@item max-cse-path-length +@item -fchkp-store-bounds +@opindex fchkp-store-bounds +@opindex fno-chkp-store-bounds +Instructs Pointer Bounds Checker to generate bounds stores for +pointer writes. Enabled by default. -The maximum number of basic blocks on path that CSE considers. -The default is 10. +@item -fchkp-instrument-calls +@opindex fchkp-instrument-calls +@opindex fno-chkp-instrument-calls +Instructs Pointer Bounds Checker to pass pointer bounds to calls. +Enabled by default. -@item max-cse-insns -The maximum number of instructions CSE processes before flushing. -The default is 1000. +@item -fchkp-instrument-marked-only +@opindex fchkp-instrument-marked-only +@opindex fno-chkp-instrument-marked-only +Instructs Pointer Bounds Checker to instrument only functions +marked with the @code{bnd_instrument} attribute +(@pxref{Function Attributes}). Disabled by default. -@item ggc-min-expand +@item -fchkp-use-wrappers +@opindex fchkp-use-wrappers +@opindex fno-chkp-use-wrappers +Allows Pointer Bounds Checker to replace calls to built-in functions +with calls to wrapper functions. When @option{-fchkp-use-wrappers} +is used to link a program, the GCC driver automatically links +against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}. +Enabled by default. -GCC uses a garbage collector to manage its own memory allocation. This -parameter specifies the minimum percentage by which the garbage -collector's heap should be allowed to expand between collections. -Tuning this may improve compilation speed; it has no effect on code -generation. +@item -fstack-protector +@opindex fstack-protector +Emit extra code to check for buffer overflows, such as stack smashing +attacks. This is done by adding a guard variable to functions with +vulnerable objects. This includes functions that call @code{alloca}, and +functions with buffers larger than 8 bytes. The guards are initialized +when a function is entered and then checked when the function exits. +If a guard check fails, an error message is printed and the program exits. -The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when -RAM >= 1GB@. If @code{getrlimit} is available, the notion of ``RAM'' is -the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If -GCC is not able to calculate RAM on a particular platform, the lower -bound of 30% is used. Setting this parameter and -@option{ggc-min-heapsize} to zero causes a full collection to occur at -every opportunity. This is extremely slow, but can be useful for -debugging. +@item -fstack-protector-all +@opindex fstack-protector-all +Like @option{-fstack-protector} except that all functions are protected. -@item ggc-min-heapsize +@item -fstack-protector-strong +@opindex fstack-protector-strong +Like @option{-fstack-protector} but includes additional functions to +be protected --- those that have local array definitions, or have +references to local frame addresses. -Minimum size of the garbage collector's heap before it begins bothering -to collect garbage. The first collection occurs after the heap expands -by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again, -tuning this may improve compilation speed, and has no effect on code -generation. +@item -fstack-protector-explicit +@opindex fstack-protector-explicit +Like @option{-fstack-protector} but only protects those functions which +have the @code{stack_protect} attribute. -The default is the smaller of RAM/8, RLIMIT_RSS, or a limit that -tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but -with a lower bound of 4096 (four megabytes) and an upper bound of -131072 (128 megabytes). If GCC is not able to calculate RAM on a -particular platform, the lower bound is used. Setting this parameter -very large effectively disables garbage collection. Setting this -parameter and @option{ggc-min-expand} to zero causes a full collection -to occur at every opportunity. +@item -fstack-check +@opindex fstack-check +Generate code to verify that you do not go beyond the boundary of the +stack. You should specify this flag if you are running in an +environment with multiple threads, but you only rarely need to specify it in +a single-threaded environment since stack overflow is automatically +detected on nearly all systems if there is only one stack. -@item max-reload-search-insns -The maximum number of instruction reload should look backward for equivalent -register. Increasing values mean more aggressive optimization, making the -compilation time increase with probably slightly better performance. -The default value is 100. +Note that this switch does not actually cause checking to be done; the +operating system or the language runtime must do that. The switch causes +generation of code to ensure that they see the stack being extended. -@item max-cselib-memory-locations -The maximum number of memory locations cselib should take into account. -Increasing values mean more aggressive optimization, making the compilation time -increase with probably slightly better performance. The default value is 500. +You can additionally specify a string parameter: @samp{no} means no +checking, @samp{generic} means force the use of old-style checking, +@samp{specific} means use the best checking method and is equivalent +to bare @option{-fstack-check}. -@item reorder-blocks-duplicate -@itemx reorder-blocks-duplicate-feedback +Old-style checking is a generic mechanism that requires no specific +target support in the compiler but comes with the following drawbacks: -Used by the basic block reordering pass to decide whether to use unconditional -branch or duplicate the code on its destination. Code is duplicated when its -estimated size is smaller than this value multiplied by the estimated size of -unconditional jump in the hot spots of the program. +@enumerate +@item +Modified allocation strategy for large objects: they are always +allocated dynamically if their size exceeds a fixed threshold. -The @option{reorder-block-duplicate-feedback} parameter -is used only when profile -feedback is available. It may be set to higher values than -@option{reorder-block-duplicate} since information about the hot spots is more -accurate. +@item +Fixed limit on the size of the static frame of functions: when it is +topped by a particular function, stack checking is not reliable and +a warning is issued by the compiler. -@item max-sched-ready-insns -The maximum number of instructions ready to be issued the scheduler should -consider at any given time during the first scheduling pass. Increasing -values mean more thorough searches, making the compilation time increase -with probably little benefit. The default value is 100. +@item +Inefficiency: because of both the modified allocation strategy and the +generic implementation, code performance is hampered. +@end enumerate -@item max-sched-region-blocks -The maximum number of blocks in a region to be considered for -interblock scheduling. The default value is 10. +Note that old-style stack checking is also the fallback method for +@samp{specific} if no target support has been added in the compiler. -@item max-pipeline-region-blocks -The maximum number of blocks in a region to be considered for -pipelining in the selective scheduler. The default value is 15. +@item -fstack-limit-register=@var{reg} +@itemx -fstack-limit-symbol=@var{sym} +@itemx -fno-stack-limit +@opindex fstack-limit-register +@opindex fstack-limit-symbol +@opindex fno-stack-limit +Generate code to ensure that the stack does not grow beyond a certain value, +either the value of a register or the address of a symbol. If a larger +stack is required, a signal is raised at run time. For most targets, +the signal is raised before the stack overruns the boundary, so +it is possible to catch the signal without taking special precautions. -@item max-sched-region-insns -The maximum number of insns in a region to be considered for -interblock scheduling. The default value is 100. +For instance, if the stack starts at absolute address @samp{0x80000000} +and grows downwards, you can use the flags +@option{-fstack-limit-symbol=__stack_limit} and +@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit +of 128KB@. Note that this may only work with the GNU linker. -@item max-pipeline-region-insns -The maximum number of insns in a region to be considered for -pipelining in the selective scheduler. The default value is 200. +You can locally override stack limit checking by using the +@code{no_stack_limit} function attribute (@pxref{Function Attributes}). -@item min-spec-prob -The minimum probability (in percents) of reaching a source block -for interblock speculative scheduling. The default value is 40. +@item -fsplit-stack +@opindex fsplit-stack +Generate code to automatically split the stack before it overflows. +The resulting program has a discontiguous stack which can only +overflow if the program is unable to allocate any more memory. This +is most useful when running threaded programs, as it is no longer +necessary to calculate a good stack size to use for each thread. This +is currently only implemented for the x86 targets running +GNU/Linux. -@item max-sched-extend-regions-iters -The maximum number of iterations through CFG to extend regions. -A value of 0 (the default) disables region extensions. +When code compiled with @option{-fsplit-stack} calls code compiled +without @option{-fsplit-stack}, there may not be much stack space +available for the latter code to run. If compiling all code, +including library code, with @option{-fsplit-stack} is not an option, +then the linker can fix up these calls so that the code compiled +without @option{-fsplit-stack} always has a large stack. Support for +this is implemented in the gold linker in GNU binutils release 2.21 +and later. -@item max-sched-insn-conflict-delay -The maximum conflict delay for an insn to be considered for speculative motion. -The default value is 3. +@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} +@opindex fvtable-verify +This option is only available when compiling C++ code. +It turns on (or off, if using @option{-fvtable-verify=none}) the security +feature that verifies at run time, for every virtual call, that +the vtable pointer through which the call is made is valid for the type of +the object, and has not been corrupted or overwritten. If an invalid vtable +pointer is detected at run time, an error is reported and execution of the +program is immediately halted. -@item sched-spec-prob-cutoff -The minimal probability of speculation success (in percents), so that -speculative insns are scheduled. -The default value is 40. +This option causes run-time data structures to be built at program startup, +which are used for verifying the vtable pointers. +The options @samp{std} and @samp{preinit} +control the timing of when these data structures are built. In both cases the +data structures are built before execution reaches @code{main}. Using +@option{-fvtable-verify=std} causes the data structures to be built after +shared libraries have been loaded and initialized. +@option{-fvtable-verify=preinit} causes them to be built before shared +libraries have been loaded and initialized. -@item sched-spec-state-edge-prob-cutoff -The minimum probability an edge must have for the scheduler to save its -state across it. -The default value is 10. +If this option appears multiple times in the command line with different +values specified, @samp{none} takes highest priority over both @samp{std} and +@samp{preinit}; @samp{preinit} takes priority over @samp{std}. -@item sched-mem-true-dep-cost -Minimal distance (in CPU cycles) between store and load targeting same -memory locations. The default value is 1. +@item -fvtv-debug +@opindex fvtv-debug +When used in conjunction with @option{-fvtable-verify=std} or +@option{-fvtable-verify=preinit}, causes debug versions of the +runtime functions for the vtable verification feature to be called. +This flag also causes the compiler to log information about which +vtable pointers it finds for each class. +This information is written to a file named @file{vtv_set_ptr_data.log} +in the directory named by the environment variable @env{VTV_LOGS_DIR} +if that is defined or the current working directory otherwise. -@item selsched-max-lookahead -The maximum size of the lookahead window of selective scheduling. It is a -depth of search for available instructions. -The default value is 50. +Note: This feature @emph{appends} data to the log file. If you want a fresh log +file, be sure to delete any existing one. -@item selsched-max-sched-times -The maximum number of times that an instruction is scheduled during -selective scheduling. This is the limit on the number of iterations -through which the instruction may be pipelined. The default value is 2. +@item -fvtv-counts +@opindex fvtv-counts +This is a debugging flag. When used in conjunction with +@option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this +causes the compiler to keep track of the total number of virtual calls +it encounters and the number of verifications it inserts. It also +counts the number of calls to certain run-time library functions +that it inserts and logs this information for each compilation unit. +The compiler writes this information to a file named +@file{vtv_count_data.log} in the directory named by the environment +variable @env{VTV_LOGS_DIR} if that is defined or the current working +directory otherwise. It also counts the size of the vtable pointer sets +for each class, and writes this information to @file{vtv_class_set_sizes.log} +in the same directory. -@item selsched-max-insns-to-rename -The maximum number of best instructions in the ready list that are considered -for renaming in the selective scheduler. The default value is 2. +Note: This feature @emph{appends} data to the log files. To get fresh log +files, be sure to delete any existing ones. -@item sms-min-sc -The minimum value of stage count that swing modulo scheduler -generates. The default value is 2. +@item -finstrument-functions +@opindex finstrument-functions +Generate instrumentation calls for entry and exit to functions. Just +after function entry and just before function exit, the following +profiling functions are called with the address of the current +function and its call site. (On some platforms, +@code{__builtin_return_address} does not work beyond the current +function, so the call site information may not be available to the +profiling functions otherwise.) -@item max-last-value-rtl -The maximum size measured as number of RTLs that can be recorded in an expression -in combiner for a pseudo register as last known value of that register. The default -is 10000. +@smallexample +void __cyg_profile_func_enter (void *this_fn, + void *call_site); +void __cyg_profile_func_exit (void *this_fn, + void *call_site); +@end smallexample -@item max-combine-insns -The maximum number of instructions the RTL combiner tries to combine. -The default value is 2 at @option{-Og} and 4 otherwise. +The first argument is the address of the start of the current function, +which may be looked up exactly in the symbol table. -@item integer-share-limit -Small integer constants can use a shared data structure, reducing the -compiler's memory usage and increasing its speed. This sets the maximum -value of a shared integer constant. The default value is 256. +This instrumentation is also done for functions expanded inline in other +functions. The profiling calls indicate where, conceptually, the +inline function is entered and exited. This means that addressable +versions of such functions must be available. If all your uses of a +function are expanded inline, this may mean an additional expansion of +code size. If you use @code{extern inline} in your C code, an +addressable version of such functions must be provided. (This is +normally the case anyway, but if you get lucky and the optimizer always +expands the functions inline, you might have gotten away without +providing static copies.) -@item ssp-buffer-size -The minimum size of buffers (i.e.@: arrays) that receive stack smashing -protection when @option{-fstack-protection} is used. +A function may be given the attribute @code{no_instrument_function}, in +which case this instrumentation is not done. This can be used, for +example, for the profiling functions listed above, high-priority +interrupt routines, and any functions from which the profiling functions +cannot safely be called (perhaps signal handlers, if the profiling +routines generate output or allocate memory). -@item min-size-for-stack-sharing -The minimum size of variables taking part in stack slot sharing when not -optimizing. The default value is 32. +@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} +@opindex finstrument-functions-exclude-file-list -@item max-jump-thread-duplication-stmts -Maximum number of statements allowed in a block that needs to be -duplicated when threading jumps. +Set the list of functions that are excluded from instrumentation (see +the description of @option{-finstrument-functions}). If the file that +contains a function definition matches with one of @var{file}, then +that function is not instrumented. The match is done on substrings: +if the @var{file} parameter is a substring of the file name, it is +considered to be a match. -@item max-fields-for-field-sensitive -Maximum number of fields in a structure treated in -a field sensitive manner during pointer analysis. The default is zero -for @option{-O0} and @option{-O1}, -and 100 for @option{-Os}, @option{-O2}, and @option{-O3}. +For example: -@item prefetch-latency -Estimate on average number of instructions that are executed before -prefetch finishes. The distance prefetched ahead is proportional -to this constant. Increasing this number may also lead to less -streams being prefetched (see @option{simultaneous-prefetches}). +@smallexample +-finstrument-functions-exclude-file-list=/bits/stl,include/sys +@end smallexample -@item simultaneous-prefetches -Maximum number of prefetches that can run at the same time. +@noindent +excludes any inline function defined in files whose pathnames +contain @file{/bits/stl} or @file{include/sys}. -@item l1-cache-line-size -The size of cache line in L1 cache, in bytes. +If, for some reason, you want to include letter @samp{,} in one of +@var{sym}, write @samp{\,}. For example, +@option{-finstrument-functions-exclude-file-list='\,\,tmp'} +(note the single quote surrounding the option). -@item l1-cache-size -The size of L1 cache, in kilobytes. +@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} +@opindex finstrument-functions-exclude-function-list -@item l2-cache-size -The size of L2 cache, in kilobytes. +This is similar to @option{-finstrument-functions-exclude-file-list}, +but this option sets the list of function names to be excluded from +instrumentation. The function name to be matched is its user-visible +name, such as @code{vector blah(const vector &)}, not the +internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The +match is done on substrings: if the @var{sym} parameter is a substring +of the function name, it is considered to be a match. For C99 and C++ +extended identifiers, the function name must be given in UTF-8, not +using universal character names. -@item min-insn-to-prefetch-ratio -The minimum ratio between the number of instructions and the -number of prefetches to enable prefetching in a loop. +@end table -@item prefetch-min-insn-to-mem-ratio -The minimum ratio between the number of instructions and the -number of memory references to enable prefetching in a loop. -@item use-canonical-types -Whether the compiler should use the ``canonical'' type system. By -default, this should always be 1, which uses a more efficient internal -mechanism for comparing types in C++ and Objective-C++. However, if -bugs in the canonical type system are causing compilation failures, -set this value to 0 to disable canonical types. +@node Preprocessor Options +@section Options Controlling the Preprocessor +@cindex preprocessor options +@cindex options, preprocessor -@item switch-conversion-max-branch-ratio -Switch initialization conversion refuses to create arrays that are -bigger than @option{switch-conversion-max-branch-ratio} times the number of -branches in the switch. +These options control the C preprocessor, which is run on each C source +file before actual compilation. -@item max-partial-antic-length -Maximum length of the partial antic set computed during the tree -partial redundancy elimination optimization (@option{-ftree-pre}) when -optimizing at @option{-O3} and above. For some sorts of source code -the enhanced partial redundancy elimination optimization can run away, -consuming all of the memory available on the host machine. This -parameter sets a limit on the length of the sets that are computed, -which prevents the runaway behavior. Setting a value of 0 for -this parameter allows an unlimited set length. +If you use the @option{-E} option, nothing is done except preprocessing. +Some of these options make sense only together with @option{-E} because +they cause the preprocessor output to be unsuitable for actual +compilation. -@item sccvn-max-scc-size -Maximum size of a strongly connected component (SCC) during SCCVN -processing. If this limit is hit, SCCVN processing for the whole -function is not done and optimizations depending on it are -disabled. The default maximum SCC size is 10000. +@table @gcctabopt +@item -Wp,@var{option} +@opindex Wp +You can use @option{-Wp,@var{option}} to bypass the compiler driver +and pass @var{option} directly through to the preprocessor. If +@var{option} contains commas, it is split into multiple options at the +commas. However, many options are modified, translated or interpreted +by the compiler driver before being passed to the preprocessor, and +@option{-Wp} forcibly bypasses this phase. The preprocessor's direct +interface is undocumented and subject to change, so whenever possible +you should avoid using @option{-Wp} and let the driver handle the +options instead. -@item sccvn-max-alias-queries-per-access -Maximum number of alias-oracle queries we perform when looking for -redundancies for loads and stores. If this limit is hit the search -is aborted and the load or store is not considered redundant. The -number of queries is algorithmically limited to the number of -stores on all paths from the load to the function entry. -The default maxmimum number of queries is 1000. +@item -Xpreprocessor @var{option} +@opindex Xpreprocessor +Pass @var{option} as an option to the preprocessor. You can use this to +supply system-specific preprocessor options that GCC does not +recognize. -@item ira-max-loops-num -IRA uses regional register allocation by default. If a function -contains more loops than the number given by this parameter, only at most -the given number of the most frequently-executed loops form regions -for regional register allocation. The default value of the -parameter is 100. +If you want to pass an option that takes an argument, you must use +@option{-Xpreprocessor} twice, once for the option and once for the argument. -@item ira-max-conflict-table-size -Although IRA uses a sophisticated algorithm to compress the conflict -table, the table can still require excessive amounts of memory for -huge functions. If the conflict table for a function could be more -than the size in MB given by this parameter, the register allocator -instead uses a faster, simpler, and lower-quality -algorithm that does not require building a pseudo-register conflict table. -The default value of the parameter is 2000. +@item -no-integrated-cpp +@opindex no-integrated-cpp +Perform preprocessing as a separate pass before compilation. +By default, GCC performs preprocessing as an integrated part of +input tokenization and parsing. +If this option is provided, the appropriate language front end +(@command{cc1}, @command{cc1plus}, or @command{cc1obj} for C, C++, +and Objective-C, respectively) is instead invoked twice, +once for preprocessing only and once for actual compilation +of the preprocessed input. +This option may be useful in conjunction with the @option{-B} or +@option{-wrapper} options to specify an alternate preprocessor or +perform additional processing of the program source between +normal preprocessing and compilation. +@end table -@item ira-loop-reserved-regs -IRA can be used to evaluate more accurate register pressure in loops -for decisions to move loop invariants (see @option{-O3}). The number -of available registers reserved for some other purposes is given -by this parameter. The default value of the parameter is 2, which is -the minimal number of registers needed by typical instructions. -This value is the best found from numerous experiments. +@include cppopts.texi -@item lra-inheritance-ebb-probability-cutoff -LRA tries to reuse values reloaded in registers in subsequent insns. -This optimization is called inheritance. EBB is used as a region to -do this optimization. The parameter defines a minimal fall-through -edge probability in percentage used to add BB to inheritance EBB in -LRA. The default value of the parameter is 40. The value was chosen -from numerous runs of SPEC2000 on x86-64. +@node Assembler Options +@section Passing Options to the Assembler -@item loop-invariant-max-bbs-in-loop -Loop invariant motion can be very expensive, both in compilation time and -in amount of needed compile-time memory, with very large loops. Loops -with more basic blocks than this parameter won't have loop invariant -motion optimization performed on them. The default value of the -parameter is 1000 for @option{-O1} and 10000 for @option{-O2} and above. +@c prevent bad page break with this line +You can pass options to the assembler. -@item loop-max-datarefs-for-datadeps -Building data dapendencies is expensive for very large loops. This -parameter limits the number of data references in loops that are -considered for data dependence analysis. These large loops are no -handled by the optimizations using loop data dependencies. -The default value is 1000. +@table @gcctabopt +@item -Wa,@var{option} +@opindex Wa +Pass @var{option} as an option to the assembler. If @var{option} +contains commas, it is split into multiple options at the commas. -@item max-vartrack-size -Sets a maximum number of hash table slots to use during variable -tracking dataflow analysis of any function. If this limit is exceeded -with variable tracking at assignments enabled, analysis for that -function is retried without it, after removing all debug insns from -the function. If the limit is exceeded even without debug insns, var -tracking analysis is completely disabled for the function. Setting -the parameter to zero makes it unlimited. +@item -Xassembler @var{option} +@opindex Xassembler +Pass @var{option} as an option to the assembler. You can use this to +supply system-specific assembler options that GCC does not +recognize. -@item max-vartrack-expr-depth -Sets a maximum number of recursion levels when attempting to map -variable names or debug temporaries to value expressions. This trades -compilation time for more complete debug information. If this is set too -low, value expressions that are available and could be represented in -debug information may end up not being used; setting this higher may -enable the compiler to find more complex debug expressions, but compile -time and memory use may grow. The default is 12. +If you want to pass an option that takes an argument, you must use +@option{-Xassembler} twice, once for the option and once for the argument. -@item min-nondebug-insn-uid -Use uids starting at this parameter for nondebug insns. The range below -the parameter is reserved exclusively for debug insns created by -@option{-fvar-tracking-assignments}, but debug insns may get -(non-overlapping) uids above it if the reserved range is exhausted. +@end table -@item ipa-sra-ptr-growth-factor -IPA-SRA replaces a pointer to an aggregate with one or more new -parameters only when their cumulative size is less or equal to -@option{ipa-sra-ptr-growth-factor} times the size of the original -pointer parameter. +@node Link Options +@section Options for Linking +@cindex link options +@cindex options, linking -@item sra-max-scalarization-size-Ospeed -@item sra-max-scalarization-size-Osize -The two Scalar Reduction of Aggregates passes (SRA and IPA-SRA) aim to -replace scalar parts of aggregates with uses of independent scalar -variables. These parameters control the maximum size, in storage units, -of aggregate which is considered for replacement when compiling for -speed -(@option{sra-max-scalarization-size-Ospeed}) or size -(@option{sra-max-scalarization-size-Osize}) respectively. +These options come into play when the compiler links object files into +an executable output file. They are meaningless if the compiler is +not doing a link step. -@item tm-max-aggregate-size -When making copies of thread-local variables in a transaction, this -parameter specifies the size in bytes after which variables are -saved with the logging functions as opposed to save/restore code -sequence pairs. This option only applies when using -@option{-fgnu-tm}. - -@item graphite-max-nb-scop-params -To avoid exponential effects in the Graphite loop transforms, the -number of parameters in a Static Control Part (SCoP) is bounded. The -default value is 10 parameters. A variable whose value is unknown at -compilation time and defined outside a SCoP is a parameter of the SCoP. +@table @gcctabopt +@cindex file names +@item @var{object-file-name} +A file name that does not end in a special recognized suffix is +considered to name an object file or library. (Object files are +distinguished from libraries by the linker according to the file +contents.) If linking is done, these object files are used as input +to the linker. -@item graphite-max-bbs-per-function -To avoid exponential effects in the detection of SCoPs, the size of -the functions analyzed by Graphite is bounded. The default value is -100 basic blocks. +@item -c +@itemx -S +@itemx -E +@opindex c +@opindex S +@opindex E +If any of these options is used, then the linker is not run, and +object file names should not be used as arguments. @xref{Overall +Options}. -@item loop-block-tile-size -Loop blocking or strip mining transforms, enabled with -@option{-floop-block} or @option{-floop-strip-mine}, strip mine each -loop in the loop nest by a given number of iterations. The strip -length can be changed using the @option{loop-block-tile-size} -parameter. The default value is 51 iterations. +@item -fuse-ld=bfd +@opindex fuse-ld=bfd +Use the @command{bfd} linker instead of the default linker. -@item loop-unroll-jam-size -Specify the unroll factor for the @option{-floop-unroll-and-jam} option. The -default value is 4. +@item -fuse-ld=gold +@opindex fuse-ld=gold +Use the @command{gold} linker instead of the default linker. -@item loop-unroll-jam-depth -Specify the dimension to be unrolled (counting from the most inner loop) -for the @option{-floop-unroll-and-jam}. The default value is 2. +@cindex Libraries +@item -l@var{library} +@itemx -l @var{library} +@opindex l +Search the library named @var{library} when linking. (The second +alternative with the library as a separate argument is only for +POSIX compliance and is not recommended.) -@item ipa-cp-value-list-size -IPA-CP attempts to track all possible values and types passed to a function's -parameter in order to propagate them and perform devirtualization. -@option{ipa-cp-value-list-size} is the maximum number of values and types it -stores per one formal parameter of a function. +It makes a difference where in the command you write this option; the +linker searches and processes libraries and object files in the order they +are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z} +after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers +to functions in @samp{z}, those functions may not be loaded. -@item ipa-cp-eval-threshold -IPA-CP calculates its own score of cloning profitability heuristics -and performs those cloning opportunities with scores that exceed -@option{ipa-cp-eval-threshold}. +The linker searches a standard list of directories for the library, +which is actually a file named @file{lib@var{library}.a}. The linker +then uses this file as if it had been specified precisely by name. -@item ipa-cp-recursion-penalty -Percentage penalty the recursive functions will receive when they -are evaluated for cloning. +The directories searched include several standard system directories +plus any that you specify with @option{-L}. -@item ipa-cp-single-call-penalty -Percentage penalty functions containg a single call to another -function will receive when they are evaluated for cloning. +Normally the files found this way are library files---archive files +whose members are object files. The linker handles an archive file by +scanning through it for members which define symbols that have so far +been referenced but not defined. But if the file that is found is an +ordinary object file, it is linked in the usual fashion. The only +difference between using an @option{-l} option and specifying a file name +is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a} +and searches several directories. +@item -lobjc +@opindex lobjc +You need this special case of the @option{-l} option in order to +link an Objective-C or Objective-C++ program. -@item ipa-max-agg-items -IPA-CP is also capable to propagate a number of scalar values passed -in an aggregate. @option{ipa-max-agg-items} controls the maximum -number of such values per one parameter. +@item -nostartfiles +@opindex nostartfiles +Do not use the standard system startup files when linking. +The standard system libraries are used normally, unless @option{-nostdlib} +or @option{-nodefaultlibs} is used. -@item ipa-cp-loop-hint-bonus -When IPA-CP determines that a cloning candidate would make the number -of iterations of a loop known, it adds a bonus of -@option{ipa-cp-loop-hint-bonus} to the profitability score of -the candidate. +@item -nodefaultlibs +@opindex nodefaultlibs +Do not use the standard system libraries when linking. +Only the libraries you specify are passed to the linker, and options +specifying linkage of the system libraries, such as @option{-static-libgcc} +or @option{-shared-libgcc}, are ignored. +The standard startup files are used normally, unless @option{-nostartfiles} +is used. -@item ipa-cp-array-index-hint-bonus -When IPA-CP determines that a cloning candidate would make the index of -an array access known, it adds a bonus of -@option{ipa-cp-array-index-hint-bonus} to the profitability -score of the candidate. +The compiler may generate calls to @code{memcmp}, +@code{memset}, @code{memcpy} and @code{memmove}. +These entries are usually resolved by entries in +libc. These entry points should be supplied through some other +mechanism when this option is specified. -@item ipa-max-aa-steps -During its analysis of function bodies, IPA-CP employs alias analysis -in order to track values pointed to by function parameters. In order -not spend too much time analyzing huge functions, it gives up and -consider all memory clobbered after examining -@option{ipa-max-aa-steps} statements modifying memory. +@item -nostdlib +@opindex nostdlib +Do not use the standard system startup files or libraries when linking. +No startup files and only the libraries you specify are passed to +the linker, and options specifying linkage of the system libraries, such as +@option{-static-libgcc} or @option{-shared-libgcc}, are ignored. -@item lto-partitions -Specify desired number of partitions produced during WHOPR compilation. -The number of partitions should exceed the number of CPUs used for compilation. -The default value is 32. +The compiler may generate calls to @code{memcmp}, @code{memset}, +@code{memcpy} and @code{memmove}. +These entries are usually resolved by entries in +libc. These entry points should be supplied through some other +mechanism when this option is specified. -@item lto-minpartition -Size of minimal partition for WHOPR (in estimated instructions). -This prevents expenses of splitting very small programs into too many -partitions. +@cindex @option{-lgcc}, use with @option{-nostdlib} +@cindex @option{-nostdlib} and unresolved references +@cindex unresolved references and @option{-nostdlib} +@cindex @option{-lgcc}, use with @option{-nodefaultlibs} +@cindex @option{-nodefaultlibs} and unresolved references +@cindex unresolved references and @option{-nodefaultlibs} +One of the standard libraries bypassed by @option{-nostdlib} and +@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines +which GCC uses to overcome shortcomings of particular machines, or special +needs for some languages. +(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler +Collection (GCC) Internals}, +for more discussion of @file{libgcc.a}.) +In most cases, you need @file{libgcc.a} even when you want to avoid +other standard libraries. In other words, when you specify @option{-nostdlib} +or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well. +This ensures that you have no unresolved references to internal GCC +library subroutines. +(An example of such an internal subroutine is @code{__main}, used to ensure C++ +constructors are called; @pxref{Collect2,,@code{collect2}, gccint, +GNU Compiler Collection (GCC) Internals}.) -@item cxx-max-namespaces-for-diagnostic-help -The maximum number of namespaces to consult for suggestions when C++ -name lookup fails for an identifier. The default is 1000. +@item -pie +@opindex pie +Produce a position independent executable on targets that support it. +For predictable results, you must also specify the same set of options +used for compilation (@option{-fpie}, @option{-fPIE}, +or model suboptions) when you specify this linker option. -@item sink-frequency-threshold -The maximum relative execution frequency (in percents) of the target block -relative to a statement's original block to allow statement sinking of a -statement. Larger numbers result in more aggressive statement sinking. -The default value is 75. A small positive adjustment is applied for -statements with memory operands as those are even more profitable so sink. +@item -no-pie +@opindex no-pie +Don't produce a position independent executable. -@item max-stores-to-sink -The maximum number of conditional stores paires that can be sunk. Set to 0 -if either vectorization (@option{-ftree-vectorize}) or if-conversion -(@option{-ftree-loop-if-convert}) is disabled. The default is 2. +@item -rdynamic +@opindex rdynamic +Pass the flag @option{-export-dynamic} to the ELF linker, on targets +that support it. This instructs the linker to add all symbols, not +only used ones, to the dynamic symbol table. This option is needed +for some uses of @code{dlopen} or to allow obtaining backtraces +from within a program. -@item allow-store-data-races -Allow optimizers to introduce new data races on stores. -Set to 1 to allow, otherwise to 0. This option is enabled by default -at optimization level @option{-Ofast}. +@item -s +@opindex s +Remove all symbol table and relocation information from the executable. -@item case-values-threshold -The smallest number of different values for which it is best to use a -jump-table instead of a tree of conditional branches. If the value is -0, use the default for the machine. The default is 0. +@item -static +@opindex static +On systems that support dynamic linking, this prevents linking with the shared +libraries. On other systems, this option has no effect. -@item tree-reassoc-width -Set the maximum number of instructions executed in parallel in -reassociated tree. This parameter overrides target dependent -heuristics used by default if has non zero value. +@item -shared +@opindex shared +Produce a shared object which can then be linked with other objects to +form an executable. Not all systems support this option. For predictable +results, you must also specify the same set of options used for compilation +(@option{-fpic}, @option{-fPIC}, or model suboptions) when +you specify this linker option.@footnote{On some systems, @samp{gcc -shared} +needs to build supplementary stub code for constructors to work. On +multi-libbed systems, @samp{gcc -shared} must select the correct support +libraries to link against. Failing to supply the correct flags may lead +to subtle defects. Supplying them in cases where they are not necessary +is innocuous.} -@item sched-pressure-algorithm -Choose between the two available implementations of -@option{-fsched-pressure}. Algorithm 1 is the original implementation -and is the more likely to prevent instructions from being reordered. -Algorithm 2 was designed to be a compromise between the relatively -conservative approach taken by algorithm 1 and the rather aggressive -approach taken by the default scheduler. It relies more heavily on -having a regular register file and accurate register pressure classes. -See @file{haifa-sched.c} in the GCC sources for more details. +@item -shared-libgcc +@itemx -static-libgcc +@opindex shared-libgcc +@opindex static-libgcc +On systems that provide @file{libgcc} as a shared library, these options +force the use of either the shared or static version, respectively. +If no shared version of @file{libgcc} was built when the compiler was +configured, these options have no effect. -The default choice depends on the target. +There are several situations in which an application should use the +shared @file{libgcc} instead of the static version. The most common +of these is when the application wishes to throw and catch exceptions +across different shared libraries. In that case, each of the libraries +as well as the application itself should use the shared @file{libgcc}. -@item max-slsr-cand-scan -Set the maximum number of existing candidates that are considered when -seeking a basis for a new straight-line strength reduction candidate. +Therefore, the G++ and GCJ drivers automatically add +@option{-shared-libgcc} whenever you build a shared library or a main +executable, because C++ and Java programs typically use exceptions, so +this is the right thing to do. -@item asan-globals -Enable buffer overflow detection for global objects. This kind -of protection is enabled by default if you are using -@option{-fsanitize=address} option. -To disable global objects protection use @option{--param asan-globals=0}. +If, instead, you use the GCC driver to create shared libraries, you may +find that they are not always linked with the shared @file{libgcc}. +If GCC finds, at its configuration time, that you have a non-GNU linker +or a GNU linker that does not support option @option{--eh-frame-hdr}, +it links the shared version of @file{libgcc} into shared libraries +by default. Otherwise, it takes advantage of the linker and optimizes +away the linking with the shared version of @file{libgcc}, linking with +the static version of libgcc by default. This allows exceptions to +propagate through such shared libraries, without incurring relocation +costs at library load time. -@item asan-stack -Enable buffer overflow detection for stack objects. This kind of -protection is enabled by default when using @option{-fsanitize=address}. -To disable stack protection use @option{--param asan-stack=0} option. +However, if a library or main executable is supposed to throw or catch +exceptions, you must link it using the G++ or GCJ driver, as appropriate +for the languages used in the program, or using the option +@option{-shared-libgcc}, such that it is linked with the shared +@file{libgcc}. -@item asan-instrument-reads -Enable buffer overflow detection for memory reads. This kind of -protection is enabled by default when using @option{-fsanitize=address}. -To disable memory reads protection use -@option{--param asan-instrument-reads=0}. +@item -static-libasan +@opindex static-libasan +When the @option{-fsanitize=address} option is used to link a program, +the GCC driver automatically links against @option{libasan}. If +@file{libasan} is available as a shared library, and the @option{-static} +option is not used, then this links against the shared version of +@file{libasan}. The @option{-static-libasan} option directs the GCC +driver to link @file{libasan} statically, without necessarily linking +other libraries statically. -@item asan-instrument-writes -Enable buffer overflow detection for memory writes. This kind of -protection is enabled by default when using @option{-fsanitize=address}. -To disable memory writes protection use -@option{--param asan-instrument-writes=0} option. +@item -static-libtsan +@opindex static-libtsan +When the @option{-fsanitize=thread} option is used to link a program, +the GCC driver automatically links against @option{libtsan}. If +@file{libtsan} is available as a shared library, and the @option{-static} +option is not used, then this links against the shared version of +@file{libtsan}. The @option{-static-libtsan} option directs the GCC +driver to link @file{libtsan} statically, without necessarily linking +other libraries statically. -@item asan-memintrin -Enable detection for built-in functions. This kind of protection -is enabled by default when using @option{-fsanitize=address}. -To disable built-in functions protection use -@option{--param asan-memintrin=0}. +@item -static-liblsan +@opindex static-liblsan +When the @option{-fsanitize=leak} option is used to link a program, +the GCC driver automatically links against @option{liblsan}. If +@file{liblsan} is available as a shared library, and the @option{-static} +option is not used, then this links against the shared version of +@file{liblsan}. The @option{-static-liblsan} option directs the GCC +driver to link @file{liblsan} statically, without necessarily linking +other libraries statically. -@item asan-use-after-return -Enable detection of use-after-return. This kind of protection -is enabled by default when using @option{-fsanitize=address} option. -To disable use-after-return detection use -@option{--param asan-use-after-return=0}. +@item -static-libubsan +@opindex static-libubsan +When the @option{-fsanitize=undefined} option is used to link a program, +the GCC driver automatically links against @option{libubsan}. If +@file{libubsan} is available as a shared library, and the @option{-static} +option is not used, then this links against the shared version of +@file{libubsan}. The @option{-static-libubsan} option directs the GCC +driver to link @file{libubsan} statically, without necessarily linking +other libraries statically. -@item asan-instrumentation-with-call-threshold -If number of memory accesses in function being instrumented -is greater or equal to this number, use callbacks instead of inline checks. -E.g. to disable inline code use -@option{--param asan-instrumentation-with-call-threshold=0}. +@item -static-libmpx +@opindex static-libmpx +When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are +used to link a program, the GCC driver automatically links against +@file{libmpx}. If @file{libmpx} is available as a shared library, +and the @option{-static} option is not used, then this links against +the shared version of @file{libmpx}. The @option{-static-libmpx} +option directs the GCC driver to link @file{libmpx} statically, +without necessarily linking other libraries statically. -@item chkp-max-ctor-size -Static constructors generated by Pointer Bounds Checker may become very -large and significantly increase compile time at optimization level -@option{-O1} and higher. This parameter is a maximum nubmer of statements -in a single generated constructor. Default value is 5000. +@item -static-libmpxwrappers +@opindex static-libmpxwrappers +When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are used +to link a program without also using @option{-fno-chkp-use-wrappers}, the +GCC driver automatically links against @file{libmpxwrappers}. If +@file{libmpxwrappers} is available as a shared library, and the +@option{-static} option is not used, then this links against the shared +version of @file{libmpxwrappers}. The @option{-static-libmpxwrappers} +option directs the GCC driver to link @file{libmpxwrappers} statically, +without necessarily linking other libraries statically. -@item max-fsm-thread-path-insns -Maximum number of instructions to copy when duplicating blocks on a -finite state automaton jump thread path. The default is 100. +@item -static-libstdc++ +@opindex static-libstdc++ +When the @command{g++} program is used to link a C++ program, it +normally automatically links against @option{libstdc++}. If +@file{libstdc++} is available as a shared library, and the +@option{-static} option is not used, then this links against the +shared version of @file{libstdc++}. That is normally fine. However, it +is sometimes useful to freeze the version of @file{libstdc++} used by +the program without going all the way to a fully static link. The +@option{-static-libstdc++} option directs the @command{g++} driver to +link @file{libstdc++} statically, without necessarily linking other +libraries statically. -@item max-fsm-thread-length -Maximum number of basic blocks on a finite state automaton jump thread -path. The default is 10. +@item -symbolic +@opindex symbolic +Bind references to global symbols when building a shared object. Warn +about any unresolved references (unless overridden by the link editor +option @option{-Xlinker -z -Xlinker defs}). Only a few systems support +this option. -@item max-fsm-thread-paths -Maximum number of new jump thread paths to create for a finite state -automaton. The default is 50. +@item -T @var{script} +@opindex T +@cindex linker script +Use @var{script} as the linker script. This option is supported by most +systems using the GNU linker. On some targets, such as bare-board +targets without an operating system, the @option{-T} option may be required +when linking to avoid references to undefined symbols. -@item parloops-chunk-size -Chunk size of omp schedule for loops parallelized by parloops. The default -is 0. +@item -Xlinker @var{option} +@opindex Xlinker +Pass @var{option} as an option to the linker. You can use this to +supply system-specific linker options that GCC does not recognize. -@item parloops-schedule -Schedule type of omp schedule for loops parallelized by parloops (static, -dynamic, guided, auto, runtime). The default is static. +If you want to pass an option that takes a separate argument, you must use +@option{-Xlinker} twice, once for the option and once for the argument. +For example, to pass @option{-assert definitions}, you must write +@option{-Xlinker -assert -Xlinker definitions}. It does not work to write +@option{-Xlinker "-assert definitions"}, because this passes the entire +string as a single argument, which is not what the linker expects. -@item max-ssa-name-query-depth -Maximum depth of recursion when querying properties of SSA names in things -like fold routines. One level of recursion corresponds to following a -use-def chain. -@end table -@end table +When using the GNU linker, it is usually more convenient to pass +arguments to linker options using the @option{@var{option}=@var{value}} +syntax than as separate arguments. For example, you can specify +@option{-Xlinker -Map=output.map} rather than +@option{-Xlinker -Map -Xlinker output.map}. Other linkers may not support +this syntax for command-line options. -@node Instrumentation Options -@section Program Instrumentation Options -@cindex instrumentation options -@cindex program instrumentation options -@cindex run-time error checking options -@cindex profiling options -@cindex options, program instrumentation -@cindex options, run-time error checking -@cindex options, profiling +@item -Wl,@var{option} +@opindex Wl +Pass @var{option} as an option to the linker. If @var{option} contains +commas, it is split into multiple options at the commas. You can use this +syntax to pass an argument to the option. +For example, @option{-Wl,-Map,output.map} passes @option{-Map output.map} to the +linker. When using the GNU linker, you can also get the same effect with +@option{-Wl,-Map=output.map}. -GCC supports a number of command-line options that control adding -run-time instrumentation to the code it normally generates. -For example, one purpose of instrumentation is collect profiling -statistics for use in finding program hot spots, code coverage -analysis, or profile-guided optimizations. -Another class of program instrumentation is adding run-time checking -to detect programming errors like invalid pointer -dereferences or out-of-bounds array accesses, as well as deliberately -hostile attacks such as stack smashing or C++ vtable hijacking. -There is also a general hook which can be used to implement other -forms of tracing or function-level instrumentation for debug or -program analysis purposes. +@item -u @var{symbol} +@opindex u +Pretend the symbol @var{symbol} is undefined, to force linking of +library modules to define it. You can use @option{-u} multiple times with +different symbols to force loading of additional library modules. -@table @gcctabopt -@cindex @command{prof} -@item -p -@opindex p -Generate extra code to write profile information suitable for the -analysis program @command{prof}. You must use this option when compiling -the source files you want data about, and you must also use it when -linking. +@item -z @var{keyword} +@opindex z +@option{-z} is passed directly on to the linker along with the keyword +@var{keyword}. See the section in the documentation of your linker for +permitted values and their meanings. +@end table -@cindex @command{gprof} -@item -pg -@opindex pg -Generate extra code to write profile information suitable for the -analysis program @command{gprof}. You must use this option when compiling -the source files you want data about, and you must also use it when -linking. +@node Directory Options +@section Options for Directory Search +@cindex directory options +@cindex options, directory search +@cindex search path -@item -fprofile-arcs -@opindex fprofile-arcs -Add code so that program flow @dfn{arcs} are instrumented. During -execution the program records how many times each branch and call is -executed and how many times it is taken or returns. When the compiled -program exits it saves this data to a file called -@file{@var{auxname}.gcda} for each source file. The data may be used for -profile-directed optimizations (@option{-fbranch-probabilities}), or for -test coverage analysis (@option{-ftest-coverage}). Each object file's -@var{auxname} is generated from the name of the output file, if -explicitly specified and it is not the final executable, otherwise it is -the basename of the source file. In both cases any suffix is removed -(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or -@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}). -@xref{Cross-profiling}. +These options specify directories to search for header files, for +libraries and for parts of the compiler: -@cindex @command{gcov} -@item --coverage -@opindex coverage - -This option is used to compile and link code instrumented for coverage -analysis. The option is a synonym for @option{-fprofile-arcs} -@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when -linking). See the documentation for those options for more details. +@table @gcctabopt +@item -I@var{dir} +@opindex I +Add the directory @var{dir} to the head of the list of directories to be +searched for header files. This can be used to override a system header +file, substituting your own version, since these directories are +searched before the system header file directories. However, you should +not use this option to add directories that contain vendor-supplied +system header files (use @option{-isystem} for that). If you use more than +one @option{-I} option, the directories are scanned in left-to-right +order; the standard system directories come after. -@itemize +If a standard system include directory, or a directory specified with +@option{-isystem}, is also specified with @option{-I}, the @option{-I} +option is ignored. The directory is still searched but as a +system directory at its normal position in the system include chain. +This is to ensure that GCC's procedure to fix buggy system headers and +the ordering for the @code{include_next} directive are not inadvertently changed. +If you really need to change the search order for system directories, +use the @option{-nostdinc} and/or @option{-isystem} options. -@item -Compile the source files with @option{-fprofile-arcs} plus optimization -and code generation options. For test coverage analysis, use the -additional @option{-ftest-coverage} option. You do not need to profile -every source file in a program. +@item -iplugindir=@var{dir} +@opindex iplugindir= +Set the directory to search for plugins that are passed +by @option{-fplugin=@var{name}} instead of +@option{-fplugin=@var{path}/@var{name}.so}. This option is not meant +to be used by the user, but only passed by the driver. -@item -Link your object files with @option{-lgcov} or @option{-fprofile-arcs} -(the latter implies the former). +@item -iquote@var{dir} +@opindex iquote +Add the directory @var{dir} to the head of the list of directories to +be searched for header files only for the case of @code{#include +"@var{file}"}; they are not searched for @code{#include <@var{file}>}, +otherwise just like @option{-I}. -@item -Run the program on a representative workload to generate the arc profile -information. This may be repeated any number of times. You can run -concurrent instances of your program, and provided that the file system -supports locking, the data files will be correctly updated. Also -@code{fork} calls are detected and correctly handled (double counting -will not happen). +@item -L@var{dir} +@opindex L +Add directory @var{dir} to the list of directories to be searched +for @option{-l}. -@item -For profile-directed optimizations, compile the source files again with -the same optimization and code generation options plus -@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that -Control Optimization}). +@item -B@var{prefix} +@opindex B +This option specifies where to find the executables, libraries, +include files, and data files of the compiler itself. -@item -For test coverage analysis, use @command{gcov} to produce human readable -information from the @file{.gcno} and @file{.gcda} files. Refer to the -@command{gcov} documentation for further information. +The compiler driver program runs one or more of the subprograms +@command{cpp}, @command{cc1}, @command{as} and @command{ld}. It tries +@var{prefix} as a prefix for each program it tries to run, both with and +without @samp{@var{machine}/@var{version}/} for the corresponding target +machine and compiler version. -@end itemize +For each subprogram to be run, the compiler driver first tries the +@option{-B} prefix, if any. If that name is not found, or if @option{-B} +is not specified, the driver tries two standard prefixes, +@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of +those results in a file name that is found, the unmodified program +name is searched for using the directories specified in your +@env{PATH} environment variable. -With @option{-fprofile-arcs}, for each function of your program GCC -creates a program flow graph, then finds a spanning tree for the graph. -Only arcs that are not on the spanning tree have to be instrumented: the -compiler adds code to count the number of times that these arcs are -executed. When an arc is the only exit or only entrance to a block, the -instrumentation code can be added to the block; otherwise, a new basic -block must be created to hold the instrumentation code. +The compiler checks to see if the path provided by @option{-B} +refers to a directory, and if necessary it adds a directory +separator character at the end of the path. -@need 2000 -@item -ftest-coverage -@opindex ftest-coverage -Produce a notes file that the @command{gcov} code-coverage utility -(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to -show program coverage. Each source file's note file is called -@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option -above for a description of @var{auxname} and instructions on how to -generate test coverage data. Coverage data matches the source files -more closely if you do not optimize. +@option{-B} prefixes that effectively specify directory names also apply +to libraries in the linker, because the compiler translates these +options into @option{-L} options for the linker. They also apply to +include files in the preprocessor, because the compiler translates these +options into @option{-isystem} options for the preprocessor. In this case, +the compiler appends @samp{include} to the prefix. -@item -fprofile-dir=@var{path} -@opindex fprofile-dir +The runtime support file @file{libgcc.a} can also be searched for using +the @option{-B} prefix, if needed. If it is not found there, the two +standard prefixes above are tried, and that is all. The file is left +out of the link if it is not found by those means. -Set the directory to search for the profile data files in to @var{path}. -This option affects only the profile data generated by -@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs} -and used by @option{-fprofile-use} and @option{-fbranch-probabilities} -and its related options. Both absolute and relative paths can be used. -By default, GCC uses the current directory as @var{path}, thus the -profile data file appears in the same directory as the object file. +Another way to specify a prefix much like the @option{-B} prefix is to use +the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment +Variables}. -@item -fprofile-generate -@itemx -fprofile-generate=@var{path} -@opindex fprofile-generate +As a special kludge, if the path provided by @option{-B} is +@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to +9, then it is replaced by @file{[dir/]include}. This is to help +with boot-strapping the compiler. -Enable options usually used for instrumenting application to produce -profile useful for later recompilation with profile feedback based -optimization. You must use @option{-fprofile-generate} both when -compiling and when linking your program. +@item -no-canonical-prefixes +@opindex no-canonical-prefixes +Do not expand any symbolic links, resolve references to @samp{/../} +or @samp{/./}, or make the path absolute when generating a relative +prefix. -The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}. +@item --sysroot=@var{dir} +@opindex sysroot +Use @var{dir} as the logical root directory for headers and libraries. +For example, if the compiler normally searches for headers in +@file{/usr/include} and libraries in @file{/usr/lib}, it instead +searches @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}. -If @var{path} is specified, GCC looks at the @var{path} to find -the profile feedback data files. See @option{-fprofile-dir}. +If you use both this option and the @option{-isysroot} option, then +the @option{--sysroot} option applies to libraries, but the +@option{-isysroot} option applies to header files. -To optimize the program based on the collected profile information, use -@option{-fprofile-use}. @xref{Optimize Options}, for more information. +The GNU linker (beginning with version 2.16) has the necessary support +for this option. If your linker does not support this option, the +header file aspect of @option{--sysroot} still works, but the +library aspect does not. -@item -fsanitize=address -@opindex fsanitize=address -Enable AddressSanitizer, a fast memory error detector. -Memory access instructions are instrumented to detect -out-of-bounds and use-after-free bugs. -See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for -more details. The run-time behavior can be influenced using the -@env{ASAN_OPTIONS} environment variable. When set to @code{help=1}, -the available options are shown at startup of the instrumended program. See -@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags} -for a list of supported options. +@item --no-sysroot-suffix +@opindex no-sysroot-suffix +For some targets, a suffix is added to the root directory specified +with @option{--sysroot}, depending on the other options used, so that +headers may for example be found in +@file{@var{dir}/@var{suffix}/usr/include} instead of +@file{@var{dir}/usr/include}. This option disables the addition of +such a suffix. -@item -fsanitize=kernel-address -@opindex fsanitize=kernel-address -Enable AddressSanitizer for Linux kernel. -See @uref{https://github.com/google/kasan/wiki} for more details. +@item -I- +@opindex I- +This option has been deprecated. Please use @option{-iquote} instead for +@option{-I} directories before the @option{-I-} and remove the @option{-I-} +option. +Any directories you specify with @option{-I} options before the @option{-I-} +option are searched only for the case of @code{#include "@var{file}"}; +they are not searched for @code{#include <@var{file}>}. -@item -fsanitize=thread -@opindex fsanitize=thread -Enable ThreadSanitizer, a fast data race detector. -Memory access instructions are instrumented to detect -data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more -details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS} -environment variable; see -@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of -supported options. +If additional directories are specified with @option{-I} options after +the @option{-I-} option, these directories are searched for all @code{#include} +directives. (Ordinarily @emph{all} @option{-I} directories are used +this way.) -@item -fsanitize=leak -@opindex fsanitize=leak -Enable LeakSanitizer, a memory leak detector. -This option only matters for linking of executables and if neither -@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that -case the executable is linked against a library that overrides @code{malloc} -and other allocator functions. See -@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more -details. The run-time behavior can be influenced using the -@env{LSAN_OPTIONS} environment variable. +In addition, the @option{-I-} option inhibits the use of the current +directory (where the current input file came from) as the first search +directory for @code{#include "@var{file}"}. There is no way to +override this effect of @option{-I-}. With @option{-I.} you can specify +searching the directory that is current when the compiler is +invoked. That is not exactly the same as what the preprocessor does +by default, but it is often satisfactory. -@item -fsanitize=undefined -@opindex fsanitize=undefined -Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. -Various computations are instrumented to detect undefined behavior -at runtime. Current suboptions are: +@option{-I-} does not inhibit the use of the standard system directories +for header files. Thus, @option{-I-} and @option{-nostdinc} are +independent. +@end table -@table @gcctabopt +@node Code Gen Options +@section Options for Code Generation Conventions +@cindex code generation conventions +@cindex options, code generation +@cindex run-time options -@item -fsanitize=shift -@opindex fsanitize=shift -This option enables checking that the result of a shift operation is -not undefined. Note that what exactly is considered undefined differs -slightly between C and C++, as well as between ISO C90 and C99, etc. +These machine-independent options control the interface conventions +used in code generation. -@item -fsanitize=integer-divide-by-zero -@opindex fsanitize=integer-divide-by-zero -Detect integer division by zero as well as @code{INT_MIN / -1} division. +Most of them have both positive and negative forms; the negative form +of @option{-ffoo} is @option{-fno-foo}. In the table below, only +one of the forms is listed---the one that is not the default. You +can figure out the other form by either removing @samp{no-} or adding +it. -@item -fsanitize=unreachable -@opindex fsanitize=unreachable -With this option, the compiler turns the @code{__builtin_unreachable} -call into a diagnostics message call instead. When reaching the -@code{__builtin_unreachable} call, the behavior is undefined. +@table @gcctabopt +@item -fstack-reuse=@var{reuse-level} +@opindex fstack_reuse +This option controls stack space reuse for user declared local/auto variables +and compiler generated temporaries. @var{reuse_level} can be @samp{all}, +@samp{named_vars}, or @samp{none}. @samp{all} enables stack reuse for all +local variables and temporaries, @samp{named_vars} enables the reuse only for +user defined local variables with names, and @samp{none} disables stack reuse +completely. The default value is @samp{all}. The option is needed when the +program extends the lifetime of a scoped local variable or a compiler generated +temporary beyond the end point defined by the language. When a lifetime of +a variable ends, and if the variable lives in memory, the optimizing compiler +has the freedom to reuse its stack space with other temporaries or scoped +local variables whose live range does not overlap with it. Legacy code extending +local lifetime is likely to break with the stack reuse optimization. -@item -fsanitize=vla-bound -@opindex fsanitize=vla-bound -This option instructs the compiler to check that the size of a variable -length array is positive. +For example, -@item -fsanitize=null -@opindex fsanitize=null -This option enables pointer checking. Particularly, the application -built with this option turned on will issue an error message when it -tries to dereference a NULL pointer, or if a reference (possibly an -rvalue reference) is bound to a NULL pointer, or if a method is invoked -on an object pointed by a NULL pointer. +@smallexample + int *p; + @{ + int local1; -@item -fsanitize=return -@opindex fsanitize=return -This option enables return statement checking. Programs -built with this option turned on will issue an error message -when the end of a non-void function is reached without actually -returning a value. This option works in C++ only. + p = &local1; + local1 = 10; + .... + @} + @{ + int local2; + local2 = 20; + ... + @} -@item -fsanitize=signed-integer-overflow -@opindex fsanitize=signed-integer-overflow -This option enables signed integer overflow checking. We check that -the result of @code{+}, @code{*}, and both unary and binary @code{-} -does not overflow in the signed arithmetics. Note, integer promotion -rules must be taken into account. That is, the following is not an -overflow: -@smallexample -signed char a = SCHAR_MAX; -a++; + if (*p == 10) // out of scope use of local1 + @{ + + @} @end smallexample -@item -fsanitize=bounds -@opindex fsanitize=bounds -This option enables instrumentation of array bounds. Various out of bounds -accesses are detected. Flexible array members, flexible array member-like -arrays, and initializers of variables with static storage are not instrumented. +Another example: +@smallexample -@item -fsanitize=bounds-strict -@opindex fsanitize=bounds-strict -This option enables strict instrumentation of array bounds. Most out of bounds -accesses are detected, including flexible array members and flexible array -member-like arrays. Initializers of variables with static storage are not -instrumented. + struct A + @{ + A(int k) : i(k), j(k) @{ @} + int i; + int j; + @}; -@item -fsanitize=alignment -@opindex fsanitize=alignment + A *ap; -This option enables checking of alignment of pointers when they are -dereferenced, or when a reference is bound to insufficiently aligned target, -or when a method or constructor is invoked on insufficiently aligned object. + void foo(const A& ar) + @{ + ap = &ar; + @} -@item -fsanitize=object-size -@opindex fsanitize=object-size -This option enables instrumentation of memory references using the -@code{__builtin_object_size} function. Various out of bounds pointer -accesses are detected. + void bar() + @{ + foo(A(10)); // temp object's lifetime ends when foo returns -@item -fsanitize=float-divide-by-zero -@opindex fsanitize=float-divide-by-zero -Detect floating-point division by zero. Unlike other similar options, -@option{-fsanitize=float-divide-by-zero} is not enabled by -@option{-fsanitize=undefined}, since floating-point division by zero can -be a legitimate way of obtaining infinities and NaNs. + @{ + A a(20); + .... + @} + ap->i+= 10; // ap references out of scope temp whose space + // is reused with a. What is the value of ap->i? + @} -@item -fsanitize=float-cast-overflow -@opindex fsanitize=float-cast-overflow -This option enables floating-point type to integer conversion checking. -We check that the result of the conversion does not overflow. -Unlike other similar options, @option{-fsanitize=float-cast-overflow} is -not enabled by @option{-fsanitize=undefined}. -This option does not work well with @code{FE_INVALID} exceptions enabled. +@end smallexample -@item -fsanitize=nonnull-attribute -@opindex fsanitize=nonnull-attribute +The lifetime of a compiler generated temporary is well defined by the C++ +standard. When a lifetime of a temporary ends, and if the temporary lives +in memory, the optimizing compiler has the freedom to reuse its stack +space with other temporaries or scoped local variables whose live range +does not overlap with it. However some of the legacy code relies on +the behavior of older compilers in which temporaries' stack space is +not reused, the aggressive stack reuse can lead to runtime errors. This +option is used to control the temporary stack reuse optimization. -This option enables instrumentation of calls, checking whether null values -are not passed to arguments marked as requiring a non-null value by the -@code{nonnull} function attribute. +@item -ftrapv +@opindex ftrapv +This option generates traps for signed overflow on addition, subtraction, +multiplication operations. +The options @option{-ftrapv} and @option{-fwrapv} override each other, so using +@option{-ftrapv} @option{-fwrapv} on the command-line results in +@option{-fwrapv} being effective. Note that only active options override, so +using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line +results in @option{-ftrapv} being effective. -@item -fsanitize=returns-nonnull-attribute -@opindex fsanitize=returns-nonnull-attribute +@item -fwrapv +@opindex fwrapv +This option instructs the compiler to assume that signed arithmetic +overflow of addition, subtraction and multiplication wraps around +using twos-complement representation. This flag enables some optimizations +and disables others. This option is enabled by default for the Java +front end, as required by the Java language specification. +The options @option{-ftrapv} and @option{-fwrapv} override each other, so using +@option{-ftrapv} @option{-fwrapv} on the command-line results in +@option{-fwrapv} being effective. Note that only active options override, so +using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line +results in @option{-ftrapv} being effective. -This option enables instrumentation of return statements in functions -marked with @code{returns_nonnull} function attribute, to detect returning -of null values from such functions. +@item -fexceptions +@opindex fexceptions +Enable exception handling. Generates extra code needed to propagate +exceptions. For some targets, this implies GCC generates frame +unwind information for all functions, which can produce significant data +size overhead, although it does not affect execution. If you do not +specify this option, GCC enables it by default for languages like +C++ that normally require exception handling, and disables it for +languages like C that do not normally require it. However, you may need +to enable this option when compiling C code that needs to interoperate +properly with exception handlers written in C++. You may also wish to +disable this option if you are compiling older C++ programs that don't +use exception handling. -@item -fsanitize=bool -@opindex fsanitize=bool +@item -fnon-call-exceptions +@opindex fnon-call-exceptions +Generate code that allows trapping instructions to throw exceptions. +Note that this requires platform-specific runtime support that does +not exist everywhere. Moreover, it only allows @emph{trapping} +instructions to throw exceptions, i.e.@: memory references or floating-point +instructions. It does not allow exceptions to be thrown from +arbitrary signal handlers such as @code{SIGALRM}. -This option enables instrumentation of loads from bool. If a value other -than 0/1 is loaded, a run-time error is issued. +@item -fdelete-dead-exceptions +@opindex fdelete-dead-exceptions +Consider that instructions that may throw exceptions but don't otherwise +contribute to the execution of the program can be optimized away. +This option is enabled by default for the Ada front end, as permitted by +the Ada language specification. +Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels. -@item -fsanitize=enum -@opindex fsanitize=enum +@item -funwind-tables +@opindex funwind-tables +Similar to @option{-fexceptions}, except that it just generates any needed +static data, but does not affect the generated code in any other way. +You normally do not need to enable this option; instead, a language processor +that needs this handling enables it on your behalf. -This option enables instrumentation of loads from an enum type. If -a value outside the range of values for the enum type is loaded, -a run-time error is issued. +@item -fasynchronous-unwind-tables +@opindex fasynchronous-unwind-tables +Generate unwind table in DWARF 2 format, if supported by target machine. The +table is exact at each instruction boundary, so it can be used for stack +unwinding from asynchronous events (such as debugger or garbage collector). -@item -fsanitize=vptr -@opindex fsanitize=vptr +@item -fno-gnu-unique +@opindex fno-gnu-unique +On systems with recent GNU assembler and C library, the C++ compiler +uses the @code{STB_GNU_UNIQUE} binding to make sure that definitions +of template static data members and static local variables in inline +functions are unique even in the presence of @code{RTLD_LOCAL}; this +is necessary to avoid problems with a library used by two different +@code{RTLD_LOCAL} plugins depending on a definition in one of them and +therefore disagreeing with the other one about the binding of the +symbol. But this causes @code{dlclose} to be ignored for affected +DSOs; if your program relies on reinitialization of a DSO via +@code{dlclose} and @code{dlopen}, you can use +@option{-fno-gnu-unique}. -This option enables instrumentation of C++ member function calls, member -accesses and some conversions between pointers to base and derived classes, -to verify the referenced object has the correct dynamic type. +@item -fpcc-struct-return +@opindex fpcc-struct-return +Return ``short'' @code{struct} and @code{union} values in memory like +longer ones, rather than in registers. This convention is less +efficient, but it has the advantage of allowing intercallability between +GCC-compiled files and files compiled with other compilers, particularly +the Portable C Compiler (pcc). -@end table +The precise convention for returning structures in memory depends +on the target configuration macros. -While @option{-ftrapv} causes traps for signed overflows to be emitted, -@option{-fsanitize=undefined} gives a diagnostic message. -This currently works only for the C family of languages. +Short structures and unions are those whose size and alignment match +that of some integer type. -@item -fno-sanitize=all -@opindex fno-sanitize=all +@strong{Warning:} code compiled with the @option{-fpcc-struct-return} +switch is not binary compatible with code compiled with the +@option{-freg-struct-return} switch. +Use it to conform to a non-default application binary interface. -This option disables all previously enabled sanitizers. -@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used -together. +@item -freg-struct-return +@opindex freg-struct-return +Return @code{struct} and @code{union} values in registers when possible. +This is more efficient for small structures than +@option{-fpcc-struct-return}. -@item -fasan-shadow-offset=@var{number} -@opindex fasan-shadow-offset -This option forces GCC to use custom shadow offset in AddressSanitizer checks. -It is useful for experimenting with different shadow memory layouts in -Kernel AddressSanitizer. - -@item -fsanitize-sections=@var{s1},@var{s2},... -@opindex fsanitize-sections -Sanitize global variables in selected user-defined sections. @var{si} may -contain wildcards. +If you specify neither @option{-fpcc-struct-return} nor +@option{-freg-struct-return}, GCC defaults to whichever convention is +standard for the target. If there is no standard convention, GCC +defaults to @option{-fpcc-struct-return}, except on targets where GCC is +the principal compiler. In those cases, we can choose the standard, and +we chose the more efficient register return alternative. -@item -fsanitize-recover@r{[}=@var{opts}@r{]} -@opindex fsanitize-recover -@opindex fno-sanitize-recover -@option{-fsanitize-recover=} controls error recovery mode for sanitizers -mentioned in comma-separated list of @var{opts}. Enabling this option -for a sanitizer component causes it to attempt to continue -running the program as if no error happened. This means multiple -runtime errors can be reported in a single program run, and the exit -code of the program may indicate success even when errors -have been reported. The @option{-fno-sanitize-recover=} option -can be used to alter -this behavior: only the first detected error is reported -and program then exits with a non-zero exit code. +@strong{Warning:} code compiled with the @option{-freg-struct-return} +switch is not binary compatible with code compiled with the +@option{-fpcc-struct-return} switch. +Use it to conform to a non-default application binary interface. -Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions -except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}), -@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero}, -@option{-fsanitize=kernel-address} and @option{-fsanitize=address}. -For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address}, -for which this feature is experimental. -@option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also -accepted, the former enables recovery for all sanitizers that support it, -the latter disables recovery for all sanitizers that support it. +@item -fshort-enums +@opindex fshort-enums +Allocate to an @code{enum} type only as many bytes as it needs for the +declared range of possible values. Specifically, the @code{enum} type +is equivalent to the smallest integer type that has enough room. -Syntax without explicit @var{opts} parameter is deprecated. It is equivalent to -@smallexample --fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero -@end smallexample -@noindent -Similarly @option{-fno-sanitize-recover} is equivalent to -@smallexample --fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero -@end smallexample +@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Use it to conform to a non-default application binary interface. -@item -fsanitize-undefined-trap-on-error -@opindex fsanitize-undefined-trap-on-error -The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to -report undefined behavior using @code{__builtin_trap} rather than -a @code{libubsan} library routine. The advantage of this is that the -@code{libubsan} library is not needed and is not linked in, so this -is usable even in freestanding environments. +@item -fshort-double +@opindex fshort-double +Use the same size for @code{double} as for @code{float}. -@item -fsanitize-coverage=trace-pc -@opindex fsanitize-coverage=trace-pc -Enable coverage-guided fuzzing code instrumentation. -Inserts call to __sanitizer_cov_trace_pc into every basic block. +@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Use it to conform to a non-default application binary interface. -@item -fbounds-check -@opindex fbounds-check -For front ends that support it, generate additional code to check that -indices used to access arrays are within the declared range. This is -currently only supported by the Java and Fortran front ends, where -this option defaults to true and false respectively. +@item -fshort-wchar +@opindex fshort-wchar +Override the underlying type for @code{wchar_t} to be @code{short +unsigned int} instead of the default for the target. This option is +useful for building programs to run under WINE@. -@item -fcheck-pointer-bounds -@opindex fcheck-pointer-bounds -@opindex fno-check-pointer-bounds -@cindex Pointer Bounds Checker options -Enable Pointer Bounds Checker instrumentation. Each memory reference -is instrumented with checks of the pointer used for memory access against -bounds associated with that pointer. +@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Use it to conform to a non-default application binary interface. -Currently there -is only an implementation for Intel MPX available, thus x86 target -and @option{-mmpx} are required to enable this feature. -MPX-based instrumentation requires -a runtime library to enable MPX in hardware and handle bounds -violation signals. By default when @option{-fcheck-pointer-bounds} -and @option{-mmpx} options are used to link a program, the GCC driver -links against the @file{libmpx} runtime library and @file{libmpxwrappers} -library. It also passes '-z bndplt' to a linker in case it supports this -option (which is checked on libmpx configuration). Note that old versions -of linker may ignore option. Gold linker doesn't support '-z bndplt' -option. With no '-z bndplt' support in linker all calls to dynamic libraries -lose passed bounds reducing overall protection level. It's highly -recommended to use linker with '-z bndplt' support. In case such linker -is not available it is adviced to always use @option{-static-libmpxwrappers} -for better protection level or use @option{-static} to completely avoid -external calls to dynamic libraries. MPX-based instrumentation -may be used for debugging and also may be included in production code -to increase program security. Depending on usage, you may -have different requirements for the runtime library. The current version -of the MPX runtime library is more oriented for use as a debugging -tool. MPX runtime library usage implies @option{-lpthread}. See -also @option{-static-libmpx}. The runtime library behavior can be -influenced using various @env{CHKP_RT_*} environment variables. See -@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler} -for more details. +@item -fno-common +@opindex fno-common +In C code, controls the placement of uninitialized global variables. +Unix C compilers have traditionally permitted multiple definitions of +such variables in different compilation units by placing the variables +in a common block. +This is the behavior specified by @option{-fcommon}, and is the default +for GCC on most targets. +On the other hand, this behavior is not required by ISO C, and on some +targets may carry a speed or code size penalty on variable references. +The @option{-fno-common} option specifies that the compiler should place +uninitialized global variables in the data section of the object file, +rather than generating them as common blocks. +This has the effect that if the same variable is declared +(without @code{extern}) in two different compilations, +you get a multiple-definition error when you link them. +In this case, you must compile with @option{-fcommon} instead. +Compiling with @option{-fno-common} is useful on targets for which +it provides better performance, or if you wish to verify that the +program will work on other systems that always treat uninitialized +variable declarations this way. -Generated instrumentation may be controlled by various -@option{-fchkp-*} options and by the @code{bnd_variable_size} -structure field attribute (@pxref{Type Attributes}) and -@code{bnd_legacy}, and @code{bnd_instrument} function attributes -(@pxref{Function Attributes}). GCC also provides a number of built-in -functions for controlling the Pointer Bounds Checker. @xref{Pointer -Bounds Checker builtins}, for more information. +@item -fno-ident +@opindex fno-ident +Ignore the @code{#ident} directive. -@item -fchkp-check-incomplete-type -@opindex fchkp-check-incomplete-type -@opindex fno-chkp-check-incomplete-type -Generate pointer bounds checks for variables with incomplete type. -Enabled by default. +@item -finhibit-size-directive +@opindex finhibit-size-directive +Don't output a @code{.size} assembler directive, or anything else that +would cause trouble if the function is split in the middle, and the +two halves are placed at locations far apart in memory. This option is +used when compiling @file{crtstuff.c}; you should not need to use it +for anything else. -@item -fchkp-narrow-bounds -@opindex fchkp-narrow-bounds -@opindex fno-chkp-narrow-bounds -Controls bounds used by Pointer Bounds Checker for pointers to object -fields. If narrowing is enabled then field bounds are used. Otherwise -object bounds are used. See also @option{-fchkp-narrow-to-innermost-array} -and @option{-fchkp-first-field-has-own-bounds}. Enabled by default. +@item -fverbose-asm +@opindex fverbose-asm +Put extra commentary information in the generated assembly code to +make it more readable. This option is generally only of use to those +who actually need to read the generated assembly code (perhaps while +debugging the compiler itself). -@item -fchkp-first-field-has-own-bounds -@opindex fchkp-first-field-has-own-bounds -@opindex fno-chkp-first-field-has-own-bounds -Forces Pointer Bounds Checker to use narrowed bounds for the address of the -first field in the structure. By default a pointer to the first field has -the same bounds as a pointer to the whole structure. +@option{-fno-verbose-asm}, the default, causes the +extra information to be omitted and is useful when comparing two assembler +files. -@item -fchkp-narrow-to-innermost-array -@opindex fchkp-narrow-to-innermost-array -@opindex fno-chkp-narrow-to-innermost-array -Forces Pointer Bounds Checker to use bounds of the innermost arrays in -case of nested static array access. By default this option is disabled and -bounds of the outermost array are used. +@item -frecord-gcc-switches +@opindex frecord-gcc-switches +This switch causes the command line used to invoke the +compiler to be recorded into the object file that is being created. +This switch is only implemented on some targets and the exact format +of the recording is target and binary file format dependent, but it +usually takes the form of a section containing ASCII text. This +switch is related to the @option{-fverbose-asm} switch, but that +switch only records information in the assembler output file as +comments, so it never reaches the object file. +See also @option{-grecord-gcc-switches} for another +way of storing compiler options into the object file. -@item -fchkp-optimize -@opindex fchkp-optimize -@opindex fno-chkp-optimize -Enables Pointer Bounds Checker optimizations. Enabled by default at -optimization levels @option{-O}, @option{-O2}, @option{-O3}. +@item -fpic +@opindex fpic +@cindex global offset table +@cindex PIC +Generate position-independent code (PIC) suitable for use in a shared +library, if supported for the target machine. Such code accesses all +constant addresses through a global offset table (GOT)@. The dynamic +loader resolves the GOT entries when the program starts (the dynamic +loader is not part of GCC; it is part of the operating system). If +the GOT size for the linked executable exceeds a machine-specific +maximum size, you get an error message from the linker indicating that +@option{-fpic} does not work; in that case, recompile with @option{-fPIC} +instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k +on the m68k and RS/6000. The x86 has no such limit.) -@item -fchkp-use-fast-string-functions -@opindex fchkp-use-fast-string-functions -@opindex fno-chkp-use-fast-string-functions -Enables use of @code{*_nobnd} versions of string functions (not copying bounds) -by Pointer Bounds Checker. Disabled by default. +Position-independent code requires special support, and therefore works +only on certain machines. For the x86, GCC supports PIC for System V +but not for the Sun 386i. Code generated for the IBM RS/6000 is always +position-independent. -@item -fchkp-use-nochk-string-functions -@opindex fchkp-use-nochk-string-functions -@opindex fno-chkp-use-nochk-string-functions -Enables use of @code{*_nochk} versions of string functions (not checking bounds) -by Pointer Bounds Checker. Disabled by default. +When this flag is set, the macros @code{__pic__} and @code{__PIC__} +are defined to 1. -@item -fchkp-use-static-bounds -@opindex fchkp-use-static-bounds -@opindex fno-chkp-use-static-bounds -Allow Pointer Bounds Checker to generate static bounds holding -bounds of static variables. Enabled by default. +@item -fPIC +@opindex fPIC +If supported for the target machine, emit position-independent code, +suitable for dynamic linking and avoiding any limit on the size of the +global offset table. This option makes a difference on AArch64, m68k, +PowerPC and SPARC@. -@item -fchkp-use-static-const-bounds -@opindex fchkp-use-static-const-bounds -@opindex fno-chkp-use-static-const-bounds -Use statically-initialized bounds for constant bounds instead of -generating them each time they are required. By default enabled when -@option{-fchkp-use-static-bounds} is enabled. +Position-independent code requires special support, and therefore works +only on certain machines. -@item -fchkp-treat-zero-dynamic-size-as-infinite -@opindex fchkp-treat-zero-dynamic-size-as-infinite -@opindex fno-chkp-treat-zero-dynamic-size-as-infinite -With this option, objects with incomplete type whose -dynamically-obtained size is zero are treated as having infinite size -instead by Pointer Bounds -Checker. This option may be helpful if a program is linked with a library -missing size information for some symbols. Disabled by default. +When this flag is set, the macros @code{__pic__} and @code{__PIC__} +are defined to 2. -@item -fchkp-check-read -@opindex fchkp-check-read -@opindex fno-chkp-check-read -Instructs Pointer Bounds Checker to generate checks for all read -accesses to memory. Enabled by default. +@item -fpie +@itemx -fPIE +@opindex fpie +@opindex fPIE +These options are similar to @option{-fpic} and @option{-fPIC}, but +generated position independent code can be only linked into executables. +Usually these options are used when @option{-pie} GCC option is +used during linking. -@item -fchkp-check-write -@opindex fchkp-check-write -@opindex fno-chkp-check-write -Instructs Pointer Bounds Checker to generate checks for all write -accesses to memory. Enabled by default. +@option{-fpie} and @option{-fPIE} both define the macros +@code{__pie__} and @code{__PIE__}. The macros have the value 1 +for @option{-fpie} and 2 for @option{-fPIE}. -@item -fchkp-store-bounds -@opindex fchkp-store-bounds -@opindex fno-chkp-store-bounds -Instructs Pointer Bounds Checker to generate bounds stores for -pointer writes. Enabled by default. +@item -fno-plt +@opindex fno-plt +Do not use the PLT for external function calls in position-independent code. +Instead, load the callee address at call sites from the GOT and branch to it. +This leads to more efficient code by eliminating PLT stubs and exposing +GOT loads to optimizations. On architectures such as 32-bit x86 where +PLT stubs expect the GOT pointer in a specific register, this gives more +register allocation freedom to the compiler. +Lazy binding requires use of the PLT; +with @option{-fno-plt} all external symbols are resolved at load time. -@item -fchkp-instrument-calls -@opindex fchkp-instrument-calls -@opindex fno-chkp-instrument-calls -Instructs Pointer Bounds Checker to pass pointer bounds to calls. -Enabled by default. +Alternatively, the function attribute @code{noplt} can be used to avoid calls +through the PLT for specific external functions. -@item -fchkp-instrument-marked-only -@opindex fchkp-instrument-marked-only -@opindex fno-chkp-instrument-marked-only -Instructs Pointer Bounds Checker to instrument only functions -marked with the @code{bnd_instrument} attribute -(@pxref{Function Attributes}). Disabled by default. +In position-dependent code, a few targets also convert calls to +functions that are marked to not use the PLT to use the GOT instead. -@item -fchkp-use-wrappers -@opindex fchkp-use-wrappers -@opindex fno-chkp-use-wrappers -Allows Pointer Bounds Checker to replace calls to built-in functions -with calls to wrapper functions. When @option{-fchkp-use-wrappers} -is used to link a program, the GCC driver automatically links -against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}. -Enabled by default. +@item -fno-jump-tables +@opindex fno-jump-tables +Do not use jump tables for switch statements even where it would be +more efficient than other code generation strategies. This option is +of use in conjunction with @option{-fpic} or @option{-fPIC} for +building code that forms part of a dynamic linker and cannot +reference the address of a jump table. On some targets, jump tables +do not require a GOT and this option is not needed. -@item -fstack-protector -@opindex fstack-protector -Emit extra code to check for buffer overflows, such as stack smashing -attacks. This is done by adding a guard variable to functions with -vulnerable objects. This includes functions that call @code{alloca}, and -functions with buffers larger than 8 bytes. The guards are initialized -when a function is entered and then checked when the function exits. -If a guard check fails, an error message is printed and the program exits. +@item -ffixed-@var{reg} +@opindex ffixed +Treat the register named @var{reg} as a fixed register; generated code +should never refer to it (except perhaps as a stack pointer, frame +pointer or in some other fixed role). -@item -fstack-protector-all -@opindex fstack-protector-all -Like @option{-fstack-protector} except that all functions are protected. +@var{reg} must be the name of a register. The register names accepted +are machine-specific and are defined in the @code{REGISTER_NAMES} +macro in the machine description macro file. -@item -fstack-protector-strong -@opindex fstack-protector-strong -Like @option{-fstack-protector} but includes additional functions to -be protected --- those that have local array definitions, or have -references to local frame addresses. +This flag does not have a negative form, because it specifies a +three-way choice. -@item -fstack-protector-explicit -@opindex fstack-protector-explicit -Like @option{-fstack-protector} but only protects those functions which -have the @code{stack_protect} attribute. +@item -fcall-used-@var{reg} +@opindex fcall-used +Treat the register named @var{reg} as an allocable register that is +clobbered by function calls. It may be allocated for temporaries or +variables that do not live across a call. Functions compiled this way +do not save and restore the register @var{reg}. -@item -fstack-check -@opindex fstack-check -Generate code to verify that you do not go beyond the boundary of the -stack. You should specify this flag if you are running in an -environment with multiple threads, but you only rarely need to specify it in -a single-threaded environment since stack overflow is automatically -detected on nearly all systems if there is only one stack. +It is an error to use this flag with the frame pointer or stack pointer. +Use of this flag for other registers that have fixed pervasive roles in +the machine's execution model produces disastrous results. -Note that this switch does not actually cause checking to be done; the -operating system or the language runtime must do that. The switch causes -generation of code to ensure that they see the stack being extended. +This flag does not have a negative form, because it specifies a +three-way choice. -You can additionally specify a string parameter: @samp{no} means no -checking, @samp{generic} means force the use of old-style checking, -@samp{specific} means use the best checking method and is equivalent -to bare @option{-fstack-check}. +@item -fcall-saved-@var{reg} +@opindex fcall-saved +Treat the register named @var{reg} as an allocable register saved by +functions. It may be allocated even for temporaries or variables that +live across a call. Functions compiled this way save and restore +the register @var{reg} if they use it. -Old-style checking is a generic mechanism that requires no specific -target support in the compiler but comes with the following drawbacks: +It is an error to use this flag with the frame pointer or stack pointer. +Use of this flag for other registers that have fixed pervasive roles in +the machine's execution model produces disastrous results. -@enumerate -@item -Modified allocation strategy for large objects: they are always -allocated dynamically if their size exceeds a fixed threshold. +A different sort of disaster results from the use of this flag for +a register in which function values may be returned. -@item -Fixed limit on the size of the static frame of functions: when it is -topped by a particular function, stack checking is not reliable and -a warning is issued by the compiler. +This flag does not have a negative form, because it specifies a +three-way choice. -@item -Inefficiency: because of both the modified allocation strategy and the -generic implementation, code performance is hampered. -@end enumerate +@item -fpack-struct[=@var{n}] +@opindex fpack-struct +Without a value specified, pack all structure members together without +holes. When a value is specified (which must be a small power of two), pack +structure members according to this value, representing the maximum +alignment (that is, objects with default alignment requirements larger than +this are output potentially unaligned at the next fitting location. -Note that old-style stack checking is also the fallback method for -@samp{specific} if no target support has been added in the compiler. +@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate +code that is not binary compatible with code generated without that switch. +Additionally, it makes the code suboptimal. +Use it to conform to a non-default application binary interface. -@item -fstack-limit-register=@var{reg} -@itemx -fstack-limit-symbol=@var{sym} -@itemx -fno-stack-limit -@opindex fstack-limit-register -@opindex fstack-limit-symbol -@opindex fno-stack-limit -Generate code to ensure that the stack does not grow beyond a certain value, -either the value of a register or the address of a symbol. If a larger -stack is required, a signal is raised at run time. For most targets, -the signal is raised before the stack overruns the boundary, so -it is possible to catch the signal without taking special precautions. +@item -fleading-underscore +@opindex fleading-underscore +This option and its counterpart, @option{-fno-leading-underscore}, forcibly +change the way C symbols are represented in the object file. One use +is to help link with legacy assembly code. -For instance, if the stack starts at absolute address @samp{0x80000000} -and grows downwards, you can use the flags -@option{-fstack-limit-symbol=__stack_limit} and -@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit -of 128KB@. Note that this may only work with the GNU linker. +@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to +generate code that is not binary compatible with code generated without that +switch. Use it to conform to a non-default application binary interface. +Not all targets provide complete support for this switch. -You can locally override stack limit checking by using the -@code{no_stack_limit} function attribute (@pxref{Function Attributes}). +@item -ftls-model=@var{model} +@opindex ftls-model +Alter the thread-local storage model to be used (@pxref{Thread-Local}). +The @var{model} argument should be one of @samp{global-dynamic}, +@samp{local-dynamic}, @samp{initial-exec} or @samp{local-exec}. +Note that the choice is subject to optimization: the compiler may use +a more efficient model for symbols not visible outside of the translation +unit, or if @option{-fpic} is not given on the command line. -@item -fsplit-stack -@opindex fsplit-stack -Generate code to automatically split the stack before it overflows. -The resulting program has a discontiguous stack which can only -overflow if the program is unable to allocate any more memory. This -is most useful when running threaded programs, as it is no longer -necessary to calculate a good stack size to use for each thread. This -is currently only implemented for the x86 targets running -GNU/Linux. +The default without @option{-fpic} is @samp{initial-exec}; with +@option{-fpic} the default is @samp{global-dynamic}. -When code compiled with @option{-fsplit-stack} calls code compiled -without @option{-fsplit-stack}, there may not be much stack space -available for the latter code to run. If compiling all code, -including library code, with @option{-fsplit-stack} is not an option, -then the linker can fix up these calls so that the code compiled -without @option{-fsplit-stack} always has a large stack. Support for -this is implemented in the gold linker in GNU binutils release 2.21 -and later. +@item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} +@opindex fvisibility +Set the default ELF image symbol visibility to the specified option---all +symbols are marked with this unless overridden within the code. +Using this feature can very substantially improve linking and +load times of shared object libraries, produce more optimized +code, provide near-perfect API export and prevent symbol clashes. +It is @strong{strongly} recommended that you use this in any shared objects +you distribute. -@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} -@opindex fvtable-verify -This option is only available when compiling C++ code. -It turns on (or off, if using @option{-fvtable-verify=none}) the security -feature that verifies at run time, for every virtual call, that -the vtable pointer through which the call is made is valid for the type of -the object, and has not been corrupted or overwritten. If an invalid vtable -pointer is detected at run time, an error is reported and execution of the -program is immediately halted. +Despite the nomenclature, @samp{default} always means public; i.e., +available to be linked against from outside the shared object. +@samp{protected} and @samp{internal} are pretty useless in real-world +usage so the only other commonly used option is @samp{hidden}. +The default if @option{-fvisibility} isn't specified is +@samp{default}, i.e., make every symbol public. -This option causes run-time data structures to be built at program startup, -which are used for verifying the vtable pointers. -The options @samp{std} and @samp{preinit} -control the timing of when these data structures are built. In both cases the -data structures are built before execution reaches @code{main}. Using -@option{-fvtable-verify=std} causes the data structures to be built after -shared libraries have been loaded and initialized. -@option{-fvtable-verify=preinit} causes them to be built before shared -libraries have been loaded and initialized. +A good explanation of the benefits offered by ensuring ELF +symbols have the correct visibility is given by ``How To Write +Shared Libraries'' by Ulrich Drepper (which can be found at +@w{@uref{http://www.akkadia.org/drepper/}})---however a superior +solution made possible by this option to marking things hidden when +the default is public is to make the default hidden and mark things +public. This is the norm with DLLs on Windows and with @option{-fvisibility=hidden} +and @code{__attribute__ ((visibility("default")))} instead of +@code{__declspec(dllexport)} you get almost identical semantics with +identical syntax. This is a great boon to those working with +cross-platform projects. -If this option appears multiple times in the command line with different -values specified, @samp{none} takes highest priority over both @samp{std} and -@samp{preinit}; @samp{preinit} takes priority over @samp{std}. +For those adding visibility support to existing code, you may find +@code{#pragma GCC visibility} of use. This works by you enclosing +the declarations you wish to set visibility for with (for example) +@code{#pragma GCC visibility push(hidden)} and +@code{#pragma GCC visibility pop}. +Bear in mind that symbol visibility should be viewed @strong{as +part of the API interface contract} and thus all new code should +always specify visibility when it is not the default; i.e., declarations +only for use within the local DSO should @strong{always} be marked explicitly +as hidden as so to avoid PLT indirection overheads---making this +abundantly clear also aids readability and self-documentation of the code. +Note that due to ISO C++ specification requirements, @code{operator new} and +@code{operator delete} must always be of default visibility. -@item -fvtv-debug -@opindex fvtv-debug -When used in conjunction with @option{-fvtable-verify=std} or -@option{-fvtable-verify=preinit}, causes debug versions of the -runtime functions for the vtable verification feature to be called. -This flag also causes the compiler to log information about which -vtable pointers it finds for each class. -This information is written to a file named @file{vtv_set_ptr_data.log} -in the directory named by the environment variable @env{VTV_LOGS_DIR} -if that is defined or the current working directory otherwise. +Be aware that headers from outside your project, in particular system +headers and headers from any other library you use, may not be +expecting to be compiled with visibility other than the default. You +may need to explicitly say @code{#pragma GCC visibility push(default)} +before including any such headers. -Note: This feature @emph{appends} data to the log file. If you want a fresh log -file, be sure to delete any existing one. +@code{extern} declarations are not affected by @option{-fvisibility}, so +a lot of code can be recompiled with @option{-fvisibility=hidden} with +no modifications. However, this means that calls to @code{extern} +functions with no explicit visibility use the PLT, so it is more +effective to use @code{__attribute ((visibility))} and/or +@code{#pragma GCC visibility} to tell the compiler which @code{extern} +declarations should be treated as hidden. -@item -fvtv-counts -@opindex fvtv-counts -This is a debugging flag. When used in conjunction with -@option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this -causes the compiler to keep track of the total number of virtual calls -it encounters and the number of verifications it inserts. It also -counts the number of calls to certain run-time library functions -that it inserts and logs this information for each compilation unit. -The compiler writes this information to a file named -@file{vtv_count_data.log} in the directory named by the environment -variable @env{VTV_LOGS_DIR} if that is defined or the current working -directory otherwise. It also counts the size of the vtable pointer sets -for each class, and writes this information to @file{vtv_class_set_sizes.log} -in the same directory. +Note that @option{-fvisibility} does affect C++ vague linkage +entities. This means that, for instance, an exception class that is +be thrown between DSOs must be explicitly marked with default +visibility so that the @samp{type_info} nodes are unified between +the DSOs. -Note: This feature @emph{appends} data to the log files. To get fresh log -files, be sure to delete any existing ones. +An overview of these techniques, their benefits and how to use them +is at @uref{http://gcc.gnu.org/@/wiki/@/Visibility}. -@item -finstrument-functions -@opindex finstrument-functions -Generate instrumentation calls for entry and exit to functions. Just -after function entry and just before function exit, the following -profiling functions are called with the address of the current -function and its call site. (On some platforms, -@code{__builtin_return_address} does not work beyond the current -function, so the call site information may not be available to the -profiling functions otherwise.) +@item -fstrict-volatile-bitfields +@opindex fstrict-volatile-bitfields +This option should be used if accesses to volatile bit-fields (or other +structure fields, although the compiler usually honors those types +anyway) should use a single access of the width of the +field's type, aligned to a natural alignment if possible. For +example, targets with memory-mapped peripheral registers might require +all such accesses to be 16 bits wide; with this flag you can +declare all peripheral bit-fields as @code{unsigned short} (assuming short +is 16 bits on these targets) to force GCC to use 16-bit accesses +instead of, perhaps, a more efficient 32-bit access. -@smallexample -void __cyg_profile_func_enter (void *this_fn, - void *call_site); -void __cyg_profile_func_exit (void *this_fn, - void *call_site); -@end smallexample +If this option is disabled, the compiler uses the most efficient +instruction. In the previous example, that might be a 32-bit load +instruction, even though that accesses bytes that do not contain +any portion of the bit-field, or memory-mapped registers unrelated to +the one being updated. -The first argument is the address of the start of the current function, -which may be looked up exactly in the symbol table. +In some cases, such as when the @code{packed} attribute is applied to a +structure field, it may not be possible to access the field with a single +read or write that is correctly aligned for the target machine. In this +case GCC falls back to generating multiple accesses rather than code that +will fault or truncate the result at run time. -This instrumentation is also done for functions expanded inline in other -functions. The profiling calls indicate where, conceptually, the -inline function is entered and exited. This means that addressable -versions of such functions must be available. If all your uses of a -function are expanded inline, this may mean an additional expansion of -code size. If you use @code{extern inline} in your C code, an -addressable version of such functions must be provided. (This is -normally the case anyway, but if you get lucky and the optimizer always -expands the functions inline, you might have gotten away without -providing static copies.) +Note: Due to restrictions of the C/C++11 memory model, write accesses are +not allowed to touch non bit-field members. It is therefore recommended +to define all bits of the field's type as bit-field members. -A function may be given the attribute @code{no_instrument_function}, in -which case this instrumentation is not done. This can be used, for -example, for the profiling functions listed above, high-priority -interrupt routines, and any functions from which the profiling functions -cannot safely be called (perhaps signal handlers, if the profiling -routines generate output or allocate memory). +The default value of this option is determined by the application binary +interface for the target processor. -@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} -@opindex finstrument-functions-exclude-file-list +@item -fsync-libcalls +@opindex fsync-libcalls +This option controls whether any out-of-line instance of the @code{__sync} +family of functions may be used to implement the C++11 @code{__atomic} +family of functions. -Set the list of functions that are excluded from instrumentation (see -the description of @option{-finstrument-functions}). If the file that -contains a function definition matches with one of @var{file}, then -that function is not instrumented. The match is done on substrings: -if the @var{file} parameter is a substring of the file name, it is -considered to be a match. +The default value of this option is enabled, thus the only useful form +of the option is @option{-fno-sync-libcalls}. This option is used in +the implementation of the @file{libatomic} runtime library. -For example: +@end table -@smallexample --finstrument-functions-exclude-file-list=/bits/stl,include/sys -@end smallexample +@node Developer Options +@section GCC Developer Options +@cindex developer options +@cindex debugging GCC +@cindex debug dump options +@cindex dump options +@cindex compilation statistics + +This section describes command-line options that are primarily of +interest to GCC developers, including options to support compiler +testing and investigation of compiler bugs and compile-time +performance problems. This includes options that produce debug dumps +at various points in the compilation; that print statistics such as +memory use and execution time; and that print information about GCC's +configuration, such as where it searches for libraries. You should +rarely need to use any of these options for ordinary compilation and +linking tasks. -@noindent -excludes any inline function defined in files whose pathnames -contain @file{/bits/stl} or @file{include/sys}. +@table @gcctabopt -If, for some reason, you want to include letter @samp{,} in one of -@var{sym}, write @samp{\,}. For example, -@option{-finstrument-functions-exclude-file-list='\,\,tmp'} -(note the single quote surrounding the option). +@item -d@var{letters} +@itemx -fdump-rtl-@var{pass} +@itemx -fdump-rtl-@var{pass}=@var{filename} +@opindex d +@opindex fdump-rtl-@var{pass} +Says to make debugging dumps during compilation at times specified by +@var{letters}. This is used for debugging the RTL-based passes of the +compiler. The file names for most of the dumps are made by appending +a pass number and a word to the @var{dumpname}, and the files are +created in the directory of the output file. In case of +@option{=@var{filename}} option, the dump is output on the given file +instead of the pass numbered dump files. Note that the pass number is +assigned as passes are registered into the pass manager. Most passes +are registered in the order that they will execute and for these passes +the number corresponds to the pass execution order. However, passes +registered by plugins, passes specific to compilation targets, or +passes that are otherwise registered after all the other passes are +numbered higher than a pass named "final", even if they are executed +earlier. @var{dumpname} is generated from the name of the output +file if explicitly specified and not an executable, otherwise it is +the basename of the source file. These switches may have different +effects when @option{-E} is used for preprocessing. -@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} -@opindex finstrument-functions-exclude-function-list +Debug dumps can be enabled with a @option{-fdump-rtl} switch or some +@option{-d} option @var{letters}. Here are the possible +letters for use in @var{pass} and @var{letters}, and their meanings: -This is similar to @option{-finstrument-functions-exclude-file-list}, -but this option sets the list of function names to be excluded from -instrumentation. The function name to be matched is its user-visible -name, such as @code{vector blah(const vector &)}, not the -internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The -match is done on substrings: if the @var{sym} parameter is a substring -of the function name, it is considered to be a match. For C99 and C++ -extended identifiers, the function name must be given in UTF-8, not -using universal character names. +@table @gcctabopt -@end table +@item -fdump-rtl-alignments +@opindex fdump-rtl-alignments +Dump after branch alignments have been computed. +@item -fdump-rtl-asmcons +@opindex fdump-rtl-asmcons +Dump after fixing rtl statements that have unsatisfied in/out constraints. -@node Preprocessor Options -@section Options Controlling the Preprocessor -@cindex preprocessor options -@cindex options, preprocessor +@item -fdump-rtl-auto_inc_dec +@opindex fdump-rtl-auto_inc_dec +Dump after auto-inc-dec discovery. This pass is only run on +architectures that have auto inc or auto dec instructions. -These options control the C preprocessor, which is run on each C source -file before actual compilation. +@item -fdump-rtl-barriers +@opindex fdump-rtl-barriers +Dump after cleaning up the barrier instructions. -If you use the @option{-E} option, nothing is done except preprocessing. -Some of these options make sense only together with @option{-E} because -they cause the preprocessor output to be unsuitable for actual -compilation. +@item -fdump-rtl-bbpart +@opindex fdump-rtl-bbpart +Dump after partitioning hot and cold basic blocks. -@table @gcctabopt -@item -Wp,@var{option} -@opindex Wp -You can use @option{-Wp,@var{option}} to bypass the compiler driver -and pass @var{option} directly through to the preprocessor. If -@var{option} contains commas, it is split into multiple options at the -commas. However, many options are modified, translated or interpreted -by the compiler driver before being passed to the preprocessor, and -@option{-Wp} forcibly bypasses this phase. The preprocessor's direct -interface is undocumented and subject to change, so whenever possible -you should avoid using @option{-Wp} and let the driver handle the -options instead. +@item -fdump-rtl-bbro +@opindex fdump-rtl-bbro +Dump after block reordering. -@item -Xpreprocessor @var{option} -@opindex Xpreprocessor -Pass @var{option} as an option to the preprocessor. You can use this to -supply system-specific preprocessor options that GCC does not -recognize. +@item -fdump-rtl-btl1 +@itemx -fdump-rtl-btl2 +@opindex fdump-rtl-btl2 +@opindex fdump-rtl-btl2 +@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping +after the two branch +target load optimization passes. -If you want to pass an option that takes an argument, you must use -@option{-Xpreprocessor} twice, once for the option and once for the argument. +@item -fdump-rtl-bypass +@opindex fdump-rtl-bypass +Dump after jump bypassing and control flow optimizations. -@item -no-integrated-cpp -@opindex no-integrated-cpp -Perform preprocessing as a separate pass before compilation. -By default, GCC performs preprocessing as an integrated part of -input tokenization and parsing. -If this option is provided, the appropriate language front end -(@command{cc1}, @command{cc1plus}, or @command{cc1obj} for C, C++, -and Objective-C, respectively) is instead invoked twice, -once for preprocessing only and once for actual compilation -of the preprocessed input. -This option may be useful in conjunction with the @option{-B} or -@option{-wrapper} options to specify an alternate preprocessor or -perform additional processing of the program source between -normal preprocessing and compilation. -@end table +@item -fdump-rtl-combine +@opindex fdump-rtl-combine +Dump after the RTL instruction combination pass. -@include cppopts.texi +@item -fdump-rtl-compgotos +@opindex fdump-rtl-compgotos +Dump after duplicating the computed gotos. -@node Assembler Options -@section Passing Options to the Assembler +@item -fdump-rtl-ce1 +@itemx -fdump-rtl-ce2 +@itemx -fdump-rtl-ce3 +@opindex fdump-rtl-ce1 +@opindex fdump-rtl-ce2 +@opindex fdump-rtl-ce3 +@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and +@option{-fdump-rtl-ce3} enable dumping after the three +if conversion passes. -@c prevent bad page break with this line -You can pass options to the assembler. +@item -fdump-rtl-cprop_hardreg +@opindex fdump-rtl-cprop_hardreg +Dump after hard register copy propagation. -@table @gcctabopt -@item -Wa,@var{option} -@opindex Wa -Pass @var{option} as an option to the assembler. If @var{option} -contains commas, it is split into multiple options at the commas. +@item -fdump-rtl-csa +@opindex fdump-rtl-csa +Dump after combining stack adjustments. -@item -Xassembler @var{option} -@opindex Xassembler -Pass @var{option} as an option to the assembler. You can use this to -supply system-specific assembler options that GCC does not -recognize. +@item -fdump-rtl-cse1 +@itemx -fdump-rtl-cse2 +@opindex fdump-rtl-cse1 +@opindex fdump-rtl-cse2 +@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after +the two common subexpression elimination passes. -If you want to pass an option that takes an argument, you must use -@option{-Xassembler} twice, once for the option and once for the argument. +@item -fdump-rtl-dce +@opindex fdump-rtl-dce +Dump after the standalone dead code elimination passes. -@end table +@item -fdump-rtl-dbr +@opindex fdump-rtl-dbr +Dump after delayed branch scheduling. -@node Link Options -@section Options for Linking -@cindex link options -@cindex options, linking +@item -fdump-rtl-dce1 +@itemx -fdump-rtl-dce2 +@opindex fdump-rtl-dce1 +@opindex fdump-rtl-dce2 +@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after +the two dead store elimination passes. -These options come into play when the compiler links object files into -an executable output file. They are meaningless if the compiler is -not doing a link step. +@item -fdump-rtl-eh +@opindex fdump-rtl-eh +Dump after finalization of EH handling code. -@table @gcctabopt -@cindex file names -@item @var{object-file-name} -A file name that does not end in a special recognized suffix is -considered to name an object file or library. (Object files are -distinguished from libraries by the linker according to the file -contents.) If linking is done, these object files are used as input -to the linker. +@item -fdump-rtl-eh_ranges +@opindex fdump-rtl-eh_ranges +Dump after conversion of EH handling range regions. -@item -c -@itemx -S -@itemx -E -@opindex c -@opindex S -@opindex E -If any of these options is used, then the linker is not run, and -object file names should not be used as arguments. @xref{Overall -Options}. +@item -fdump-rtl-expand +@opindex fdump-rtl-expand +Dump after RTL generation. -@item -fuse-ld=bfd -@opindex fuse-ld=bfd -Use the @command{bfd} linker instead of the default linker. +@item -fdump-rtl-fwprop1 +@itemx -fdump-rtl-fwprop2 +@opindex fdump-rtl-fwprop1 +@opindex fdump-rtl-fwprop2 +@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable +dumping after the two forward propagation passes. -@item -fuse-ld=gold -@opindex fuse-ld=gold -Use the @command{gold} linker instead of the default linker. +@item -fdump-rtl-gcse1 +@itemx -fdump-rtl-gcse2 +@opindex fdump-rtl-gcse1 +@opindex fdump-rtl-gcse2 +@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping +after global common subexpression elimination. -@cindex Libraries -@item -l@var{library} -@itemx -l @var{library} -@opindex l -Search the library named @var{library} when linking. (The second -alternative with the library as a separate argument is only for -POSIX compliance and is not recommended.) +@item -fdump-rtl-init-regs +@opindex fdump-rtl-init-regs +Dump after the initialization of the registers. -It makes a difference where in the command you write this option; the -linker searches and processes libraries and object files in the order they -are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z} -after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers -to functions in @samp{z}, those functions may not be loaded. +@item -fdump-rtl-initvals +@opindex fdump-rtl-initvals +Dump after the computation of the initial value sets. -The linker searches a standard list of directories for the library, -which is actually a file named @file{lib@var{library}.a}. The linker -then uses this file as if it had been specified precisely by name. +@item -fdump-rtl-into_cfglayout +@opindex fdump-rtl-into_cfglayout +Dump after converting to cfglayout mode. -The directories searched include several standard system directories -plus any that you specify with @option{-L}. +@item -fdump-rtl-ira +@opindex fdump-rtl-ira +Dump after iterated register allocation. -Normally the files found this way are library files---archive files -whose members are object files. The linker handles an archive file by -scanning through it for members which define symbols that have so far -been referenced but not defined. But if the file that is found is an -ordinary object file, it is linked in the usual fashion. The only -difference between using an @option{-l} option and specifying a file name -is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a} -and searches several directories. +@item -fdump-rtl-jump +@opindex fdump-rtl-jump +Dump after the second jump optimization. -@item -lobjc -@opindex lobjc -You need this special case of the @option{-l} option in order to -link an Objective-C or Objective-C++ program. +@item -fdump-rtl-loop2 +@opindex fdump-rtl-loop2 +@option{-fdump-rtl-loop2} enables dumping after the rtl +loop optimization passes. -@item -nostartfiles -@opindex nostartfiles -Do not use the standard system startup files when linking. -The standard system libraries are used normally, unless @option{-nostdlib} -or @option{-nodefaultlibs} is used. +@item -fdump-rtl-mach +@opindex fdump-rtl-mach +Dump after performing the machine dependent reorganization pass, if that +pass exists. -@item -nodefaultlibs -@opindex nodefaultlibs -Do not use the standard system libraries when linking. -Only the libraries you specify are passed to the linker, and options -specifying linkage of the system libraries, such as @option{-static-libgcc} -or @option{-shared-libgcc}, are ignored. -The standard startup files are used normally, unless @option{-nostartfiles} -is used. +@item -fdump-rtl-mode_sw +@opindex fdump-rtl-mode_sw +Dump after removing redundant mode switches. -The compiler may generate calls to @code{memcmp}, -@code{memset}, @code{memcpy} and @code{memmove}. -These entries are usually resolved by entries in -libc. These entry points should be supplied through some other -mechanism when this option is specified. +@item -fdump-rtl-rnreg +@opindex fdump-rtl-rnreg +Dump after register renumbering. -@item -nostdlib -@opindex nostdlib -Do not use the standard system startup files or libraries when linking. -No startup files and only the libraries you specify are passed to -the linker, and options specifying linkage of the system libraries, such as -@option{-static-libgcc} or @option{-shared-libgcc}, are ignored. +@item -fdump-rtl-outof_cfglayout +@opindex fdump-rtl-outof_cfglayout +Dump after converting from cfglayout mode. -The compiler may generate calls to @code{memcmp}, @code{memset}, -@code{memcpy} and @code{memmove}. -These entries are usually resolved by entries in -libc. These entry points should be supplied through some other -mechanism when this option is specified. +@item -fdump-rtl-peephole2 +@opindex fdump-rtl-peephole2 +Dump after the peephole pass. -@cindex @option{-lgcc}, use with @option{-nostdlib} -@cindex @option{-nostdlib} and unresolved references -@cindex unresolved references and @option{-nostdlib} -@cindex @option{-lgcc}, use with @option{-nodefaultlibs} -@cindex @option{-nodefaultlibs} and unresolved references -@cindex unresolved references and @option{-nodefaultlibs} -One of the standard libraries bypassed by @option{-nostdlib} and -@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines -which GCC uses to overcome shortcomings of particular machines, or special -needs for some languages. -(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler -Collection (GCC) Internals}, -for more discussion of @file{libgcc.a}.) -In most cases, you need @file{libgcc.a} even when you want to avoid -other standard libraries. In other words, when you specify @option{-nostdlib} -or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well. -This ensures that you have no unresolved references to internal GCC -library subroutines. -(An example of such an internal subroutine is @code{__main}, used to ensure C++ -constructors are called; @pxref{Collect2,,@code{collect2}, gccint, -GNU Compiler Collection (GCC) Internals}.) +@item -fdump-rtl-postreload +@opindex fdump-rtl-postreload +Dump after post-reload optimizations. -@item -pie -@opindex pie -Produce a position independent executable on targets that support it. -For predictable results, you must also specify the same set of options -used for compilation (@option{-fpie}, @option{-fPIE}, -or model suboptions) when you specify this linker option. +@item -fdump-rtl-pro_and_epilogue +@opindex fdump-rtl-pro_and_epilogue +Dump after generating the function prologues and epilogues. -@item -no-pie -@opindex no-pie -Don't produce a position independent executable. +@item -fdump-rtl-sched1 +@itemx -fdump-rtl-sched2 +@opindex fdump-rtl-sched1 +@opindex fdump-rtl-sched2 +@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping +after the basic block scheduling passes. -@item -rdynamic -@opindex rdynamic -Pass the flag @option{-export-dynamic} to the ELF linker, on targets -that support it. This instructs the linker to add all symbols, not -only used ones, to the dynamic symbol table. This option is needed -for some uses of @code{dlopen} or to allow obtaining backtraces -from within a program. +@item -fdump-rtl-ree +@opindex fdump-rtl-ree +Dump after sign/zero extension elimination. -@item -s -@opindex s -Remove all symbol table and relocation information from the executable. +@item -fdump-rtl-seqabstr +@opindex fdump-rtl-seqabstr +Dump after common sequence discovery. -@item -static -@opindex static -On systems that support dynamic linking, this prevents linking with the shared -libraries. On other systems, this option has no effect. +@item -fdump-rtl-shorten +@opindex fdump-rtl-shorten +Dump after shortening branches. -@item -shared -@opindex shared -Produce a shared object which can then be linked with other objects to -form an executable. Not all systems support this option. For predictable -results, you must also specify the same set of options used for compilation -(@option{-fpic}, @option{-fPIC}, or model suboptions) when -you specify this linker option.@footnote{On some systems, @samp{gcc -shared} -needs to build supplementary stub code for constructors to work. On -multi-libbed systems, @samp{gcc -shared} must select the correct support -libraries to link against. Failing to supply the correct flags may lead -to subtle defects. Supplying them in cases where they are not necessary -is innocuous.} +@item -fdump-rtl-sibling +@opindex fdump-rtl-sibling +Dump after sibling call optimizations. -@item -shared-libgcc -@itemx -static-libgcc -@opindex shared-libgcc -@opindex static-libgcc -On systems that provide @file{libgcc} as a shared library, these options -force the use of either the shared or static version, respectively. -If no shared version of @file{libgcc} was built when the compiler was -configured, these options have no effect. +@item -fdump-rtl-split1 +@itemx -fdump-rtl-split2 +@itemx -fdump-rtl-split3 +@itemx -fdump-rtl-split4 +@itemx -fdump-rtl-split5 +@opindex fdump-rtl-split1 +@opindex fdump-rtl-split2 +@opindex fdump-rtl-split3 +@opindex fdump-rtl-split4 +@opindex fdump-rtl-split5 +These options enable dumping after five rounds of +instruction splitting. -There are several situations in which an application should use the -shared @file{libgcc} instead of the static version. The most common -of these is when the application wishes to throw and catch exceptions -across different shared libraries. In that case, each of the libraries -as well as the application itself should use the shared @file{libgcc}. +@item -fdump-rtl-sms +@opindex fdump-rtl-sms +Dump after modulo scheduling. This pass is only run on some +architectures. -Therefore, the G++ and GCJ drivers automatically add -@option{-shared-libgcc} whenever you build a shared library or a main -executable, because C++ and Java programs typically use exceptions, so -this is the right thing to do. +@item -fdump-rtl-stack +@opindex fdump-rtl-stack +Dump after conversion from GCC's ``flat register file'' registers to the +x87's stack-like registers. This pass is only run on x86 variants. -If, instead, you use the GCC driver to create shared libraries, you may -find that they are not always linked with the shared @file{libgcc}. -If GCC finds, at its configuration time, that you have a non-GNU linker -or a GNU linker that does not support option @option{--eh-frame-hdr}, -it links the shared version of @file{libgcc} into shared libraries -by default. Otherwise, it takes advantage of the linker and optimizes -away the linking with the shared version of @file{libgcc}, linking with -the static version of libgcc by default. This allows exceptions to -propagate through such shared libraries, without incurring relocation -costs at library load time. +@item -fdump-rtl-subreg1 +@itemx -fdump-rtl-subreg2 +@opindex fdump-rtl-subreg1 +@opindex fdump-rtl-subreg2 +@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after +the two subreg expansion passes. -However, if a library or main executable is supposed to throw or catch -exceptions, you must link it using the G++ or GCJ driver, as appropriate -for the languages used in the program, or using the option -@option{-shared-libgcc}, such that it is linked with the shared -@file{libgcc}. +@item -fdump-rtl-unshare +@opindex fdump-rtl-unshare +Dump after all rtl has been unshared. -@item -static-libasan -@opindex static-libasan -When the @option{-fsanitize=address} option is used to link a program, -the GCC driver automatically links against @option{libasan}. If -@file{libasan} is available as a shared library, and the @option{-static} -option is not used, then this links against the shared version of -@file{libasan}. The @option{-static-libasan} option directs the GCC -driver to link @file{libasan} statically, without necessarily linking -other libraries statically. +@item -fdump-rtl-vartrack +@opindex fdump-rtl-vartrack +Dump after variable tracking. -@item -static-libtsan -@opindex static-libtsan -When the @option{-fsanitize=thread} option is used to link a program, -the GCC driver automatically links against @option{libtsan}. If -@file{libtsan} is available as a shared library, and the @option{-static} -option is not used, then this links against the shared version of -@file{libtsan}. The @option{-static-libtsan} option directs the GCC -driver to link @file{libtsan} statically, without necessarily linking -other libraries statically. +@item -fdump-rtl-vregs +@opindex fdump-rtl-vregs +Dump after converting virtual registers to hard registers. -@item -static-liblsan -@opindex static-liblsan -When the @option{-fsanitize=leak} option is used to link a program, -the GCC driver automatically links against @option{liblsan}. If -@file{liblsan} is available as a shared library, and the @option{-static} -option is not used, then this links against the shared version of -@file{liblsan}. The @option{-static-liblsan} option directs the GCC -driver to link @file{liblsan} statically, without necessarily linking -other libraries statically. +@item -fdump-rtl-web +@opindex fdump-rtl-web +Dump after live range splitting. + +@item -fdump-rtl-regclass +@itemx -fdump-rtl-subregs_of_mode_init +@itemx -fdump-rtl-subregs_of_mode_finish +@itemx -fdump-rtl-dfinit +@itemx -fdump-rtl-dfinish +@opindex fdump-rtl-regclass +@opindex fdump-rtl-subregs_of_mode_init +@opindex fdump-rtl-subregs_of_mode_finish +@opindex fdump-rtl-dfinit +@opindex fdump-rtl-dfinish +These dumps are defined but always produce empty files. + +@item -da +@itemx -fdump-rtl-all +@opindex da +@opindex fdump-rtl-all +Produce all the dumps listed above. + +@item -dA +@opindex dA +Annotate the assembler output with miscellaneous debugging information. + +@item -dD +@opindex dD +Dump all macro definitions, at the end of preprocessing, in addition to +normal output. + +@item -dH +@opindex dH +Produce a core dump whenever an error occurs. + +@item -dp +@opindex dp +Annotate the assembler output with a comment indicating which +pattern and alternative is used. The length of each instruction is +also printed. + +@item -dP +@opindex dP +Dump the RTL in the assembler output as a comment before each instruction. +Also turns on @option{-dp} annotation. + +@item -dx +@opindex dx +Just generate RTL for a function instead of compiling it. Usually used +with @option{-fdump-rtl-expand}. +@end table + +@item -fdump-noaddr +@opindex fdump-noaddr +When doing debugging dumps, suppress address output. This makes it more +feasible to use diff on debugging dumps for compiler invocations with +different compiler binaries and/or different +text / bss / data / heap / stack / dso start locations. + +@item -freport-bug +@opindex freport-bug +Collect and dump debug information into temporary file if ICE in C/C++ +compiler occured. + +@item -fdump-unnumbered +@opindex fdump-unnumbered +When doing debugging dumps, suppress instruction numbers and address output. +This makes it more feasible to use diff on debugging dumps for compiler +invocations with different options, in particular with and without +@option{-g}. + +@item -fdump-unnumbered-links +@opindex fdump-unnumbered-links +When doing debugging dumps (see @option{-d} option above), suppress +instruction numbers for the links to the previous and next instructions +in a sequence. + +@item -fdump-translation-unit @r{(C++ only)} +@itemx -fdump-translation-unit-@var{options} @r{(C++ only)} +@opindex fdump-translation-unit +Dump a representation of the tree structure for the entire translation +unit to a file. The file name is made by appending @file{.tu} to the +source file name, and the file is created in the same directory as the +output file. If the @samp{-@var{options}} form is used, @var{options} +controls the details of the dump as described for the +@option{-fdump-tree} options. + +@item -fdump-class-hierarchy @r{(C++ only)} +@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)} +@opindex fdump-class-hierarchy +Dump a representation of each class's hierarchy and virtual function +table layout to a file. The file name is made by appending +@file{.class} to the source file name, and the file is created in the +same directory as the output file. If the @samp{-@var{options}} form +is used, @var{options} controls the details of the dump as described +for the @option{-fdump-tree} options. + +@item -fdump-ipa-@var{switch} +@opindex fdump-ipa +Control the dumping at various stages of inter-procedural analysis +language tree to a file. The file name is generated by appending a +switch specific suffix to the source file name, and the file is created +in the same directory as the output file. The following dumps are +possible: + +@table @samp +@item all +Enables all inter-procedural analysis dumps. + +@item cgraph +Dumps information about call-graph optimization, unused function removal, +and inlining decisions. + +@item inline +Dump after function inlining. + +@end table + +@item -fdump-passes +@opindex fdump-passes +Dump the list of optimization passes that are turned on and off by +the current command-line options. + +@item -fdump-statistics-@var{option} +@opindex fdump-statistics +Enable and control dumping of pass statistics in a separate file. The +file name is generated by appending a suffix ending in +@samp{.statistics} to the source file name, and the file is created in +the same directory as the output file. If the @samp{-@var{option}} +form is used, @samp{-stats} causes counters to be summed over the +whole compilation unit while @samp{-details} dumps every event as +the passes generate them. The default with no option is to sum +counters for each function compiled. + +@item -fdump-tree-@var{switch} +@itemx -fdump-tree-@var{switch}-@var{options} +@itemx -fdump-tree-@var{switch}-@var{options}=@var{filename} +@opindex fdump-tree +Control the dumping at various stages of processing the intermediate +language tree to a file. The file name is generated by appending a +switch-specific suffix to the source file name, and the file is +created in the same directory as the output file. In case of +@option{=@var{filename}} option, the dump is output on the given file +instead of the auto named dump files. If the @samp{-@var{options}} +form is used, @var{options} is a list of @samp{-} separated options +which control the details of the dump. Not all options are applicable +to all dumps; those that are not meaningful are ignored. The +following options are available + +@table @samp +@item address +Print the address of each node. Usually this is not meaningful as it +changes according to the environment and source file. Its primary use +is for tying up a dump file with a debug environment. +@item asmname +If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that +in the dump instead of @code{DECL_NAME}. Its primary use is ease of +use working backward from mangled names in the assembly file. +@item slim +When dumping front-end intermediate representations, inhibit dumping +of members of a scope or body of a function merely because that scope +has been reached. Only dump such items when they are directly reachable +by some other path. + +When dumping pretty-printed trees, this option inhibits dumping the +bodies of control structures. + +When dumping RTL, print the RTL in slim (condensed) form instead of +the default LISP-like representation. +@item raw +Print a raw representation of the tree. By default, trees are +pretty-printed into a C-like representation. +@item details +Enable more detailed dumps (not honored by every dump option). Also +include information from the optimization passes. +@item stats +Enable dumping various statistics about the pass (not honored by every dump +option). +@item blocks +Enable showing basic block boundaries (disabled in raw dumps). +@item graph +For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}), +dump a representation of the control flow graph suitable for viewing with +GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in +the file is pretty-printed as a subgraph, so that GraphViz can render them +all in a single plot. + +This option currently only works for RTL dumps, and the RTL is always +dumped in slim form. +@item vops +Enable showing virtual operands for every statement. +@item lineno +Enable showing line numbers for statements. +@item uid +Enable showing the unique ID (@code{DECL_UID}) for each variable. +@item verbose +Enable showing the tree dump for each statement. +@item eh +Enable showing the EH region number holding each statement. +@item scev +Enable showing scalar evolution analysis details. +@item optimized +Enable showing optimization information (only available in certain +passes). +@item missed +Enable showing missed optimization information (only available in certain +passes). +@item note +Enable other detailed optimization information (only available in +certain passes). +@item =@var{filename} +Instead of an auto named dump file, output into the given file +name. The file names @file{stdout} and @file{stderr} are treated +specially and are considered already open standard streams. For +example, + +@smallexample +gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump + -fdump-tree-pre=stderr file.c +@end smallexample + +outputs vectorizer dump into @file{foo.dump}, while the PRE dump is +output on to @file{stderr}. If two conflicting dump filenames are +given for the same pass, then the latter option overrides the earlier +one. -@item -static-libubsan -@opindex static-libubsan -When the @option{-fsanitize=undefined} option is used to link a program, -the GCC driver automatically links against @option{libubsan}. If -@file{libubsan} is available as a shared library, and the @option{-static} -option is not used, then this links against the shared version of -@file{libubsan}. The @option{-static-libubsan} option directs the GCC -driver to link @file{libubsan} statically, without necessarily linking -other libraries statically. +@item split-paths +@opindex fdump-tree-split-paths +Dump each function after splitting paths to loop backedges. The file +name is made by appending @file{.split-paths} to the source file name. -@item -static-libmpx -@opindex static-libmpx -When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are -used to link a program, the GCC driver automatically links against -@file{libmpx}. If @file{libmpx} is available as a shared library, -and the @option{-static} option is not used, then this links against -the shared version of @file{libmpx}. The @option{-static-libmpx} -option directs the GCC driver to link @file{libmpx} statically, -without necessarily linking other libraries statically. +@item all +Turn on all options, except @option{raw}, @option{slim}, @option{verbose} +and @option{lineno}. -@item -static-libmpxwrappers -@opindex static-libmpxwrappers -When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are used -to link a program without also using @option{-fno-chkp-use-wrappers}, the -GCC driver automatically links against @file{libmpxwrappers}. If -@file{libmpxwrappers} is available as a shared library, and the -@option{-static} option is not used, then this links against the shared -version of @file{libmpxwrappers}. The @option{-static-libmpxwrappers} -option directs the GCC driver to link @file{libmpxwrappers} statically, -without necessarily linking other libraries statically. +@item optall +Turn on all optimization options, i.e., @option{optimized}, +@option{missed}, and @option{note}. +@end table -@item -static-libstdc++ -@opindex static-libstdc++ -When the @command{g++} program is used to link a C++ program, it -normally automatically links against @option{libstdc++}. If -@file{libstdc++} is available as a shared library, and the -@option{-static} option is not used, then this links against the -shared version of @file{libstdc++}. That is normally fine. However, it -is sometimes useful to freeze the version of @file{libstdc++} used by -the program without going all the way to a fully static link. The -@option{-static-libstdc++} option directs the @command{g++} driver to -link @file{libstdc++} statically, without necessarily linking other -libraries statically. +The following tree dumps are possible: +@table @samp -@item -symbolic -@opindex symbolic -Bind references to global symbols when building a shared object. Warn -about any unresolved references (unless overridden by the link editor -option @option{-Xlinker -z -Xlinker defs}). Only a few systems support -this option. +@item original +@opindex fdump-tree-original +Dump before any tree based optimization, to @file{@var{file}.original}. -@item -T @var{script} -@opindex T -@cindex linker script -Use @var{script} as the linker script. This option is supported by most -systems using the GNU linker. On some targets, such as bare-board -targets without an operating system, the @option{-T} option may be required -when linking to avoid references to undefined symbols. +@item optimized +@opindex fdump-tree-optimized +Dump after all tree based optimization, to @file{@var{file}.optimized}. -@item -Xlinker @var{option} -@opindex Xlinker -Pass @var{option} as an option to the linker. You can use this to -supply system-specific linker options that GCC does not recognize. +@item gimple +@opindex fdump-tree-gimple +Dump each function before and after the gimplification pass to a file. The +file name is made by appending @file{.gimple} to the source file name. -If you want to pass an option that takes a separate argument, you must use -@option{-Xlinker} twice, once for the option and once for the argument. -For example, to pass @option{-assert definitions}, you must write -@option{-Xlinker -assert -Xlinker definitions}. It does not work to write -@option{-Xlinker "-assert definitions"}, because this passes the entire -string as a single argument, which is not what the linker expects. +@item cfg +@opindex fdump-tree-cfg +Dump the control flow graph of each function to a file. The file name is +made by appending @file{.cfg} to the source file name. -When using the GNU linker, it is usually more convenient to pass -arguments to linker options using the @option{@var{option}=@var{value}} -syntax than as separate arguments. For example, you can specify -@option{-Xlinker -Map=output.map} rather than -@option{-Xlinker -Map -Xlinker output.map}. Other linkers may not support -this syntax for command-line options. +@item ch +@opindex fdump-tree-ch +Dump each function after copying loop headers. The file name is made by +appending @file{.ch} to the source file name. -@item -Wl,@var{option} -@opindex Wl -Pass @var{option} as an option to the linker. If @var{option} contains -commas, it is split into multiple options at the commas. You can use this -syntax to pass an argument to the option. -For example, @option{-Wl,-Map,output.map} passes @option{-Map output.map} to the -linker. When using the GNU linker, you can also get the same effect with -@option{-Wl,-Map=output.map}. +@item ssa +@opindex fdump-tree-ssa +Dump SSA related information to a file. The file name is made by appending +@file{.ssa} to the source file name. -@item -u @var{symbol} -@opindex u -Pretend the symbol @var{symbol} is undefined, to force linking of -library modules to define it. You can use @option{-u} multiple times with -different symbols to force loading of additional library modules. +@item alias +@opindex fdump-tree-alias +Dump aliasing information for each function. The file name is made by +appending @file{.alias} to the source file name. -@item -z @var{keyword} -@opindex z -@option{-z} is passed directly on to the linker along with the keyword -@var{keyword}. See the section in the documentation of your linker for -permitted values and their meanings. -@end table +@item ccp +@opindex fdump-tree-ccp +Dump each function after CCP@. The file name is made by appending +@file{.ccp} to the source file name. -@node Directory Options -@section Options for Directory Search -@cindex directory options -@cindex options, directory search -@cindex search path +@item storeccp +@opindex fdump-tree-storeccp +Dump each function after STORE-CCP@. The file name is made by appending +@file{.storeccp} to the source file name. -These options specify directories to search for header files, for -libraries and for parts of the compiler: +@item pre +@opindex fdump-tree-pre +Dump trees after partial redundancy elimination. The file name is made +by appending @file{.pre} to the source file name. -@table @gcctabopt -@item -I@var{dir} -@opindex I -Add the directory @var{dir} to the head of the list of directories to be -searched for header files. This can be used to override a system header -file, substituting your own version, since these directories are -searched before the system header file directories. However, you should -not use this option to add directories that contain vendor-supplied -system header files (use @option{-isystem} for that). If you use more than -one @option{-I} option, the directories are scanned in left-to-right -order; the standard system directories come after. +@item fre +@opindex fdump-tree-fre +Dump trees after full redundancy elimination. The file name is made +by appending @file{.fre} to the source file name. -If a standard system include directory, or a directory specified with -@option{-isystem}, is also specified with @option{-I}, the @option{-I} -option is ignored. The directory is still searched but as a -system directory at its normal position in the system include chain. -This is to ensure that GCC's procedure to fix buggy system headers and -the ordering for the @code{include_next} directive are not inadvertently changed. -If you really need to change the search order for system directories, -use the @option{-nostdinc} and/or @option{-isystem} options. +@item copyprop +@opindex fdump-tree-copyprop +Dump trees after copy propagation. The file name is made +by appending @file{.copyprop} to the source file name. -@item -iplugindir=@var{dir} -@opindex iplugindir= -Set the directory to search for plugins that are passed -by @option{-fplugin=@var{name}} instead of -@option{-fplugin=@var{path}/@var{name}.so}. This option is not meant -to be used by the user, but only passed by the driver. +@item store_copyprop +@opindex fdump-tree-store_copyprop +Dump trees after store copy-propagation. The file name is made +by appending @file{.store_copyprop} to the source file name. -@item -iquote@var{dir} -@opindex iquote -Add the directory @var{dir} to the head of the list of directories to -be searched for header files only for the case of @code{#include -"@var{file}"}; they are not searched for @code{#include <@var{file}>}, -otherwise just like @option{-I}. +@item dce +@opindex fdump-tree-dce +Dump each function after dead code elimination. The file name is made by +appending @file{.dce} to the source file name. -@item -L@var{dir} -@opindex L -Add directory @var{dir} to the list of directories to be searched -for @option{-l}. +@item sra +@opindex fdump-tree-sra +Dump each function after performing scalar replacement of aggregates. The +file name is made by appending @file{.sra} to the source file name. -@item -B@var{prefix} -@opindex B -This option specifies where to find the executables, libraries, -include files, and data files of the compiler itself. +@item sink +@opindex fdump-tree-sink +Dump each function after performing code sinking. The file name is made +by appending @file{.sink} to the source file name. -The compiler driver program runs one or more of the subprograms -@command{cpp}, @command{cc1}, @command{as} and @command{ld}. It tries -@var{prefix} as a prefix for each program it tries to run, both with and -without @samp{@var{machine}/@var{version}/} for the corresponding target -machine and compiler version. +@item dom +@opindex fdump-tree-dom +Dump each function after applying dominator tree optimizations. The file +name is made by appending @file{.dom} to the source file name. -For each subprogram to be run, the compiler driver first tries the -@option{-B} prefix, if any. If that name is not found, or if @option{-B} -is not specified, the driver tries two standard prefixes, -@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of -those results in a file name that is found, the unmodified program -name is searched for using the directories specified in your -@env{PATH} environment variable. +@item dse +@opindex fdump-tree-dse +Dump each function after applying dead store elimination. The file +name is made by appending @file{.dse} to the source file name. -The compiler checks to see if the path provided by @option{-B} -refers to a directory, and if necessary it adds a directory -separator character at the end of the path. +@item phiopt +@opindex fdump-tree-phiopt +Dump each function after optimizing PHI nodes into straightline code. The file +name is made by appending @file{.phiopt} to the source file name. -@option{-B} prefixes that effectively specify directory names also apply -to libraries in the linker, because the compiler translates these -options into @option{-L} options for the linker. They also apply to -include files in the preprocessor, because the compiler translates these -options into @option{-isystem} options for the preprocessor. In this case, -the compiler appends @samp{include} to the prefix. +@item backprop +@opindex fdump-tree-backprop +Dump each function after back-propagating use information up the definition +chain. The file name is made by appending @file{.backprop} to the +source file name. + +@item forwprop +@opindex fdump-tree-forwprop +Dump each function after forward propagating single use variables. The file +name is made by appending @file{.forwprop} to the source file name. -The runtime support file @file{libgcc.a} can also be searched for using -the @option{-B} prefix, if needed. If it is not found there, the two -standard prefixes above are tried, and that is all. The file is left -out of the link if it is not found by those means. +@item nrv +@opindex fdump-tree-nrv +Dump each function after applying the named return value optimization on +generic trees. The file name is made by appending @file{.nrv} to the source +file name. -Another way to specify a prefix much like the @option{-B} prefix is to use -the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment -Variables}. +@item vect +@opindex fdump-tree-vect +Dump each function after applying vectorization of loops. The file name is +made by appending @file{.vect} to the source file name. -As a special kludge, if the path provided by @option{-B} is -@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to -9, then it is replaced by @file{[dir/]include}. This is to help -with boot-strapping the compiler. +@item slp +@opindex fdump-tree-slp +Dump each function after applying vectorization of basic blocks. The file name +is made by appending @file{.slp} to the source file name. -@item -no-canonical-prefixes -@opindex no-canonical-prefixes -Do not expand any symbolic links, resolve references to @samp{/../} -or @samp{/./}, or make the path absolute when generating a relative -prefix. +@item vrp +@opindex fdump-tree-vrp +Dump each function after Value Range Propagation (VRP). The file name +is made by appending @file{.vrp} to the source file name. -@item --sysroot=@var{dir} -@opindex sysroot -Use @var{dir} as the logical root directory for headers and libraries. -For example, if the compiler normally searches for headers in -@file{/usr/include} and libraries in @file{/usr/lib}, it instead -searches @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}. +@item oaccdevlow +@opindex fdump-tree-oaccdevlow +Dump each function after applying device-specific OpenACC transformations. +The file name is made by appending @file{.oaccdevlow} to the source file name. -If you use both this option and the @option{-isysroot} option, then -the @option{--sysroot} option applies to libraries, but the -@option{-isysroot} option applies to header files. +@item all +@opindex fdump-tree-all +Enable all the available tree dumps with the flags provided in this option. +@end table -The GNU linker (beginning with version 2.16) has the necessary support -for this option. If your linker does not support this option, the -header file aspect of @option{--sysroot} still works, but the -library aspect does not. +@item -fopt-info +@itemx -fopt-info-@var{options} +@itemx -fopt-info-@var{options}=@var{filename} +@opindex fopt-info +Controls optimization dumps from various optimization passes. If the +@samp{-@var{options}} form is used, @var{options} is a list of +@samp{-} separated option keywords to select the dump details and +optimizations. -@item --no-sysroot-suffix -@opindex no-sysroot-suffix -For some targets, a suffix is added to the root directory specified -with @option{--sysroot}, depending on the other options used, so that -headers may for example be found in -@file{@var{dir}/@var{suffix}/usr/include} instead of -@file{@var{dir}/usr/include}. This option disables the addition of -such a suffix. +The @var{options} can be divided into two groups: options describing the +verbosity of the dump, and options describing which optimizations +should be included. The options from both the groups can be freely +mixed as they are non-overlapping. However, in case of any conflicts, +the later options override the earlier options on the command +line. -@item -I- -@opindex I- -This option has been deprecated. Please use @option{-iquote} instead for -@option{-I} directories before the @option{-I-} and remove the @option{-I-} -option. -Any directories you specify with @option{-I} options before the @option{-I-} -option are searched only for the case of @code{#include "@var{file}"}; -they are not searched for @code{#include <@var{file}>}. +The following options control the dump verbosity: -If additional directories are specified with @option{-I} options after -the @option{-I-} option, these directories are searched for all @code{#include} -directives. (Ordinarily @emph{all} @option{-I} directories are used -this way.) +@table @samp +@item optimized +Print information when an optimization is successfully applied. It is +up to a pass to decide which information is relevant. For example, the +vectorizer passes print the source location of loops which are +successfully vectorized. +@item missed +Print information about missed optimizations. Individual passes +control which information to include in the output. +@item note +Print verbose information about optimizations, such as certain +transformations, more detailed messages about decisions etc. +@item all +Print detailed optimization information. This includes +@samp{optimized}, @samp{missed}, and @samp{note}. +@end table -In addition, the @option{-I-} option inhibits the use of the current -directory (where the current input file came from) as the first search -directory for @code{#include "@var{file}"}. There is no way to -override this effect of @option{-I-}. With @option{-I.} you can specify -searching the directory that is current when the compiler is -invoked. That is not exactly the same as what the preprocessor does -by default, but it is often satisfactory. +One or more of the following option keywords can be used to describe a +group of optimizations: -@option{-I-} does not inhibit the use of the standard system directories -for header files. Thus, @option{-I-} and @option{-nostdinc} are -independent. +@table @samp +@item ipa +Enable dumps from all interprocedural optimizations. +@item loop +Enable dumps from all loop optimizations. +@item inline +Enable dumps from all inlining optimizations. +@item vec +Enable dumps from all vectorization optimizations. +@item optall +Enable dumps from all optimizations. This is a superset of +the optimization groups listed above. @end table -@node Code Gen Options -@section Options for Code Generation Conventions -@cindex code generation conventions -@cindex options, code generation -@cindex run-time options +If @var{options} is +omitted, it defaults to @samp{optimized-optall}, which means to dump all +info about successful optimizations from all the passes. -These machine-independent options control the interface conventions -used in code generation. +If the @var{filename} is provided, then the dumps from all the +applicable optimizations are concatenated into the @var{filename}. +Otherwise the dump is output onto @file{stderr}. Though multiple +@option{-fopt-info} options are accepted, only one of them can include +a @var{filename}. If other filenames are provided then all but the +first such option are ignored. -Most of them have both positive and negative forms; the negative form -of @option{-ffoo} is @option{-fno-foo}. In the table below, only -one of the forms is listed---the one that is not the default. You -can figure out the other form by either removing @samp{no-} or adding -it. +Note that the output @var{filename} is overwritten +in case of multiple translation units. If a combined output from +multiple translation units is desired, @file{stderr} should be used +instead. -@table @gcctabopt -@item -fstack-reuse=@var{reuse-level} -@opindex fstack_reuse -This option controls stack space reuse for user declared local/auto variables -and compiler generated temporaries. @var{reuse_level} can be @samp{all}, -@samp{named_vars}, or @samp{none}. @samp{all} enables stack reuse for all -local variables and temporaries, @samp{named_vars} enables the reuse only for -user defined local variables with names, and @samp{none} disables stack reuse -completely. The default value is @samp{all}. The option is needed when the -program extends the lifetime of a scoped local variable or a compiler generated -temporary beyond the end point defined by the language. When a lifetime of -a variable ends, and if the variable lives in memory, the optimizing compiler -has the freedom to reuse its stack space with other temporaries or scoped -local variables whose live range does not overlap with it. Legacy code extending -local lifetime is likely to break with the stack reuse optimization. +In the following example, the optimization info is output to +@file{stderr}: -For example, +@smallexample +gcc -O3 -fopt-info +@end smallexample +This example: @smallexample - int *p; - @{ - int local1; +gcc -O3 -fopt-info-missed=missed.all +@end smallexample - p = &local1; - local1 = 10; - .... - @} - @{ - int local2; - local2 = 20; - ... - @} +@noindent +outputs missed optimization report from all the passes into +@file{missed.all}, and this one: - if (*p == 10) // out of scope use of local1 - @{ +@smallexample +gcc -O2 -ftree-vectorize -fopt-info-vec-missed +@end smallexample - @} +@noindent +prints information about missed optimization opportunities from +vectorization passes on @file{stderr}. +Note that @option{-fopt-info-vec-missed} is equivalent to +@option{-fopt-info-missed-vec}. + +As another example, +@smallexample +gcc -O3 -fopt-info-inline-optimized-missed=inline.txt @end smallexample -Another example: +@noindent +outputs information about missed optimizations as well as +optimized locations from all the inlining passes into +@file{inline.txt}. + +Finally, consider: + @smallexample +gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt +@end smallexample - struct A - @{ - A(int k) : i(k), j(k) @{ @} - int i; - int j; - @}; +@noindent +Here the two output filenames @file{vec.miss} and @file{loop.opt} are +in conflict since only one output file is allowed. In this case, only +the first option takes effect and the subsequent options are +ignored. Thus only @file{vec.miss} is produced which contains +dumps from the vectorizer about missed opportunities. - A *ap; +@item -fsched-verbose=@var{n} +@opindex fsched-verbose +On targets that use instruction scheduling, this option controls the +amount of debugging output the scheduler prints to the dump files. - void foo(const A& ar) - @{ - ap = &ar; - @} +For @var{n} greater than zero, @option{-fsched-verbose} outputs the +same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}. +For @var{n} greater than one, it also output basic block probabilities, +detailed ready list information and unit/insn info. For @var{n} greater +than two, it includes RTL at abort point, control-flow and regions info. +And for @var{n} over four, @option{-fsched-verbose} also includes +dependence info. + + + +@item -fenable-@var{kind}-@var{pass} +@itemx -fdisable-@var{kind}-@var{pass}=@var{range-list} +@opindex fdisable- +@opindex fenable- + +This is a set of options that are used to explicitly disable/enable +optimization passes. These options are intended for use for debugging GCC. +Compiler users should use regular options for enabling/disabling +passes instead. - void bar() - @{ - foo(A(10)); // temp object's lifetime ends when foo returns +@table @gcctabopt - @{ - A a(20); - .... - @} - ap->i+= 10; // ap references out of scope temp whose space - // is reused with a. What is the value of ap->i? - @} +@item -fdisable-ipa-@var{pass} +Disable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is +statically invoked in the compiler multiple times, the pass name should be +appended with a sequential number starting from 1. -@end smallexample +@item -fdisable-rtl-@var{pass} +@itemx -fdisable-rtl-@var{pass}=@var{range-list} +Disable RTL pass @var{pass}. @var{pass} is the pass name. If the same pass is +statically invoked in the compiler multiple times, the pass name should be +appended with a sequential number starting from 1. @var{range-list} is a +comma-separated list of function ranges or assembler names. Each range is a number +pair separated by a colon. The range is inclusive in both ends. If the range +is trivial, the number pair can be simplified as a single number. If the +function's call graph node's @var{uid} falls within one of the specified ranges, +the @var{pass} is disabled for that function. The @var{uid} is shown in the +function header of a dump file, and the pass names can be dumped by using +option @option{-fdump-passes}. -The lifetime of a compiler generated temporary is well defined by the C++ -standard. When a lifetime of a temporary ends, and if the temporary lives -in memory, the optimizing compiler has the freedom to reuse its stack -space with other temporaries or scoped local variables whose live range -does not overlap with it. However some of the legacy code relies on -the behavior of older compilers in which temporaries' stack space is -not reused, the aggressive stack reuse can lead to runtime errors. This -option is used to control the temporary stack reuse optimization. +@item -fdisable-tree-@var{pass} +@itemx -fdisable-tree-@var{pass}=@var{range-list} +Disable tree pass @var{pass}. See @option{-fdisable-rtl} for the description of +option arguments. -@item -ftrapv -@opindex ftrapv -This option generates traps for signed overflow on addition, subtraction, -multiplication operations. -The options @option{-ftrapv} and @option{-fwrapv} override each other, so using -@option{-ftrapv} @option{-fwrapv} on the command-line results in -@option{-fwrapv} being effective. Note that only active options override, so -using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line -results in @option{-ftrapv} being effective. +@item -fenable-ipa-@var{pass} +Enable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is +statically invoked in the compiler multiple times, the pass name should be +appended with a sequential number starting from 1. -@item -fwrapv -@opindex fwrapv -This option instructs the compiler to assume that signed arithmetic -overflow of addition, subtraction and multiplication wraps around -using twos-complement representation. This flag enables some optimizations -and disables others. This option is enabled by default for the Java -front end, as required by the Java language specification. -The options @option{-ftrapv} and @option{-fwrapv} override each other, so using -@option{-ftrapv} @option{-fwrapv} on the command-line results in -@option{-fwrapv} being effective. Note that only active options override, so -using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line -results in @option{-ftrapv} being effective. +@item -fenable-rtl-@var{pass} +@itemx -fenable-rtl-@var{pass}=@var{range-list} +Enable RTL pass @var{pass}. See @option{-fdisable-rtl} for option argument +description and examples. -@item -fexceptions -@opindex fexceptions -Enable exception handling. Generates extra code needed to propagate -exceptions. For some targets, this implies GCC generates frame -unwind information for all functions, which can produce significant data -size overhead, although it does not affect execution. If you do not -specify this option, GCC enables it by default for languages like -C++ that normally require exception handling, and disables it for -languages like C that do not normally require it. However, you may need -to enable this option when compiling C code that needs to interoperate -properly with exception handlers written in C++. You may also wish to -disable this option if you are compiling older C++ programs that don't -use exception handling. +@item -fenable-tree-@var{pass} +@itemx -fenable-tree-@var{pass}=@var{range-list} +Enable tree pass @var{pass}. See @option{-fdisable-rtl} for the description +of option arguments. -@item -fnon-call-exceptions -@opindex fnon-call-exceptions -Generate code that allows trapping instructions to throw exceptions. -Note that this requires platform-specific runtime support that does -not exist everywhere. Moreover, it only allows @emph{trapping} -instructions to throw exceptions, i.e.@: memory references or floating-point -instructions. It does not allow exceptions to be thrown from -arbitrary signal handlers such as @code{SIGALRM}. +@end table -@item -fdelete-dead-exceptions -@opindex fdelete-dead-exceptions -Consider that instructions that may throw exceptions but don't otherwise -contribute to the execution of the program can be optimized away. -This option is enabled by default for the Ada front end, as permitted by -the Ada language specification. -Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels. +Here are some examples showing uses of these options. -@item -funwind-tables -@opindex funwind-tables -Similar to @option{-fexceptions}, except that it just generates any needed -static data, but does not affect the generated code in any other way. -You normally do not need to enable this option; instead, a language processor -that needs this handling enables it on your behalf. +@smallexample -@item -fasynchronous-unwind-tables -@opindex fasynchronous-unwind-tables -Generate unwind table in DWARF 2 format, if supported by target machine. The -table is exact at each instruction boundary, so it can be used for stack -unwinding from asynchronous events (such as debugger or garbage collector). +# disable ccp1 for all functions + -fdisable-tree-ccp1 +# disable complete unroll for function whose cgraph node uid is 1 + -fenable-tree-cunroll=1 +# disable gcse2 for functions at the following ranges [1,1], +# [300,400], and [400,1000] +# disable gcse2 for functions foo and foo2 + -fdisable-rtl-gcse2=foo,foo2 +# disable early inlining + -fdisable-tree-einline +# disable ipa inlining + -fdisable-ipa-inline +# enable tree full unroll + -fenable-tree-unroll -@item -fno-gnu-unique -@opindex fno-gnu-unique -On systems with recent GNU assembler and C library, the C++ compiler -uses the @code{STB_GNU_UNIQUE} binding to make sure that definitions -of template static data members and static local variables in inline -functions are unique even in the presence of @code{RTLD_LOCAL}; this -is necessary to avoid problems with a library used by two different -@code{RTLD_LOCAL} plugins depending on a definition in one of them and -therefore disagreeing with the other one about the binding of the -symbol. But this causes @code{dlclose} to be ignored for affected -DSOs; if your program relies on reinitialization of a DSO via -@code{dlclose} and @code{dlopen}, you can use -@option{-fno-gnu-unique}. +@end smallexample -@item -fpcc-struct-return -@opindex fpcc-struct-return -Return ``short'' @code{struct} and @code{union} values in memory like -longer ones, rather than in registers. This convention is less -efficient, but it has the advantage of allowing intercallability between -GCC-compiled files and files compiled with other compilers, particularly -the Portable C Compiler (pcc). +@item -fchecking +@opindex fchecking +@opindex fno-checking +Enable internal consistency checking. The default depends on +the compiler configuration. -The precise convention for returning structures in memory depends -on the target configuration macros. +@item -frandom-seed=@var{string} +@opindex frandom-seed +This option provides a seed that GCC uses in place of +random numbers in generating certain symbol names +that have to be different in every compiled file. It is also used to +place unique stamps in coverage data files and the object files that +produce them. You can use the @option{-frandom-seed} option to produce +reproducibly identical object files. -Short structures and unions are those whose size and alignment match -that of some integer type. +The @var{string} can either be a number (decimal, octal or hex) or an +arbitrary string (in which case it's converted to a number by +computing CRC32). -@strong{Warning:} code compiled with the @option{-fpcc-struct-return} -switch is not binary compatible with code compiled with the -@option{-freg-struct-return} switch. -Use it to conform to a non-default application binary interface. +The @var{string} should be different for every file you compile. -@item -freg-struct-return -@opindex freg-struct-return -Return @code{struct} and @code{union} values in registers when possible. -This is more efficient for small structures than -@option{-fpcc-struct-return}. +@item -save-temps +@itemx -save-temps=cwd +@opindex save-temps +Store the usual ``temporary'' intermediate files permanently; place them +in the current directory and name them based on the source file. Thus, +compiling @file{foo.c} with @option{-c -save-temps} produces files +@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a +preprocessed @file{foo.i} output file even though the compiler now +normally uses an integrated preprocessor. -If you specify neither @option{-fpcc-struct-return} nor -@option{-freg-struct-return}, GCC defaults to whichever convention is -standard for the target. If there is no standard convention, GCC -defaults to @option{-fpcc-struct-return}, except on targets where GCC is -the principal compiler. In those cases, we can choose the standard, and -we chose the more efficient register return alternative. +When used in combination with the @option{-x} command-line option, +@option{-save-temps} is sensible enough to avoid over writing an +input source file with the same extension as an intermediate file. +The corresponding intermediate file may be obtained by renaming the +source file before using @option{-save-temps}. -@strong{Warning:} code compiled with the @option{-freg-struct-return} -switch is not binary compatible with code compiled with the -@option{-fpcc-struct-return} switch. -Use it to conform to a non-default application binary interface. +If you invoke GCC in parallel, compiling several different source +files that share a common base name in different subdirectories or the +same source file compiled for multiple output destinations, it is +likely that the different parallel compilers will interfere with each +other, and overwrite the temporary files. For instance: -@item -fshort-enums -@opindex fshort-enums -Allocate to an @code{enum} type only as many bytes as it needs for the -declared range of possible values. Specifically, the @code{enum} type -is equivalent to the smallest integer type that has enough room. +@smallexample +gcc -save-temps -o outdir1/foo.o indir1/foo.c& +gcc -save-temps -o outdir2/foo.o indir2/foo.c& +@end smallexample -@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate -code that is not binary compatible with code generated without that switch. -Use it to conform to a non-default application binary interface. +may result in @file{foo.i} and @file{foo.o} being written to +simultaneously by both compilers. -@item -fshort-double -@opindex fshort-double -Use the same size for @code{double} as for @code{float}. +@item -save-temps=obj +@opindex save-temps=obj +Store the usual ``temporary'' intermediate files permanently. If the +@option{-o} option is used, the temporary files are based on the +object file. If the @option{-o} option is not used, the +@option{-save-temps=obj} switch behaves like @option{-save-temps}. -@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate -code that is not binary compatible with code generated without that switch. -Use it to conform to a non-default application binary interface. +For example: -@item -fshort-wchar -@opindex fshort-wchar -Override the underlying type for @code{wchar_t} to be @code{short -unsigned int} instead of the default for the target. This option is -useful for building programs to run under WINE@. +@smallexample +gcc -save-temps=obj -c foo.c +gcc -save-temps=obj -c bar.c -o dir/xbar.o +gcc -save-temps=obj foobar.c -o dir2/yfoobar +@end smallexample -@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate -code that is not binary compatible with code generated without that switch. -Use it to conform to a non-default application binary interface. +@noindent +creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i}, +@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and +@file{dir2/yfoobar.o}. + +@item -time@r{[}=@var{file}@r{]} +@opindex time +Report the CPU time taken by each subprocess in the compilation +sequence. For C source files, this is the compiler proper and assembler +(plus the linker if linking is done). -@item -fno-common -@opindex fno-common -In C code, controls the placement of uninitialized global variables. -Unix C compilers have traditionally permitted multiple definitions of -such variables in different compilation units by placing the variables -in a common block. -This is the behavior specified by @option{-fcommon}, and is the default -for GCC on most targets. -On the other hand, this behavior is not required by ISO C, and on some -targets may carry a speed or code size penalty on variable references. -The @option{-fno-common} option specifies that the compiler should place -uninitialized global variables in the data section of the object file, -rather than generating them as common blocks. -This has the effect that if the same variable is declared -(without @code{extern}) in two different compilations, -you get a multiple-definition error when you link them. -In this case, you must compile with @option{-fcommon} instead. -Compiling with @option{-fno-common} is useful on targets for which -it provides better performance, or if you wish to verify that the -program will work on other systems that always treat uninitialized -variable declarations this way. +Without the specification of an output file, the output looks like this: -@item -fno-ident -@opindex fno-ident -Ignore the @code{#ident} directive. +@smallexample +# cc1 0.12 0.01 +# as 0.00 0.01 +@end smallexample -@item -finhibit-size-directive -@opindex finhibit-size-directive -Don't output a @code{.size} assembler directive, or anything else that -would cause trouble if the function is split in the middle, and the -two halves are placed at locations far apart in memory. This option is -used when compiling @file{crtstuff.c}; you should not need to use it -for anything else. +The first number on each line is the ``user time'', that is time spent +executing the program itself. The second number is ``system time'', +time spent executing operating system routines on behalf of the program. +Both numbers are in seconds. -@item -fverbose-asm -@opindex fverbose-asm -Put extra commentary information in the generated assembly code to -make it more readable. This option is generally only of use to those -who actually need to read the generated assembly code (perhaps while -debugging the compiler itself). +With the specification of an output file, the output is appended to the +named file, and it looks like this: -@option{-fno-verbose-asm}, the default, causes the -extra information to be omitted and is useful when comparing two assembler -files. +@smallexample +0.12 0.01 cc1 @var{options} +0.00 0.01 as @var{options} +@end smallexample -@item -frecord-gcc-switches -@opindex frecord-gcc-switches -This switch causes the command line used to invoke the -compiler to be recorded into the object file that is being created. -This switch is only implemented on some targets and the exact format -of the recording is target and binary file format dependent, but it -usually takes the form of a section containing ASCII text. This -switch is related to the @option{-fverbose-asm} switch, but that -switch only records information in the assembler output file as -comments, so it never reaches the object file. -See also @option{-grecord-gcc-switches} for another -way of storing compiler options into the object file. +The ``user time'' and the ``system time'' are moved before the program +name, and the options passed to the program are displayed, so that one +can later tell what file was being compiled, and with which options. -@item -fpic -@opindex fpic -@cindex global offset table -@cindex PIC -Generate position-independent code (PIC) suitable for use in a shared -library, if supported for the target machine. Such code accesses all -constant addresses through a global offset table (GOT)@. The dynamic -loader resolves the GOT entries when the program starts (the dynamic -loader is not part of GCC; it is part of the operating system). If -the GOT size for the linked executable exceeds a machine-specific -maximum size, you get an error message from the linker indicating that -@option{-fpic} does not work; in that case, recompile with @option{-fPIC} -instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k -on the m68k and RS/6000. The x86 has no such limit.) +@item -fdump-final-insns@r{[}=@var{file}@r{]} +@opindex fdump-final-insns +Dump the final internal representation (RTL) to @var{file}. If the +optional argument is omitted (or if @var{file} is @code{.}), the name +of the dump file is determined by appending @code{.gkd} to the +compilation output file name. -Position-independent code requires special support, and therefore works -only on certain machines. For the x86, GCC supports PIC for System V -but not for the Sun 386i. Code generated for the IBM RS/6000 is always -position-independent. +@item -fcompare-debug@r{[}=@var{opts}@r{]} +@opindex fcompare-debug +@opindex fno-compare-debug +If no error occurs during compilation, run the compiler a second time, +adding @var{opts} and @option{-fcompare-debug-second} to the arguments +passed to the second compilation. Dump the final internal +representation in both compilations, and print an error if they differ. -When this flag is set, the macros @code{__pic__} and @code{__PIC__} -are defined to 1. +If the equal sign is omitted, the default @option{-gtoggle} is used. -@item -fPIC -@opindex fPIC -If supported for the target machine, emit position-independent code, -suitable for dynamic linking and avoiding any limit on the size of the -global offset table. This option makes a difference on AArch64, m68k, -PowerPC and SPARC@. +The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty +and nonzero, implicitly enables @option{-fcompare-debug}. If +@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash, +then it is used for @var{opts}, otherwise the default @option{-gtoggle} +is used. -Position-independent code requires special support, and therefore works -only on certain machines. +@option{-fcompare-debug=}, with the equal sign but without @var{opts}, +is equivalent to @option{-fno-compare-debug}, which disables the dumping +of the final representation and the second compilation, preventing even +@env{GCC_COMPARE_DEBUG} from taking effect. -When this flag is set, the macros @code{__pic__} and @code{__PIC__} -are defined to 2. +To verify full coverage during @option{-fcompare-debug} testing, set +@env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden}, +which GCC rejects as an invalid option in any actual compilation +(rather than preprocessing, assembly or linking). To get just a +warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug +not overridden} will do. -@item -fpie -@itemx -fPIE -@opindex fpie -@opindex fPIE -These options are similar to @option{-fpic} and @option{-fPIC}, but -generated position independent code can be only linked into executables. -Usually these options are used when @option{-pie} GCC option is -used during linking. +@item -fcompare-debug-second +@opindex fcompare-debug-second +This option is implicitly passed to the compiler for the second +compilation requested by @option{-fcompare-debug}, along with options to +silence warnings, and omitting other options that would cause +side-effect compiler outputs to files or to the standard output. Dump +files and preserved temporary files are renamed so as to contain the +@code{.gk} additional extension during the second compilation, to avoid +overwriting those generated by the first. -@option{-fpie} and @option{-fPIE} both define the macros -@code{__pie__} and @code{__PIE__}. The macros have the value 1 -for @option{-fpie} and 2 for @option{-fPIE}. +When this option is passed to the compiler driver, it causes the +@emph{first} compilation to be skipped, which makes it useful for little +other than debugging the compiler proper. -@item -fno-plt -@opindex fno-plt -Do not use the PLT for external function calls in position-independent code. -Instead, load the callee address at call sites from the GOT and branch to it. -This leads to more efficient code by eliminating PLT stubs and exposing -GOT loads to optimizations. On architectures such as 32-bit x86 where -PLT stubs expect the GOT pointer in a specific register, this gives more -register allocation freedom to the compiler. -Lazy binding requires use of the PLT; -with @option{-fno-plt} all external symbols are resolved at load time. +@item -gtoggle +@opindex gtoggle +Turn off generation of debug info, if leaving out this option +generates it, or turn it on at level 2 otherwise. The position of this +argument in the command line does not matter; it takes effect after all +other options are processed, and it does so only once, no matter how +many times it is given. This is mainly intended to be used with +@option{-fcompare-debug}. -Alternatively, the function attribute @code{noplt} can be used to avoid calls -through the PLT for specific external functions. +@item -fvar-tracking-assignments-toggle +@opindex fvar-tracking-assignments-toggle +@opindex fno-var-tracking-assignments-toggle +Toggle @option{-fvar-tracking-assignments}, in the same way that +@option{-gtoggle} toggles @option{-g}. -In position-dependent code, a few targets also convert calls to -functions that are marked to not use the PLT to use the GOT instead. +@item -Q +@opindex Q +Makes the compiler print out each function name as it is compiled, and +print some statistics about each pass when it finishes. -@item -fno-jump-tables -@opindex fno-jump-tables -Do not use jump tables for switch statements even where it would be -more efficient than other code generation strategies. This option is -of use in conjunction with @option{-fpic} or @option{-fPIC} for -building code that forms part of a dynamic linker and cannot -reference the address of a jump table. On some targets, jump tables -do not require a GOT and this option is not needed. +@item -ftime-report +@opindex ftime-report +Makes the compiler print some statistics about the time consumed by each +pass when it finishes. -@item -ffixed-@var{reg} -@opindex ffixed -Treat the register named @var{reg} as a fixed register; generated code -should never refer to it (except perhaps as a stack pointer, frame -pointer or in some other fixed role). +@item -fira-verbose=@var{n} +@opindex fira-verbose +Control the verbosity of the dump file for the integrated register allocator. +The default value is 5. If the value @var{n} is greater or equal to 10, +the dump output is sent to stderr using the same format as @var{n} minus 10. -@var{reg} must be the name of a register. The register names accepted -are machine-specific and are defined in the @code{REGISTER_NAMES} -macro in the machine description macro file. +@item -flto-report +@opindex flto-report +Prints a report with internal details on the workings of the link-time +optimizer. The contents of this report vary from version to version. +It is meant to be useful to GCC developers when processing object +files in LTO mode (via @option{-flto}). -This flag does not have a negative form, because it specifies a -three-way choice. +Disabled by default. -@item -fcall-used-@var{reg} -@opindex fcall-used -Treat the register named @var{reg} as an allocable register that is -clobbered by function calls. It may be allocated for temporaries or -variables that do not live across a call. Functions compiled this way -do not save and restore the register @var{reg}. +@item -flto-report-wpa +@opindex flto-report-wpa +Like @option{-flto-report}, but only print for the WPA phase of Link +Time Optimization. -It is an error to use this flag with the frame pointer or stack pointer. -Use of this flag for other registers that have fixed pervasive roles in -the machine's execution model produces disastrous results. +@item -fmem-report +@opindex fmem-report +Makes the compiler print some statistics about permanent memory +allocation when it finishes. -This flag does not have a negative form, because it specifies a -three-way choice. +@item -fmem-report-wpa +@opindex fmem-report-wpa +Makes the compiler print some statistics about permanent memory +allocation for the WPA phase only. -@item -fcall-saved-@var{reg} -@opindex fcall-saved -Treat the register named @var{reg} as an allocable register saved by -functions. It may be allocated even for temporaries or variables that -live across a call. Functions compiled this way save and restore -the register @var{reg} if they use it. +@item -fpre-ipa-mem-report +@opindex fpre-ipa-mem-report +@item -fpost-ipa-mem-report +@opindex fpost-ipa-mem-report +Makes the compiler print some statistics about permanent memory +allocation before or after interprocedural optimization. -It is an error to use this flag with the frame pointer or stack pointer. -Use of this flag for other registers that have fixed pervasive roles in -the machine's execution model produces disastrous results. +@item -fprofile-report +@opindex fprofile-report +Makes the compiler print some statistics about consistency of the +(estimated) profile and effect of individual passes. -A different sort of disaster results from the use of this flag for -a register in which function values may be returned. +@item -fstack-usage +@opindex fstack-usage +Makes the compiler output stack usage information for the program, on a +per-function basis. The filename for the dump is made by appending +@file{.su} to the @var{auxname}. @var{auxname} is generated from the name of +the output file, if explicitly specified and it is not an executable, +otherwise it is the basename of the source file. An entry is made up +of three fields: -This flag does not have a negative form, because it specifies a -three-way choice. +@itemize +@item +The name of the function. +@item +A number of bytes. +@item +One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}. +@end itemize -@item -fpack-struct[=@var{n}] -@opindex fpack-struct -Without a value specified, pack all structure members together without -holes. When a value is specified (which must be a small power of two), pack -structure members according to this value, representing the maximum -alignment (that is, objects with default alignment requirements larger than -this are output potentially unaligned at the next fitting location. +The qualifier @code{static} means that the function manipulates the stack +statically: a fixed number of bytes are allocated for the frame on function +entry and released on function exit; no stack adjustments are otherwise made +in the function. The second field is this fixed number of bytes. -@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate -code that is not binary compatible with code generated without that switch. -Additionally, it makes the code suboptimal. -Use it to conform to a non-default application binary interface. +The qualifier @code{dynamic} means that the function manipulates the stack +dynamically: in addition to the static allocation described above, stack +adjustments are made in the body of the function, for example to push/pop +arguments around function calls. If the qualifier @code{bounded} is also +present, the amount of these adjustments is bounded at compile time and +the second field is an upper bound of the total amount of stack used by +the function. If it is not present, the amount of these adjustments is +not bounded at compile time and the second field only represents the +bounded part. -@item -fleading-underscore -@opindex fleading-underscore -This option and its counterpart, @option{-fno-leading-underscore}, forcibly -change the way C symbols are represented in the object file. One use -is to help link with legacy assembly code. +@item -fstats +@opindex fstats +Emit statistics about front-end processing at the end of the compilation. +This option is supported only by the C++ front end, and +the information is generally only useful to the G++ development team. -@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to -generate code that is not binary compatible with code generated without that -switch. Use it to conform to a non-default application binary interface. -Not all targets provide complete support for this switch. +@item -fdbg-cnt-list +@opindex fdbg-cnt-list +Print the name and the counter upper bound for all debug counters. -@item -ftls-model=@var{model} -@opindex ftls-model -Alter the thread-local storage model to be used (@pxref{Thread-Local}). -The @var{model} argument should be one of @samp{global-dynamic}, -@samp{local-dynamic}, @samp{initial-exec} or @samp{local-exec}. -Note that the choice is subject to optimization: the compiler may use -a more efficient model for symbols not visible outside of the translation -unit, or if @option{-fpic} is not given on the command line. -The default without @option{-fpic} is @samp{initial-exec}; with -@option{-fpic} the default is @samp{global-dynamic}. +@item -fdbg-cnt=@var{counter-value-list} +@opindex fdbg-cnt +Set the internal debug counter upper bound. @var{counter-value-list} +is a comma-separated list of @var{name}:@var{value} pairs +which sets the upper bound of each debug counter @var{name} to @var{value}. +All debug counters have the initial upper bound of @code{UINT_MAX}; +thus @code{dbg_cnt} returns true always unless the upper bound +is set by this option. +For example, with @option{-fdbg-cnt=dce:10,tail_call:0}, +@code{dbg_cnt(dce)} returns true only for first 10 invocations. -@item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} -@opindex fvisibility -Set the default ELF image symbol visibility to the specified option---all -symbols are marked with this unless overridden within the code. -Using this feature can very substantially improve linking and -load times of shared object libraries, produce more optimized -code, provide near-perfect API export and prevent symbol clashes. -It is @strong{strongly} recommended that you use this in any shared objects -you distribute. +@item -print-file-name=@var{library} +@opindex print-file-name +Print the full absolute name of the library file @var{library} that +would be used when linking---and don't do anything else. With this +option, GCC does not compile or link anything; it just prints the +file name. -Despite the nomenclature, @samp{default} always means public; i.e., -available to be linked against from outside the shared object. -@samp{protected} and @samp{internal} are pretty useless in real-world -usage so the only other commonly used option is @samp{hidden}. -The default if @option{-fvisibility} isn't specified is -@samp{default}, i.e., make every symbol public. +@item -print-multi-directory +@opindex print-multi-directory +Print the directory name corresponding to the multilib selected by any +other switches present in the command line. This directory is supposed +to exist in @env{GCC_EXEC_PREFIX}. -A good explanation of the benefits offered by ensuring ELF -symbols have the correct visibility is given by ``How To Write -Shared Libraries'' by Ulrich Drepper (which can be found at -@w{@uref{http://www.akkadia.org/drepper/}})---however a superior -solution made possible by this option to marking things hidden when -the default is public is to make the default hidden and mark things -public. This is the norm with DLLs on Windows and with @option{-fvisibility=hidden} -and @code{__attribute__ ((visibility("default")))} instead of -@code{__declspec(dllexport)} you get almost identical semantics with -identical syntax. This is a great boon to those working with -cross-platform projects. +@item -print-multi-lib +@opindex print-multi-lib +Print the mapping from multilib directory names to compiler switches +that enable them. The directory name is separated from the switches by +@samp{;}, and each switch starts with an @samp{@@} instead of the +@samp{-}, without spaces between multiple switches. This is supposed to +ease shell processing. -For those adding visibility support to existing code, you may find -@code{#pragma GCC visibility} of use. This works by you enclosing -the declarations you wish to set visibility for with (for example) -@code{#pragma GCC visibility push(hidden)} and -@code{#pragma GCC visibility pop}. -Bear in mind that symbol visibility should be viewed @strong{as -part of the API interface contract} and thus all new code should -always specify visibility when it is not the default; i.e., declarations -only for use within the local DSO should @strong{always} be marked explicitly -as hidden as so to avoid PLT indirection overheads---making this -abundantly clear also aids readability and self-documentation of the code. -Note that due to ISO C++ specification requirements, @code{operator new} and -@code{operator delete} must always be of default visibility. +@item -print-multi-os-directory +@opindex print-multi-os-directory +Print the path to OS libraries for the selected +multilib, relative to some @file{lib} subdirectory. If OS libraries are +present in the @file{lib} subdirectory and no multilibs are used, this is +usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}} +sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or +@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}} +subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}. -Be aware that headers from outside your project, in particular system -headers and headers from any other library you use, may not be -expecting to be compiled with visibility other than the default. You -may need to explicitly say @code{#pragma GCC visibility push(default)} -before including any such headers. +@item -print-multiarch +@opindex print-multiarch +Print the path to OS libraries for the selected multiarch, +relative to some @file{lib} subdirectory. -@code{extern} declarations are not affected by @option{-fvisibility}, so -a lot of code can be recompiled with @option{-fvisibility=hidden} with -no modifications. However, this means that calls to @code{extern} -functions with no explicit visibility use the PLT, so it is more -effective to use @code{__attribute ((visibility))} and/or -@code{#pragma GCC visibility} to tell the compiler which @code{extern} -declarations should be treated as hidden. +@item -print-prog-name=@var{program} +@opindex print-prog-name +Like @option{-print-file-name}, but searches for a program such as @command{cpp}. -Note that @option{-fvisibility} does affect C++ vague linkage -entities. This means that, for instance, an exception class that is -be thrown between DSOs must be explicitly marked with default -visibility so that the @samp{type_info} nodes are unified between -the DSOs. +@item -print-libgcc-file-name +@opindex print-libgcc-file-name +Same as @option{-print-file-name=libgcc.a}. -An overview of these techniques, their benefits and how to use them -is at @uref{http://gcc.gnu.org/@/wiki/@/Visibility}. +This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs} +but you do want to link with @file{libgcc.a}. You can do: -@item -fstrict-volatile-bitfields -@opindex fstrict-volatile-bitfields -This option should be used if accesses to volatile bit-fields (or other -structure fields, although the compiler usually honors those types -anyway) should use a single access of the width of the -field's type, aligned to a natural alignment if possible. For -example, targets with memory-mapped peripheral registers might require -all such accesses to be 16 bits wide; with this flag you can -declare all peripheral bit-fields as @code{unsigned short} (assuming short -is 16 bits on these targets) to force GCC to use 16-bit accesses -instead of, perhaps, a more efficient 32-bit access. +@smallexample +gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` +@end smallexample -If this option is disabled, the compiler uses the most efficient -instruction. In the previous example, that might be a 32-bit load -instruction, even though that accesses bytes that do not contain -any portion of the bit-field, or memory-mapped registers unrelated to -the one being updated. +@item -print-search-dirs +@opindex print-search-dirs +Print the name of the configured installation directory and a list of +program and library directories @command{gcc} searches---and don't do anything else. -In some cases, such as when the @code{packed} attribute is applied to a -structure field, it may not be possible to access the field with a single -read or write that is correctly aligned for the target machine. In this -case GCC falls back to generating multiple accesses rather than code that -will fault or truncate the result at run time. +This is useful when @command{gcc} prints the error message +@samp{installation problem, cannot exec cpp0: No such file or directory}. +To resolve this you either need to put @file{cpp0} and the other compiler +components where @command{gcc} expects to find them, or you can set the environment +variable @env{GCC_EXEC_PREFIX} to the directory where you installed them. +Don't forget the trailing @samp{/}. +@xref{Environment Variables}. -Note: Due to restrictions of the C/C++11 memory model, write accesses are -not allowed to touch non bit-field members. It is therefore recommended -to define all bits of the field's type as bit-field members. +@item -print-sysroot +@opindex print-sysroot +Print the target sysroot directory that is used during +compilation. This is the target sysroot specified either at configure +time or using the @option{--sysroot} option, possibly with an extra +suffix that depends on compilation options. If no target sysroot is +specified, the option prints nothing. -The default value of this option is determined by the application binary -interface for the target processor. +@item -print-sysroot-headers-suffix +@opindex print-sysroot-headers-suffix +Print the suffix added to the target sysroot when searching for +headers, or give an error if the compiler is not configured with such +a suffix---and don't do anything else. -@item -fsync-libcalls -@opindex fsync-libcalls -This option controls whether any out-of-line instance of the @code{__sync} -family of functions may be used to implement the C++11 @code{__atomic} -family of functions. +@item -dumpmachine +@opindex dumpmachine +Print the compiler's target machine (for example, +@samp{i686-pc-linux-gnu})---and don't do anything else. -The default value of this option is enabled, thus the only useful form -of the option is @option{-fno-sync-libcalls}. This option is used in -the implementation of the @file{libatomic} runtime library. +@item -dumpversion +@opindex dumpversion +Print the compiler version (for example, @code{3.0})---and don't do +anything else. +@item -dumpspecs +@opindex dumpspecs +Print the compiler's built-in specs---and don't do anything else. (This +is used when GCC itself is being built.) @xref{Spec Files}. @end table @node Submodel Options -- 2.30.2