diff options
Diffstat (limited to 'gcc/doc/invoke.texi')
| -rw-r--r-- | gcc/doc/invoke.texi | 722 |
1 files changed, 276 insertions, 446 deletions
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 760c1952018..0b527b2598f 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -157,7 +157,7 @@ in the following sections. @xref{Overall Options,,Options Controlling the Kind of Output}. @gccoptlist{ -c -S -E -o @var{file} -pipe -pass-exit-codes -x @var{language} @gol --v --target-help --help} +-v -### --help --target-help --version} @item C Language Options @xref{C Dialect Options,,Options Controlling C Dialect}. @@ -165,11 +165,11 @@ in the following sections. -ansi -std=@var{standard} -aux-info @var{filename} @gol -fno-asm -fno-builtin -fno-builtin-@var{function} @gol -fhosted -ffreestanding @gol --trigraphs -traditional -traditional-cpp @gol +-trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol -fallow-single-precision -fcond-mismatch @gol -fsigned-bitfields -fsigned-char @gol -funsigned-bitfields -funsigned-char @gol --fwritable-strings -fshort-wchar} +-fwritable-strings} @item C++ Language Options @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. @@ -187,7 +187,7 @@ in the following sections. -fno-optional-diags -fpermissive @gol -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol -fuse-cxa-atexit -fvtable-gc -fno-weak -nostdinc++ @gol --fno-default-inline -Wctor-dtor-privacy @gol +-fno-default-inline -Wabi -Wctor-dtor-privacy @gol -Wnon-virtual-dtor -Wreorder @gol -Weffc++ -Wno-deprecated @gol -Wno-non-template-friend -Wold-style-cast @gol @@ -211,7 +211,7 @@ in the following sections. @xref{Warning Options,,Options to Request or Suppress Warnings}. @gccoptlist{ -fsyntax-only -pedantic -pedantic-errors @gol --w -W -Wall -Waggregate-return @gol +-w -W -Wall -Waggregate-return @gol -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol -Wconversion -Wno-deprecated-declarations @gol -Wdisabled-optimization -Wdiv-by-zero -Werror @gol @@ -222,7 +222,7 @@ in the following sections. -Werror-implicit-function-declaration @gol -Wimport -Winline @gol -Wlarger-than-@var{len} -Wlong-long @gol --Wmain -Wmissing-braces -Wmissing-declarations @gol +-Wmain -Wmissing-braces @gol -Wmissing-format-attribute -Wmissing-noreturn @gol -Wmultichar -Wno-format-extra-args -Wno-format-y2k @gol -Wno-import -Wpacked -Wpadded @gol @@ -236,7 +236,8 @@ in the following sections. @item C-only Warning Options @gccoptlist{ --Wbad-function-cast -Wmissing-prototypes -Wnested-externs @gol +-Wbad-function-cast -Wmissing-declarations @gol +-Wmissing-prototypes -Wnested-externs @gol -Wstrict-prototypes -Wtraditional} @item Debugging Options @@ -248,7 +249,8 @@ in the following sections. -fdump-tree-original@r{[}-@var{n}@r{]} -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol -fmem-report -fpretend-float @gol --fprofile-arcs -ftest-coverage -ftime-report @gol +-fprofile-arcs -fsched-verbose=@var{n} @gol +-ftest-coverage -ftime-report @gol -g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2 @gol -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol @@ -261,6 +263,7 @@ in the following sections. @gccoptlist{ -falign-functions=@var{n} -falign-jumps=@var{n} @gol -falign-labels=@var{n} -falign-loops=@var{n} @gol +-fbounds-check @gol -fbranch-probabilities -fcaller-saves -fcprop-registers @gol -fcse-follow-jumps -fcse-skip-blocks -fdata-sections @gol -fdelayed-branch -fdelete-null-pointer-checks @gol @@ -269,7 +272,8 @@ in the following sections. -fgcse -fgcse-lm -fgcse-sm @gol -finline-functions -finline-limit=@var{n} -fkeep-inline-functions @gol -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol --fmove-all-movables -fno-default-inline -fno-defer-pop @gol +-fmove-all-movables -fno-branch-count-reg @gol +-fno-default-inline -fno-defer-pop @gol -fno-function-cse -fno-guess-branch-probability @gol -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol -funsafe-math-optimizations -fno-trapping-math @gol @@ -278,9 +282,11 @@ in the following sections. -freduce-all-givs -fregmove -frename-registers @gol -frerun-cse-after-loop -frerun-loop-opt @gol -fschedule-insns -fschedule-insns2 @gol +-fno-sched-interblock -fno-sched-spec @gol +-fsched-spec-load -fsched-spec-load-dangerous @gol -fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol --fstrength-reduce -fstrict-aliasing -fthread-jumps -ftrapv @gol --funroll-all-loops -funroll-loops @gol +-fstrength-reduce -fstrict-aliasing -fthread-jumps @gol +-ftrapv -funroll-all-loops -funroll-loops @gol --param @var{name}=@var{value} -O -O0 -O1 -O2 -O3 -Os} @@ -348,10 +354,10 @@ in the following sections. -mcmodel=@var{code-model} @gol -m32 -m64 @gol -mapp-regs -mbroken-saverestore -mcypress @gol --mepilogue -mfaster-structs -mflat @gol +-mfaster-structs -mflat @gol -mfpu -mhard-float -mhard-quad-float @gol -mimpure-text -mlive-g0 -mno-app-regs @gol --mno-epilogue -mno-faster-structs -mno-flat -mno-fpu @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 -msupersparc -munaligned-doubles -mv8} @@ -444,8 +450,8 @@ in the following sections. -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol -mcall-aix -mcall-sysv -mcall-netbsd @gol --maix-struct-return -msvr4-struct-return --mabi=altivec @gol +-maix-struct-return -msvr4-struct-return @gol +-mabi=altivec -mabi=no-altivec @gol -mprototype -mno-prototype @gol -msim -mmvme -mads -myellowknife -memb -msdata @gol -msdata=@var{opt} -mvxworks -G @var{num} -pthread} @@ -481,11 +487,12 @@ in the following sections. -mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol -mno-wide-multiply -mrtd -malign-double @gol -mpreferred-stack-boundary=@var{num} @gol --mmmx -msse -msse2 -msse-math -m3dnow @gol +-mmmx -msse -msse2 -m3dnow @gol -mthreads -mno-align-stringops -minline-all-stringops @gol -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol -m96bit-long-double -mregparm=@var{num} -momit-leaf-frame-pointer @gol -mno-red-zone@gol +-mcmodel=@var{code-model} @gol -m32 -m64} @emph{HPPA Options} @@ -609,8 +616,8 @@ in the following sections. @emph{D30V Options} @gccoptlist{ --mextmem -mextmemory -monchip -mno-asm-optimize -masm-optimize @gol --mbranch-cost=@var{n} -mcond-exec=@var{n}} +-mextmem -mextmemory -monchip -mno-asm-optimize @gol +-masm-optimize -mbranch-cost=@var{n} -mcond-exec=@var{n}} @emph{S/390 and zSeries Options} @gccoptlist{ @@ -669,7 +676,7 @@ in the following sections. -fno-common -fno-ident -fno-gnu-linker @gol -fpcc-struct-return -fpic -fPIC @gol -freg-struct-return -fshared-data -fshort-enums @gol --fshort-double -fvolatile @gol +-fshort-double -fshort-wchar -fvolatile @gol -fvolatile-global -fvolatile-static @gol -fverbose-asm -fpack-struct -fstack-check @gol -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol @@ -783,10 +790,6 @@ package body). Such files are also called @dfn{bodies}. @c @var{file}.p @c @var{file}.pas -@item @var{file}.ch -@itemx @var{file}.chi -CHILL source code (preprocessed with the traditional preprocessor). - @item @var{file}.s Assembler code. @@ -813,7 +816,6 @@ c++ c++-cpp-output objective-c objc-cpp-output assembler assembler-with-cpp ada -chill f77 f77-cpp-input ratfor java @end example @@ -892,6 +894,12 @@ Print (on standard error output) the commands executed to run the stages of compilation. Also print the version number of the compiler driver program and of the preprocessor and the compiler proper. +@item -### +@opindex ### +Like @option{-v} except the commands are not executed and all command +arguments are quoted. This is useful for shell scripts to capture the +driver-generated command lines. + @item -pipe @opindex pipe Use pipes rather than temporary files for communication between the @@ -913,6 +921,10 @@ be displayed. @opindex target-help Print (on the standard output) a description of target specific command line options for each tool. + +@item --version +@opindex version +Display the version number and copyrights of the invoked GCC. @end table @node Invoking G++ @@ -1017,7 +1029,7 @@ ISO C89 as modified in amendment 1. @itemx iso9899:1999 @itemx iso9899:199x ISO C99. Note that this standard is not yet fully supported; see -@w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The +@w{@uref{http://gcc.gnu.org/gcc-3.1/c99status.html}} for more information. The names @samp{c9x} and @samp{iso9899:199x} are deprecated. @item gnu89 @@ -1141,6 +1153,16 @@ freestanding and hosted environments. Support ISO C trigraphs. The @option{-ansi} option (and @option{-std} options for strict ISO C conformance) implies @option{-trigraphs}. +@item -no-integrated-cpp +@opindex no-integrated-cpp +Invoke the external cpp during compilation. The default is to use the +integrated cpp (internal cpp). This option also allows a +user-supplied cpp via the @option{-B} option. This flag is applicable +in both C and C++ modes. + +We do not guarantee to retain this option in future, and we may change +its semantics. + @cindex traditional C language @cindex C language, traditional @item -traditional @@ -1285,12 +1307,6 @@ than double precision. If you must use @option{-traditional}, but want to use single precision operations when the operands are single precision, use this option. This option has no effect when compiling with ISO or GNU C conventions (the default). - -@item -fshort-wchar -@opindex fshort-wchar -Override the underlying type for @samp{wchar_t} to be @samp{short -unsigned int} instead of the default for the target. This option is -useful for building programs to run under WINE@. @end table @node C++ Dialect Options @@ -1539,6 +1555,58 @@ Do not assume @samp{inline} for functions defined inside a class scope. functions will have linkage like inline functions; they just won't be inlined by default. +@item -Wabi @r{(C++ only)} +@opindex Wabi +Warn when G++ generates code that is probably not compatible with the +vendor-neutral C++ ABI. Although an effort has been made to warn about +all such cases, there are probably some cases that are not warned about, +even though G++ is generating incompatible code. There may also be +cases where warnings are emitted even though the code that is generated +will be compatible. + +You should rewrite your code to avoid these warnings if you are +concerned about the fact that code generated by G++ may not be binary +compatible with code generated by other compilers. + +The known incompatibilites at this point include: + +@itemize @bullet + +@item +Incorrect handling of tail-padding for bit-fields. G++ may attempt to +pack data into the same byte as a base class. For example: + +@smallexample +struct A @{ virtual void f(); int f1 : 1; @}; +struct B : public A @{ int f2 : 1; @}; +@end smallexample + +@noindent +In this case, G++ will place @code{B::f2} into the same byte +as@code{A::f1}; other compilers will not. You can avoid this problem +by explicitly padding @code{A} so that its size is a multiple of the +byte size on your platform; that will cause G++ and other compilers to +layout @code{B} identically. + +@item +Incorrect handling of tail-padding for virtual bases. G++ does not use +tail padding when laying out virtual bases. For example: + +@smallexample +struct A @{ virtual void f(); char c1; @}; +struct B @{ B(); char c2; @}; +struct C : public A, public virtual B @{@}; +@end smallexample + +@noindent +In this case, G++ will not place @code{B} into the tail-padding for +@code{A}; other compilers will. You can avoid this problem by +explicitly padding @code{A} so that its size is a multiple of its +alignment (ignoring virtual base classes); that will cause G++ and other +compilers to layout @code{C} identically. + +@end itemize + @item -Wctor-dtor-privacy @r{(C++ only)} @opindex Wctor-dtor-privacy Warn when a class seems unusable, because all the constructors or @@ -1821,7 +1889,9 @@ negative form beginning @samp{-Wno-} to turn off warnings; for example, @option{-Wno-implicit}. This manual lists only one of the two forms, whichever is not the default. -These options control the amount and kinds of warnings produced by GCC: +The following options control the amount and kinds of warnings produced +by GCC; for further, language-specific options also refer to +@ref{C++ Dialect Options} and @ref{Objective-C Dialect Options}. @table @gcctabopt @cindex syntax checking @@ -2783,8 +2853,6 @@ supported). This is the format used by DEBUG on VMS systems. @itemx -gstabs@var{level} @itemx -gcoff@var{level} @itemx -gxcoff@var{level} -@itemx -gdwarf@var{level} -@itemx -gdwarf-2@var{level} @itemx -gvms@var{level} Request debugging information and also use @var{level} to specify how much information. The default level is 2. @@ -2798,6 +2866,11 @@ Level 3 includes extra information, such as all the macro definitions present in the program. Some debuggers support macro expansion when you use @option{-g3}. +Note that in order to avoid confusion between DWARF1 debug level 2, +and DWARF2, neither @option{-gdwarf} nor @option{-gdwarf-2} accept +a concatenated debug level. Instead use an additional @option{-g@var{level}} +option to change the debug level for DWARF1 or DWARF2. + @cindex @code{prof} @item -p @opindex p @@ -2860,18 +2933,7 @@ optimization and code generation options plus Control Optimization}). The other use of @option{-fprofile-arcs} is for use with @code{gcov}, -when it is used with the @option{-ftest-coverage} option. GCC -supports two methods of determining code coverage: the options that -support @code{gcov}, and options @option{-a} and @option{-ax}, which -write information to text files. The options that support @code{gcov} -do not need to instrument every arc in the program, so a program compiled -with them runs faster than a program compiled with @option{-a}, which -adds instrumentation code to every basic block in the program. The -tradeoff: since @code{gcov} does not have execution counts for all -branches, it must start with the execution counts for the instrumented -branches, and then iterate over the program flow graph until the entire -graph has been solved. Hence, @code{gcov} runs a little more slowly than -a program which uses information from @option{-a} and @option{-ax}. +when it is used with the @option{-ftest-coverage} option. With @option{-fprofile-arcs}, for each function of your program GCC creates a program flow graph, then finds a spanning tree for the graph. @@ -2881,11 +2943,6 @@ 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. -This option makes it possible to estimate branch probabilities and to -calculate basic block execution counts. In general, basic block -execution counts as provided by @option{-a} do not give enough -information to estimate all branch probabilities. - @need 2000 @item -ftest-coverage @opindex ftest-coverage @@ -3117,6 +3174,23 @@ Dump after all tree based optimization, to @file{@var{file}.optimized}. Dump after function inlining, to @file{@var{file}.inlined}. @end table +@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. This information is +written to standard error, unless @option{-dS} or @option{-dR} is +specified, in which case it is output to the usual dump +listing file, @file{.sched} or @file{.sched2} respectively. However +for @var{n} greater than nine, the output is always printed to standard +error. + +For @var{n} greater than zero, @option{-fsched-verbose} outputs the +same information as @option{-dRS}. 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 -fpretend-float @opindex fpretend-float When running a cross-compiler, pretend that the target machine uses the @@ -3421,6 +3495,14 @@ types. Languages like C or C++ require each non-automatic variable to have distinct location, so using this option will result in non-conforming behavior. +@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 -fno-function-cse @opindex fno-function-cse Do not put function addresses in registers; make each instruction that @@ -3483,6 +3565,14 @@ an exact implementation of IEEE or ISO rules/specifications for math functions. The default is @option{-ftrapping-math}. + +@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 +currenly only supported by the Java and Fortran 77 front-ends, where +this option defaults to true and false respectively. + @end table The following options control specific optimizations. The @option{-O2} @@ -3610,6 +3700,30 @@ 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 -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. + +@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-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 -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. + @item -ffunction-sections @itemx -fdata-sections @opindex ffunction-sections @@ -3933,339 +4047,18 @@ Some of these options make sense only together with @option{-E} because they cause the preprocessor output to be unsuitable for actual compilation. -@table @gcctabopt -@item -include @var{file} -@opindex include -Process @var{file} as input before processing the regular input file. -In effect, the contents of @var{file} are compiled first. Any @option{-D} -and @option{-U} options on the command line are always processed before -@option{-include @var{file}}, regardless of the order in which they are -written. All the @option{-include} and @option{-imacros} options are -processed in the order in which they are written. - -@item -imacros @var{file} -@opindex imacros -Process @var{file} as input, discarding the resulting output, before -processing the regular input file. Because the output generated from -@var{file} is discarded, the only effect of @option{-imacros @var{file}} -is to make the macros defined in @var{file} available for use in the -main input. All the @option{-include} and @option{-imacros} options are -processed in the order in which they are written. - -@item -idirafter @var{dir} -@opindex idirafter -@cindex second include path -Add the directory @var{dir} to the second include path. The directories -on the second include path are searched when a header file is not found -in any of the directories in the main include path (the one that -@option{-I} adds to). - -@item -iprefix @var{prefix} -@opindex iprefix -Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix} -options. - -@item -iwithprefix @var{dir} -@opindex iwithprefix -Add a directory to the second include path. The directory's name is -made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was -specified previously with @option{-iprefix}. If you have not specified a -prefix yet, the directory containing the installed passes of the -compiler is used as the default. - -@item -iwithprefixbefore @var{dir} -@opindex iwithprefixbefore -Add a directory to the main include path. The directory's name is made -by concatenating @var{prefix} and @var{dir}, as in the case of -@option{-iwithprefix}. - -@item -isystem @var{dir} -@opindex isystem -Add a directory to the beginning of the second include path, marking it -as a system directory, so that it gets the same special treatment as -is applied to the standard system directories. - -@item -nostdinc -@opindex nostdinc -Do not search the standard system directories for header files. Only -the directories you have specified with @option{-I} options (and the -current directory, if appropriate) are searched. @xref{Directory -Options}, for information on @option{-I}. - -By using both @option{-nostdinc} and @option{-I-}, you can limit the include-file -search path to only those directories you specify explicitly. - -@item -remap -@opindex remap -When searching for a header file in a directory, remap file names if a -file named @file{header.gcc} exists in that directory. This can be used -to work around limitations of file systems with file name restrictions. -The @file{header.gcc} file should contain a series of lines with two -tokens on each line: the first token is the name to map, and the second -token is the actual name to use. - -@item -undef -@opindex undef -Do not predefine any nonstandard macros. (Including architecture flags). - -@item -E -@opindex E -Run only the C preprocessor. Preprocess all the C source files -specified and output the results to standard output or to the -specified output file. - -@item -C -@opindex C -Tell the preprocessor not to discard comments. Used with the -@option{-E} option. - -@item -P -@opindex P -Tell the preprocessor not to generate @samp{#line} directives. -Used with the @option{-E} option. - -@cindex make -@cindex dependencies, make -@item -M -@opindex M -Instead of outputting the result of preprocessing, output a rule -suitable for @command{make} describing the dependencies of the main -source file. The preprocessor outputs one @command{make} rule containing -the object file name for that source file, a colon, and the names of all -the included files, including those coming from @option{-include} or -@option{-imacros} command line options. - -Unless specified explicitly (with @option{-MT} or @option{-MQ}), the -object file name consists of the basename of the source file with any -suffix replaced with object file suffix. If there are many included -files then the rule is split into several lines using @samp{\}-newline. -The rule has no commands. - -Passing @option{-M} to the driver implies @option{-E}. - -@item -MM -@opindex MM -Like @option{-M} but do not mention header files that are found in -system header directories, nor header files that are included, -directly or indirectly, from such a header. - -This implies that the choice of angle brackets or double quotes in an -@samp{#include} directive does not in itself determine whether that -header will appear in @option{-MM} dependency output. This is a -slight change in semantics from GCC versions 3.0 and earlier. - -@item -MD -@opindex MD -@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that -@option{-E} is not implied. The driver determines @var{file} based on -whether an @option{-o} option is given. If it is, the driver uses its -argument but with a suffix of @file{.d}, otherwise it take the -basename of the input file and applies a @file{.d} suffix. - -If @option{-MD} is used in conjunction with @option{-E}, any -@option{-o} switch is understood to specify the dependency output file -(but @pxref{-MF}), but if used without @option{-E}, each @option{-o} -is understood to specify a target object file. - -Since @option{-E} is not implied, @option{-MD} can be used to generate -a dependency output file as a side-effect of the compilation process. - -With Mach, you can use the utility @code{md} to merge multiple -dependency files into a single dependency file suitable for using with -the @samp{make} command. - -@item -MMD -@opindex MMD -Like @option{-MD} except mention only user header files, not system --header files. - -@item -MF @var{file} -@opindex MF -@anchor{-MF} -When used with @option{-M} or @option{-MM}, specifies a -file to write the dependencies to. If no @option{-MF} switch is given -the preprocessor sends the rules to the same place it would have sent -preprocessed output. - -When used with the driver options @option{-MD} or @option{-MMD}, -@option{-MF} overrides the default dependency output file. - -Another way to specify output of a @code{make} rule is by setting -the environment variable @env{DEPENDENCIES_OUTPUT} (@pxref{Environment -Variables}). - -@item -MG -@opindex MG -When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing -header files as generated files and assume they live in the same -directory as the source file. It suppresses preprocessed output, as a -missing header file is ordinarily an error. - -This feature is used in automatic updating of makefiles. - -@item -MP -@opindex MP -This option instructs CPP to add a phony target for each dependency -other than the main file, causing each to depend on nothing. These -dummy rules work around errors @code{make} gives if you remove header -files without updating the @code{Makefile} to match. - -This is typical output:- - -@smallexample -/tmp/test.o: /tmp/test.c /tmp/test.h - -/tmp/test.h: -@end smallexample - -@item -MQ @var{target} -@item -MT @var{target} -@opindex MQ -@opindex MT -By default CPP uses the main file name, including any path, and appends -the object suffix, normally ``.o'', to it to obtain the name of the -target for dependency generation. With @option{-MT} you can specify a -target yourself, overriding the default one. - -If you want multiple targets, you can specify them as a single argument -to @option{-MT}, or use multiple @option{-MT} options. - -The targets you specify are output in the order they appear on the -command line. @option{-MQ} is identical to @option{-MT}, except that the -target name is quoted for Make, but with @option{-MT} it isn't. For -example, @option{-MT '$(objpfx)foo.o'} gives - -@smallexample -$(objpfx)foo.o: /tmp/foo.c -@end smallexample - -but @option{-MQ '$(objpfx)foo.o'} gives - -@smallexample -$$(objpfx)foo.o: /tmp/foo.c -@end smallexample - -The default target is automatically quoted, as if it were given with -@option{-MQ}. - -@item -H -@opindex H -Print the name of each header file used, in addition to other normal -activities. - -@item -A@var{question}(@var{answer}) -@opindex A -Assert the answer @var{answer} for @var{question}, in case it is tested -with a preprocessing conditional such as @samp{#if -#@var{question}(@var{answer})}. @option{-A-} disables the standard -assertions that normally describe the target machine. - -@item -D@var{macro} -@opindex D -Define macro @var{macro} with the string @samp{1} as its definition. - -@item -D@var{macro}=@var{defn} -Define macro @var{macro} as @var{defn}. All instances of @option{-D} on -the command line are processed before any @option{-U} options. - -Any @option{-D} and @option{-U} options on the command line are processed in -order, and always before @option{-imacros @var{file}}, regardless of the -order in which they are written. - -@item -U@var{macro} -@opindex U -Undefine macro @var{macro}. @option{-U} options are evaluated after all -@option{-D} options, but before any @option{-include} and @option{-imacros} -options. - -Any @option{-D} and @option{-U} options on the command line are processed in -order, and always before @option{-imacros @var{file}}, regardless of the -order in which they are written. - -@item -dM -@opindex dM -Tell the preprocessor to output only a list of the macro definitions -that are in effect at the end of preprocessing. Used with the @option{-E} -option. - -@item -dD -@opindex dD -Tell the preprocessing to pass all macro definitions into the output, in -their proper sequence in the rest of the output. - -@item -dN -@opindex dN -Like @option{-dD} except that the macro arguments and contents are omitted. -Only @samp{#define @var{name}} is included in the output. - -@item -dI -@opindex dI -Output @samp{#include} directives in addition to the result of -preprocessing. - -@item -fpreprocessed -@opindex fpreprocessed -Indicate to the preprocessor that the input file has already been -preprocessed. This suppresses things like macro expansion, trigraph -conversion, escaped newline splicing, and processing of most directives. -The preprocessor still recognizes and removes comments, so that you can -pass a file preprocessed with @option{-C} to the compiler without -problems. In this mode the integrated preprocessor is little more than -a tokenizer for the front ends. - -@option{-fpreprocessed} is implicit if the input file has one of the -extensions @samp{i}, @samp{ii} or @samp{mi}. These are the extensions -that GCC uses for preprocessed files created by @option{-save-temps}. - -@item -trigraphs -@opindex trigraphs -Process ISO standard trigraph sequences. These are three-character -sequences, all starting with @samp{??}, that are defined by ISO C to -stand for single characters. For example, @samp{??/} stands for -@samp{\}, so @samp{'??/n'} is a character constant for a newline. By -default, GCC ignores trigraphs, but in standard-conforming modes it -converts them. See the @option{-std} and @option{-ansi} options. - -The nine trigraph sequences are -@table @samp -@item ??( -@expansion{} @samp{[} - -@item ??) -@expansion{} @samp{]} - -@item ??< -@expansion{} @samp{@{} - -@item ??> -@expansion{} @samp{@}} - -@item ??= -@expansion{} @samp{#} - -@item ??/ -@expansion{} @samp{\} - -@item ??' -@expansion{} @samp{^} - -@item ??! -@expansion{} @samp{|} - -@item ??- -@expansion{} @samp{~} - -@end table - -Trigraph support is not popular, so many compilers do not implement it -properly. Portable code should not rely on trigraphs being either -converted or ignored. - -@item -Wp,@var{option} @opindex Wp -Pass @var{option} as an option to the preprocessor. If @var{option} -contains commas, it is split into multiple options at the commas. -@end table +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. + +@include cppopts.texi @node Assembler Options @section Passing Options to the Assembler @@ -4504,15 +4297,13 @@ one @option{-I} option, the directories are scanned in left-to-right order; the standard system directories come after. If a standard system include directory, or a directory specified with -@option{-isystem}, is also specified with @option{-I}, it will be -searched only in the position requested by @option{-I}. Also, it will -not be considered a system include directory. If that directory really -does contain system headers, there is a good chance that they will -break. For instance, if GCC's installation procedure edited the headers -in @file{/usr/include} to fix bugs, @samp{-I/usr/include} will cause the -original, buggy headers to be found instead of the corrected ones. GCC -will issue a warning when a system include directory is hidden in this -way. +@option{-isystem}, is also specified with @option{-I}, the @option{-I} +option will be ignored. The directory will still be 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 include_next directive are not inadvertantly changed. +If you really need to change the search order for system directories, +use the @option{-nostdinc} and/or @option{-isystem} options. @item -I- @opindex I- @@ -5513,18 +5304,6 @@ emulates the effect of the instruction. Because of the trap handler overhead, this is much slower than calling the ABI library routines. Thus the @option{-msoft-quad-float} option is the default. -@item -mno-epilogue -@itemx -mepilogue -@opindex mno-epilogue -@opindex mepilogue -With @option{-mepilogue} (the default), the compiler always emits code for -function exit at the end of each function. Any function exit in -the middle of the function (such as a return statement in C) will -generate a jump to the exit code at the end of the function. - -With @option{-mno-epilogue}, the compiler tries to emit exit code inline -at every function exit. - @item -mno-flat @itemx -mflat @opindex mno-flat @@ -7032,6 +6811,10 @@ Extend the current ABI with AltiVec ABI extensions. This does not change the default ABI, instead it adds the AltiVec ABI extensions to the current ABI@. +@item -mabi=no-altivec +@opindex mabi=no-altivec +Disable AltiVec ABI extensions for the current ABI. + @item -mprototype @itemx -mno-prototype @opindex mprototype @@ -7711,9 +7494,12 @@ in ordinary CPU registers instead. @opindex mno-fancy-math-387 Some 387 emulators do not support the @code{sin}, @code{cos} and @code{sqrt} instructions for the 387. Specify this option to avoid -generating those instructions. This option is the default on FreeBSD@. -As of revision 2.6.1, these instructions are not generated unless you -also use the @option{-funsafe-math-optimizations} switch. +generating those instructions. This option is the default on FreeBSD, +OpenBSD and NetBSD@. This option is overridden when @option{-march} +indicates that the target cpu will always have an FPU and so the +instruction will not need emulation. As of revision 2.6.1, these +instructions are not generated unless you also use the +@option{-funsafe-math-optimizations} switch. @item -malign-double @itemx -mno-align-double @@ -7725,6 +7511,10 @@ boundary. Aligning @code{double} variables on a two word boundary will produce code that runs somewhat faster on a @samp{Pentium} at the expense of more memory. +@strong{Warning:} if you use the @samp{-malign-double} switch, +structures containing the above types will be aligned differently than +the published application binary interface specifications for the 386. + @item -m128bit-long-double @opindex m128bit-long-double Control the size of @code{long double} type. i386 application binary interface @@ -7836,6 +7626,9 @@ direct access to the MMX, SSE and 3Dnow extensions of the instruction set. @xref{X86 Built-in Functions}, for details of the functions enabled and disabled by these switches. +To have SSE/SSE2 instructions generated automatically from floating-point code, +see @option{-mfpmath=sse}. + @item -mpush-args @itemx -mno-push-args @opindex mpush-args @@ -7904,6 +7697,32 @@ by the x86-64 ABI, it is a 128-byte area beyond the location of the stack pointer that will not be modified by signal or interrupt handlers and therefore can be used for temporary data without adjusting the stack pointer. The flag @option{-mno-red-zone} disables this red zone. + +@item -mcmodel=small +@opindex mcmodel=small +Generate code for the small code model: the program and its symbols must +be linked in the lower 2 GB of the address space. Pointers are 64 bits. +Programs can be statically or dynamically linked. This is the default +code model. + +@item -mcmodel=kernel +@opindex mcmodel=kernel +Generate code for the kernel code model. The kernel runs in the +negative 2 GB of the address space. +This model has to be used for Linux kernel code. + +@item -mcmodel=medium +@opindex mcmodel=medium +Generate code for the medium model: The program is linked in the lower 2 +GB of the address space but symbols can be located anywhere in the +address space. Programs can be statically or dynamically linked, but +building of shared libraries are not supported with the medium model. + +@item -mcmodel=large +@opindex mcmodel=large +Generate code for the large model: This model makes no assumptions +about addresses and sizes of sections. Currently GCC does not implement +this model. @end table @node HPPA Options @@ -8684,8 +8503,8 @@ count register BK@. Enable (disable) generation of code using decrement and branch, DBcond(D), instructions. This is enabled by default for the C4x. To be on the safe side, this is disabled for the C3x, since the maximum -iteration count on the C3x is @math{2^23 + 1} (but who iterates loops more than -@math{2^23} times on the C3x?). Note that GCC will try to reverse a loop so +iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than +@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so that it can utilise the decrement and branch instruction, but will give up if there is more than one memory reference in the loop. Thus a loop where the loop counter is decremented can generate slightly more @@ -8753,9 +8572,9 @@ instruction, it is disabled by default. @opindex mloop-unsigned @opindex mno-loop-unsigned The maximum iteration count when using RPTS and RPTB (and DB on the C40) -is @math{2^31 + 1} since these instructions test if the iteration count is +is @math{2^{31} + 1} since these instructions test if the iteration count is negative to terminate the loop. If the iteration count is unsigned -there is a possibility than the @math{2^31 + 1} maximum iteration count may be +there is a possibility than the @math{2^{31} + 1} maximum iteration count may be exceeded. This switch allows an unsigned iteration count. @item -mti @@ -9943,7 +9762,8 @@ unwinding from asynchronous events (such as debugger or garbage collector). 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. +GCC-compiled files and files compiled with other compilers, particularly +the Portable C Compiler (pcc). The precise convention for returning structures in memory depends on the target configuration macros. @@ -9951,6 +9771,11 @@ on the target configuration macros. Short structures and unions are those whose size and alignment match that of some integer type. +@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. + @item -freg-struct-return @opindex freg-struct-return Return @code{struct} and @code{union} values in registers when possible. @@ -9964,16 +9789,39 @@ 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. +@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. + @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 will be equivalent to the smallest integer type which has enough room. +@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 -fshort-double @opindex fshort-double Use the same size for @code{double} as for @code{float}. +@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 -fshort-wchar +@opindex fshort-wchar +Override the underlying type for @samp{wchar_t} to be @samp{short +unsigned int} instead of the default for the target. This option is +useful for building programs to run under WINE@. + +@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. + @item -fshared-data @opindex fshared-data Requests that the data and non-@code{const} variables of this @@ -10115,9 +9963,12 @@ three-way choice. @item -fpack-struct @opindex fpack-struct -Pack all structure members together without holes. Usually you would -not want to use this option, since it makes the code suboptimal, and -the offsets of structure members won't agree with system libraries. +Pack all structure members together without holes. + +@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 suboptimial. +Use it to conform to a non-default application binary interface. @item -finstrument-functions @opindex finstrument-functions @@ -10214,8 +10065,10 @@ 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. -Be warned that you should know what you are doing when invoking this -option, and that not all targets provide complete support for it. +@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. @end table @c man end @@ -10336,35 +10189,6 @@ using GCC also uses these directories when searching for ordinary libraries for the @option{-l} option (but directories specified with @option{-L} come first). -@item C_INCLUDE_PATH -@itemx CPLUS_INCLUDE_PATH -@itemx OBJC_INCLUDE_PATH -@findex C_INCLUDE_PATH -@findex CPLUS_INCLUDE_PATH -@findex OBJC_INCLUDE_PATH -@c @itemx OBJCPLUS_INCLUDE_PATH -These environment variables pertain to particular languages. Each -variable's value is a colon-separated list of directories, much like -@env{PATH}. When GCC searches for header files, it tries the -directories listed in the variable for the language you are using, after -the directories specified with @option{-I} but before the standard header -file directories. - -@item DEPENDENCIES_OUTPUT -@findex DEPENDENCIES_OUTPUT -@cindex dependencies for make as output -If this variable is set, its value specifies how to output dependencies -for Make based on the header files processed by the compiler. This -output looks much like the output from the @option{-M} option -(@pxref{Preprocessor Options}), but it goes to a separate file, and is -in addition to the usual results of compilation. - -The value of @env{DEPENDENCIES_OUTPUT} can be just a file name, in -which case the Make rules are written to that file, guessing the target -name from the source file name. Or the value can have the form -@samp{@var{file} @var{target}}, in which case the rules are written to -file @var{file} using @var{target} as the target name. - @item LANG @findex LANG @cindex locale definition @@ -10388,6 +10212,12 @@ compiler will use mblen and mbtowc as defined by the default locale to recognize and translate multibyte characters. @end table +@noindent +Some additional environments variables affect the behavior of the +preprocessor. + +@include cppenv.texi + @c man end @node Running Protoize |