diff options
Diffstat (limited to 'gcc/doc/invoke.texi')
| -rw-r--r-- | gcc/doc/invoke.texi | 605 |
1 files changed, 369 insertions, 236 deletions
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 79f57af8a7b..5bfef420cbc 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -183,7 +183,7 @@ in the following sections. -fno-nonansi-builtins -fno-operator-names @gol -fno-optional-diags -fpermissive @gol -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol --fuse-cxa-atexit -fvtable-gc -fno-weak -nostdinc++ @gol +-fuse-cxa-atexit -fno-weak -nostdinc++ @gol -fno-default-inline -Wabi -Wctor-dtor-privacy @gol -Wnon-virtual-dtor -Wreorder @gol -Weffc++ -Wno-deprecated @gol @@ -193,8 +193,14 @@ in the following sections. @item Objective-C Language Options @xref{Objective-C Dialect Options,,Options Controlling Objective-C Dialect}. -@gccoptlist{-fconstant-string-class=@var{class-name} @gol --fgnu-runtime -fnext-runtime -gen-decls @gol +@gccoptlist{ +-fconstant-string-class=@var{class-name} @gol +-fgnu-runtime -fnext-runtime @gol +-fno-nil-receivers @gol +-fobjc-exceptions @gol +-freplace-objc-classes @gol +-fzero-link @gol +-gen-decls @gol -Wno-protocol -Wselector -Wundeclared-selector} @item Language Independent Options @@ -208,19 +214,18 @@ in the following sections. -w -Wextra -Wall -Waggregate-return @gol -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol -Wconversion -Wno-deprecated-declarations @gol --Wdisabled-optimization -Wno-div-by-zero -Werror @gol +-Wdisabled-optimization -Wno-div-by-zero -Wendif-labels @gol +-Werror -Werror-implicit-function-declaration @gol -Wfloat-equal -Wformat -Wformat=2 @gol --Wformat-nonliteral -Wformat-security @gol --Wimplicit -Wimplicit-int @gol --Wimplicit-function-declaration @gol --Werror-implicit-function-declaration @gol --Wimport -Winline -Winvalid-pch -Wno-endif-labels @gol --Wno-invalid-offsetof @gol +-Wno-format-extra-args -Wformat-nonliteral @gol +-Wformat-security -Wno-format-y2k @gol +-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol +-Wimport -Wno-import -Winit-self -Winline @gol +-Wno-invalid-offsetof -Winvalid-pch @gol -Wlarger-than-@var{len} -Wlong-long @gol -Wmain -Wmissing-braces @gol -Wmissing-format-attribute -Wmissing-noreturn @gol --Wno-multichar -Wno-format-extra-args -Wno-format-y2k @gol --Wno-import -Wnonnull -Wpacked -Wpadded @gol +-Wno-multichar -Wnonnull -Wpacked -Wpadded @gol -Wparentheses -Wpointer-arith -Wredundant-decls @gol -Wreturn-type -Wsequence-point -Wshadow @gol -Wsign-compare -Wstrict-aliasing @gol @@ -232,8 +237,9 @@ in the following sections. @item C-only Warning Options @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol --Wmissing-prototypes -Wnested-externs @gol --Wstrict-prototypes -Wtraditional} +-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol +-Wstrict-prototypes -Wtraditional @gol +-Wdeclaration-after-statement} @item Debugging Options @xref{Debugging Options,,Options for Debugging Your Program or GCC}. @@ -279,7 +285,7 @@ in the following sections. -freduce-all-givs -fregmove -frename-registers @gol -freorder-blocks -freorder-functions @gol -frerun-cse-after-loop -frerun-loop-opt @gol --fschedule-insns -fschedule-insns2 @gol +-frounding-math -fschedule-insns -fschedule-insns2 @gol -fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol -fsched-spec-load-dangerous -fsched2-use-superblocks @gol -fsched2-use-traces -fsignaling-nans @gol @@ -300,7 +306,8 @@ in the following sections. -include @var{file} -imacros @var{file} @gol -iprefix @var{file} -iwithprefix @var{dir} @gol -iwithprefixbefore @var{dir} -isystem @var{dir} @gol --M -MM -MF -MG -MP -MQ -MT -nostdinc -P -remap @gol +-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol +-P -fworking-directory -remap @gol -trigraphs -undef -U@var{macro} -Wp,@var{option} @gol -Xpreprocessor @var{option}} @@ -350,7 +357,7 @@ in the following sections. -mapp-regs -mbroken-saverestore -mcypress @gol -mfaster-structs -mflat @gol -mfpu -mhard-float -mhard-quad-float @gol --mimpure-text -mlive-g0 -mno-app-regs @gol +-mimpure-text -mlittle-endian -mlive-g0 -mno-app-regs @gol -mno-faster-structs -mno-flat -mno-fpu @gol -mno-impure-text -mno-stack-bias -mno-unaligned-doubles @gol -msoft-float -msoft-quad-float -msparclite -mstack-bias @gol @@ -386,6 +393,7 @@ in the following sections. @emph{MN10300 Options} @gccoptlist{-mmult-bug -mno-mult-bug @gol -mam33 -mno-am33 @gol +-mam33-2 -mno-am33-2 @gol -mno-crt0 -mrelax} @emph{M32R/D Options} @@ -444,7 +452,7 @@ in the following sections. -force_flat_namespace -headerpad_max_install_names @gol -image_base -init -install_name -keep_private_externs @gol -multi_module -multiply_defined -multiply_defined_unused @gol --noall_load -nomultidefs -noprebind -noseglinkedit @gol +-noall_load -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol -pagezero_size -prebind -prebind_all_twolevel_modules @gol -private_bundle -read_only_relocs -sectalign @gol -sectobjectsymbols -whyload -seg1addr @gol @@ -468,7 +476,7 @@ in the following sections. -mgas -mgp32 -mgp64 -mhard-float -mint64 -mips1 @gol -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol -mlong64 -mlong32 -mlong-calls -mmemcpy @gol --mmips-as -mmips-tfile -mno-abicalls @gol +-mmips-as -mmips-tfile -mno-abicalls -mxgot @gol -mno-embedded-data -mno-uninit-const-in-rodata @gol -mno-embedded-pic -mno-long-calls @gol -mno-memcpy -mno-mips-tfile -mno-rnames @gol @@ -476,7 +484,8 @@ in the following sections. -m4650 -msingle-float -mmad @gol -EL -EB -G @var{num} -nocpp @gol -mabi=32 -mabi=n32 -mabi=64 -mabi=eabi -mabi-fake-default @gol --mfix7000 -mno-crt0 -mflush-func=@var{func} -mno-flush-func @gol +-mfix7000 -mfix-sb1 -mno-fix-sb1 @gol +-mno-crt0 -mflush-func=@var{func} -mno-flush-func @gol -mbranch-likely -mno-branch-likely} @emph{i386 and x86-64 Options} @@ -567,6 +576,7 @@ in the following sections. -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol -mapp-regs -mno-app-regs @gol -mdisable-callt -mno-disable-callt @gol +-mv850e1 @gol -mv850e @gol -mv850 -mbig-switch} @@ -632,19 +642,7 @@ in the following sections. @gccoptlist{-msim} @emph{Xtensa Options} -@gccoptlist{-mbig-endian -mlittle-endian @gol --mdensity -mno-density @gol --mconst16 -mno-const16 @gol --mabs -mno-abs @gol --maddx -mno-addx @gol --mmac16 -mno-mac16 @gol --mmul16 -mno-mul16 @gol --mmul32 -mno-mul32 @gol --mnsa -mno-nsa @gol --mminmax -mno-minmax @gol --msext -mno-sext @gol --mbooleans -mno-booleans @gol --mhard-float -msoft-float @gol +@gccoptlist{-mconst16 -mno-const16 @gol -mfused-madd -mno-fused-madd @gol -mtext-section-literals -mno-text-section-literals @gol -mtarget-align -mno-target-align @gol @@ -709,10 +707,12 @@ in the following sections. @section Options Controlling the Kind of Output Compilation can involve up to four stages: preprocessing, compilation -proper, assembly and linking, always in that order. The first three -stages apply to an individual source file, and end by producing an -object file; linking combines all the object files (those newly -compiled, and those specified as input) into an executable file. +proper, assembly and linking, always in that order. GCC is capable of +preprocessing and compiling several files either into several +assembler input files, or into one assembler input file; then each +assembler input file produces an object file, and linking combines all +the object files (those newly compiled, and those specified as input) +into an executable file. @cindex file name suffix For any given input file, the file name suffix determines what kind of @@ -884,9 +884,9 @@ Place output in file @var{file}. This applies regardless to whatever sort of output is being produced, whether it be an executable file, an object file, an assembler file or preprocessed C code. -Since only one output file can be specified, it does not make sense to -use @option{-o} when compiling more than one input file, unless you are -producing an executable file as output. +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 @@ -1413,10 +1413,9 @@ a name having multiple meanings within a class. @item -fpermissive @opindex fpermissive -Downgrade messages about nonconformant code from errors to warnings. By -default, G++ effectively sets @option{-pedantic-errors} without -@option{-pedantic}; this option reverses that. This behavior and this -option are superseded by @option{-pedantic}, which works as it does for GNU C@. +Downgrade some diagnostics about nonconformant code from errors to +warnings. Thus, using @option{-fpermissive} will allow some +nonconforming code to compile. @item -frepo @opindex frepo @@ -1453,17 +1452,6 @@ This option is required for fully standards-compliant handling of static destructors, but will only work if your C library supports @code{__cxa_atexit}. -@item -fvtable-gc -@opindex fvtable-gc -Emit special relocations for vtables and virtual function references -so that the linker can identify unused virtual functions and zero out -vtable slots that refer to them. This is most useful with -@option{-ffunction-sections} and @option{-Wl,--gc-sections}, in order to -also discard the functions themselves. - -This optimization requires GNU as and GNU ld. Not all systems support -this option. @option{-Wl,--gc-sections} is ignored without @option{-static}. - @item -fno-weak @opindex fno-weak Do not use weak symbol support, even if it is provided by the linker. @@ -1591,14 +1579,14 @@ Instantiations of these templates may be mangled incorrectly. @item -Wctor-dtor-privacy @r{(C++ only)} @opindex Wctor-dtor-privacy -Warn when a class seems unusable, because all the constructors or -destructors in a class are private and the class has no friends or +Warn when a class seems unusable because all the constructors or +destructors in that class are private, and it has neither friends nor public static member functions. @item -Wnon-virtual-dtor @r{(C++ only)} @opindex Wnon-virtual-dtor -Warn when a class declares a non-virtual destructor that should probably -be virtual, because it looks like the class will be used polymorphically. +Warn when a class appears to be polymorphic, thereby requiring a virtual +destructor, yet it declares a non-virtual one. This warning is enabled by @option{-Wall}. @item -Wreorder @r{(C++ only)} @@ -1616,9 +1604,9 @@ struct A @{ @}; @end smallexample -Here the compiler will warn that the member initializers for @samp{i} -and @samp{j} will be rearranged to match the declaration order of the -members. This warning is enabled by @option{-Wall}. +The compiler will rearrange the member initializers for @samp{i} +and @samp{j} to match the declaration order of the members, emitting +a warning to that effect. This warning is enabled by @option{-Wall}. @end table The following @option{-W@dots{}} options are not affected by @option{-Wall}. @@ -1648,8 +1636,8 @@ Item 23: Don't try to return a reference when you must return an object. @end itemize -and about violations of the following style guidelines from Scott Meyers' -@cite{More Effective C++} book: +Also warn about violations of the following style guidelines from +Scott Meyers' @cite{More Effective C++} book: @itemize @bullet @item @@ -1661,8 +1649,8 @@ Item 7: Never overload @code{&&}, @code{||}, or @code{,}. @end itemize -If you use this option, you should be aware that the standard library -headers do not obey all of these guidelines; you can use @samp{grep -v} +When selecting this option, be aware that the standard library +headers do not obey all of these guidelines; use @samp{grep -v} to filter out those warnings. @item -Wno-deprecated @r{(C++ only)} @@ -1672,7 +1660,7 @@ Do not warn about usage of deprecated features. @xref{Deprecated Features}. @item -Wno-non-template-friend @r{(C++ only)} @opindex Wno-non-template-friend Disable warnings when non-templatized friend functions are declared -within a template. With the advent of explicit template specification +within a template. Since the advent of explicit template specification support in G++, if the name of the friend is an unqualified-id (i.e., @samp{friend foo(int)}), the C++ language specification demands that the friend declare or define an ordinary, nontemplate function. (Section @@ -1680,7 +1668,7 @@ friend declare or define an ordinary, nontemplate function. (Section could be interpreted as a particular specialization of a templatized function. Because this non-conforming behavior is no longer the default behavior for G++, @option{-Wnon-template-friend} allows the compiler to -check existing code for potential trouble spots, and is on by default. +check existing code for potential trouble spots and is on by default. This new compiler behavior can be turned off with @option{-Wno-non-template-friend} which keeps the conformant compiler code but disables the helpful warning. @@ -1690,7 +1678,7 @@ but disables the helpful warning. Warn if an old-style (C-style) cast to a non-void type is used within a C++ program. The new-style casts (@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to -unintended effects, and much easier to grep for. +unintended effects and much easier to search for. @item -Woverloaded-virtual @r{(C++ only)} @opindex Woverloaded-virtual @@ -1710,7 +1698,7 @@ struct B: public A @{ @end smallexample the @code{A} class version of @code{f} is hidden in @code{B}, and code -like this: +like: @smallexample B* b; @@ -1727,7 +1715,7 @@ to a plain pointer. @item -Wsign-promo @r{(C++ only)} @opindex Wsign-promo Warn when overload resolution chooses a promotion from unsigned or -enumeral type to a signed type over a conversion to an unsigned type of +enumeral type to a signed type, over a conversion to an unsigned type of the same size. Previous versions of G++ would try to preserve unsignedness, but the standard mandates the current behavior. @@ -1761,8 +1749,11 @@ In this example, G++ will synthesize a default @samp{A& operator = @cindex compiler options, Objective-C @cindex Objective-C options, command line @cindex options, Objective-C +(NOTE: This manual does not describe the Objective-C language itself. See +@w{@uref{http://gcc.gnu.org/readings.html}} for references.) + This section describes the command-line options that are only meaningful -for Objective-C programs; but you can also use most of the GNU compiler +for Objective-C programs, but you can also use most of the GNU compiler options regardless of what language your program is in. For example, you might compile a file @code{some_class.m} like this: @@ -1771,7 +1762,7 @@ gcc -g -fgnu-runtime -O -c some_class.m @end example @noindent -In this example, only @option{-fgnu-runtime} is an option meant only for +In this example, @option{-fgnu-runtime} is an option meant only for Objective-C programs; you can use the other options with any language supported by GCC@. @@ -1783,7 +1774,11 @@ programs: @opindex fconstant-string-class Use @var{class-name} as the name of the class to instantiate for each literal string specified with the syntax @code{@@"@dots{}"}. The default -class name is @code{NXConstantString}. +class name is @code{NXConstantString} if the GNU runtime is being used, and +@code{NSConstantString} if the NeXT runtime is being used (see below). The +@option{-fconstant-cfstrings} option, if also present, will override the +@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals +to be laid out as constant CoreFoundation strings. @item -fgnu-runtime @opindex fgnu-runtime @@ -1797,6 +1792,117 @@ for NeXT-based systems, including Darwin and Mac OS X@. The macro @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is used. +@item -fno-nil-receivers +@opindex -fno-nil-receivers +Assume that all Objective-C message dispatches (e.g., +@code{[receiver message:arg]}) in this translation unit ensure that the receiver +is not @code{nil}. This allows for more efficient entry points in the runtime to be +used. Currently, this option is only available in conjunciton with +the NeXT runtime on Mac OS X 10.3 and later. + +@item -fobjc-exceptions +@opindex -fobjc-exceptions +Enable syntactic support for structured exception handling in Objective-C, +similar to what is offered by C++ and Java. Currently, this option is only +available in conjunciton with the NeXT runtime on Mac OS X 10.3 and later. + +@smallexample + @@try @{ + @dots{} + @@throw expr; + @dots{} + @} + @@catch (AnObjCClass *exc) @{ + @dots{} + @@throw expr; + @dots{} + @@throw; + @dots{} + @} + @@catch (AnotherClass *exc) @{ + @dots{} + @} + @@catch (id allOthers) @{ + @dots{} + @} + @@finally @{ + @dots{} + @@throw expr; + @dots{} + @} +@end smallexample + +The @code{@@throw} statement may appear anywhere in an Objective-C or +Objective-C++ program; when used inside of a @code{@@catch} block, the +@code{@@throw} may appear without an argument (as shown above), in which case +the object caught by the @code{@@catch} will be rethrown. + +Note that only (pointers to) Objective-C objects may be thrown and +caught using this scheme. When an object is thrown, it will be caught +by the nearest @code{@@catch} clause capable of handling objects of that type, +analogously to how @code{catch} blocks work in C++ and Java. A +@code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch +any and all Objective-C exceptions not caught by previous @code{@@catch} +clauses (if any). + +The @code{@@finally} clause, if present, will be executed upon exit from the +immediately preceding @code{@@try @dots{} @@catch} section. This will happen +regardless of whether any exceptions are thrown, caught or rethrown +inside the @code{@@try @dots{} @@catch} section, analogously to the behavior +of the @code{finally} clause in Java. + +There are several caveats to using the new exception mechanism: + +@itemize @bullet +@item +Although currently designed to be binary compatible with @code{NS_HANDLER}-style +idioms provided by the @code{NSException} class, the new +exceptions can only be used on Mac OS X 10.3 (Panther) and later +systems, due to additional functionality needed in the (NeXT) Objective-C +runtime. + +@item +As mentioned above, the new exceptions do not support handling +types other than Objective-C objects. Furthermore, when used from +Objective-C++, the Objective-C exception model does not interoperate with C++ +exceptions at this time. This means you cannot @code{@@throw} an exception +from Objective-C and @code{catch} it in C++, or vice versa +(i.e., @code{throw @dots{} @@catch}). +@end itemize + +The @option{-fobjc-exceptions} switch also enables the use of synchronization +blocks for thread-safe execution: + +@smallexample + @@synchronized (ObjCClass *lock) @{ + @dots{} + @} +@end smallexample + +Unlike Java, Objective-C does not allow for entire methods to be marked +@code{@@synchronized}. Note that throwing exceptions out of +@code{@@synchronized} blocks is allowed, and will cause the guarding object +to be unlocked properly. + +@item -freplace-objc-classes +@opindex -freplace-objc-classes +When compiling for the NeXT runtime, the compiler ordinarily replaces calls +to @code{objc_getClass("@dots{}")} (when the name of the class is known at +compile time) with static class references that get initialized at load time, +which improves run-time performance. Specifying the +@option{-freplace-objc-classes} flag suppresses this behavior and causes calls +to @code{objc_getClass("@dots{}")} to be retained. This is useful in +Fix-and-Continue debugging mode, since it allows for individual class +implementations to be modified during program execution. + +@item -fzero-link +@opindex -fzero-link +Emit a special marker instructing @command{ld(1)} not to statically link in +the resulting object file, and allow @command{dyld(1)} to load it in at +run time instead. This is used in conjunction with the Zero Link debugging +mode. Currently, this option is only available in conjunciton with +the NeXT runtime on Mac OS X 10.3 and later. + @item -gen-decls @opindex gen-decls Dump interface declarations for all classes seen in the source file to a @@ -1817,8 +1923,8 @@ and no warning is issued for them. Warn if multiple methods of different types for the same selector are found during compilation. The check is performed on the list of methods in the final stage of compilation. Additionally, a check is performed -that for each selector appearing in a @code{@@selector(@dots{})} -expression, a corresponding method with that selector has been found +for each selector appearing in a @code{@@selector(@dots{})} +expression, and a corresponding method for that selector has been found during compilation. Because these checks scan the method table only at the end of compilation, these warnings are not produced if the final stage of compilation is not reached, for example because an error is @@ -1829,13 +1935,13 @@ being used. @opindex Wundeclared-selector Warn if a @code{@@selector(@dots{})} expression referring to an undeclared selector is found. A selector is considered undeclared if no -method with that name has been declared (explicitly, in an -@code{@@interface} or @code{@@protocol} declaration, or implicitly, in -an @code{@@implementation} section) before the -@code{@@selector(@dots{})} expression. This option always performs its -checks as soon as a @code{@@selector(@dots{})} expression is found -(while @code{-Wselector} only performs its checks in the final stage of -compilation), and so additionally enforces the coding style convention +method with that name has been declared before the +@code{@@selector(@dots{})} expression, either explicitly in an +@code{@@interface} or @code{@@protocol} declaration, or implicitly in +an @code{@@implementation} section. This option always performs its +checks as soon as a @code{@@selector(@dots{})} expression is found, +while @code{-Wselector} only performs its checks in the final stage of +compilation. This also enforces the coding style convention that methods and selectors must be declared before being used. @c not documented because only avail via -Wp @@ -2062,6 +2168,24 @@ requiring a non-null value by the @code{nonnull} function attribute. @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It can be disabled with the @option{-Wno-nonnull} option. +@item -Winit-self @r{(C, C++, and Objective-C only)} +@opindex Winit-self +Enable warning about uninitialized variables which are initalized with themselves. +Note this option can only be used with the @option{-Wuninitialized} option and +that only works with @option{-O}. + +For an example, the following code will not warn about i being uninitialized +without this option: +@smallexample +@group +int f() +@{ + int i = i; + return i; +@} +@end group +@end smallexample + @item -Wimplicit-int @opindex Wimplicit-int Warn when a declaration does not specify a type. @@ -2272,6 +2396,9 @@ because they require data flow information that is computed only when optimizing. If you don't specify @option{-O}, you simply won't get these warnings. +If you want to warn about code which uses the uninitialized value of the +variable in its own initializer, use the @option{-Winit-self} option. + These warnings occur only for variables that are candidates for register allocation. Therefore, they do not occur for a variable that is declared @code{volatile}, or whose address is taken, or whose size @@ -2607,6 +2734,13 @@ because that feature is already a gcc extension and thus not relevant to traditional C compatibility. @end itemize +@item -Wdeclaration-after-statement @r{(C only)} +@opindex Wdeclaration-after-statement +Warn when a declaration is found after a statement in a block. This +construct, known from C++, was introduced with ISO C99 and is by default +allowed in GCC@. It is not supported by ISO C90 and was not supported by +GCC versions before GCC 3.0. @xref{Mixed Declarations}. + @item -Wundef @opindex Wundef Warn if an undefined identifier is evaluated in an @samp{#if} directive. @@ -2698,6 +2832,11 @@ argument types. (An old-style function definition is permitted without a warning if preceded by a declaration which specifies the argument types.) +@item -Wold-style-definition @r{(C only)} +@opindex Wold-style-definition +Warn if an old-style function definition is used. A warning is given +even if there is a previous prototype. + @item -Wmissing-prototypes @r{(C only)} @opindex Wmissing-prototypes Warn if a global function is defined without a previous prototype @@ -3039,14 +3178,14 @@ 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}.da} for each source file. The data may be used for +@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.da} for input file @file{dir/foo.c}, or -@file{dir/foo.da} for output file specified as @option{-o dir/foo.o}). +(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}). @itemize @@ -3076,7 +3215,7 @@ Control Optimization}). @item For test coverage analysis, use @command{gcov} to produce human readable -information from the @file{.bbg} and @file{.da} files. Refer to the +information from the @file{.gcno} and @file{.gcda} files. Refer to the @command{gcov} documentation for further information. @end itemize @@ -3092,10 +3231,10 @@ block must be created to hold the instrumentation code. @need 2000 @item -ftest-coverage @opindex ftest-coverage -Produce a graph file that the @command{gcov} code-coverage utility +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 data file is called -@file{@var{auxname}.bbg}. Refer to the @option{-fprofile-arcs} option +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 will match the source files more closely, if you do not optimize. @@ -3471,6 +3610,14 @@ 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. +The compiler performs optimisation 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 compiler to use information gained from all of the files when +compiling each of them. + Not all optimizations are controlled directly by a flag. Only optimizations that have a flag are listed. @@ -4230,8 +4377,8 @@ them to store all pertinent intermediate computations into variables. @item -ffast-math @opindex ffast-math Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @* -@option{-fno-trapping-math}, @option{-ffinite-math-only} and @* -@option{-fno-signaling-nans}. +@option{-fno-trapping-math}, @option{-ffinite-math-only}, +@option{-fno-rounding-math} and @option{-fno-signaling-nans}. This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. @@ -4295,6 +4442,26 @@ math functions. The default is @option{-ftrapping-math}. +@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. + +The default is @option{-fno-rounding-math}. + +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 -fsignaling-nans @opindex fsignaling-nans Compile code assuming that IEEE signaling NaNs may generate user-visible @@ -4331,7 +4498,7 @@ After running a program compiled with @option{-fprofile-arcs} @option{-fbranch-probabilities}, to improve optimizations based on the number of times each branch was taken. When the program compiled with @option{-fprofile-arcs} exits it saves arc execution -counts to a file called @file{@var{sourcename}.da} for each source +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. @@ -4348,6 +4515,10 @@ exactly determine which path is taken more often. If combined with @option{-fprofile-arcs}, it adds code so that some data about values of expressions in the program is gathered. +With @option{-fbranch-probabilities}, it reads back the data gathered +from profiling values of expressions and adds @samp{REG_VALUE_PROFILE} +notes to instructions for their later usage in optimizations. + @item -fnew-ra @opindex fnew-ra Use a graph coloring register allocator. Currently this option is meant @@ -4362,8 +4533,9 @@ 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. +Parse the whole compilation unit before starting to produce code. +This allows some extra optimizations to take place but consumes more +memory. @item -funroll-loops @opindex funroll-loops @@ -4535,7 +4707,7 @@ This number sets the maximum number of instructions (counted in gcc's internal representation) in a single function that the tree inliner will consider for inlining. This only affects functions declared inline and methods implemented in a class declaration (C++). -The default value is 100. +The default value is 500. @item max-inline-insns-auto When you use @option{-finline-functions} (included in @option{-O3}), @@ -4543,7 +4715,7 @@ a lot of functions that would otherwise not be considered for inlining by the compiler will be investigated. To those functions, a different (more restrictive) limit compared to functions declared inline can be applied. -The default value is 100. +The default value is 150. @item max-inline-insns The tree inliner does decrease the allowable size for single functions @@ -4561,6 +4733,7 @@ After exceeding the maximum number of inlined instructions by repeated inlining, a linear function is used to decrease the allowable size for single functions. The slope of that function is the negative reciprocal of the number specified here. +This parameter is ignored when @option{-funit-at-a-time} is used. The default value is 32. @item min-inline-insns @@ -4568,8 +4741,27 @@ The repeated inlining is throttled more and more by the linear function after exceeding the limit. To avoid too much throttling, a minimum for this function is specified here to allow repeated inlining for very small functions even when a lot of repeated inlining already has been done. +This parameter is ignored when @option{-funit-at-a-time} is used. The default value is 10. +@item large-function-insns +The limit specifying really large functions. For functions greater than this +limit inlining is constrained by @option{--param large-function-growth}. +This parameter is usefull primarily to avoid extreme compilation time caused by non-linear +algorithms used by the backend. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 30000. + +@item large-function-growth +Specifies maximal growth of large functtion caused by inlining in percents. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 200. + +@item inline-unit-growth +Specifies maximal overall growth of the compilation unit caused by inlining. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 150. + @item max-inline-insns-rtl For languages that use the RTL inliner (this happens at a later stage than tree inlining), you can set the maximum allowable size (counted @@ -4693,7 +4885,7 @@ collection to occur at every opportunity. @itemx reorder-blocks-duplicate-feedback Used by basic block reordering pass to decide whether to use unconditional -branch or duplicate the code on it's destination. Code is duplicated when it's +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. @@ -5044,7 +5236,7 @@ without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}). 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} was not specified, the driver tries two standard prefixes, which are -@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of +@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. @@ -5991,22 +6183,6 @@ this to work. Generate output containing quad-word (long double) floating point instructions. -@item -mimpure-text -@opindex mimpure-text -@option{-mimpure-text}, used in addition to @option{-shared}, tells -the compiler to not pass @option{-z text} to the linker when linking a -shared object. Using this option, you can link position-dependent -code into a shared object. - -@option{-mimpure-text} suppresses the ``relocations remain against -allocatable but non-writable sections'' linker error message. -However, the necessary relocations will trigger copy-on-write, and the -shared object is not actually shared across processes. Instead of -using @option{-mimpure-text}, you should compile all source code with -@option{-fpic} or @option{-fPIC}. - -This option is only available on SunOS and Solaris. - @item -msoft-quad-float @opindex msoft-quad-float Generate output containing library calls for quad-word (long double) @@ -6060,6 +6236,22 @@ ABI@. Thus, it's intended only for use on targets where the developer acknowledges that their resulting code will not be directly in line with the rules of the ABI@. +@item -mimpure-text +@opindex mimpure-text +@option{-mimpure-text}, used in addition to @option{-shared}, tells +the compiler to not pass @option{-z text} to the linker when linking a +shared object. Using this option, you can link position-dependent +code into a shared object. + +@option{-mimpure-text} suppresses the ``relocations remain against +allocatable but non-writable sections'' linker error message. +However, the necessary relocations will trigger copy-on-write, and the +shared object is not actually shared across processes. Instead of +using @option{-mimpure-text}, you should compile all source code with +@option{-fpic} or @option{-fPIC}. + +This option is only available on SunOS and Solaris. + @item -mv8 @itemx -msparclite @opindex mv8 @@ -6168,7 +6360,8 @@ on SPARC V9 processors in 64-bit environments. @table @gcctabopt @item -mlittle-endian @opindex mlittle-endian -Generate code for a processor running in little-endian mode. +Generate code for a processor running in little-endian mode. It is only +available for a few configurations and most notably not on Solaris. @item -m32 @itemx -m64 @@ -7591,6 +7784,7 @@ output file being linked. See man ld(1) for more information. @item -multiply_defined @item -multiply_defined_unused @item -noall_load +@item -nofixprebinding @item -nomultidefs @item -noprebind @item -noseglinkedit @@ -7647,6 +7841,7 @@ output file being linked. See man ld(1) for more information. @opindex multiply_defined @opindex multiply_defined_unused @opindex noall_load +@opindex nofixprebinding @opindex nomultidefs @opindex noprebind @opindex noseglinkedit @@ -7759,10 +7954,12 @@ The processor names are: @samp{4kc}, @samp{4kp}, @samp{5kc}, @samp{20kc}, @samp{m4k}, @samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400}, -@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000}, +@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000}, @samp{rm7000}, +@samp{rm9000}, @samp{orion}, @samp{sb1}, -@samp{vr4100}, @samp{vr4300}, and @samp{vr5000}. +@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @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, @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@. @@ -8009,6 +8206,35 @@ Emit (or do not emit) the pseudo operations @samp{.abicalls}, @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for position independent code. +@item -mxgot +@itemx -mno-xgot +@opindex mxgot +@opindex mno-xgot +Lift (or do not lift) the usual restrictions on the size of the global +offset table. + +GCC normally uses a single instruction to load values from the GOT. +While this is relatively efficient, it will only work if the GOT +is smaller than about 64k. Anything larger will cause the linker +to report an error such as: + +@cindex relocation truncated to fit (MIPS) +@smallexample +relocation truncated to fit: R_MIPS_GOT16 foobar +@end smallexample + +If this happens, you should recompile your code with @option{-mxgot}. +It should then work with very large GOTs, although it will also be +less efficient, since it will take three instructions to fetch the +value of a global symbol. + +Note that some linkers can create multiple GOTs. If you have such a +linker, you should only need to use @option{-mxgot} when a single object +file accesses more than 64k's worth of GOT entries. Very few do. + +These options have no effect unless GCC is generating position +independent code. + @item -mlong-calls @itemx -mno-long-calls @opindex mlong-calls @@ -8111,6 +8337,13 @@ Pass an option to gas which will cause nops to be inserted if the read of the destination register of an mfhi or mflo instruction occurs in the following two instructions. +@item -mfix-sb1 +@itemx -mno-fix-sb1 +@opindex mfix-sb1 +Work around certain SB-1 CPU core errata. +(This flag currently works around the SB-1 revision 2 +``F1'' and ``F2'' floating point errata.) + @item -no-crt0 @opindex no-crt0 Do not include the default crt0. @@ -9539,11 +9772,11 @@ option is on by default if you optimize. @itemx -mprolog-function @opindex mno-prolog-function @opindex mprolog-function -Do not use (do use) external functions to save and restore registers at -the prolog and epilog of a function. The external functions are slower, -but use less code space if more than one function saves the same number -of registers. The @option{-mprolog-function} option is on by default if -you optimize. +Do not use (do use) external functions to save and restore registers +at the prologue and epilogue of a function. The external functions +are slower, but use less code space if more than one function saves +the same number of registers. The @option{-mprolog-function} option +is on by default if you optimize. @item -mspace @opindex mspace @@ -9586,14 +9819,20 @@ the compiler. This setting is the default. @opindex mno-app-regs This option will cause r2 and r5 to be treated as fixed registers. +@item -mv850e1 +@opindex mv850e1 +Specify that the target processor is the V850E1. The preprocessor +constants @samp{__v850e1__} and @samp{__v850e__} will be defined if +this option is used. + @item -mv850e @opindex mv850e Specify that the target processor is the V850E. The preprocessor constant @samp{__v850e__} will be defined if this option is used. -If neither @option{-mv850} nor @option{-mv850e} are defined -then a default target processor will be chosen and the relevant -@samp{__v850*__} preprocessor constant will be defined. +If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1} +are defined then a default target processor will be chosen and the +relevant @samp{__v850*__} preprocessor constant will be defined. The preprocessor constants @samp{__v850} and @samp{__v851__} are always defined, regardless of which processor variant is the target. @@ -9601,7 +9840,7 @@ defined, regardless of which processor variant is the target. @item -mdisable-callt @opindex mdisable-callt This option will suppress generation of the CALLT instruction for the -v850e flavors of the v850 architecture. The default is +v850e and v850e1 flavors of the v850 architecture. The default is @option{-mno-disable-callt} which allows the CALLT instruction to be used. @end table @@ -10739,26 +10978,9 @@ Select the processor type for which to generate code. Possible values are @subsection Xtensa Options @cindex Xtensa Options -The Xtensa architecture is designed to support many different -configurations. The compiler's default options can be set to match a -particular Xtensa configuration by copying a configuration file into the -GCC sources when building GCC@. The options below may be used to -override the default options. +These options are supported for Xtensa targets: @table @gcctabopt -@item -mbig-endian -@itemx -mlittle-endian -@opindex mbig-endian -@opindex mlittle-endian -Specify big-endian or little-endian byte ordering for the target Xtensa -processor. - -@item -mdensity -@itemx -mno-density -@opindex mdensity -@opindex mno-density -Enable or disable use of the optional Xtensa code density instructions. - @item -mconst16 @itemx -mno-const16 @opindex mconst16 @@ -10770,95 +10992,6 @@ instructions are always used in place of the standard @code{L32R} instructions. The use of @code{CONST16} is enabled by default only if the @code{L32R} instruction is not available. -@item -mabs -@itemx -mno-abs -@opindex mabs -@opindex mno-abs -Enable or disable use of the Xtensa @code{ABS} instruction for absolute -value operations. - -@item -maddx -@itemx -mno-addx -@opindex maddx -@opindex mno-addx -Enable or disable use of the Xtensa @code{ADDX} and @code{SUBX} -instructions. - -@item -mmac16 -@itemx -mno-mac16 -@opindex mmac16 -@opindex mno-mac16 -Enable or disable use of the Xtensa MAC16 option. When enabled, GCC -will generate MAC16 instructions from standard C code, with the -limitation that it will use neither the MR register file nor any -instruction that operates on the MR registers. When this option is -disabled, GCC will translate 16-bit multiply/accumulate operations to a -combination of core instructions and library calls, depending on whether -any other multiplier options are enabled. - -@item -mmul16 -@itemx -mno-mul16 -@opindex mmul16 -@opindex mno-mul16 -Enable or disable use of the 16-bit integer multiplier option. When -enabled, the compiler will generate 16-bit multiply instructions for -multiplications of 16 bits or smaller in standard C code. When this -option is disabled, the compiler will either use 32-bit multiply or -MAC16 instructions if they are available or generate library calls to -perform the multiply operations using shifts and adds. - -@item -mmul32 -@itemx -mno-mul32 -@opindex mmul32 -@opindex mno-mul32 -Enable or disable use of the 32-bit integer multiplier option. When -enabled, the compiler will generate 32-bit multiply instructions for -multiplications of 32 bits or smaller in standard C code. When this -option is disabled, the compiler will generate library calls to perform -the multiply operations using either shifts and adds or 16-bit multiply -instructions if they are available. - -@item -mnsa -@itemx -mno-nsa -@opindex mnsa -@opindex mno-nsa -Enable or disable use of the optional normalization shift amount -(@code{NSA}) instructions to implement the built-in @code{ffs} function. - -@item -mminmax -@itemx -mno-minmax -@opindex mminmax -@opindex mno-minmax -Enable or disable use of the optional minimum and maximum value -instructions. - -@item -msext -@itemx -mno-sext -@opindex msext -@opindex mno-sext -Enable or disable use of the optional sign extend (@code{SEXT}) -instruction. - -@item -mbooleans -@itemx -mno-booleans -@opindex mbooleans -@opindex mno-booleans -Enable or disable support for the boolean register file used by Xtensa -coprocessors. This is not typically useful by itself but may be -required for other options that make use of the boolean registers (e.g., -the floating-point option). - -@item -mhard-float -@itemx -msoft-float -@opindex mhard-float -@opindex msoft-float -Enable or disable use of the floating-point option. When enabled, GCC -generates floating-point instructions for 32-bit @code{float} -operations. When this option is disabled, GCC generates library calls -to emulate 32-bit floating-point operations using integer instructions. -Regardless of this option, 64-bit @code{double} operations are always -emulated with calls to library functions. - @item -mfused-madd @itemx -mno-fused-madd @opindex mfused-madd @@ -11395,7 +11528,7 @@ If GCC cannot find the subprogram using the specified prefix, it tries looking in the usual places for the subprogram. The default value of @env{GCC_EXEC_PREFIX} is -@file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value +@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value of @code{prefix} when you ran the @file{configure} script. Other prefixes specified with @option{-B} take precedence over this prefix. @@ -11405,7 +11538,7 @@ used for linking. In addition, the prefix is used in an unusual way in finding the directories to search for header files. For each of the standard -directories whose name normally begins with @samp{/usr/local/lib/gcc-lib} +directories whose name normally begins with @samp{/usr/local/lib/gcc} (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries replacing that beginning with the specified prefix to produce an alternate directory name. Thus, with @option{-Bfoo/}, GCC will search |