@table @emph
@item Overall Options
@xref{Overall Options,,Options Controlling the Kind of Output}.
-@gccoptlist{-c -S -E -o @var{file} -pipe -pass-exit-codes @gol
+@gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
-x @var{language} -v -### --help --target-help --version}
@item C Language Options
-foptimize-sibling-calls -fprefetch-loop-arrays @gol
-fprofile-generate -fprofile-use @gol
-freduce-all-givs -fregmove -frename-registers @gol
--freorder-blocks -freorder-functions @gol
+-freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
-frerun-cse-after-loop -frerun-loop-opt @gol
-frounding-math -fschedule-insns -fschedule-insns2 @gol
-fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
@emph{ARM Options}
@gccoptlist{-mapcs-frame -mno-apcs-frame @gol
+-mabi=@var{name} @gol
-mapcs-26 -mapcs-32 @gol
-mapcs-stack-check -mno-apcs-stack-check @gol
-mapcs-float -mno-apcs-float @gol
@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
--mxgot -mno-xgot -membedded-pic -mno-embedded-pic @gol
--mgp32 -mgp64 -mfp32 -mfp64 -mhard-float -msoft-float @gol
--msingle-float -mdouble-float -mint64 -mlong64 -mlong32 @gol
+-mxgot -mno-xgot -mgp32 -mgp64 -mfp32 -mfp64 @gol
+-mhard-float -msoft-float -msingle-float -mdouble-float @gol
+-mint64 -mlong64 -mlong32 @gol
-G@var{num} -membedded-data -mno-embedded-data @gol
-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
-msplit-addresses -mno-split-addresses @gol
-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
-mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
--mfix-sb1 -mno-fix-sb1 @gol
+-mfix-vr4120 -mno-fix-vr4120 -mfix-sb1 -mno-fix-sb1 @gol
-mflush-func=@var{func} -mno-flush-func @gol
--mbranch-likely -mno-branch-likely}
+-mbranch-likely -mno-branch-likely @gol
+-mfp-exceptions -mno-fp-exceptions}
@emph{i386 and x86-64 Options}
@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
sort of output is being produced, whether it be an executable file,
an object file, an assembler file or preprocessed C code.
-If you specify @option{-o} when compiling more than one input file, or
-you are producing an executable file as output, all the source files
-on the command line will be compiled at once.
-
If @option{-o} is not specified, the default is to put an executable file
in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
@file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
the assembler is unable to read from a pipe; but the GNU assembler has
no trouble.
+@item -combine
+@opindex combine
+If you are compiling multiple source files, this option tells the driver
+to pass all the source files to the compiler at once (for those
+languages for which the compiler can handle this). This will allow
+intermodule analysis (IMA) to be performed by the compiler. Currently the only
+language for which this is supported is C. If you pass source files for
+multiple languages to the driver, using this option, the driver will invoke
+the compiler(s) that support IMA once each, passing each compiler all the
+source files appropriate for it. For those languages that do not support
+IMA this option will be ignored, and the compiler will be invoked once for
+each source file in that language. If you use this option in conjunction
+with -save-temps, the compiler will generate multiple pre-processed files
+(one for each source file), but only one (combined) .o or .s file.
+
@item --help
@opindex help
Print (on the standard output) a description of the command line options
and possibly the ability to debug the program.
The compiler performs optimization based on the knowledge it has of
-the program. Using the @option{-funit-at-a-time} flag will allow the
-compiler to consider information gained from later functions in the
-file when compiling a function. Compiling multiple files at once to a
-single output file (and using @option{-funit-at-a-time}) will allow
+the program. Optimization levels @option{-O2} and above, in
+particular, enable @emph{unit-at-a-time} mode, which allows the
+compiler to consider information gained from later functions in
+the file when compiling a function. Compiling multiple files at
+once to a single output file in @emph{unit-at-a-time} mode allows
the compiler to use information gained from all of the files when
compiling each of them.
@option{-Os} disables the following optimization flags:
@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
--falign-labels -freorder-blocks -fprefetch-loop-arrays}
+-falign-labels -freorder-blocks -freorder-blocks-and-partition -fprefetch-loop-arrays}
If you use multiple @option{-O} options, with or without level numbers,
the last such option is the one that is effective.
Enabled at levels @option{-O2}, @option{-O3}.
+@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 -freorder-functions
@opindex freorder-functions
Reorder basic blocks in the compiled function in order to reduce number of
taken branches and 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
+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.
Enabled at levels @option{-O2}, @option{-O3}.
-@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
-will most benefit processors with lots of registers. It can, however,
-make debugging impossible, since variables will no longer stay in
-a ``home register''.
+@item -funit-at-a-time
+@opindex funit-at-a-time
+Parse the whole compilation unit before starting to produce code.
+This allows some extra optimizations to take place but consumes
+more memory (in general). There are some compatibility issues
+with @emph{unit-at-at-time} mode:
+@itemize @bullet
+@item
+enabling @emph{unit-at-a-time} mode may change the order
+in which functions, variables, and top-level @code{asm} statements
+are emitted, and will likely break code relying on some particular
+ordering. The majority of such top-level @code{asm} statements,
+though, can be replaced by @code{section} attributes.
+
+@item
+@emph{unit-at-a-time} mode removes unreferenced static variables
+and functions are removed. This may result in undefined references
+when an @code{asm} statement refers directly to variables or functions
+that are otherwise unused. In that case either the variable/function
+shall be listed as an operand of the @code{asm} statement operand or,
+in the case of top-level @code{asm} statements the attribute @code{used}
+shall be used on the declaration.
+
+@item
+Static functions now can use non-standard passing conventions that
+may break @code{asm} statements calling functions directly. Again,
+attribute @code{used} will prevent this behavior.
+@end itemize
+
+As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
+but this scheme may not be supported by future releases of GCC.
+
+Enabled at levels @option{-O2}, @option{-O3}.
@item -fweb
@opindex fweb
however, make debugging impossible, since variables will no longer stay in a
``home register''.
-Enabled at levels @option{-O3}.
+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os},
+on targets where the default format for debugging information supports
+variable tracking.
@item -fno-cprop-registers
@opindex fno-cprop-registers
@item -fprofile-generate
@opindex fprofile-generate
-Enable options usually used for instrumenting application to produce profile usefull
-for later recompilation profile feedback based optimization.
-The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}
+Enable options usually used for instrumenting application to produce
+profile useful for later recompilation with profile feedback based
+optimization. You must use @code{-fprofile-generate} both when
+compiling and when linking your program.
+
+The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
@item -fprofile-use
@opindex fprofile-use
from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
notes to instructions for their later usage in optimizations.
+Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
+
@item -fvpt
@opindex fvpt
If combined with @option{-fprofile-arcs}, it instructs the compiler to add
Currently the optimizations include specialization of division operation
using the knowledge about the value of the denominator.
+Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
+
+@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
+will most benefit processors with lots of registers. Depending on the
+debug information format adopted by the target, however, it can
+make debugging impossible, since variables will no longer stay in
+a ``home register''.
+
+Not enabled by default at any level because it has known bugs.
+
@item -fnew-ra
@opindex fnew-ra
Use a graph coloring register allocator. Currently this option is meant
simplifies the control flow of the function allowing other optimizations to do
better job.
-@item -funit-at-a-time
-@opindex funit-at-a-time
-Parse the whole compilation unit before starting to produce code.
-This allows some extra optimizations to take place but consumes more
-memory.
+Enabled with @option{-fprofile-use}.
@item -funroll-loops
@opindex funroll-loops
(i.e. complete removal of loops with small constant number of iterations).
This option makes code larger, and may or may not make it run faster.
+Enabled with @option{-fprofile-use}.
+
@item -funroll-all-loops
@opindex funroll-all-loops
Unroll all loops, even if their number of iterations is uncertain when
roll much (from profile feedback). It also turns on complete loop peeling
(i.e. complete removal of loops with small constant number of iterations).
+Enabled with @option{-fprofile-use}.
+
@item -funswitch-loops
@opindex funswitch-loops
Move branches with loop invariant conditions out of the loop, with duplicates
@option{-fold-unroll-all-loops} implies the same options as
@option{-fold-unroll-loops}.
-@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 -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 -fprefetch-loop-arrays
@opindex fprefetch-loop-arrays
If supported by the target machine, generate instructions to prefetch
@item -fbtr-bb-exclusive
@opindex fbtr-bb-exclusive
-WHen performing branch target register load optimization, don't reuse
+When performing branch target register load optimization, don't reuse
branch target registers in within any basic block.
@item --param @var{name}=@var{value}
optimization will not be done.
@item max-gcse-passes
-The maximum number of passes of GCSE to run.
+The maximum number of passes of GCSE to run. The default is 1.
@item max-pending-list-length
The maximum number of pending dependencies scheduling will allow
@item max-cse-path-length
-Maximum number of basic blocks on path that cse considers.
+Maximum number of basic blocks on path that cse considers. The default is 10.
@item ggc-min-expand
architectures:
@table @gcctabopt
+@item -mabi=@var{name}
+@opindex mabi
+Generate code for the specified ABI. Permissible values are: @samp{apcs-gnu},
+@samp{atpcs}, @samp{aapcs} and @samp{iwmmxt}.
+
@item -mapcs-frame
@opindex mapcs-frame
Generate a stack frame that is compliant with the ARM Procedure Call
@item -mstructure-size-boundary=@var{n}
@opindex mstructure-size-boundary
The size of all structures and unions will be rounded up to a multiple
-of the number of bits set by this option. Permissible values are 8 and
-32. The default value varies for different toolchains. For the COFF
-targeted toolchain the default value is 8. Specifying the larger number
-can produce faster, more efficient code, but can also increase the size
-of the program. The two values are potentially incompatible. Code
-compiled with one value cannot necessarily expect to work with code or
-libraries compiled with the other value, if they exchange information
-using structures or unions.
+of the number of bits set by this option. Permissible values are 8, 32
+and 64. The default value varies for different toolchains. For the COFF
+targeted toolchain the default value is 8. A value of 64 is only allowed
+if the underlying ABI supports it.
+
+Specifying the larger number can produce faster, more efficient code, but
+can also increase the size of the program. Different values are potentially
+incompatible. Code compiled with one value cannot necessarily expect to
+work with code or libraries compiled with another value, if they exchange
+information using structures or unions.
@item -mabort-on-noreturn
@opindex mabort-on-noreturn
@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
@samp{860}, @samp{970}, @samp{common}, @samp{ec603e}, @samp{G3},
@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
-@samp{power4}, @samp{powerpc}, @samp{powerpc64}, @samp{rios},
-@samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64a}.
+@samp{power4}, @samp{power5}, @samp{powerpc}, @samp{powerpc64},
+@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64a}.
@option{-mcpu=common} selects a completely generic processor. Code
generated under this option will run on any POWER or PowerPC processor.
@samp{rm9000},
@samp{orion},
@samp{sb1},
-@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4300},
+@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
The special value @samp{from-abi} selects the
most compatible architecture for the selected ABI (that is,
generates 64-bit code when you select a 64-bit architecture, but you
can use @option{-mgp32} to get 32-bit code instead.
+For information about the O64 ABI, see
+@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
+
@item -mabicalls
@itemx -mno-abicalls
@opindex mabicalls
These options have no effect unless GCC is generating position
independent code.
-@item -membedded-pic
-@itemx -mno-embedded-pic
-@opindex membedded-pic
-@opindex mno-embedded-pic
-Generate (do not generate) position-independent code suitable for some
-embedded systems. All calls are made using PC relative addresses, and
-all data is addressed using the $gp register. No more than 65536
-bytes of global data may be used. This requires GNU as and GNU ld,
-which do most of the work.
-
@item -mgp32
@opindex mgp32
Assume that general-purpose registers are 32 bits wide.
immediately after starting an integer division.
@end itemize
+@item -mfix-vr4120
+@itemx -mno-fix-vr4120
+@opindex mfix-vr4120
+Work around certain VR4120 errata:
+@itemize @minus
+@item
+@code{dmultu} does not always produce the correct result.
+@item
+@code{div} and @code{ddiv} do not always produce the correct result if one
+of the operands is negative.
+@end itemize
+The workarounds for the division errata rely on special functions in
+@file{libgcc.a}. At present, these functions are only provided by
+the @code{mips64vr*-elf} configurations.
+
+Other VR4120 errata require a nop to be inserted between certain pairs of
+instructions. These errata are handled by the assembler, not by GCC itself.
+
@item -mfix-sb1
@itemx -mno-fix-sb1
@opindex mfix-sb1
and processors which implement those architectures; for those, Branch
Likely instructions will not be generated by default because the MIPS32
and MIPS64 architectures specifically deprecate their use.
+
+@item -mfp-exceptions
+@itemx -mno-fp-exceptions
+@opindex mfp-exceptions
+Specifies whether FP exceptions are enabled. This affects how we schedule
+FP instructions for some processors. The default is that FP exceptions are
+enabled.
+
+For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
+64-bit code, then we can use both FP pipes. Otherwise, we can only use one
+FP pipe.
@end table
@node i386 and x86-64 Options
`precompile' a header file; then, if builds can use the precompiled
header file they will be much faster.
+@strong{Caution:} There are a few known situations where GCC will
+crash when trying to use a precompiled header. If you have trouble
+with a precompiled header, you should remove the precompiled header
+and compile without it. In addition, please use GCC's on-line
+defect-tracking system to report any problems you encounter with
+precompiled headers. @xref{Bugs}.
+
To create a precompiled header file, simply compile it as you would any
other file, if necessary using the @option{-x} option to make the driver
treat it as a C or C++ header file. You will probably want to use a
If you need to precompile the same header file for different
languages, targets, or compiler options, you can instead make a
@emph{directory} named like @file{all.h.gch}, and put each precompiled
-header in the directory. (It doesn't matter what you call the files
-in the directory, every precompiled header in the directory will be
-considered.) The first precompiled header encountered in the
-directory that is valid for this compilation will be used; they're
-searched in no particular order.
+header in the directory, perhaps using @option{-o}. It doesn't matter
+what you call the files in the directory, every precompiled header in
+the directory will be considered. The first precompiled header
+encountered in the directory that is valid for this compilation will
+be used; they're searched in no particular order.
There are many other possibilities, limited only by your imagination,
good sense, and the constraints of your build system.
@itemize
@item
Only one precompiled header can be used in a particular compilation.
+
@item
A precompiled header can't be used once the first C token is seen. You
can have preprocessor directives before a precompiled header; you can
even include a precompiled header from inside another header, so long as
there are no C tokens before the @code{#include}.
+
@item
The precompiled header file must be produced for the same language as
the current compilation. You can't use a C precompiled header for a C++
compilation.
+
@item
The precompiled header file must be produced by the same compiler
version and configuration as the current compilation is using.
The easiest way to guarantee this is to use the same compiler binary
for creating and using precompiled headers.
+
@item
-Any macros defined before the precompiled header (including with
-@option{-D}) must either be defined in the same way as when the
-precompiled header was generated, or must not affect the precompiled
-header, which usually means that the they don't appear in the
-precompiled header at all.
+Any macros defined before the precompiled header is included must
+either be defined in the same way as when the precompiled header was
+generated, or must not affect the precompiled header, which usually
+means that the they don't appear in the precompiled header at all.
+
+The @option{-D} option is one way to define a macro before a
+precompiled header is included; using a @code{#define} can also do it.
+There are also some options that define macros implicitly, like
+@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
+defined this way.
+
+@item If debugging information is output when using the precompiled
+header, using @option{-g} or similar, the same kind of debugging information
+must have been output when building the precompiled header. However,
+a precompiled header built using @option{-g} can be used in a compilation
+when no debugging information is being output.
+
+@item The same @option{-m} options must generally be used when building
+and using the precompiled header. @xref{Submodel Options},
+for any cases where this rule is relaxed.
+
+@item Each of the following options must be the same when building and using
+the precompiled header:
+
+@gccoptlist{-fexceptions -funit-at-a-time}
+
@item
-Certain command-line options must be defined in the same way as when the
-precompiled header was generated. At present, it's not clear which
-options are safe to change and which are not; the safest choice is to
-use exactly the same options when generating and using the precompiled
-header.
+Some other command-line options starting with @option{-f},
+@option{-p}, or @option{-O} must be defined in the same way as when
+the precompiled header was generated. At present, it's not clear
+which options are safe to change and which are not; the safest choice
+is to use exactly the same options when generating and using the
+precompiled header. The following are known to be safe:
+
+@gccoptlist{-pedantic-errors}
+
@end itemize
-For all of these but the last, the compiler will automatically ignore
-the precompiled header if the conditions aren't met. For the last item,
-some option changes will cause the precompiled header to be rejected,
-but not all incompatible option combinations have yet been found. If
-you find a new incompatible combination, please consider filing a bug
-report, see @ref{Bugs}.
+For all of these except the last, the compiler will automatically
+ignore the precompiled header if the conditions aren't met. If you
+find an option combination that doesn't work and doesn't cause the
+precompiled header to be ignored, please consider filing a bug report,
+see @ref{Bugs}.
@node Running Protoize
@section Running Protoize