diff options
Diffstat (limited to 'gcc_arm/invoke.texi')
| -rwxr-xr-x | gcc_arm/invoke.texi | 7000 |
1 files changed, 7000 insertions, 0 deletions
diff --git a/gcc_arm/invoke.texi b/gcc_arm/invoke.texi new file mode 100755 index 0000000..4e614f4 --- /dev/null +++ b/gcc_arm/invoke.texi @@ -0,0 +1,7000 @@ +@c Copyright (C) 1988,89,92,93,94,95,96,97,98,1999 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Invoking GCC +@chapter GNU CC Command Options +@cindex GNU CC command options +@cindex command options +@cindex options, GNU CC command + +When you invoke GNU CC, it normally does preprocessing, compilation, +assembly and linking. The ``overall options'' allow you to stop this +process at an intermediate stage. For example, the @samp{-c} option +says not to run the linker. Then the output consists of object files +output by the assembler. + +Other options are passed on to one stage of processing. Some options +control the preprocessor and others the compiler itself. Yet other +options control the assembler and linker; most of these are not +documented here, since you rarely need to use any of them. + +@cindex C compilation options +Most of the command line options that you can use with GNU CC are useful +for C programs; when an option is only useful with another language +(usually C++), the explanation says so explicitly. If the description +for a particular option does not mention a source language, you can use +that option with all supported languages. + +@cindex C++ compilation options +@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special +options for compiling C++ programs. + +@cindex grouping options +@cindex options, grouping +The @code{gcc} program accepts options and file names as operands. Many +options have multiletter names; therefore multiple single-letter options +may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d +-r}}. + +@cindex order of options +@cindex options, order +You can mix options and other arguments. For the most part, the order +you use doesn't matter. Order does matter when you use several options +of the same kind; for example, if you specify @samp{-L} more than once, +the directories are searched in the order specified. + +Many options have long names starting with @samp{-f} or with +@samp{-W}---for example, @samp{-fforce-mem}, +@samp{-fstrength-reduce}, @samp{-Wformat} and so on. Most of +these have both positive and negative forms; the negative form of +@samp{-ffoo} would be @samp{-fno-foo}. This manual documents +only one of these two forms, whichever one is not the default. + +@c CYGNUS LOCAL v850 Offset Info +@c The entry "Offset info" in the following menu is needed for +@c Cygnus-only sections of the doc. Unfortunately makeinfo gets confused if +@c comments to this effect are inside the menu. +@menu +* Option Summary:: Brief list of all options, without explanations. +* Overall Options:: Controlling the kind of output: + an executable, object files, assembler files, + or preprocessed source. +* Invoking G++:: Compiling C++ programs. +* C Dialect Options:: Controlling the variant of C language compiled. +* C++ Dialect Options:: Variations on C++. +* Warning Options:: How picky should the compiler be? +* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Optimize Options:: How much optimization? +* Preprocessor Options:: Controlling header files and macro definitions. + Also, getting dependency information for Make. +* Assembler Options:: Passing options to the assembler. +* Link Options:: Specifying libraries and so on. +* Directory Options:: Where to find header files and libraries. + Where to find the compiler executable files. +* Target Options:: Running a cross-compiler, or an old version of GNU CC. +* Submodel Options:: Specifying minor hardware or convention variations, + such as 68010 vs 68020. +* Code Gen Options:: Specifying conventions for function calls, data layout + and register usage. +* Offset info Option:: Producing assembler symbols for structure members. +* Environment Variables:: Env vars that affect GNU CC. +* Running Protoize:: Automatically adding or removing function prototypes. +@end menu + +@node Option Summary +@section Option Summary + +Here is a summary of all the options, grouped by type. Explanations are +in the following sections. + +@table @emph +@item Overall Options +@xref{Overall Options,,Options Controlling the Kind of Output}. +@smallexample +-c -S -E -o @var{file} -pipe -v --help -x @var{language} +@end smallexample + +@item C Language Options +@xref{C Dialect Options,,Options Controlling C Dialect}. +@smallexample +-ansi -flang-isoc9x -fallow-single-precision -fcond-mismatch -fno-asm +-fno-builtin -ffreestanding -fhosted -fsigned-bitfields -fsigned-char +-funsigned-bitfields -funsigned-char -fwritable-strings +-traditional -traditional-cpp -trigraphs +@end smallexample + +@item C++ Language Options +@xref{C++ Dialect Options,,Options Controlling C++ Dialect}. +@smallexample +-fno-access-control -fcheck-new -fconserve-space -fdollars-in-identifiers +-fno-elide-constructors -fexternal-templates -ffor-scope +-fno-for-scope -fno-gnu-keywords -fguiding-decls -fhandle-signatures +-fhonor-std -fhuge-objects -fno-implicit-templates -finit-priority +-fno-implement-inlines -fname-mangling-version-@var{n} -fno-default-inline +-foperator-names -fno-optional-diags -frepo -fstrict-prototype +-fsquangle -ftemplate-depth-@var{n} -fthis-is-variable -fvtable-thunks +-nostdinc++ -Wctor-dtor-privacy -Weffc++ -Wno-non-template-friend +-Wnon-virtual-dtor -Wold-style-cast -Woverloaded-virtual +-Wno-pmf-conversions -Wreorder -Wsign-promo -Wsynth +@end smallexample + +@item Warning Options +@xref{Warning Options,,Options to Request or Suppress Warnings}. +@smallexample +-fsyntax-only -pedantic -pedantic-errors +-w -W -Wall -Waggregate-return -Wbad-function-cast +-Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment +-Wconversion -Werror -Wformat +-Wid-clash-@var{len} -Wimplicit -Wimplicit-int +-Wimplicit-function-declaration -Wimport +-Werror-implicit-function-declaration -Winline +-Wlarger-than-@var{len} -Wlong-long +-Wmain -Wmissing-declarations -Wmissing-noreturn +-Wmissing-prototypes -Wmultichar -Wnested-externs -Wno-import +-Wparentheses -Wpointer-arith -Wredundant-decls +-Wreturn-type -Wshadow -Wsign-compare -Wstrict-prototypes +-Wswitch -Wtraditional +-Wtrigraphs -Wundef -Wuninitialized -Wunused -Wwrite-strings +-Wunknown-pragmas +@end smallexample + +@item Debugging Options +@xref{Debugging Options,,Options for Debugging Your Program or GCC}. +@smallexample +-a -ax -d@var{letters} -fdump-unnumbered -fpretend-float +-fprofile-arcs -ftest-coverage +-g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2 +-ggdb -gstabs -gstabs+ -gxcoff -gxcoff+ +-p -pg -print-file-name=@var{library} -print-libgcc-file-name +-print-prog-name=@var{program} -print-search-dirs -save-temps +@end smallexample + +@item Optimization Options +@xref{Optimize Options,,Options that Control Optimization}. +@smallexample +-fbranch-probabilities -foptimize-register-moves +-fcaller-saves -fcse-follow-jumps -fcse-skip-blocks +-fdelayed-branch -fexpensive-optimizations +-ffast-math -ffloat-store -fforce-addr -fforce-mem +-fdata-sections -ffunction-sections -fgcse +@c CYGNUS LOCAL LRS +-flive-range +@c END CYGNUS LOCAL +-finline-functions -fkeep-inline-functions +-fno-default-inline -fno-defer-pop -fno-function-cse +-fno-inline -fno-peephole -fomit-frame-pointer -fregmove +-frerun-cse-after-loop -frerun-loop-opt -fschedule-insns +-fschedule-insns2 -fstrength-reduce -fthread-jumps +-funroll-all-loops -funroll-loops +-fmove-all-movables -freduce-all-givs -fstrict-aliasing +-O -O0 -O1 -O2 -O3 -Os +@end smallexample + +@item Preprocessor Options +@xref{Preprocessor Options,,Options Controlling the Preprocessor}. +@smallexample +-A@var{question}(@var{answer}) -C -dD -dM -dN +-D@var{macro}@r{[}=@var{defn}@r{]} -E -H +-idirafter @var{dir} +-include @var{file} -imacros @var{file} +-iprefix @var{file} -iwithprefix @var{dir} +-iwithprefixbefore @var{dir} -isystem @var{dir} -isystem-c++ @var{dir} +-M -MD -MM -MMD -MG -nostdinc -P -trigraphs +-undef -U@var{macro} -Wp,@var{option} +@end smallexample + +@item Assembler Option +@xref{Assembler Options,,Passing Options to the Assembler}. +@smallexample +-Wa,@var{option} +@end smallexample + +@item Linker Options +@xref{Link Options,,Options for Linking}. +@smallexample +@var{object-file-name} -l@var{library} +-nostartfiles -nodefaultlibs -nostdlib +-s -static -shared -symbolic +-Wl,@var{option} -Xlinker @var{option} +-u @var{symbol} +@end smallexample + +@item Directory Options +@xref{Directory Options,,Options for Directory Search}. +@smallexample +-B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file} +@end smallexample + +@item Target Options +@c I wrote this xref this way to avoid overfull hbox. -- rms +@xref{Target Options}. +@smallexample +-b @var{machine} -V @var{version} +@end smallexample + +@item Machine Dependent Options +@xref{Submodel Options,,Hardware Models and Configurations}. +@smallexample +@emph{M680x0 Options} +-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 +-m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020 +-mfpa -mnobitfield -mrtd -mshort -msoft-float +-malign-int + +@emph{VAX Options} +-mg -mgnu -munix + +@emph{SPARC Options} +-mcpu=@var{cpu type} +-mtune=@var{cpu type} +-mcmodel=@var{code model} +-malign-jumps=@var{num} -malign-loops=@var{num} +-malign-functions=@var{num} +-m32 -m64 +-mapp-regs -mbroken-saverestore -mcypress -mepilogue +-mflat -mfpu -mhard-float -mhard-quad-float +-mimpure-text -mlive-g0 -mno-app-regs -mno-epilogue +-mno-flat -mno-fpu -mno-impure-text +-mno-stack-bias -mno-unaligned-doubles +-msoft-float -msoft-quad-float -msparclite -mstack-bias +-msupersparc -munaligned-doubles -mv8 + +@emph{Convex Options} +-mc1 -mc2 -mc32 -mc34 -mc38 +-margcount -mnoargcount +-mlong32 -mlong64 +-mvolatile-cache -mvolatile-nocache + +@emph{AMD29K Options} +-m29000 -m29050 -mbw -mnbw -mdw -mndw +-mlarge -mnormal -msmall +-mkernel-registers -mno-reuse-arg-regs +-mno-stack-check -mno-storem-bug +-mreuse-arg-regs -msoft-float -mstack-check +-mstorem-bug -muser-registers + +@emph{ARM Options} +-mapcs-frame -mno-apcs-frame +-mapcs-26 -mapcs-32 +-mapcs-stack-check -mno-apcs-stack-check +-mapcs-float -mno-apcs-float +-mapcs-reentrant -mno-apcs-reentrant +-msched-prolog -mno-sched-prolog +-mlittle-endian -mbig-endian -mwords-little-endian +-mshort-load-bytes -mno-short-load-bytes -mshort-load-words -mno-short-load-words +-msoft-float -mhard-float -mfpe +-mthumb-interwork -mno-thumb-interwork +-mcpu= -march= -mfpe= +-mstructure-size-boundary= +-mbsd -mxopen -mno-symrename +-mabort-on-noreturn +@c CYGNUS LOCAL nickc/thumb-pe +-mnop-fun-dllimport -mno-nop-fun-dllimport +@c END CYGNUS LOCAL + +@emph{Thumb Options} +-mtpcs-frame -mno-tpcs-frame +-mtpcs-leaf-frame -mno-tpcs-leaf-frame +-mlittle-endian -mbig-endian +-mthumb-interwork -mno-thumb-interwork +-mstructure-size-boundary= +@c CYGNUS LOCAL nickc/thumb-pe +-mnop-fun-dllimport -mno-nop-fun-dllimport +-mcallee-super-interworking -mno-callee-super-interworking +-mcaller-super-interworking -mno-caller-super-interworking +@c END CYGNUS LOCAL + +@emph{MN10200 Options} +-mrelax + +@emph{MN10300 Options} +-mmult-bug +-mno-mult-bug +-mrelax + +@emph{M32R/D/X Options} +-mcode-model=@var{model type} -msdata=@var{sdata type} +-G @var{num} +-m32rx -m32r +-mcond-exec=@var{n} + +@emph{M88K Options} +-m88000 -m88100 -m88110 -mbig-pic +-mcheck-zero-division -mhandle-large-shift +-midentify-revision -mno-check-zero-division +-mno-ocs-debug-info -mno-ocs-frame-position +-mno-optimize-arg-area -mno-serialize-volatile +-mno-underscores -mocs-debug-info +-mocs-frame-position -moptimize-arg-area +-mserialize-volatile -mshort-data-@var{num} -msvr3 +-msvr4 -mtrap-large-shift -muse-div-instruction +-mversion-03.00 -mwarn-passed-structs + +@emph{RS/6000 and PowerPC Options} +-mcpu=@var{cpu type} +-mtune=@var{cpu type} +-mpower -mno-power -mpower2 -mno-power2 +-mpowerpc -mno-powerpc +-mpowerpc-gpopt -mno-powerpc-gpopt +-mpowerpc-gfxopt -mno-powerpc-gfxopt +-mnew-mnemonics -mno-new-mnemonics +-mfull-toc -mminimal-toc -mno-fop-in-toc -mno-sum-in-toc +-maix64 -maix32 -mxl-call -mno-xl-call -mthreads -mpe +-msoft-float -mhard-float -mmultiple -mno-multiple +-mstring -mno-string -mupdate -mno-update +-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align +-mstrict-align -mno-strict-align -mrelocatable +-mno-relocatable -mrelocatable-lib -mno-relocatable-lib +-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian +-mcall-aix -mcall-sysv -mprototype -mno-prototype +@c CYGNUS LOCAL vmakarov +-msched-epilog -mno-sched-epilog -msched-prolog -mno-sched-prolog +-mcall-i960-old -mbit-word -mno-bit-word -mbranch-cost=@var{n} +@c END CYGNUS LOCAL +-msim -mmvme -mads -myellowknife -memb -msdata +-msdata=@var{opt} -G @var{num} +@c CYGNUS LOCAL vmakarov +-mvxworks +@c END CYGNUS LOCAL +@c CYGNUS LOCAL jlemke +-mmpc860c0[=@var{num}] +@c END CYGNUS LOCAL + +@emph{RT Options} +-mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs +-mfull-fp-blocks -mhc-struct-return -min-line-mul +-mminimum-fp-blocks -mnohc-struct-return + +@emph{MIPS Options} +-mabicalls -mcpu=@var{cpu type} -membedded-data +-membedded-pic -mfp32 -mfp64 -mgas -mgp32 -mgp64 +-mgpopt -mhalf-pic -mhard-float -mint64 -mips1 +-mips2 -mips3 -mips4 -mlong64 -mlong-calls -mmemcpy +-mmips-as -mmips-tfile -mno-abicalls +-mno-embedded-data -mno-embedded-pic +-mno-gpopt -mno-long-calls +-mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats +-mrnames -msoft-float +-m4650 -msingle-float -mmad +-mstats -EL -EB -G @var{num} -nocpp +-mabi=32 -mabi=n32 -mabi=64 -mabi=eabi +@c CYGNUS LOCAL law +-malign-jumps=@var{num} -malign-loops=@var{num} +-malign-functions=@var{num} +-mmax-skip-jumps=@var{num} +-mmax-skip-loops=@var{num} +-mmax-skip-funtions=@var{num} +@c END CYGNUS LOCAL + +@emph{i386 Options} +-mcpu=@var{cpu type} +-march=@var{cpu type} +-mieee-fp -mno-fancy-math-387 +-mno-fp-ret-in-387 -msoft-float -msvr3-shlib +-mno-wide-multiply -mrtd -malign-double +-mreg-alloc=@var{list} -mregparm=@var{num} +-malign-jumps=@var{num} -malign-loops=@var{num} +-malign-functions=@var{num} + +@emph{HPPA Options} +-mbig-switch -mdisable-fpregs -mdisable-indexing +-mfast-indirect-calls -mgas -mjump-in-delay +-mlong-load-store -mno-big-switch -mno-disable-fpregs +-mno-disable-indexing -mno-fast-indirect-calls -mno-gas +-mno-jump-in-delay -mno-long-load-store +-mno-portable-runtime -mno-soft-float -mno-space +-mno-space-regs -msoft-float -mpa-risc-1-0 +-mpa-risc-1-1 -mportable-runtime +-mschedule=@var{list} -mspace -mspace-regs + +@emph{Intel 960 Options} +-m@var{cpu type} -masm-compat -mclean-linkage +-mcode-align -mcomplex-addr -mleaf-procedures +-mic-compat -mic2.0-compat -mic3.0-compat +-mintel-asm -mno-clean-linkage -mno-code-align +-mno-complex-addr -mno-leaf-procedures +-mno-old-align -mno-strict-align -mno-tail-call +-mnumerics -mold-align -msoft-float -mstrict-align +-mtail-call + +@emph{DEC Alpha Options} +-mfp-regs -mno-fp-regs -mno-soft-float -msoft-float +-malpha-as -mgas +-mieee -mieee-with-inexact -mieee-conformant +-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} +-mtrap-precision=@var{mode} -mbuild-constants +-mcpu=@var{cpu type} +-mbwx -mno-bwx -mcix -mno-cix -mmax -mno-max +-mmemory-latency=@var{time} + +@emph{Clipper Options} +-mc300 -mc400 + +@emph{H8/300 Options} +-mrelax -mh -ms -mint32 -malign-300 + +@emph{SH Options} +-m1 -m2 -m3 -m3e -mb -ml -mdalign -mrelax + +@emph{System V Options} +-Qy -Qn -YP,@var{paths} -Ym,@var{dir} + +@c CYGNUS LOCAL: z8k docs +@emph{Z8000 Option} +-mz8001 +@c END CYGNUS LOCAL + +@emph{ARC Options} +-EB -EL +-mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text section} +-mdata=@var{data section} -mrodata=@var{readonly data section} + +@c CYGNUS LOCAL -- meissner/d10v +@emph{D10V Options} +-mint16 -mint32 -mdouble32 -mdouble64 +-maddac3 -mno-addac3 -maccum -mno-accum -msim +-mno-cond-move -mcond-move +-masm-optimize -mno-asm-optimize +-msmall-insns -mno-small-insns +-mbranch-cost=@var{n} -mcond-exec=@var{n} +@c END CYGNUS LOCAL -- meissner/d10v + +@emph{V850 Options} +-mlong-calls -mno-long-calls -mep -mno-ep +-mprolog-function -mno-prolog-function -mspace +-mtda=@var{n} -msda=@var{n} -mzda=@var{n} +-mv850 -mbig-switch +-mapp-regs -mno-app-regs +@c CYGNUS LOCAL v850e +-mv850e +-mdisable-callt -mno-disable-callt +@c CYGNUS LOCAL v850e + +@emph{NS32K Options} +-m32032 -m32332 -m32532 -m32081 -m32381 -mmult-add -mnomult-add +-msoft-float -mrtd -mnortd -mregparam -mnoregparam -msb -mnosb +-mbitfield -mnobitfield -mhimem -mnohimem +@end smallexample + +@item Code Generation Options +@xref{Code Gen Options,,Options for Code Generation Conventions}. +@smallexample +-fcall-saved-@var{reg} -fcall-used-@var{reg} +-fexceptions -ffixed-@var{reg} -finhibit-size-directive +-fcheck-memory-usage -fprefix-function-name +-fno-common -fno-ident -fno-gnu-linker +-fpcc-struct-return -fpic -fPIC +-freg-struct-return -fshared-data -fshort-enums +-fshort-double -fvolatile -fvolatile-global +@c CYGNUS LOCAL unaligned-pointers, unaligned-struct-hack +-funaligned-pointers -funaligned-struct-hack +@c END CYGNUS LOCAL +@c CYGNUS LOCAL -- meissner/nortel +-foptimize-comparisons +@c END CYGNUS LOCAL -- meissner/nortel +-fverbose-asm -fpack-struct -fstack-check +-fargument-alias -fargument-noalias +-fargument-noalias-global +-fleading-underscore +@end smallexample +@end table + +@menu +* Overall Options:: Controlling the kind of output: + an executable, object files, assembler files, + or preprocessed source. +* C Dialect Options:: Controlling the variant of C language compiled. +* C++ Dialect Options:: Variations on C++. +* Warning Options:: How picky should the compiler be? +* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Optimize Options:: How much optimization? +* Preprocessor Options:: Controlling header files and macro definitions. + Also, getting dependency information for Make. +* Assembler Options:: Passing options to the assembler. +* Link Options:: Specifying libraries and so on. +* Directory Options:: Where to find header files and libraries. + Where to find the compiler executable files. +* Target Options:: Running a cross-compiler, or an old version of GNU CC. +@end menu + +@node Overall Options +@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. + +@cindex file name suffix +For any given input file, the file name suffix determines what kind of +compilation is done: + +@table @code +@item @var{file}.c +C source code which must be preprocessed. + +@item @var{file}.i +C source code which should not be preprocessed. + +@item @var{file}.ii +C++ source code which should not be preprocessed. + +@item @var{file}.m +Objective-C source code. Note that you must link with the library +@file{libobjc.a} to make an Objective-C program work. + +@item @var{file}.h +C header file (not to be compiled or linked). + +@item @var{file}.cc +@itemx @var{file}.cxx +@itemx @var{file}.cpp +@itemx @var{file}.C +C++ source code which must be preprocessed. Note that in @samp{.cxx}, +the last two letters must both be literally @samp{x}. Likewise, +@samp{.C} refers to a literal capital C. + +@item @var{file}.s +Assembler code. + +@item @var{file}.S +Assembler code which must be preprocessed. + +@item @var{other} +An object file to be fed straight into linking. +Any file name with no recognized suffix is treated this way. +@end table + +You can specify the input language explicitly with the @samp{-x} option: + +@table @code +@item -x @var{language} +Specify explicitly the @var{language} for the following input files +(rather than letting the compiler choose a default based on the file +name suffix). This option applies to all following input files until +the next @samp{-x} option. Possible values for @var{language} are: +@example +c objective-c c++ +c-header cpp-output c++-cpp-output +assembler assembler-with-cpp +@end example + +@item -x none +Turn off any specification of a language, so that subsequent files are +handled according to their file name suffixes (as they are if @samp{-x} +has not been used at all). +@end table + +If you only want some of the stages of compilation, you can use +@samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and +one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where +@code{gcc} is to stop. Note that some combinations (for example, +@samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all. + +@table @code +@item -c +Compile or assemble the source files, but do not link. The linking +stage simply is not done. The ultimate output is in the form of an +object file for each source file. + +By default, the object file name for a source file is made by replacing +the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}. + +Unrecognized input files, not requiring compilation or assembly, are +ignored. + +@item -S +Stop after the stage of compilation proper; do not assemble. The output +is in the form of an assembler code file for each non-assembler input +file specified. + +By default, the assembler file name for a source file is made by +replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}. + +Input files that don't require compilation are ignored. + +@item -E +Stop after the preprocessing stage; do not run the compiler proper. The +output is in the form of preprocessed source code, which is sent to the +standard output. + +Input files which don't require preprocessing are ignored. + +@cindex output file option +@item -o @var{file} +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 @samp{-o} when compiling more than one input file, unless you are +producing an executable file as output. + +If @samp{-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 +all preprocessed C source on standard output.@refill + +@item -v +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 -pipe +Use pipes rather than temporary files for communication between the +various stages of compilation. This fails to work on some systems where +the assembler is unable to read from a pipe; but the GNU assembler has +no trouble. + +@item --help +Print (on the standard output) a description of the command line options +understood by @code{gcc}. If the @code{-v} option is also specified +then @code{--help} will also be passed on to the various processes +invoked by @code{gcc}, so that they can display the command line options +they accept. If the @code{-W} option is also specified then command +line options which have no documentation associated with them will also +be displayed. +@end table + +@node Invoking G++ +@section Compiling C++ Programs + +@cindex suffixes for C++ source +@cindex C++ source file suffixes +C++ source files conventionally use one of the suffixes @samp{.C}, +@samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx}; +preprocessed C++ files use the suffix @samp{.ii}. GNU CC recognizes +files with these names and compiles them as C++ programs even if you +call the compiler the same way as for compiling C programs (usually with +the name @code{gcc}). + +@findex g++ +@findex c++ +However, C++ programs often require class libraries as well as a +compiler that understands the C++ language---and under some +circumstances, you might want to compile programs from standard input, +or otherwise without a suffix that flags them as C++ programs. +@code{g++} is a program that calls GNU CC with the default language +set to C++, and automatically specifies linking against the C++ +library. On many systems, the script @code{g++} is also +installed with the name @code{c++}. + +@cindex invoking @code{g++} +When you compile C++ programs, you may specify many of the same +command-line options that you use for compiling programs in any +language; or command-line options meaningful for C and related +languages; or options that are meaningful only for C++ programs. +@xref{C Dialect Options,,Options Controlling C Dialect}, for +explanations of options for languages related to C. +@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for +explanations of options that are meaningful only for C++ programs. + +@node C Dialect Options +@section Options Controlling C Dialect +@cindex dialect options +@cindex language dialect options +@cindex options, dialect + +The following options control the dialect of C (or languages derived +from C, such as C++ and Objective C) that the compiler accepts: + +@table @code +@cindex ANSI support +@item -ansi +Support all ANSI standard C programs. + +This turns off certain features of GNU C that are incompatible with ANSI +C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and +predefined macros such as @code{unix} and @code{vax} that identify the +type of system you are using. It also enables the undesirable and +rarely used ANSI trigraph feature, and it disables recognition of C++ +style @samp{//} comments. + +The alternate keywords @code{__asm__}, @code{__extension__}, +@code{__inline__} and @code{__typeof__} continue to work despite +@samp{-ansi}. You would not want to use them in an ANSI C program, of +course, but it is useful to put them in header files that might be included +in compilations done with @samp{-ansi}. Alternate predefined macros +such as @code{__unix__} and @code{__vax__} are also available, with or +without @samp{-ansi}. + +The @samp{-ansi} option does not cause non-ANSI programs to be +rejected gratuitously. For that, @samp{-pedantic} is required in +addition to @samp{-ansi}. @xref{Warning Options}. + +The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi} +option is used. Some header files may notice this macro and refrain +from declaring certain functions or defining certain macros that the +ANSI standard doesn't call for; this is to avoid interfering with any +programs that might use these names for other things. + +The functions @code{alloca}, @code{abort}, @code{exit}, and +@code{_exit} are not builtin functions when @samp{-ansi} is used. + +@item -flang-isoc9x +Enable support for features found in the C9X standard. In particular, +enable support for the C9X @code{restrict} keyword. + +Even when this option is not specified, you can still use some C9X +features in so far as they do not conflict with previous C standards. +For example, you may use @code{__restrict__} even when -flang-isoc9x +is not specified. + +@item -fno-asm +Do not recognize @code{asm}, @code{inline} or @code{typeof} as a +keyword, so that code can use these words as identifiers. You can use +the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__} +instead. @samp{-ansi} implies @samp{-fno-asm}. + +In C++, this switch only affects the @code{typeof} keyword, since +@code{asm} and @code{inline} are standard keywords. You may want to +use the @samp{-fno-gnu-keywords} flag instead, as it also disables the +other, C++-specific, extension keywords such as @code{headof}. + +@item -fno-builtin +@cindex builtin functions +@findex abort +@findex abs +@findex alloca +@findex cos +@findex exit +@findex fabs +@findex ffs +@findex labs +@findex memcmp +@findex memcpy +@findex sin +@findex sqrt +@findex strcmp +@findex strcpy +@findex strlen +Don't recognize builtin functions that do not begin with `__builtin_' +as prefix. Currently, the functions affected include @code{abort}, +@code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs}, +@code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin}, +@code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}. + +GCC normally generates special code to handle certain builtin functions +more efficiently; for instance, calls to @code{alloca} may become single +instructions that adjust the stack directly, and calls to @code{memcpy} +may become inline copy loops. The resulting code is often both smaller +and faster, but since the function calls no longer appear as such, you +cannot set a breakpoint on those calls, nor can you change the behavior +of the functions by linking with a different library. + +The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being +builtin functions, since these functions do not have an ANSI standard +meaning. + +@item -fhosted +@cindex hosted environment + +Assert that compilation takes place in a hosted environment. This implies +@samp{-fbuiltin}. A hosted environment is one in which the +entire standard library is available, and in which @code{main} has a return +type of @code{int}. Examples are nearly everything except a kernel. +This is equivalent to @samp{-fno-freestanding}. + +@item -ffreestanding +@cindex hosted environment + +Assert that compilation takes place in a freestanding environment. This +implies @samp{-fno-builtin}. A freestanding environment +is one in which the standard library may not exist, and program startup may +not necessarily be at @code{main}. The most obvious example is an OS kernel. +This is equivalent to @samp{-fno-hosted}. + +@item -trigraphs +Support ANSI C trigraphs. You don't want to know about this +brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}. + +@cindex traditional C language +@cindex C language, traditional +@item -traditional +Attempt to support some aspects of traditional C compilers. +Specifically: + +@itemize @bullet +@item +All @code{extern} declarations take effect globally even if they +are written inside of a function definition. This includes implicit +declarations of functions. + +@item +The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const} +and @code{volatile} are not recognized. (You can still use the +alternative keywords such as @code{__typeof__}, @code{__inline__}, and +so on.) + +@item +Comparisons between pointers and integers are always allowed. + +@item +Integer types @code{unsigned short} and @code{unsigned char} promote +to @code{unsigned int}. + +@item +Out-of-range floating point literals are not an error. + +@item +Certain constructs which ANSI regards as a single invalid preprocessing +number, such as @samp{0xe-0xd}, are treated as expressions instead. + +@item +String ``constants'' are not necessarily constant; they are stored in +writable space, and identical looking constants are allocated +separately. (This is the same as the effect of +@samp{-fwritable-strings}.) + +@cindex @code{longjmp} and automatic variables +@item +All automatic variables not declared @code{register} are preserved by +@code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables +not declared @code{volatile} may be clobbered. + +@item +@kindex \x +@kindex \a +@cindex escape sequences, traditional +The character escape sequences @samp{\x} and @samp{\a} evaluate as the +literal characters @samp{x} and @samp{a} respectively. Without +@w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal +representation of a character, and @samp{\a} produces a bell. +@end itemize + +You may wish to use @samp{-fno-builtin} as well as @samp{-traditional} +if your program uses names that are normally GNU C builtin functions for +other purposes of its own. + +You cannot use @samp{-traditional} if you include any header files that +rely on ANSI C features. Some vendors are starting to ship systems with +ANSI C header files and you cannot use @samp{-traditional} on such +systems to compile files that include any system headers. + +The @samp{-traditional} option also enables @samp{-traditional-cpp}, +which is described next. + +@item -traditional-cpp +Attempt to support some aspects of traditional C preprocessors. +Specifically: + +@itemize @bullet +@item +Comments convert to nothing at all, rather than to a space. This allows +traditional token concatenation. + +@item +In a preprocessing directive, the @samp{#} symbol must appear as the first +character of a line. + +@item +Macro arguments are recognized within string constants in a macro +definition (and their values are stringified, though without additional +quote marks, when they appear in such a context). The preprocessor +always considers a string constant to end at a newline. + +@item +@cindex detecting @w{@samp{-traditional}} +The predefined macro @code{__STDC__} is not defined when you use +@samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions +which @code{__GNUC__} indicates are not affected by +@samp{-traditional}). If you need to write header files that work +differently depending on whether @samp{-traditional} is in use, by +testing both of these predefined macros you can distinguish four +situations: GNU C, traditional GNU C, other ANSI C compilers, and other +old C compilers. The predefined macro @code{__STDC_VERSION__} is also +not defined when you use @samp{-traditional}. @xref{Standard +Predefined,,Standard Predefined Macros,cpp.info,The C Preprocessor}, +for more discussion of these and other predefined macros. + +@item +@cindex string constants vs newline +@cindex newline vs string constants +The preprocessor considers a string constant to end at a newline (unless +the newline is escaped with @samp{\}). (Without @w{@samp{-traditional}}, +string constants can contain the newline character as typed.) +@end itemize + +@item -fcond-mismatch +Allow conditional expressions with mismatched types in the second and +third arguments. The value of such an expression is void. + +@item -funsigned-char +Let the type @code{char} be unsigned, like @code{unsigned char}. + +Each kind of machine has a default for what @code{char} should +be. It is either like @code{unsigned char} by default or like +@code{signed char} by default. + +Ideally, a portable program should always use @code{signed char} or +@code{unsigned char} when it depends on the signedness of an object. +But many programs have been written to use plain @code{char} and +expect it to be signed, or expect it to be unsigned, depending on the +machines they were written for. This option, and its inverse, let you +make such a program work with the opposite default. + +The type @code{char} is always a distinct type from each of +@code{signed char} or @code{unsigned char}, even though its behavior +is always just like one of those two. + +@item -fsigned-char +Let the type @code{char} be signed, like @code{signed char}. + +Note that this is equivalent to @samp{-fno-unsigned-char}, which is +the negative form of @samp{-funsigned-char}. Likewise, the option +@samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}. + +You may wish to use @samp{-fno-builtin} as well as @samp{-traditional} +if your program uses names that are normally GNU C builtin functions for +other purposes of its own. + +You cannot use @samp{-traditional} if you include any header files that +rely on ANSI C features. Some vendors are starting to ship systems with +ANSI C header files and you cannot use @samp{-traditional} on such +systems to compile files that include any system headers. + +@item -fsigned-bitfields +@itemx -funsigned-bitfields +@itemx -fno-signed-bitfields +@itemx -fno-unsigned-bitfields +These options control whether a bitfield is signed or unsigned, when the +declaration does not use either @code{signed} or @code{unsigned}. By +default, such a bitfield is signed, because this is consistent: the +basic integer types such as @code{int} are signed types. + +However, when @samp{-traditional} is used, bitfields are all unsigned +no matter what. + +@item -fwritable-strings +Store string constants in the writable data segment and don't uniquize +them. This is for compatibility with old programs which assume they can +write into string constants. The option @samp{-traditional} also has +this effect. + +Writing into string constants is a very bad idea; ``constants'' should +be constant. + +@item -fallow-single-precision +Do not promote single precision math operations to double precision, +even when compiling with @samp{-traditional}. + +Traditional K&R C promotes all floating point operations to double +precision, regardless of the sizes of the operands. On the +architecture for which you are compiling, single precision may be faster +than double precision. If you must use @samp{-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 ANSI or GNU C conventions (the default). + +@end table + +@node C++ Dialect Options +@section Options Controlling C++ Dialect + +@cindex compiler options, C++ +@cindex C++ options, command line +@cindex options, C++ +This section describes the command-line options that are only meaningful +for 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{firstClass.C} like this: + +@example +g++ -g -frepo -O -c firstClass.C +@end example + +@noindent +In this example, only @samp{-frepo} is an option meant +only for C++ programs; you can use the other options with any +language supported by GNU CC. + +Here is a list of options that are @emph{only} for compiling C++ programs: + +@table @code +@item -fno-access-control +Turn off all access checking. This switch is mainly useful for working +around bugs in the access control code. + +@item -fcheck-new +Check that the pointer returned by @code{operator new} is non-null +before attempting to modify the storage allocated. The current Working +Paper requires that @code{operator new} never return a null pointer, so +this check is normally unnecessary. + +An alternative to using this option is to specify that your +@code{operator new} does not throw any exceptions; if you declare it +@samp{throw()}, g++ will check the return value. See also @samp{new +(nothrow)}. + +@item -fconserve-space +Put uninitialized or runtime-initialized global variables into the +common segment, as C does. This saves space in the executable at the +cost of not diagnosing duplicate definitions. If you compile with this +flag and your program mysteriously crashes after @code{main()} has +completed, you may have an object that is being destroyed twice because +two definitions were merged. + +This option is no longer useful on most targets, now that support has +been added for putting variables into BSS without making them common. + +@item -fdollars-in-identifiers +Accept @samp{$} in identifiers. You can also explicitly prohibit use of +@samp{$} with the option @samp{-fno-dollars-in-identifiers}. (GNU C allows +@samp{$} by default on most target systems, but there are a few exceptions.) +Traditional C allowed the character @samp{$} to form part of +identifiers. However, ANSI C and C++ forbid @samp{$} in identifiers. + +@c CYGNUS LOCAL Embedded C++ +@item -fembedded-cxx +In compliance with the Embedded C++ specification, make the use of templates, +exception handling, multiple inheritance, or RTTI illegal. Attempts to use +namespaces are also not allowed. This makes the use of these keywords result +in warnings by default: @code{template}, @code{typename}, @code{catch}, +@code{throw}, @code{try}, @code{using}, @code{namespace}, @code{dynamic_cast}, +@code{static_cast}, @code{reinterpret_cast}, @code{const_cast}, and +@code{typeid}. +To make the warnings for these things be given as errors, add the +@code{-pedantic-errors} flag. +@c END CYGNUS LOCAL Embedded C++ + +@item -fno-elide-constructors +The C++ standard allows an implementation to omit creating a temporary +which is only used to initialize another object of the same type. +Specifying this option disables that optimization, and forces g++ to +call the copy constructor in all cases. + +@item -fexternal-templates +Cause template instantiations to obey @samp{#pragma interface} and +@samp{implementation}; template instances are emitted or not according +to the location of the template definition. @xref{Template +Instantiation}, for more information. + +This option is deprecated. + +@item -falt-external-templates +Similar to -fexternal-templates, but template instances are emitted or +not according to the place where they are first instantiated. +@xref{Template Instantiation}, for more information. + +This option is deprecated. + +@item -ffor-scope +@itemx -fno-for-scope +If -ffor-scope is specified, the scope of variables declared in +a @i{for-init-statement} is limited to the @samp{for} loop itself, +as specified by the draft C++ standard. +If -fno-for-scope is specified, the scope of variables declared in +a @i{for-init-statement} extends to the end of the enclosing scope, +as was the case in old versions of gcc, and other (traditional) +implementations of C++. + +The default if neither flag is given to follow the standard, +but to allow and give a warning for old-style code that would +otherwise be invalid, or have different behavior. + +@item -fno-gnu-keywords +Do not recognize @code{classof}, @code{headof}, @code{signature}, +@code{sigof} or @code{typeof} as a keyword, so that code can use these +words as identifiers. You can use the keywords @code{__classof__}, +@code{__headof__}, @code{__signature__}, @code{__sigof__}, and +@code{__typeof__} instead. @samp{-ansi} implies +@samp{-fno-gnu-keywords}. + +@item -fguiding-decls +Treat a function declaration with the same type as a potential function +template instantiation as though it declares that instantiation, not a +normal function. If a definition is given for the function later in the +translation unit (or another translation unit if the target supports +weak symbols), that definition will be used; otherwise the template will +be instantiated. This behavior reflects the C++ language prior to +September 1996, when guiding declarations were removed. + +This option implies @samp{-fname-mangling-version-0}, and will not work +with other name mangling versions. Like all options that change the +ABI, all C++ code, @emph{including libgcc.a} must be built with the same +setting of this option. + +@item -fno-implicit-templates +Never emit code for templates which are instantiated implicitly (i.e. by +use); only emit code for explicit instantiations. @xref{Template +Instantiation}, for more information. + +@item -fhandle-signatures +Recognize the @code{signature} and @code{sigof} keywords for specifying +abstract types. The default (@samp{-fno-handle-signatures}) is not to +recognize them. @xref{C++ Signatures, Type Abstraction using +Signatures}. + +@item -fhonor-std +Treat the @code{namespace std} as a namespace, instead of ignoring +it. For compatibility with earlier versions of g++, the compiler will, +by default, ignore @code{namespace-declarations}, +@code{using-declarations}, @code{using-directives}, and +@code{namespace-names}, if they involve @code{std}. + +@item -fhuge-objects +Support virtual function calls for objects that exceed the size +representable by a @samp{short int}. Users should not use this flag by +default; if you need to use it, the compiler will tell you so. + +This flag is not useful when compiling with -fvtable-thunks. + +Like all options that change the ABI, all C++ code, @emph{including +libgcc} must be built with the same setting of this option. + +@item -fno-implicit-templates +Never emit code for non-inline templates which are instantiated +implicitly (i.e. by use); only emit code for explicit instantiations. +@xref{Template Instantiation}, for more information. + +@item -fno-implicit-inline-templates +Don't emit code for implicit instantiations of inline templates, either. +The default is to handle inlines differently so that compiles with and +without optimization will need the same set of explicit instantiations. + +@item -finit-priority +Support @samp{__attribute__ ((init_priority (n)))} for controlling the +order of initialization of file-scope objects. On ELF targets, this +requires GNU ld 2.10 or later. + +@item -fno-implement-inlines +To save space, do not emit out-of-line copies of inline functions +controlled by @samp{#pragma implementation}. This will cause linker +errors if these functions are not inlined everywhere they are called. + +@item -fname-mangling-version-@var{n} +Control the way in which names are mangled. Version 0 is compatible +with versions of g++ before 2.8. Version 1 is the default. Version 1 +will allow correct mangling of function templates. For example, +version 0 mangling does not mangle foo<int, double> and foo<int, char> +given this declaration: + +@example +template <class T, class U> void foo(T t); +@end example + +Like all options that change the ABI, all C++ code, @emph{including +libgcc} must be built with the same setting of this option. + +@item -foperator-names +Recognize the operator name keywords @code{and}, @code{bitand}, +@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as +synonyms for the symbols they refer to. @samp{-ansi} implies +@samp{-foperator-names}. + +@item -fno-optional-diags +Disable diagnostics that the standard says a compiler does not need to +issue. Currently, the only such diagnostic issued by g++ is the one for +a name having multiple meanings within a class. + +@item -frepo +Enable automatic template instantiation. This option also implies +@samp{-fno-implicit-templates}. @xref{Template Instantiation}, for more +information. + +@item -fstrict-prototype +Within an @samp{extern "C"} linkage specification, treat a function +declaration with no arguments, such as @samp{int foo ();}, as declaring +the function to take no arguments. Normally, such a declaration means +that the function @code{foo} can take any combination of arguments, as +in C. @samp{-pedantic} implies @samp{-fstrict-prototype} unless +overridden with @samp{-fno-strict-prototype}. + +Specifying this option will also suppress implicit declarations of +functions. + +This flag no longer affects declarations with C++ linkage. + +@item -fsquangle +@itemx -fno-squangle +@samp{-fsquangle} will enable a compressed form of name mangling for +identifiers. In particular, it helps to shorten very long names by recognizing +types and class names which occur more than once, replacing them with special +short ID codes. This option also requires any C++ libraries being used to +be compiled with this option as well. The compiler has this disabled (the +equivalent of @samp{-fno-squangle}) by default. + +Like all options that change the ABI, all C++ code, @emph{including +libgcc.a} must be built with the same setting of this option. + +@item -ftemplate-depth-@var{n} +Set the maximum instantiation depth for template classes to @var{n}. +A limit on the template instantiation depth is needed to detect +endless recursions during template class instantiation. ANSI/ISO C++ +conforming programs must not rely on a maximum depth greater than 17. + +@item -fthis-is-variable +Permit assignment to @code{this}. The incorporation of user-defined +free store management into C++ has made assignment to @samp{this} an +anachronism. Therefore, by default it is invalid to assign to +@code{this} within a class member function; that is, GNU C++ treats +@samp{this} in a member function of class @code{X} as a non-lvalue of +type @samp{X *}. However, for backwards compatibility, you can make it +valid with @samp{-fthis-is-variable}. + +@item -fvtable-thunks +Use @samp{thunks} to implement the virtual function dispatch table +(@samp{vtable}). The traditional (cfront-style) approach to +implementing vtables was to store a pointer to the function and two +offsets for adjusting the @samp{this} pointer at the call site. Newer +implementations store a single pointer to a @samp{thunk} function which +does any necessary adjustment and then calls the target function. + +This option also enables a heuristic for controlling emission of +vtables; if a class has any non-inline virtual functions, the vtable +will be emitted in the translation unit containing the first one of +those. + +Like all options that change the ABI, all C++ code, @emph{including +libgcc.a} must be built with the same setting of this option. + +@item -nostdinc++ +Do not search for header files in the standard directories specific to +C++, but do still search the other standard directories. (This option +is used when building the C++ library.) +@end table + +In addition, these optimization, warning, and code generation options +have meanings only for C++ programs: + +@table @code +@item -fno-default-inline +Do not assume @samp{inline} for functions defined inside a class scope. +@xref{Optimize Options,,Options That Control Optimization}. Note that these +functions will have linkage like inline functions; they just won't be +inlined by default. + +@item -Wctor-dtor-privacy (C++ only) +Warn when a class seems unusable, because all the constructors or +destructors in a class are private and the class has no friends or +public static member functions. + +@item -Wnon-virtual-dtor (C++ only) +Warn when a class declares a non-virtual destructor that should probably +be virtual, because it looks like the class will be used polymorphically. + +@item -Wreorder (C++ only) +@cindex reordering, warning +@cindex warning for reordering of member initializers +Warn when the order of member initializers given in the code does not +match the order in which they must be executed. For instance: + +@smallexample +struct A @{ + int i; + int j; + A(): j (0), i (1) @{ @} +@}; +@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. +@end table + +The following @samp{-W@dots{}} options are not affected by @samp{-Wall}. + +@table @code +@item -Weffc++ (C++ only) +Warn about violations of various style guidelines from Scott Meyers' +@cite{Effective C++} books. 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} to filter out those warnings. + +@item -Wno-non-template-friend (C++ only) +Disable warnings when non-templatized friend functions are declared +within a template. With the advent of explicit template specification +support in g++, if the name of the friend is an unqualified-id (ie, +@samp{friend foo(int)}), the C++ language specification demands that the +friend declare or define an ordinary, nontemplate function. (Section +14.5.3). Before g++ implemented explicit specification, unqualified-ids +could be interpreted as a particular specialization of a templatized +function. Because this non-conforming behavior is no longer the default +behavior for g++, @samp{-Wnon-template-friend} allows the compiler to +check existing code for potential trouble spots, and is on by default. +This new compiler behavior can also be turned off with the flag +@samp{-fguiding-decls}, which activates the older, non-specification +compiler code, or with @samp{-Wno-non-template-friend} which keeps the +conformant compiler code but disables the helpful warning. + +@item -Wold-style-cast (C++ only) +Warn if an old-style (C-style) cast 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. + +@item -Woverloaded-virtual (C++ only) +@cindex overloaded virtual fn, warning +@cindex warning for overloaded virtual fn +Warn when a derived class function declaration may be an error in +defining a virtual function. In a derived class, the +definitions of virtual functions must match the type signature of a +virtual function declared in the base class. With this option, the +compiler warns when you define a function with the same name as a +virtual function, but with a type signature that does not match any +declarations from the base class. + +@item -Wno-pmf-conversions (C++ only) +Disable the diagnostic for converting a bound pointer to member function +to a plain pointer. + +@item -Wsign-promo (C++ only) +Warn when overload resolution chooses a promotion from unsigned or +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. + +@item -Wsynth (C++ only) +@cindex warning for synthesized methods +@cindex synthesized methods, warning +Warn when g++'s synthesis behavior does not match that of cfront. For +instance: + +@smallexample +struct A @{ + operator int (); + A& operator = (int); +@}; + +main () +@{ + A a,b; + a = b; +@} +@end smallexample + +In this example, g++ will synthesize a default @samp{A& operator = +(const A&);}, while cfront will use the user-defined @samp{operator =}. +@end table + +@node Warning Options +@section Options to Request or Suppress Warnings +@cindex options to control warnings +@cindex warning messages +@cindex messages, warning +@cindex suppressing warnings + +Warnings are diagnostic messages that report constructions which +are not inherently erroneous but which are risky or suggest there +may have been an error. + +You can request many specific warnings with options beginning @samp{-W}, +for example @samp{-Wimplicit} to request warnings on implicit +declarations. Each of these specific warning options also has a +negative form beginning @samp{-Wno-} to turn off warnings; +for example, @samp{-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 GNU +CC: + +@table @code +@cindex syntax checking +@item -fsyntax-only +Check the code for syntax errors, but don't do anything beyond that. + +@item -pedantic +Issue all the warnings demanded by strict ANSI C and ISO C++; +reject all programs that use forbidden extensions. + +Valid ANSI C and ISO C++ programs should compile properly with or without +this option (though a rare few will require @samp{-ansi}). However, +without this option, certain GNU extensions and traditional C and C++ +features are supported as well. With this option, they are rejected. + +@samp{-pedantic} does not cause warning messages for use of the +alternate keywords whose names begin and end with @samp{__}. Pedantic +warnings are also disabled in the expression that follows +@code{__extension__}. However, only system header files should use +these escape routes; application programs should avoid them. +@xref{Alternate Keywords}. + +This option is not intended to be @i{useful}; it exists only to satisfy +pedants who would otherwise claim that GNU CC fails to support the ANSI +standard. + +Some users try to use @samp{-pedantic} to check programs for strict ANSI +C conformance. They soon find that it does not do quite what they want: +it finds some non-ANSI practices, but not all---only those for which +ANSI C @emph{requires} a diagnostic. + +A feature to report any failure to conform to ANSI C might be useful in +some instances, but would require considerable additional work and would +be quite different from @samp{-pedantic}. We don't have plans to +support such a feature in the near future. + +@item -pedantic-errors +Like @samp{-pedantic}, except that errors are produced rather than +warnings. + +@item -w +Inhibit all warning messages. + +@item -Wno-import +Inhibit warning messages about the use of @samp{#import}. + +@item -Wchar-subscripts +Warn if an array subscript has type @code{char}. This is a common cause +of error, as programmers often forget that this type is signed on some +machines. + +@item -Wcomment +Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} +comment, or whenever a Backslash-Newline appears in a @samp{//} comment. + +@item -Wformat +Check calls to @code{printf} and @code{scanf}, etc., to make sure that +the arguments supplied have types appropriate to the format string +specified. + +@item -Wimplicit-int +Warn when a declaration does not specify a type. + +@item -Wimplicit-function-declaration +@itemx -Werror-implicit-function-declaration +Give a warning (or error) whenever a function is used before being +declared. + +@item -Wimplicit +Same as @samp{-Wimplicit-int} and @samp{-Wimplicit-function-}@* +@samp{declaration}. + +@item -Wmain +Warn if the type of @samp{main} is suspicious. @samp{main} should be a +function with external linkage, returning int, taking either zero +arguments, two, or three arguments of appropriate types. + +@item -Wmultichar +Warn if a multicharacter constant (@samp{'FOOF'}) is used. Usually they +indicate a typo in the user's code, as they have implementation-defined +values, and should not be used in portable code. + +@item -Wparentheses +Warn if parentheses are omitted in certain contexts, such +as when there is an assignment in a context where a truth value +is expected, or when operators are nested whose precedence people +often get confused about. + +Also warn about constructions where there may be confusion to which +@code{if} statement an @code{else} branch belongs. Here is an example of +such a case: + +@smallexample +@{ + if (a) + if (b) + foo (); + else + bar (); +@} +@end smallexample + +In C, every @code{else} branch belongs to the innermost possible @code{if} +statement, which in this example is @code{if (b)}. This is often not +what the programmer expected, as illustrated in the above example by +indentation the programmer chose. When there is the potential for this +confusion, GNU C will issue a warning when this flag is specified. +To eliminate the warning, add explicit braces around the innermost +@code{if} statement so there is no way the @code{else} could belong to +the enclosing @code{if}. The resulting code would look like this: + +@smallexample +@{ + if (a) + @{ + if (b) + foo (); + else + bar (); + @} +@} +@end smallexample + +@item -Wreturn-type +Warn whenever a function is defined with a return-type that defaults +to @code{int}. Also warn about any @code{return} statement with no +return-value in a function whose return-type is not @code{void}. + +@item -Wswitch +Warn whenever a @code{switch} statement has an index of enumeral type +and lacks a @code{case} for one or more of the named codes of that +enumeration. (The presence of a @code{default} label prevents this +warning.) @code{case} labels outside the enumeration range also +provoke warnings when this option is used. + +@item -Wtrigraphs +Warn if any trigraphs are encountered (assuming they are enabled). + +@item -Wunused +Warn whenever a variable is unused aside from its declaration, +whenever a function is declared static but never defined, whenever a +label is declared but not used, and whenever a statement computes a +result that is explicitly not used. + +In order to get a warning about an unused function parameter, you must +specify both @samp{-W} and @samp{-Wunused}. + +To suppress this warning for an expression, simply cast it to void. For +unused variables, parameters and labels, use the @samp{unused} attribute +(@pxref{Variable Attributes}). + +@item -Wuninitialized +An automatic variable is used without first being initialized. + +These warnings are possible only in optimizing compilation, +because they require data flow information that is computed only +when optimizing. If you don't specify @samp{-O}, you simply won't +get these warnings. + +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 +is other than 1, 2, 4 or 8 bytes. Also, they do not occur for +structures, unions or arrays, even when they are in registers. + +Note that there may be no warning about a variable that is used only +to compute a value that itself is never used, because such +computations may be deleted by data flow analysis before the warnings +are printed. + +These warnings are made optional because GNU CC is not smart +enough to see all the reasons why the code might be correct +despite appearing to have an error. Here is one example of how +this can happen: + +@smallexample +@{ + int x; + switch (y) + @{ + case 1: x = 1; + break; + case 2: x = 4; + break; + case 3: x = 5; + @} + foo (x); +@} +@end smallexample + +@noindent +If the value of @code{y} is always 1, 2 or 3, then @code{x} is +always initialized, but GNU CC doesn't know this. Here is +another common case: + +@smallexample +@{ + int save_y; + if (change_y) save_y = y, y = new_y; + @dots{} + if (change_y) y = save_y; +@} +@end smallexample + +@noindent +This has no bug because @code{save_y} is used only if it is set. + +Some spurious warnings can be avoided if you declare all the functions +you use that never return as @code{noreturn}. @xref{Function +Attributes}. + +@item -Wunknown-pragmas +@cindex warning for unknown pragmas +@cindex unknown pragmas, warning +@cindex pragmas, warning of unknown +Warn when a #pragma directive is encountered which is not understood by +GCC. If this command line option is used, warnings will even be issued +for unknown pragmas in system header files. This is not the case if +the warnings were only enabled by the @samp{-Wall} command line option. + +@item -Wall +All of the above @samp{-W} options combined. This enables all the +warnings about constructions that some users consider questionable, and +that are easy to avoid (or modify to prevent the warning), even in +conjunction with macros. +@end table + +The following @samp{-W@dots{}} options are not implied by @samp{-Wall}. +Some of them warn about constructions that users generally do not +consider questionable, but which occasionally you might wish to check +for; others warn about constructions that are necessary or hard to avoid +in some cases, and there is no simple way to modify the code to suppress +the warning. + +@table @code +@item -W +Print extra warning messages for these events: + +@itemize @bullet +@cindex @code{longjmp} warnings +@item +A nonvolatile automatic variable might be changed by a call to +@code{longjmp}. These warnings as well are possible only in +optimizing compilation. + +The compiler sees only the calls to @code{setjmp}. It cannot know +where @code{longjmp} will be called; in fact, a signal handler could +call it at any point in the code. As a result, you may get a warning +even when there is in fact no problem because @code{longjmp} cannot +in fact be called at the place which would cause a problem. + +@item +A function can return either with or without a value. (Falling +off the end of the function body is considered returning without +a value.) For example, this function would evoke such a +warning: + +@smallexample +@group +foo (a) +@{ + if (a > 0) + return a; +@} +@end group +@end smallexample + +@item +An expression-statement or the left-hand side of a comma expression +contains no side effects. +To suppress the warning, cast the unused expression to void. +For example, an expression such as @samp{x[i,j]} will cause a warning, +but @samp{x[(void)i,j]} will not. + +@item +An unsigned value is compared against zero with @samp{<} or @samp{<=}. + +@item +A comparison like @samp{x<=y<=z} appears; this is equivalent to +@samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from +that of ordinary mathematical notation. + +@item +Storage-class specifiers like @code{static} are not the first things in +a declaration. According to the C Standard, this usage is obsolescent. + +@item +If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused +arguments. + +@item +A comparison between signed and unsigned values could produce an +incorrect result when the signed value is converted to unsigned. +(But don't warn if @samp{-Wno-sign-compare} is also specified.) + +@item +An aggregate has a partly bracketed initializer. +For example, the following code would evoke such a warning, +because braces are missing around the initializer for @code{x.h}: + +@smallexample +struct s @{ int f, g; @}; +struct t @{ struct s h; int i; @}; +struct t x = @{ 1, 2, 3 @}; +@end smallexample + +@item +An aggregate has an initializer which does not initialize all members. +For example, the following code would cause such a warning, because +@code{x.h} would be implicitly initialized to zero: + +@smallexample +struct s @{ int f, g, h; @}; +struct s x = @{ 3, 4 @}; +@end smallexample +@end itemize + +@item -Wtraditional +Warn about certain constructs that behave differently in traditional and +ANSI C. + +@itemize @bullet +@item +Macro arguments occurring within string constants in the macro body. +These would substitute the argument in traditional C, but are part of +the constant in ANSI C. + +@item +A function declared external in one block and then used after the end of +the block. + +@item +A @code{switch} statement has an operand of type @code{long}. +@end itemize + +@item -Wundef +Warn if an undefined identifier is evaluated in an @samp{#if} directive. + +@item -Wshadow +Warn whenever a local variable shadows another local variable. + +@item -Wid-clash-@var{len} +Warn whenever two distinct identifiers match in the first @var{len} +characters. This may helpyou prepare a program that will compile +with certain obsolete, brain-damaged compilers. + +@item -Wlarger-than-@var{len} +Warn whenever an object of larger than @var{len} bytes is defined. + +@item -Wpointer-arith +Warn about anything that depends on the ``size of'' a function type or +of @code{void}. GNU C assigns these types a size of 1, for +convenience in calculations with @code{void *} pointers and pointers +to functions. + +@item -Wbad-function-cast +Warn whenever a function call is cast to a non-matching type. +For example, warn if @code{int malloc()} is cast to @code{anything *}. + +@item -Wcast-qual +Warn whenever a pointer is cast so as to remove a type qualifier from +the target type. For example, warn if a @code{const char *} is cast +to an ordinary @code{char *}. + +@item -Wcast-align +Warn whenever a pointer is cast such that the required alignment of the +target is increased. For example, warn if a @code{char *} is cast to +an @code{int *} on machines where integers can only be accessed at +two- or four-byte boundaries. + +@item -Wwrite-strings +Give string constants the type @code{const char[@var{length}]} so that +copying the address of one into a non-@code{const} @code{char *} +pointer will get a warning. These warnings will help you find at +compile time code that can try to write into a string constant, but +only if you have been very careful about using @code{const} in +declarations and prototypes. Otherwise, it will just be a nuisance; +this is why we did not make @samp{-Wall} request these warnings. + +@item -Wconversion +Warn if a prototype causes a type conversion that is different from what +would happen to the same argument in the absence of a prototype. This +includes conversions of fixed point to floating and vice versa, and +conversions changing the width or signedness of a fixed point argument +except when the same as the default promotion. + +Also, warn if a negative integer constant expression is implicitly +converted to an unsigned type. For example, warn about the assignment +@code{x = -1} if @code{x} is unsigned. But do not warn about explicit +casts like @code{(unsigned) -1}. + +@item -Wsign-compare +@cindex warning for comparison of signed and unsigned values +@cindex comparison of signed and unsigned values, warning +@cindex signed and unsigned values, comparison warning +Warn when a comparison between signed and unsigned values could produce +an incorrect result when the signed value is converted to unsigned. +This warning is also enabled by @samp{-W}; to get the other warnings +of @samp{-W} without this warning, use @samp{-W -Wno-sign-compare}. + +@item -Waggregate-return +Warn if any functions that return structures or unions are defined or +called. (In languages where you can return an array, this also elicits +a warning.) + +@item -Wstrict-prototypes +Warn if a function is declared or defined without specifying the +argument types. (An old-style function definition is permitted without +a warning if preceded by a declaration which specifies the argument +types.) + +@item -Wmissing-prototypes +Warn if a global function is defined without a previous prototype +declaration. This warning is issued even if the definition itself +provides a prototype. The aim is to detect global functions that fail +to be declared in header files. + +@item -Wmissing-declarations +Warn if a global function is defined without a previous declaration. +Do so even if the definition itself provides a prototype. +Use this option to detect global functions that are not declared in +header files. + +@item -Wmissing-noreturn +Warn about functions which might be candidates for attribute @code{noreturn}. +Note these are only possible candidates, not absolute ones. Care should +be taken to manually verify functions actually do not ever return before +adding the @code{noreturn} attribute, otherwise subtle code generation +bugs could be introduced. + +@item -Wredundant-decls +Warn if anything is declared more than once in the same scope, even in +cases where multiple declaration is valid and changes nothing. + +@item -Wnested-externs +Warn if an @code{extern} declaration is encountered within an function. + +@item -Winline +Warn if a function can not be inlined, and either it was declared as inline, +or else the @samp{-finline-functions} option was given. + +@item -Wlong-long +Warn if @samp{long long} type is used. This is default. To inhibit +the warning messages, use @samp{-Wno-long-long}. Flags +@samp{-Wlong-long} and @samp{-Wno-long-long} are taken into account +only when @samp{-pedantic} flag is used. + +@item -Werror +Make all warnings into errors. +@end table + +@node Debugging Options +@section Options for Debugging Your Program or GNU CC +@cindex options, debugging +@cindex debugging information options + +GNU CC has various special options that are used for debugging +either your program or GCC: + +@table @code +@item -g +Produce debugging information in the operating system's native format +(stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging +information. + +On most systems that use stabs format, @samp{-g} enables use of extra +debugging information that only GDB can use; this extra information +makes debugging work better in GDB but will probably make other debuggers +crash or +refuse to read the program. If you want to control for certain whether +to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs}, +@samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf-1+}, or @samp{-gdwarf-1} +(see below). + +Unlike most other C compilers, GNU CC allows you to use @samp{-g} with +@samp{-O}. The shortcuts taken by optimized code may occasionally +produce surprising results: some variables you declared may not exist +at all; flow of control may briefly move where you did not expect it; +some statements may not be executed because they compute constant +results or their values were already at hand; some statements may +execute in different places because they were moved out of loops. + +Nevertheless it proves possible to debug optimized output. This makes +it reasonable to use the optimizer for programs that might have bugs. + +The following options are useful when GNU CC is generated with the +capability for more than one debugging format. + +@item -ggdb +Produce debugging information for use by GDB. This means to use the +most expressive format available (DWARF 2, stabs, or the native format +if neither of those are supported), including GDB extensions if at all +possible. + +@item -gstabs +Produce debugging information in stabs format (if that is supported), +without GDB extensions. This is the format used by DBX on most BSD +systems. On MIPS, Alpha and System V Release 4 systems this option +produces stabs debugging output which is not understood by DBX or SDB. +On System V Release 4 systems this option requires the GNU assembler. + +@item -gstabs+ +Produce debugging information in stabs format (if that is supported), +using GNU extensions understood only by the GNU debugger (GDB). The +use of these extensions is likely to make other debuggers crash or +refuse to read the program. + +@item -gcoff +Produce debugging information in COFF format (if that is supported). +This is the format used by SDB on most System V systems prior to +System V Release 4. + +@item -gxcoff +Produce debugging information in XCOFF format (if that is supported). +This is the format used by the DBX debugger on IBM RS/6000 systems. + +@item -gxcoff+ +Produce debugging information in XCOFF format (if that is supported), +using GNU extensions understood only by the GNU debugger (GDB). The +use of these extensions is likely to make other debuggers crash or +refuse to read the program, and may cause assemblers other than the GNU +assembler (GAS) to fail with an error. + +@item -gdwarf +Produce debugging information in DWARF version 1 format (if that is +supported). This is the format used by SDB on most System V Release 4 +systems. + +@item -gdwarf+ +Produce debugging information in DWARF version 1 format (if that is +supported), using GNU extensions understood only by the GNU debugger +(GDB). The use of these extensions is likely to make other debuggers +crash or refuse to read the program. + +@item -gdwarf-2 +Produce debugging information in DWARF version 2 format (if that is +supported). This is the format used by DBX on IRIX 6. + +@item -g@var{level} +@itemx -ggdb@var{level} +@itemx -gstabs@var{level} +@itemx -gcoff@var{level} +@itemx -gxcoff@var{level} +@itemx -gdwarf@var{level} +@itemx -gdwarf-2@var{level} +Request debugging information and also use @var{level} to specify how +much information. The default level is 2. + +Level 1 produces minimal information, enough for making backtraces in +parts of the program that you don't plan to debug. This includes +descriptions of functions and external variables, but no information +about local variables and no line numbers. + +Level 3 includes extra information, such as all the macro definitions +present in the program. Some debuggers support macro expansion when +you use @samp{-g3}. + +@cindex @code{prof} +@item -p +Generate extra code to write profile information suitable for the +analysis program @code{prof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. + +@cindex @code{gprof} +@item -pg +Generate extra code to write profile information suitable for the +analysis program @code{gprof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. + +@cindex @code{tcov} +@item -a +Generate extra code to write profile information for basic blocks, which will +record the number of times each basic block is executed, the basic block start +address, and the function name containing the basic block. If @samp{-g} is +used, the line number and filename of the start of the basic block will also be +recorded. If not overridden by the machine description, the default action is +to append to the text file @file{bb.out}. + +This data could be analyzed by a program like @code{tcov}. Note, +however, that the format of the data is not what @code{tcov} expects. +Eventually GNU @code{gprof} should be extended to process this data. + +@item -Q +Makes the compiler print out each function name as it is compiled, and +print some statistics about each pass when it finishes. + +@item -ax +Generate extra code to profile basic blocks. Your executable will +produce output that is a superset of that produced when @samp{-a} is +used. Additional output is the source and target address of the basic +blocks where a jump takes place, the number of times a jump is executed, +and (optionally) the complete sequence of basic blocks being executed. +The output is appended to file @file{bb.out}. + +You can examine different profiling aspects without recompilation. Your +executable will read a list of function names from file @file{bb.in}. +Profiling starts when a function on the list is entered and stops when +that invocation is exited. To exclude a function from profiling, prefix +its name with `-'. If a function name is not unique, you can +disambiguate it by writing it in the form +@samp{/path/filename.d:functionname}. Your executable will write the +available paths and filenames in file @file{bb.out}. + +Several function names have a special meaning: +@table @code +@item __bb_jumps__ +Write source, target and frequency of jumps to file @file{bb.out}. +@item __bb_hidecall__ +Exclude function calls from frequency count. +@item __bb_showret__ +Include function returns in frequency count. +@item __bb_trace__ +Write the sequence of basic blocks executed to file @file{bbtrace.gz}. +The file will be compressed using the program @samp{gzip}, which must +exist in your @code{PATH}. On systems without the @samp{popen} +function, the file will be named @file{bbtrace} and will not be +compressed. @strong{Profiling for even a few seconds on these systems +will produce a very large file.} Note: @code{__bb_hidecall__} and +@code{__bb_showret__} will not affect the sequence written to +@file{bbtrace.gz}. +@end table + +Here's a short example using different profiling parameters +in file @file{bb.in}. Assume function @code{foo} consists of basic blocks +1 and 2 and is called twice from block 3 of function @code{main}. After +the calls, block 3 transfers control to block 4 of @code{main}. + +With @code{__bb_trace__} and @code{main} contained in file @file{bb.in}, +the following sequence of blocks is written to file @file{bbtrace.gz}: +0 3 1 2 1 2 4. The return from block 2 to block 3 is not shown, because +the return is to a point inside the block and not to the top. The +block address 0 always indicates, that control is transferred +to the trace from somewhere outside the observed functions. With +@samp{-foo} added to @file{bb.in}, the blocks of function +@code{foo} are removed from the trace, so only 0 3 4 remains. + +With @code{__bb_jumps__} and @code{main} contained in file @file{bb.in}, +jump frequencies will be written to file @file{bb.out}. The +frequencies are obtained by constructing a trace of blocks +and incrementing a counter for every neighbouring pair of blocks +in the trace. The trace 0 3 1 2 1 2 4 displays the following +frequencies: + +@example +Jump from block 0x0 to block 0x3 executed 1 time(s) +Jump from block 0x3 to block 0x1 executed 1 time(s) +Jump from block 0x1 to block 0x2 executed 2 time(s) +Jump from block 0x2 to block 0x1 executed 1 time(s) +Jump from block 0x2 to block 0x4 executed 1 time(s) +@end example + +With @code{__bb_hidecall__}, control transfer due to call instructions +is removed from the trace, that is the trace is cut into three parts: 0 +3 4, 0 1 2 and 0 1 2. With @code{__bb_showret__}, control transfer due +to return instructions is added to the trace. The trace becomes: 0 3 1 +2 3 1 2 3 4. Note, that this trace is not the same, as the sequence +written to @file{bbtrace.gz}. It is solely used for counting jump +frequencies. + +@item -fprofile-arcs +Instrument @dfn{arcs} during compilation. For each function of your +program, GNU CC creates a program flow graph, then finds a spanning tree +for the graph. Only arcs that are not on the spanning tree have to be +instrumented: the compiler adds code to count the number of times that these +arcs are executed. When an arc is the only exit or only entrance to a +block, the instrumentation code can be added to the block; otherwise, a +new basic block must be created to hold the instrumentation code. + +Since not every arc in the program must be instrumented, programs +compiled with this option run faster than programs compiled with +@samp{-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 +@samp{-a}. + +@samp{-fprofile-arcs} also makes it possible to estimate branch +probabilities, and to calculate basic block execution counts. In +general, basic block execution counts do not give enough information to +estimate all branch probabilities. When the compiled program exits, it +saves the arc execution counts to a file called +@file{@var{sourcename}.da}. Use the compiler option +@samp{-fbranch-probabilities} (@pxref{Optimize Options,,Options that +Control Optimization}) when recompiling, to optimize using estimated +branch probabilities. + +@need 2000 +@item -ftest-coverage +Create data files for the @code{gcov} code-coverage utility +(@pxref{Gcov,, @code{gcov}: a GNU CC Test Coverage Program}). +The data file names begin with the name of your source file: + +@table @code +@item @var{sourcename}.bb +A mapping from basic blocks to line numbers, which @code{gcov} uses to +associate basic block execution counts with line numbers. + +@item @var{sourcename}.bbg +A list of all arcs in the program flow graph. This allows @code{gcov} +to reconstruct the program flow graph, so that it can compute all basic +block and arc execution counts from the information in the +@code{@var{sourcename}.da} file (this last file is the output from +@samp{-fprofile-arcs}). +@end table + +@item -Q +Makes the compiler print out each function name as it is compiled, and +print some statistics about each pass when it finishes. + +@item -d@var{letters} +Says to make debugging dumps during compilation at times specified by +@var{letters}. This is used for debugging the compiler. The file names +for most of the dumps are made by appending a word to the source file +name (e.g. @file{foo.c.rtl} or @file{foo.c.jump}). Here are the +possible letters for use in @var{letters}, and their meanings: + +@table @samp +@item b +Dump after computing branch probabilities, to @file{@var{file}.bp}. +@item c +Dump after instruction combination, to the file @file{@var{file}.combine}. +@item d +Dump after delayed branch scheduling, to @file{@var{file}.dbr}. +@item D +Dump all macro definitions, at the end of preprocessing, in addition to +normal output. +@item y +Dump debugging information during parsing, to standard error. +@item r +Dump after RTL generation, to @file{@var{file}.rtl}. +@item x +Just generate RTL for a function instead of compiling it. Usually used +with @samp{r}. +@item j +Dump after first jump optimization, to @file{@var{file}.jump}. +@item s +Dump after CSE (including the jump optimization that sometimes +follows CSE), to @file{@var{file}.cse}. +@item F +Dump after purging ADDRESSOF, to @file{@var{file}.addressof}. +@item f +Dump after flow analysis, to @file{@var{file}.flow}. +@item g +Dump after global register allocation, to @file{@var{file}.greg}. +@item G +Dump after GCSE, to @file{@var{file}.gcse}. +@item j +Dump after first jump optimization, to @file{@var{file}.jump}. +@item J +Dump after last jump optimization, to @file{@var{file}.jump2}. +@item k +Dump after conversion from registers to stack, to @file{@var{file}.stack}. +@item l +Dump after local register allocation, to @file{@var{file}.lreg}. +@item L +Dump after loop optimization, to @file{@var{file}.loop}. +@item M +Dump after performing the machine dependent reorganisation pass, to +@file{@var{file}.mach}. +@item N +Dump after the register move pass, to @file{@var{file}.regmove}. +@item r +Dump after RTL generation, to @file{@var{file}.rtl}. +@item R +Dump after the second instruction scheduling pass, to @file{@var{file}.sched2}. +@item s +Dump after CSE (including the jump optimization that sometimes follows +CSE), to @file{@var{file}.cse}. +@item S +Dump after the first instruction scheduling pass, to @file{@var{file}.sched}. +@item t +Dump after the second CSE pass (including the jump optimization that +sometimes follows CSE), to @file{@var{file}.cse2}. +@item x +Just generate RTL for a function instead of compiling it. Usually used +with @samp{r}. +@item a +Produce all the dumps listed above. +@item m +Print statistics on memory usage, at the end of the run, to +standard error. +@item p +Annotate the assembler output with a comment indicating which +pattern and alternative was used. +@item y +Dump debugging information during parsing, to standard error. +@item A +Annotate the assembler output with miscellaneous debugging information. +@end table + +@item -fdump-unnumbered +When doing debugging dumps (see -d option above), suppress instruction +numbers and line number note output. This makes it more feasible to +use diff on debugging dumps for compiler invokations with different +options, in particular with and without -g. + +@item -fpretend-float +When running a cross-compiler, pretend that the target machine uses the +same floating point format as the host machine. This causes incorrect +output of the actual floating constants, but the actual instruction +sequence will probably be the same as GNU CC would make when running on +the target machine. + +@item -save-temps +Store the usual ``temporary'' intermediate files permanently; place them +in the current directory and name them based on the source file. Thus, +compiling @file{foo.c} with @samp{-c -save-temps} would produce files +@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. + +@item -print-file-name=@var{library} +Print the full absolute name of the library file @var{library} that +would be used when linking---and don't do anything else. With this +option, GNU CC does not compile or link anything; it just prints the +file name. + +@item -print-prog-name=@var{program} +Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}. + +@item -print-libgcc-file-name +Same as @samp{-print-file-name=libgcc.a}. + +This is useful when you use @samp{-nostdlib} or @samp{-nodefaultlibs} +but you do want to link with @file{libgcc.a}. You can do + +@example +gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` +@end example + +@item -print-search-dirs +Print the name of the configured installation directory and a list of +program and library directories gcc will search---and don't do anything else. + +This is useful when gcc prints the error message +@samp{installation problem, cannot exec cpp: No such file or directory}. +To resolve this you either need to put @file{cpp} and the other compiler +components where gcc expects to find them, or you can set the environment +variable @code{GCC_EXEC_PREFIX} to the directory where you installed them. +Don't forget the trailing '/'. +@xref{Environment Variables}. +@end table + +@node Optimize Options +@section Options That Control Optimization +@cindex optimize options +@cindex options, optimization + +These options control various sorts of optimizations: + +@table @code +@item -O +@itemx -O1 +Optimize. Optimizing compilation takes somewhat more time, and a lot +more memory for a large function. + +Without @samp{-O}, the compiler's goal is to reduce the cost of +compilation and to make debugging produce the expected results. +Statements are independent: if you stop the program with a breakpoint +between statements, you can then assign a new value to any variable or +change the program counter to any other statement in the function and +get exactly the results you would expect from the source code. + +Without @samp{-O}, the compiler only allocates variables declared +@code{register} in registers. The resulting compiled code is a little +worse than produced by PCC without @samp{-O}. + +With @samp{-O}, the compiler tries to reduce code size and execution +time. + +When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps} +and @samp{-fdefer-pop} on all machines. The compiler turns on +@samp{-fdelayed-branch} on machines that have delay slots, and +@samp{-fomit-frame-pointer} on machines that can support debugging even +without a frame pointer. On some machines the compiler also turns +on other flags.@refill + +@item -O2 +Optimize even more. GNU CC performs nearly all supported optimizations +that do not involve a space-speed tradeoff. The compiler does not +perform loop unrolling or function inlining when you specify @samp{-O2}. +As compared to @samp{-O}, this option increases both compilation time +and the performance of the generated code. + +@samp{-O2} turns on all optional optimizations except for loop unrolling +and function inlining. It also turns on the @samp{-fforce-mem} option +on all machines and frame pointer elimination on machines where doing so +does not interfere with debugging. + +@item -O3 +Optimize yet more. @samp{-O3} turns on all optimizations specified by +@samp{-O2} and also turns on the @samp{inline-functions} option. + +@item -O0 +Do not optimize. + +@item -Os +Optimize for size. @samp{-Os} enables all @samp{-O2} optimizations that +do not typically increase code size. It also performs further +optimizations designed to reduce code size. + +If you use multiple @samp{-O} options, with or without level numbers, +the last such option is the one that is effective. +@end table + +Options of the form @samp{-f@var{flag}} specify machine-independent +flags. Most flags have both positive and negative forms; the negative +form of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, +only one of the forms is listed---the one which is not the default. +You can figure out the other form by either removing @samp{no-} or +adding it. + +@table @code +@item -ffloat-store +Do not store floating point variables in registers, and inhibit other +options that might change whether a floating point value is taken from a +register or memory. + +@cindex floating point precision +This option prevents undesirable excess precision on machines such as +the 68000 where the floating registers (of the 68881) keep more +precision than a @code{double} is supposed to have. Similarly for the +x86 architecture. For most programs, the excess precision does only +good, but a few programs rely on the precise definition of IEEE floating +point. Use @samp{-ffloat-store} for such programs, after modifying +them to store all pertinent intermediate computations into variables. + +@item -fno-default-inline +Do not make member functions inline by default merely because they are +defined inside the class scope (C++ only). Otherwise, when you specify +@w{@samp{-O}}, member functions defined inside class scope are compiled +inline by default; i.e., you don't need to add @samp{inline} in front of +the member function name. + +@item -fno-defer-pop +Always pop the arguments to each function call as soon as that function +returns. For machines which must pop arguments after a function call, +the compiler normally lets arguments accumulate on the stack for several +function calls and pops them all at once. + +@item -fforce-mem +Force memory operands to be copied into registers before doing +arithmetic on them. This produces better code by making all memory +references potential common subexpressions. When they are not common +subexpressions, instruction combination should eliminate the separate +register-load. The @samp{-O2} option turns on this option. + +@item -fforce-addr +Force memory address constants to be copied into registers before +doing arithmetic on them. This may produce better code just as +@samp{-fforce-mem} may. + +@item -fomit-frame-pointer +Don't keep the frame pointer in a register for functions that +don't need one. This avoids the instructions to save, set up and +restore frame pointers; it also makes an extra register available +in many functions. @strong{It also makes debugging impossible on +some machines.} + +@ifset INTERNALS +On some machines, such as the Vax, this flag has no effect, because +the standard calling sequence automatically handles the frame pointer +and nothing is saved by pretending it doesn't exist. The +machine-description macro @code{FRAME_POINTER_REQUIRED} controls +whether a target machine supports this flag. @xref{Registers}.@refill +@end ifset +@ifclear INTERNALS +On some machines, such as the Vax, this flag has no effect, because +the standard calling sequence automatically handles the frame pointer +and nothing is saved by pretending it doesn't exist. The +machine-description macro @code{FRAME_POINTER_REQUIRED} controls +whether a target machine supports this flag. @xref{Registers,,Register +Usage, gcc.info, Using and Porting GCC}.@refill +@end ifclear + +@item -fno-inline +Don't pay attention to the @code{inline} keyword. Normally this option +is used to keep the compiler from expanding any functions inline. +Note that if you are not optimizing, no functions can be expanded inline. + +@item -finline-functions +Integrate all simple functions into their callers. The compiler +heuristically decides which functions are simple enough to be worth +integrating in this way. + +If all calls to a given function are integrated, and the function is +declared @code{static}, then the function is normally not output as +assembler code in its own right. + +@item -fkeep-inline-functions +Even if all calls to a given function are integrated, and the function +is declared @code{static}, nevertheless output a separate run-time +callable version of the function. This switch does not affect +@code{extern inline} functions. + +@item -fkeep-static-consts +Emit variables declared @code{static const} when optimization isn't turned +on, even if the variables aren't referenced. + +GNU CC enables this option by default. If you want to force the compiler to +check if the variable was referenced, regardless of whether or not +optimization is turned on, use the @samp{-fno-keep-static-consts} option. + +@item -fno-function-cse +Do not put function addresses in registers; make each instruction that +calls a constant function contain the function's address explicitly. + +This option results in less efficient code, but some strange hacks +that alter the assembler output may be confused by the optimizations +performed when this option is not used. + +@item -ffast-math +This option allows GCC to violate some ANSI or IEEE rules and/or +specifications in the interest of optimizing code for speed. For +example, it allows the compiler to assume arguments to the @code{sqrt} +function are non-negative numbers and that no floating-point values +are NaNs. + +This option should never be turned on by any @samp{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ANSI rules/specifications for +math functions. +@end table + +@c following causes underfulls.. they don't look great, but we deal. +@c --mew 26jan93 +The following options control specific optimizations. The @samp{-O2} +option turns on all of these optimizations except @samp{-funroll-loops} +and @samp{-funroll-all-loops}. On most machines, the @samp{-O} option +turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options, +but specific machines may handle it differently. + +You can use the following flags in the rare cases when ``fine-tuning'' +of optimizations to be performed is desired. + +@table @code +@item -fstrength-reduce +Perform the optimizations of loop strength reduction and +elimination of iteration variables. + +@item -fthread-jumps +Perform optimizations where we check to see if a jump branches to a +location where another comparison subsumed by the first is found. If +so, the first branch is redirected to either the destination of the +second branch or a point immediately following it, depending on whether +the condition is known to be true or false. + +@item -fcse-follow-jumps +In common subexpression elimination, scan through jump instructions +when the target of the jump is not reached by any other path. For +example, when CSE encounters an @code{if} statement with an +@code{else} clause, CSE will follow the jump when the condition +tested is false. + +@item -fcse-skip-blocks +This is similar to @samp{-fcse-follow-jumps}, but causes CSE to +follow jumps which conditionally skip over blocks. When CSE +encounters a simple @code{if} statement with no else clause, +@samp{-fcse-skip-blocks} causes CSE to follow the jump around the +body of the @code{if}. + +@item -frerun-cse-after-loop +Re-run common subexpression elimination after loop optimizations has been +performed. + +@item -frerun-loop-opt +Run the loop optimizer twice. + +@item -fgcse +Perform a global common subexpression elimination pass. +This pass also performs global constant and copy propagation. + +@c CYGNUS LOCAL LRS +@item -flive-range +Perform live range splitting of variables at loop boundaries. This option +is enabled by default at @samp{-O2} optimization and higher for targets which +use stabs debug symbols. +@c END CYGNUS LOCAL + +@item -fexpensive-optimizations +Perform a number of minor optimizations that are relatively expensive. + +@item -foptimize-register-moves +@item -fregmove +Attempt to reassign register numbers in move instructions and as +operands of other simple instructions in order to maximize the amount of +register tying. This is especially helpful on machines with two-operand +instructions. GNU CC enables this optimization by default with @samp{-O2} +or higher. + +Note @code{-fregmove} and @code{-foptimize-register-moves} are the same +optimization. + +@item -fdelayed-branch +If supported for the target machine, attempt to reorder instructions +to exploit instruction slots available after delayed branch +instructions. + +@item -fschedule-insns +If supported for the target machine, attempt to reorder instructions to +eliminate execution stalls due to required data being unavailable. This +helps machines that have slow floating point or memory load instructions +by allowing other instructions to be issued until the result of the load +or floating point instruction is required. + +@item -fschedule-insns2 +Similar to @samp{-fschedule-insns}, but requests an additional pass of +instruction scheduling after register allocation has been done. This is +especially useful on machines with a relatively small number of +registers and where memory load instructions take more than one cycle. + +@item -ffunction-sections +@item -fdata-sections +Place each function or data item into its own section in the output +file if the target supports arbitrary sections. The name of the +function or the name of the data item determines the section's name +in the output file. + +Use these options on systems where the linker can perform optimizations +to improve locality of reference in the instruction space. HPPA +processors running HP-UX and Sparc processors running Solaris 2 have +linkers with such optimizations. Other systems using the ELF object format +as well as AIX may have these optimizations in the future. + +Only use these options when there are significant benefits from doing +so. When you specify these options, the assembler and linker will +create larger object and executable files and will also be slower. +You will not be able to use @code{gprof} on all systems if you +specify this option and you may have problems with debugging if +you specify both this option and @samp{-g}. + +@item -fcaller-saves +Enable values to be allocated in registers that will be clobbered by +function calls, by emitting extra instructions to save and restore the +registers around such calls. Such allocation is done only when it +seems to result in better code than would otherwise be produced. + +This option is always enabled by default on certain machines, usually +those which have no call-preserved registers to use instead. + +For all machines, optimization level 2 and higher enables this flag by +default. + +@item -funroll-loops +Perform the optimization of loop unrolling. This is only done for loops +whose number of iterations can be determined at compile time or run time. +@samp{-funroll-loop} implies both @samp{-fstrength-reduce} and +@samp{-frerun-cse-after-loop}. + +@item -funroll-all-loops +Perform the optimization of loop unrolling. This is done for all loops +and usually makes programs run more slowly. @samp{-funroll-all-loops} +implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}. + +@item -fmove-all-movables +Forces all invariant computations in loops to be moved +outside the loop. + +@item -freduce-all-givs +Forces all general-induction variables in loops to be +strength-reduced. + +@emph{Note:} When compiling programs written in Fortran, +@samp{-fmove-all-moveables} and @samp{-freduce-all-givs} are enabled +by default when you use the optimizer. + +These options may generate better or worse code; results are highly +dependent on the structure of loops within the source code. + +These two options are intended to be removed someday, once +they have helped determine the efficacy of various +approaches to improving loop optimizations. + +Please let us (@code{egcs@@cygnus.com} and @code{fortran@@gnu.org}) +know how use of these options affects +the performance of your production code. +We're very interested in code that runs @emph{slower} +when these options are @emph{enabled}. + +@item -fno-peephole +Disable any machine-specific peephole optimizations. + +@item -fbranch-probabilities +After running a program compiled with @samp{-fprofile-arcs} +(@pxref{Debugging Options,, Options for Debugging Your Program or +@code{gcc}}), you can compile it a second time using +@samp{-fbranch-probabilities}, to improve optimizations based on +guessing the path a branch might take. + +@ifset INTERNALS +With @samp{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT} +note on the first instruction of each basic block, and a +@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. +These can be used to improve optimization. Currently, they are only +used in one place: in @file{reorg.c}, instead of guessing which path a +branch is mostly to take, the @samp{REG_BR_PROB} values are used to +exactly determine which path is taken more often. +@end ifset + +@item -fstrict-aliasing +Allows the compiler to assume the strictest aliasing rules applicable to +the language being compiled. For C (and C++), this activates +optimizations based on the type of expressions. In particular, an +object of one type is assumed never to reside at the same address as an +object of a different type, unless the types are almost the same. For +example, an @code{unsigned int} can alias an @code{int}, but not a +@code{void*} or a @code{double}. A character type may alias any other +type. + +Pay special attention to code like this: +@example +union a_union @{ + int i; + double d; +@}; + +int f() @{ + a_union t; + t.d = 3.0; + return t.i; +@} +@end example +The practice of reading from a different union member than the one most +recently written to (called ``type-punning'') is common. Even with +@samp{-fstrict-aliasing}, type-punning is allowed, provided the memory +is accessed through the union type. So, the code above will work as +expected. However, this code might not: +@example +int f() @{ + a_union t; + int* ip; + t.d = 3.0; + ip = &t.i; + return *ip; +@} +@end example + +@ifset INTERNALS +Every language that wishes to perform language-specific alias analysis +should define a function that computes, given an @code{tree} +node, an alias set for the node. Nodes in different alias sets are not +allowed to alias. For an example, see the C front-end function +@code{c_get_alias_set}. +@end ifset + +@end table + +@node Preprocessor Options +@section Options Controlling the Preprocessor +@cindex preprocessor options +@cindex options, preprocessor + +These options control the C preprocessor, which is run on each C source +file before actual compilation. + +If you use the @samp{-E} option, nothing is done except preprocessing. +Some of these options make sense only together with @samp{-E} because +they cause the preprocessor output to be unsuitable for actual +compilation. + +@table @code +@item -include @var{file} +Process @var{file} as input before processing the regular input file. +In effect, the contents of @var{file} are compiled first. Any @samp{-D} +and @samp{-U} options on the command line are always processed before +@samp{-include @var{file}}, regardless of the order in which they are +written. All the @samp{-include} and @samp{-imacros} options are +processed in the order in which they are written. + +@item -imacros @var{file} +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 @samp{-imacros @var{file}} +is to make the macros defined in @var{file} available for use in the +main input. + +Any @samp{-D} and @samp{-U} options on the command line are always +processed before @samp{-imacros @var{file}}, regardless of the order in +which they are written. All the @samp{-include} and @samp{-imacros} +options are processed in the order in which they are written. + +@item -idirafter @var{dir} +@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 +@samp{-I} adds to). + +@item -iprefix @var{prefix} +Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix} +options. + +@item -iwithprefix @var{dir} +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 @samp{-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} +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 +@samp{-iwithprefix}. + +@item -isystem @var{dir} +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 -isystem-c++ @var{dir} +Same behavior as with @samp{-isystem}, but do not make headers in @var{dir} be +implicitly evaluated as if they include the @samp{extern "C"} linkage +specification. + +@item -nostdinc +Do not search the standard system directories for header files. Only +the directories you have specified with @samp{-I} options (and the +current directory, if appropriate) are searched. @xref{Directory +Options}, for information on @samp{-I}. + +By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file +search path to only those directories you specify explicitly. + +@item -undef +Do not predefine any nonstandard macros. (Including architecture flags). + +@item -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 +Tell the preprocessor not to discard comments. Used with the +@samp{-E} option. + +@item -P +Tell the preprocessor not to generate @samp{#line} directives. +Used with the @samp{-E} option. + +@cindex make +@cindex dependencies, make +@item -M +Tell the preprocessor to output a rule suitable for @code{make} +describing the dependencies of each object file. For each source file, +the preprocessor outputs one @code{make}-rule whose target is the object +file name for that source file and whose dependencies are all the +@code{#include} header files it uses. This rule may be a single line or +may be continued with @samp{\}-newline if it is long. The list of rules +is printed on standard output instead of the preprocessed C program. + +@samp{-M} implies @samp{-E}. + +Another way to specify output of a @code{make} rule is by setting +the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment +Variables}). + +@item -MM +Like @samp{-M} but the output mentions only the user header files +included with @samp{#include "@var{file}"}. System header files +included with @samp{#include <@var{file}>} are omitted. + +@item -MD +Like @samp{-M} but the dependency information is written to a file made by +replacing ".c" with ".d" at the end of the input file names. +This is in addition to compiling the file as specified---@samp{-MD} does +not inhibit ordinary compilation the way @samp{-M} does. + +In 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 +Like @samp{-MD} except mention only user header files, not system +header files. + +@item -MG +Treat missing header files as generated files and assume they live in the +same directory as the source file. If you specify @samp{-MG}, you +must also specify either @samp{-M} or @samp{-MM}. @samp{-MG} is not +supported with @samp{-MD} or @samp{-MMD}. + +@item -H +Print the name of each header file used, in addition to other normal +activities. + +@item -A@var{question}(@var{answer}) +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})}. @samp{-A-} disables the standard +assertions that normally describe the target machine. + +@item -D@var{macro} +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 @samp{-D} on +the command line are processed before any @samp{-U} options. + +@item -U@var{macro} +Undefine macro @var{macro}. @samp{-U} options are evaluated after all +@samp{-D} options, but before any @samp{-include} and @samp{-imacros} +options. + +@item -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 @samp{-E} +option. + +@item -dD +Tell the preprocessing to pass all macro definitions into the output, in +their proper sequence in the rest of the output. + +@item -dN +Like @samp{-dD} except that the macro arguments and contents are omitted. +Only @samp{#define @var{name}} is included in the output. + +@item -trigraphs +Support ANSI C trigraphs. The @samp{-ansi} option also has this effect. + +@item -Wp,@var{option} +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 + +@node Assembler Options +@section Passing Options to the Assembler + +@c prevent bad page break with this line +You can pass options to the assembler. + +@table @code +@item -Wa,@var{option} +Pass @var{option} as an option to the assembler. If @var{option} +contains commas, it is split into multiple options at the commas. +@end table + +@node Link Options +@section Options for Linking +@cindex link options +@cindex options, linking + +These options come into play when the compiler links object files into +an executable output file. They are meaningless if the compiler is +not doing a link step. + +@table @code +@cindex file names +@item @var{object-file-name} +A file name that does not end in a special recognized suffix is +considered to name an object file or library. (Object files are +distinguished from libraries by the linker according to the file +contents.) If linking is done, these object files are used as input +to the linker. + +@item -c +@itemx -S +@itemx -E +If any of these options is used, then the linker is not run, and +object file names should not be used as arguments. @xref{Overall +Options}. + +@cindex Libraries +@item -l@var{library} +Search the library named @var{library} when linking. + +It makes a difference where in the command you write this option; the +linker searches processes libraries and object files in the order they +are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z} +after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers +to functions in @samp{z}, those functions may not be loaded. + +The linker searches a standard list of directories for the library, +which is actually a file named @file{lib@var{library}.a}. The linker +then uses this file as if it had been specified precisely by name. + +The directories searched include several standard system directories +plus any that you specify with @samp{-L}. + +Normally the files found this way are library files---archive files +whose members are object files. The linker handles an archive file by +scanning through it for members which define symbols that have so far +been referenced but not defined. But if the file that is found is an +ordinary object file, it is linked in the usual fashion. The only +difference between using an @samp{-l} option and specifying a file name +is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a} +and searches several directories. + +@item -lobjc +You need this special case of the @samp{-l} option in order to +link an Objective C program. + +@item -nostartfiles +Do not use the standard system startup files when linking. +The standard system libraries are used normally, unless @code{-nostdlib} +or @code{-nodefaultlibs} is used. + +@item -nodefaultlibs +Do not use the standard system libraries when linking. +Only the libraries you specify will be passed to the linker. +The standard startup files are used normally, unless @code{-nostartfiles} +is used. The compiler may generate calls to memcmp, memset, and memcpy +for System V (and ANSI C) environments or to bcopy and bzero for +BSD environments. These entries are usually resolved by entries in +libc. These entry points should be supplied through some other +mechanism when this option is specified. + +@item -nostdlib +Do not use the standard system startup files or libraries when linking. +No startup files and only the libraries you specify will be passed to +the linker. The compiler may generate calls to memcmp, memset, and memcpy +for System V (and ANSI C) environments or to bcopy and bzero for +BSD environments. These entries are usually resolved by entries in +libc. These entry points should be supplied through some other +mechanism when this option is specified. + +@cindex @code{-lgcc}, use with @code{-nostdlib} +@cindex @code{-nostdlib} and unresolved references +@cindex unresolved references and @code{-nostdlib} +@cindex @code{-lgcc}, use with @code{-nodefaultlibs} +@cindex @code{-nodefaultlibs} and unresolved references +@cindex unresolved references and @code{-nodefaultlibs} +One of the standard libraries bypassed by @samp{-nostdlib} and +@samp{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines +that GNU CC uses to overcome shortcomings of particular machines, or special +needs for some languages. +@ifset INTERNALS +(@xref{Interface,,Interfacing to GNU CC Output}, for more discussion of +@file{libgcc.a}.) +@end ifset +@ifclear INTERNALS +(@xref{Interface,,Interfacing to GNU CC Output,gcc.info,Porting GNU CC}, +for more discussion of @file{libgcc.a}.) +@end ifclear +In most cases, you need @file{libgcc.a} even when you want to avoid +other standard libraries. In other words, when you specify @samp{-nostdlib} +or @samp{-nodefaultlibs} you should usually specify @samp{-lgcc} as well. +This ensures that you have no unresolved references to internal GNU CC +library subroutines. (For example, @samp{__main}, used to ensure C++ +constructors will be called; @pxref{Collect2,,@code{collect2}}.) + +@item -s +Remove all symbol table and relocation information from the executable. + +@item -static +On systems that support dynamic linking, this prevents linking with the shared +libraries. On other systems, this option has no effect. + +@item -shared +Produce a shared object which can then be linked with other objects to +form an executable. Not all systems support this option. You must +also specify @samp{-fpic} or @samp{-fPIC} on some systems when +you specify this option. + +@item -symbolic +Bind references to global symbols when building a shared object. Warn +about any unresolved references (unless overridden by the link editor +option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support +this option. + +@item -Xlinker @var{option} +Pass @var{option} as an option to the linker. You can use this to +supply system-specific linker options which GNU CC does not know how to +recognize. + +If you want to pass an option that takes an argument, you must use +@samp{-Xlinker} twice, once for the option and once for the argument. +For example, to pass @samp{-assert definitions}, you must write +@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write +@samp{-Xlinker "-assert definitions"}, because this passes the entire +string as a single argument, which is not what the linker expects. + +@item -Wl,@var{option} +Pass @var{option} as an option to the linker. If @var{option} contains +commas, it is split into multiple options at the commas. + +@item -u @var{symbol} +Pretend the symbol @var{symbol} is undefined, to force linking of +library modules to define it. You can use @samp{-u} multiple times with +different symbols to force loading of additional library modules. +@end table + +@node Directory Options +@section Options for Directory Search +@cindex directory options +@cindex options, directory search +@cindex search path + +These options specify directories to search for header files, for +libraries and for parts of the compiler: + +@table @code +@item -I@var{dir} +Add the directory @var{dir} to the head of the list of directories to be +searched for header files. This can be used to override a system header +file, substituting your own version, since these directories are +searched before the system header file directories. If you use more +than one @samp{-I} option, the directories are scanned in left-to-right +order; the standard system directories come after. + +@item -I- +Any directories you specify with @samp{-I} options before the @samp{-I-} +option are searched only for the case of @samp{#include "@var{file}"}; +they are not searched for @samp{#include <@var{file}>}. + +If additional directories are specified with @samp{-I} options after +the @samp{-I-}, these directories are searched for all @samp{#include} +directives. (Ordinarily @emph{all} @samp{-I} directories are used +this way.) + +In addition, the @samp{-I-} option inhibits the use of the current +directory (where the current input file came from) as the first search +directory for @samp{#include "@var{file}"}. There is no way to +override this effect of @samp{-I-}. With @samp{-I.} you can specify +searching the directory which was current when the compiler was +invoked. That is not exactly the same as what the preprocessor does +by default, but it is often satisfactory. + +@samp{-I-} does not inhibit the use of the standard system directories +for header files. Thus, @samp{-I-} and @samp{-nostdinc} are +independent. + +@item -L@var{dir} +Add directory @var{dir} to the list of directories to be searched +for @samp{-l}. + +@item -B@var{prefix} +This option specifies where to find the executables, libraries, +include files, and data files of the compiler itself. + +The compiler driver program runs one or more of the subprograms +@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries +@var{prefix} as a prefix for each program it tries to run, both with and +without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}). + +For each subprogram to be run, the compiler driver first tries the +@samp{-B} prefix, if any. If that name is not found, or if @samp{-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 +those results in a file name that is found, the unmodified program +name is searched for using the directories specified in your +@samp{PATH} environment variable. + +@samp{-B} prefixes that effectively specify directory names also apply +to libraries in the linker, because the compiler translates these +options into @samp{-L} options for the linker. They also apply to +includes files in the preprocessor, because the compiler translates these +options into @samp{-isystem} options for the preprocessor. In this case, +the compiler appends @samp{include} to the prefix. + +The run-time support file @file{libgcc.a} can also be searched for using +the @samp{-B} prefix, if needed. If it is not found there, the two +standard prefixes above are tried, and that is all. The file is left +out of the link if it is not found by those means. + +Another way to specify a prefix much like the @samp{-B} prefix is to use +the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment +Variables}. + +@item -specs=@var{file} +Process @var{file} after the compiler reads in the standard @file{specs} +file, in order to override the defaults that the @file{gcc} driver +program uses when determining what switches to pass to @file{cc1}, +@file{cc1plus}, @file{as}, @file{ld}, etc. More than one +@samp{-specs=}@var{file} can be specified on the command line, and they +are processed in order, from left to right. +@end table + +@node Target Options +@section Specifying Target Machine and Compiler Version +@cindex target options +@cindex cross compiling +@cindex specifying machine version +@cindex specifying compiler version and target machine +@cindex compiler version, specifying +@cindex target machine, specifying + +By default, GNU CC compiles code for the same type of machine that you +are using. However, it can also be installed as a cross-compiler, to +compile for some other type of machine. In fact, several different +configurations of GNU CC, for different target machines, can be +installed side by side. Then you specify which one to use with the +@samp{-b} option. + +In addition, older and newer versions of GNU CC can be installed side +by side. One of them (probably the newest) will be the default, but +you may sometimes wish to use another. + +@table @code +@item -b @var{machine} +The argument @var{machine} specifies the target machine for compilation. +This is useful when you have installed GNU CC as a cross-compiler. + +The value to use for @var{machine} is the same as was specified as the +machine type when configuring GNU CC as a cross-compiler. For +example, if a cross-compiler was configured with @samp{configure +i386v}, meaning to compile for an 80386 running System V, then you +would specify @samp{-b i386v} to run that cross compiler. + +When you do not specify @samp{-b}, it normally means to compile for +the same type of machine that you are using. + +@item -V @var{version} +The argument @var{version} specifies which version of GNU CC to run. +This is useful when multiple versions are installed. For example, +@var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0. + +The default version, when you do not specify @samp{-V}, is the last +version of GNU CC that you installed. +@end table + +The @samp{-b} and @samp{-V} options actually work by controlling part of +the file name used for the executable files and libraries used for +compilation. A given version of GNU CC, for a given target machine, is +normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill + +Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by +changing the names of these directories or adding alternate names (or +symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the +file @file{80386} is a link to the file @file{i386v}, then @samp{-b +80386} becomes an alias for @samp{-b i386v}. + +In one respect, the @samp{-b} or @samp{-V} do not completely change +to a different compiler: the top-level driver program @code{gcc} +that you originally invoked continues to run and invoke the other +executables (preprocessor, compiler per se, assembler and linker) +that do the real work. However, since no real work is done in the +driver program, it usually does not matter that the driver program +in use is not the one for the specified target and version. + +The only way that the driver program depends on the target machine is +in the parsing and handling of special machine-specific options. +However, this is controlled by a file which is found, along with the +other executables, in the directory for the specified version and +target machine. As a result, a single installed driver program adapts +to any specified target machine and compiler version. + +The driver program executable does control one significant thing, +however: the default version and target machine. Therefore, you can +install different instances of the driver program, compiled for +different targets or versions, under different names. + +For example, if the driver for version 2.0 is installed as @code{ogcc} +and that for version 2.1 is installed as @code{gcc}, then the command +@code{gcc} will use version 2.1 by default, while @code{ogcc} will use +2.0 by default. However, you can choose either version with either +command with the @samp{-V} option. + +@node Submodel Options +@section Hardware Models and Configurations +@cindex submodel options +@cindex specifying hardware config +@cindex hardware models and configurations, specifying +@cindex machine dependent options + +Earlier we discussed the standard option @samp{-b} which chooses among +different installed compilers for completely different target +machines, such as Vax vs. 68000 vs. 80386. + +In addition, each of these target machine types can have its own +special options, starting with @samp{-m}, to choose among various +hardware models or configurations---for example, 68010 vs 68020, +floating coprocessor or none. A single installed version of the +compiler can compile for any model or configuration, according to the +options specified. + +Some configurations of the compiler also support additional special +options, usually for compatibility with other compilers on the same +platform. + +@ifset INTERNALS +These options are defined by the macro @code{TARGET_SWITCHES} in the +machine description. The default for the options is also defined by +that macro, which enables you to change the defaults. +@end ifset + +@c CYGNUS LOCAL: z8k docs +@c CYGNUS LOCAL -- meissner/d10v + +@menu +* M680x0 Options:: +* VAX Options:: +* SPARC Options:: +* Convex Options:: +* AMD29K Options:: +* ARM Options:: +* Thumb Options:: +* MN10200 Options:: +* MN10300 Options:: +* M32R/D/X Options:: +* M88K Options:: +* RS/6000 and PowerPC Options:: +* RT Options:: +* MIPS Options:: +* i386 Options:: +* HPPA Options:: +* Intel 960 Options:: +* DEC Alpha Options:: +* Clipper Options:: +* H8/300 Options:: +* SH Options:: +* System V Options:: +* Z8000 Option:: +* V850 Options:: +* NS32K Options:: +* ARC Options:: +* D10V Options:: +@c CYGNUS LOCAL d30v yes, the blank line is needed. + +* D30V Options:: +@c END CYGNUS LOCAL + +@end menu + +@node M680x0 Options +@subsection M680x0 Options +@cindex M680x0 options + +These are the @samp{-m} options defined for the 68000 series. The default +values for these options depends on which style of 68000 was selected when +the compiler was configured; the defaults for the most common choices are +given below. + +@table @code +@item -m68000 +@itemx -mc68000 +Generate output for a 68000. This is the default +when the compiler is configured for 68000-based systems. + +Use this option for microcontrollers with a 68000 or EC000 core, +including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356. + +@item -m68020 +@itemx -mc68020 +Generate output for a 68020. This is the default +when the compiler is configured for 68020-based systems. + +@item -m68881 +Generate output containing 68881 instructions for floating point. +This is the default for most 68020 systems unless @samp{-nfp} was +specified when the compiler was configured. + +@item -m68030 +Generate output for a 68030. This is the default when the compiler is +configured for 68030-based systems. + +@item -m68040 +Generate output for a 68040. This is the default when the compiler is +configured for 68040-based systems. + +This option inhibits the use of 68881/68882 instructions that have to be +emulated by software on the 68040. Use this option if your 68040 does not +have code to emulate those instructions. + +@item -m68060 +Generate output for a 68060. This is the default when the compiler is +configured for 68060-based systems. + +This option inhibits the use of 68020 and 68881/68882 instructions that +have to be emulated by software on the 68060. Use this option if your 68060 +does not have code to emulate those instructions. + +@item -mcpu32 +Generate output for a CPU32. This is the default +when the compiler is configured for CPU32-based systems. + +Use this option for microcontrollers with a +CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334, +68336, 68340, 68341, 68349 and 68360. + +@item -m5200 +Generate output for a 520X "coldfire" family cpu. This is the default +when the compiler is configured for 520X-based systems. + +Use this option for microcontroller with a 5200 core, including +the MCF5202, MCF5203, MCF5204 and MCF5202. + + +@item -m68020-40 +Generate output for a 68040, without using any of the new instructions. +This results in code which can run relatively efficiently on either a +68020/68881 or a 68030 or a 68040. The generated code does use the +68881 instructions that are emulated on the 68040. + +@item -m68020-60 +Generate output for a 68060, without using any of the new instructions. +This results in code which can run relatively efficiently on either a +68020/68881 or a 68030 or a 68040. The generated code does use the +68881 instructions that are emulated on the 68060. + +@item -mfpa +Generate output containing Sun FPA instructions for floating point. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not available for all m68k +targets. Normally the facilities of the machine's usual C compiler are +used, but this can't be done directly in cross-compilation. You must +make your own arrangements to provide suitable library functions for +cross-compilation. The embedded targets @samp{m68k-*-aout} and +@samp{m68k-*-coff} do provide software floating point support. + +@item -mshort +Consider type @code{int} to be 16 bits wide, like @code{short int}. + +@item -mnobitfield +Do not use the bit-field instructions. The @samp{-m68000}, @samp{-mcpu32} +and @samp{-m5200} options imply @w{@samp{-mnobitfield}}. + +@item -mbitfield +Do use the bit-field instructions. The @samp{-m68020} option implies +@samp{-mbitfield}. This is the default if you use a configuration +designed for a 68020. + +@item -mrtd +Use a different function-calling convention, in which functions +that take a fixed number of arguments return with the @code{rtd} +instruction, which pops their arguments while returning. This +saves one instruction in the caller since there is no need to pop +the arguments there. + +This calling convention is incompatible with the one normally +used on Unix, so you cannot use it if you need to call libraries +compiled with the Unix compiler. + +Also, you must provide function prototypes for all functions that +take variable numbers of arguments (including @code{printf}); +otherwise incorrect code will be generated for calls to those +functions. + +In addition, seriously incorrect code will result if you call a +function with too many arguments. (Normally, extra arguments are +harmlessly ignored.) + +The @code{rtd} instruction is supported by the 68010, 68020, 68030, +68040, 68060 and CPU32 processors, but not by the 68000 or 5200. + +@item -malign-int +@itemx -mno-align-int +Control whether GNU CC aligns @code{int}, @code{long}, @code{long long}, +@code{float}, @code{double}, and @code{long double} variables on a 32-bit +boundary (@samp{-malign-int}) or a 16-bit boundary (@samp{-mno-align-int}). +Aligning variables on 32-bit boundaries produces code that runs somewhat +faster on processors with 32-bit busses at the expense of more memory. + +@strong{Warning:} if you use the @samp{-malign-int} switch, GNU CC will +align structures containing the above types differently than +most published application binary interface specifications for the m68k. + +@end table + +@node VAX Options +@subsection VAX Options +@cindex VAX options + +These @samp{-m} options are defined for the Vax: + +@table @code +@item -munix +Do not output certain jump instructions (@code{aobleq} and so on) +that the Unix assembler for the Vax cannot handle across long +ranges. + +@item -mgnu +Do output those jump instructions, on the assumption that you +will assemble with the GNU assembler. + +@item -mg +Output code for g-format floating point numbers instead of d-format. +@end table + +@node SPARC Options +@subsection SPARC Options +@cindex SPARC options + +These @samp{-m} switches are supported on the SPARC: + +@table @code +@item -mno-app-regs +@itemx -mapp-regs +Specify @samp{-mapp-regs} to generate output using the global registers +2 through 4, which the SPARC SVR4 ABI reserves for applications. This +is the default. + +To be fully SVR4 ABI compliant at the cost of some performance loss, +specify @samp{-mno-app-regs}. You should compile libraries and system +software with this option. + +@item -mfpu +@itemx -mhard-float +Generate output containing floating point instructions. This is the +default. + +@item -mno-fpu +@itemx -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not available for all SPARC +targets. Normally the facilities of the machine's usual C compiler are +used, but this cannot be done directly in cross-compilation. You must make +your own arrangements to provide suitable library functions for +cross-compilation. The embedded targets @samp{sparc-*-aout} and +@samp{sparclite-*-*} do provide software floating point support. + +@samp{-msoft-float} changes the calling convention in the output file; +therefore, it is only useful if you compile @emph{all} of a program with +this option. In particular, you need to compile @file{libgcc.a}, the +library that comes with GNU CC, with @samp{-msoft-float} in order for +this to work. + +@item -mhard-quad-float +Generate output containing quad-word (long double) floating point +instructions. + +@item -msoft-quad-float +Generate output containing library calls for quad-word (long double) +floating point instructions. The functions called are those specified +in the SPARC ABI. This is the default. + +As of this writing, there are no sparc implementations that have hardware +support for the quad-word floating point instructions. They all invoke +a trap handler for one of these instructions, and then the trap handler +emulates the effect of the instruction. Because of the trap handler overhead, +this is much slower than calling the ABI library routines. Thus the +@samp{-msoft-quad-float} option is the default. + +@item -mno-epilogue +@itemx -mepilogue +With @samp{-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 @samp{-mno-epilogue}, the compiler tries to emit exit code inline +at every function exit. + +@item -mno-flat +@itemx -mflat +With @samp{-mflat}, the compiler does not generate save/restore instructions +and will use a "flat" or single register window calling convention. +This model uses %i7 as the frame pointer and is compatible with the normal +register window model. Code from either may be intermixed. +The local registers and the input registers (0-5) are still treated as +"call saved" registers and will be saved on the stack as necessary. + +With @samp{-mno-flat} (the default), the compiler emits save/restore +instructions (except for leaf functions) and is the normal mode of operation. + +@item -mno-unaligned-doubles +@itemx -munaligned-doubles +Assume that doubles have 8 byte alignment. This is the default. + +With @samp{-munaligned-doubles}, GNU CC assumes that doubles have 8 byte +alignment only if they are contained in another type, or if they have an +absolute address. Otherwise, it assumes they have 4 byte alignment. +Specifying this option avoids some rare compatibility problems with code +generated by other compilers. It is not the default because it results +in a performance loss, especially for floating point code. + +@item -mv8 +@itemx -msparclite +These two options select variations on the SPARC architecture. + +By default (unless specifically configured for the Fujitsu SPARClite), +GCC generates code for the v7 variant of the SPARC architecture. + +@samp{-mv8} will give you SPARC v8 code. The only difference from v7 +code is that the compiler emits the integer multiply and integer +divide instructions which exist in SPARC v8 but not in SPARC v7. + +@samp{-msparclite} will give you SPARClite code. This adds the integer +multiply, integer divide step and scan (@code{ffs}) instructions which +exist in SPARClite but not in SPARC v7. + +These options are deprecated and will be deleted in GNU CC 2.9. +They have been replaced with @samp{-mcpu=xxx}. + +@item -mcypress +@itemx -msupersparc +These two options select the processor for which the code is optimised. + +With @samp{-mcypress} (the default), the compiler optimizes code for the +Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series. +This is also appropriate for the older SparcStation 1, 2, IPX etc. + +With @samp{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as +used in the SparcStation 10, 1000 and 2000 series. This flag also enables use +of the full SPARC v8 instruction set. + +These options are deprecated and will be deleted in GNU CC 2.9. +They have been replaced with @samp{-mcpu=xxx}. + +@item -mcpu=@var{cpu_type} +Set the instruction set, register set, and instruction scheduling parameters +for machine type @var{cpu_type}. Supported values for @var{cpu_type} are +@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite}, +@samp{hypersparc}, @samp{sparclite86x}, @samp{f930}, @samp{f934}, +@samp{sparclet}, @samp{tsc701}, @samp{v9}, and @samp{ultrasparc}. + +Default instruction scheduling parameters are used for values that select +an architecture and not an implementation. These are @samp{v7}, @samp{v8}, +@samp{sparclite}, @samp{sparclet}, @samp{v9}. + +Here is a list of each supported architecture and their supported +implementations. + +@smallexample + v7: cypress + v8: supersparc, hypersparc + sparclite: f930, f934, sparclite86x + sparclet: tsc701 + v9: ultrasparc +@end smallexample + +@item -mtune=@var{cpu_type} +Set the instruction scheduling parameters for machine type +@var{cpu_type}, but do not set the instruction set or register set that the +option @samp{-mcpu=}@var{cpu_type} would. + +The same values for @samp{-mcpu=}@var{cpu_type} are used for +@samp{-mtune=}@*@var{cpu_type}, though the only useful values are those that +select a particular cpu implementation: @samp{cypress}, @samp{supersparc}, +@samp{hypersparc}, @samp{f930}, @samp{f934}, @samp{sparclite86x}, +@samp{tsc701}, @samp{ultrasparc}. + +@item -malign-loops=@var{num} +Align loops to a 2 raised to a @var{num} byte boundary. If +@samp{-malign-loops} is not specified, the default is 2. + +@item -malign-jumps=@var{num} +Align instructions that are only jumped to to a 2 raised to a @var{num} +byte boundary. If @samp{-malign-jumps} is not specified, the default is 2. + +@item -malign-functions=@var{num} +Align the start of functions to a 2 raised to @var{num} byte boundary. +If @samp{-malign-functions} is not specified, the default is 2 if compiling +for 32 bit sparc, and 5 if compiling for 64 bit sparc. + +@end table + +These @samp{-m} switches are supported in addition to the above +on the SPARCLET processor. + +@table @code +@item -mlittle-endian +Generate code for a processor running in little-endian mode. + +@item -mlive-g0 +Treat register @code{%g0} as a normal register. +GCC will continue to clobber it as necessary but will not assume +it always reads as 0. + +@item -mbroken-saverestore +Generate code that does not use non-trivial forms of the @code{save} and +@code{restore} instructions. Early versions of the SPARCLET processor do +not correctly handle @code{save} and @code{restore} instructions used with +arguments. They correctly handle them used without arguments. A @code{save} +instruction used without arguments increments the current window pointer +but does not allocate a new stack frame. It is assumed that the window +overflow trap handler will properly handle this case as will interrupt +handlers. +@end table + +These @samp{-m} switches are supported in addition to the above +on SPARC V9 processors in 64 bit environments. + +@table @code +@item -mlittle-endian +Generate code for a processor running in little-endian mode. + +@item -m32 +@itemx -m64 +Generate code for a 32 bit or 64 bit environment. +The 32 bit environment sets int, long and pointer to 32 bits. +The 64 bit environment sets int to 32 bits and long and pointer +to 64 bits. + +@item -mcmodel=medlow +Generate code for the Medium/Low code model: the program must be linked +in the low 32 bits of the address space. Pointers are 64 bits. +Programs can be statically or dynamically linked. + +@item -mcmodel=medmid +Generate code for the Medium/Middle code model: the program must be linked +in the low 44 bits of the address space, the text segment must be less than +2G bytes, and data segment must be within 2G of the text segment. +Pointers are 64 bits. + +@item -mcmodel=medany +Generate code for the Medium/Anywhere code model: the program may be linked +anywhere in the address space, the text segment must be less than +2G bytes, and data segment must be within 2G of the text segment. +Pointers are 64 bits. + +@item -mcmodel=embmedany +Generate code for the Medium/Anywhere code model for embedded systems: +assume a 32 bit text and a 32 bit data segment, both starting anywhere +(determined at link time). Register %g4 points to the base of the +data segment. Pointers still 64 bits. +Programs are statically linked, PIC is not supported. + +@item -mstack-bias +@itemx -mno-stack-bias +With @samp{-mstack-bias}, GNU CC assumes that the stack pointer, and +frame pointer if present, are offset by -2047 which must be added back +when making stack frame references. +Otherwise, assume no such offset is present. +@end table + +@node Convex Options +@subsection Convex Options +@cindex Convex options + +These @samp{-m} options are defined for Convex: + +@table @code +@item -mc1 +Generate output for C1. The code will run on any Convex machine. +The preprocessor symbol @code{__convex__c1__} is defined. + +@item -mc2 +Generate output for C2. Uses instructions not available on C1. +Scheduling and other optimizations are chosen for max performance on C2. +The preprocessor symbol @code{__convex_c2__} is defined. + +@item -mc32 +Generate output for C32xx. Uses instructions not available on C1. +Scheduling and other optimizations are chosen for max performance on C32. +The preprocessor symbol @code{__convex_c32__} is defined. + +@item -mc34 +Generate output for C34xx. Uses instructions not available on C1. +Scheduling and other optimizations are chosen for max performance on C34. +The preprocessor symbol @code{__convex_c34__} is defined. + +@item -mc38 +Generate output for C38xx. Uses instructions not available on C1. +Scheduling and other optimizations are chosen for max performance on C38. +The preprocessor symbol @code{__convex_c38__} is defined. + +@item -margcount +Generate code which puts an argument count in the word preceding each +argument list. This is compatible with regular CC, and a few programs +may need the argument count word. GDB and other source-level debuggers +do not need it; this info is in the symbol table. + +@item -mnoargcount +Omit the argument count word. This is the default. + +@item -mvolatile-cache +Allow volatile references to be cached. This is the default. + +@item -mvolatile-nocache +Volatile references bypass the data cache, going all the way to memory. +This is only needed for multi-processor code that does not use standard +synchronization instructions. Making non-volatile references to volatile +locations will not necessarily work. + +@item -mlong32 +Type long is 32 bits, the same as type int. This is the default. + +@item -mlong64 +Type long is 64 bits, the same as type long long. This option is useless, +because no library support exists for it. +@end table + +@node AMD29K Options +@subsection AMD29K Options +@cindex AMD29K options + +These @samp{-m} options are defined for the AMD Am29000: + +@table @code +@item -mdw +@kindex -mdw +@cindex DW bit (29k) +Generate code that assumes the @code{DW} bit is set, i.e., that byte and +halfword operations are directly supported by the hardware. This is the +default. + +@item -mndw +@kindex -mndw +Generate code that assumes the @code{DW} bit is not set. + +@item -mbw +@kindex -mbw +@cindex byte writes (29k) +Generate code that assumes the system supports byte and halfword write +operations. This is the default. + +@item -mnbw +@kindex -mnbw +Generate code that assumes the systems does not support byte and +halfword write operations. @samp{-mnbw} implies @samp{-mndw}. + +@item -msmall +@kindex -msmall +@cindex memory model (29k) +Use a small memory model that assumes that all function addresses are +either within a single 256 KB segment or at an absolute address of less +than 256k. This allows the @code{call} instruction to be used instead +of a @code{const}, @code{consth}, @code{calli} sequence. + +@item -mnormal +@kindex -mnormal +Use the normal memory model: Generate @code{call} instructions only when +calling functions in the same file and @code{calli} instructions +otherwise. This works if each file occupies less than 256 KB but allows +the entire executable to be larger than 256 KB. This is the default. + +@item -mlarge +Always use @code{calli} instructions. Specify this option if you expect +a single file to compile into more than 256 KB of code. + +@item -m29050 +@kindex -m29050 +@cindex processor selection (29k) +Generate code for the Am29050. + +@item -m29000 +@kindex -m29000 +Generate code for the Am29000. This is the default. + +@item -mkernel-registers +@kindex -mkernel-registers +@cindex kernel and user registers (29k) +Generate references to registers @code{gr64-gr95} instead of to +registers @code{gr96-gr127}. This option can be used when compiling +kernel code that wants a set of global registers disjoint from that used +by user-mode code. + +Note that when this option is used, register names in @samp{-f} flags +must use the normal, user-mode, names. + +@item -muser-registers +@kindex -muser-registers +Use the normal set of global registers, @code{gr96-gr127}. This is the +default. + +@item -mstack-check +@itemx -mno-stack-check +@kindex -mstack-check +@cindex stack checks (29k) +Insert (or do not insert) a call to @code{__msp_check} after each stack +adjustment. This is often used for kernel code. + +@item -mstorem-bug +@itemx -mno-storem-bug +@kindex -mstorem-bug +@cindex storem bug (29k) +@samp{-mstorem-bug} handles 29k processors which cannot handle the +separation of a mtsrim insn and a storem instruction (most 29000 chips +to date, but not the 29050). + +@item -mno-reuse-arg-regs +@itemx -mreuse-arg-regs +@kindex -mreuse-arg-regs +@samp{-mno-reuse-arg-regs} tells the compiler to only use incoming argument +registers for copying out arguments. This helps detect calling a function +with fewer arguments than it was declared with. + +@item -mno-impure-text +@itemx -mimpure-text +@kindex -mimpure-text +@samp{-mimpure-text}, used in addition to @samp{-shared}, tells the compiler to +not pass @samp{-assert pure-text} to the linker when linking a shared object. + +@item -msoft-float +@kindex -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GNU CC. +Normally the facilities of the machine's usual C compiler are used, but +this can't be done directly in cross-compilation. You must make your +own arrangements to provide suitable library functions for +cross-compilation. +@end table + +@node ARM Options +@subsection ARM Options +@cindex ARM options + +These @samp{-m} options are defined for Advanced RISC Machines (ARM) +architectures: + +@table @code +@item -mapcs-frame +@kindex -mapcs-frame +Generate a stack frame that is compliant with the ARM Procedure Call +Standard for all functions, even if this is not strictly necessary for +correct execution of the code. Specifying @samp{-fomit-frame-pointer} +with this option will cause the stack frames not to be generated for +leaf functions. The default is @samp{-mno-apcs-frame}. + +@item -mapcs +@kindex -mapcs +This is a synonym for @samp{-mapcs-frame}. + +@item -mapcs-26 +@kindex -mapcs-26 +Generate code for a processor running with a 26-bit program counter, +and conforming to the function calling standards for the APCS 26-bit +option. This option replaces the @samp{-m2} and @samp{-m3} options +of previous releases of the compiler. + +@item -mapcs-32 +@kindex -mapcs-32 +Generate code for a processor running with a 32-bit program counter, +and conforming to the function calling standards for the APCS 32-bit +option. This option replaces the @samp{-m6} option of previous releases +of the compiler. + +@item -mapcs-stack-check +@kindex -mapcs-stack-check +@kindex -mno-apcs-stack-check +Generate code to check the amount of stack space available upon entry to +every function (that actually uses some stack space). If there is +insufficient space available then either the function +@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be +called, depending upon the amount of stack space required. The run time +system is required to provide these functions. The default is +@samp{-mno-apcs-stack-check}, since this produces smaller code. + +@item -mapcs-float +@kindex -mapcs-float +@kindex -mno-apcs-float +Pass floating point arguments using the float point registers. This is +one of the variants of the APCS. This option is reccommended if the +target hardware has a floating point unit or if a lot of floating point +arithmetic is going to be performed by the code. The default is +@samp{-mno-apcs-float}, since integer only code is slightly increased in +size if @samp{-mapcs-float} is used. + +@item -mapcs-reentrant +@kindex -mapcs-reentrant +@kindex -mno-apcs-reentrant +Generate reentrant, position independent code. This is the equivalent +to specifying the @samp{-fpic} option. The default is +@samp{-mno-apcs-reentrant}. + +@item -mthumb-interwork +@kindex -mthumb-interwork +@kindex -mno-thumb-interwork +Generate code which supports calling between the ARM and THUMB +instruction sets. Without this option the two instruction sets cannot +be reliably used inside one program. The default is +@samp{-mno-thumb-interwork}, since slightly larger code is generated +when @samp{-mthumb-interwork} is specified. + +@item -mno-sched-prolog +@kindex -mno-sched-prolog +@kindex -msched-prolog +Prevent the reordering of instructions in the function prolog, or the +merging of those instruction with the instructions in the function's +body. This means that all functions will start with a recognisable set +of instructions (or in fact one of a chioce from a small set of +different function prologues), and this information can be used to +locate the start if functions inside an executable piece of code. The +default is @samp{-msched-prolog}. + +@item -mhard-float +Generate output containing floating point instructions. This is the +default. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not available for all ARM +targets. Normally the facilities of the machine's usual C compiler are +used, but this cannot be done directly in cross-compilation. You must make +your own arrangements to provide suitable library functions for +cross-compilation. + +@samp{-msoft-float} changes the calling convention in the output file; +therefore, it is only useful if you compile @emph{all} of a program with +this option. In particular, you need to compile @file{libgcc.a}, the +library that comes with GNU CC, with @samp{-msoft-float} in order for +this to work. + +@item -mlittle-endian +Generate code for a processor running in little-endian mode. This is +the default for all standard configurations. + +@item -mbig-endian +Generate code for a processor running in big-endian mode; the default is +to compile code for a little-endian processor. + +@item -mwords-little-endian +This option only applies when generating code for big-endian processors. +Generate code for a little-endian word order but a big-endian byte +order. That is, a byte order of the form @samp{32107654}. Note: this +option should only be used if you require compatibility with code for +big-endian ARM processors generated by versions of the compiler prior to +2.8. + +@item -mshort-load-bytes +@kindex -mshort-load-bytes +Do not try to load half-words (eg @samp{short}s) by loading a word from +an unaligned address. For some targets the MMU is configured to trap +unaligned loads; use this option to generate code that is safe in these +environments. + +@item -mno-short-load-bytes +@kindex -mno-short-load-bytes +Use unaligned word loads to load half-words (eg @samp{short}s). This +option produces more efficient code, but the MMU is sometimes configured +to trap these instructions. + +@item -mshort-load-words +@kindex -mshort-load-words +This is a synonym for the @samp{-mno-short-load-bytes}. + +@item -mno-short-load-words +@kindex -mno-short-load-words +This is a synonym for the @samp{-mshort-load-bytes}. + +@item -mbsd +@kindex -mbsd +This option only applies to RISC iX. Emulate the native BSD-mode +compiler. This is the default if @samp{-ansi} is not specified. + +@item -mxopen +@kindex -mxopen +This option only applies to RISC iX. Emulate the native X/Open-mode +compiler. + +@item -mno-symrename +@kindex -mno-symrename +This option only applies to RISC iX. Do not run the assembler +post-processor, @samp{symrename}, after code has been assembled. +Normally it is necessary to modify some of the standard symbols in +preparation for linking with the RISC iX C library; this option +suppresses this pass. The post-processor is never run when the +compiler is built for cross-compilation. + +@item -mcpu=<name> +@kindex -mcpu= +This specifies the name of the target ARM processor. GCC uses this name +to determine what kind of instructions it can use when generating +assembly code. Permissable names are: arm2, arm250, arm3, arm6, arm60, +arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi, +arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe, +arm7tdmi, arm8, strongarm, strongarm110 + +@item -march=<name> +@kindex -march= +This specifies the name of the target ARM architecture. GCC uses this +name to determine what kind of instructions it can use when generating +assembly code. This option can be used in conjunction with or instead +of the @samp{-mcpu=} option. Permissable names are: armv2, armv2a, +armv3, armv3m, armv4, armv4t + +@item -mfpe=<number> +@kindex -mfpe= +This specifes the version of the floating point emulation available on +the target. Permissable values are 2 and 3. + +@item -mstructure-size-boundary=<n> +@kindex -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. Permissable 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 produced 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. Programmers are encouraged to use the 32 +value as future versions of the toolchain may default to this value. + +@item -mabort-on-noreturn +@kindex -mabort-on-noreturn +@kindex -mnoabort-on-noreturn +Generate a call to the function abort at the end of a noreturn function. +It will be executed if the function tries to return. + +@c CYGNUS LOCAL nickc/thumb-pe +@item -mnop-fun-dllimport +@kindex -mnop-fun-dllimport +Disable the support for the @emph{dllimport} attribute. + +@c END CYGNUS LOCAL + +@end table + + +@node Thumb Options +@subsection Thumb Options +@cindex Thumb Options + +@table @code + +@item -mthumb-interwork +@kindex -mthumb-interwork +@kindex -mno-thumb-interwork +Generate code which supports calling between the THUMB and ARM +instruction sets. Without this option the two instruction sets cannot +be reliably used inside one program. The default is +@samp{-mno-thumb-interwork}, since slightly smaller code is generated +with this option. + +@item -mtpcs-frame +@kindex -mtpcs-frame +@kindex -mno-tpcs-frame +Generate a stack frame that is compliant with the Thumb Procedure Call +Standard for all non-leaf functions. (A leaf function is one that does +not call any other functions). The default is @samp{-mno-apcs-frame}. + +@item -mtpcs-leaf-frame +@kindex -mtpcs-leaf-frame +@kindex -mno-tpcs-leaf-frame +Generate a stack frame that is compliant with the Thumb Procedure Call +Standard for all leaf functions. (A leaf function is one that does +not call any other functions). The default is @samp{-mno-apcs-leaf-frame}. + +@item -mlittle-endian +@kindex -mlittle-endian +Generate code for a processor running in little-endian mode. This is +the default for all standard configurations. + +@item -mbig-endian +@kindex -mbig-endian +Generate code for a processor running in big-endian mode. + +@item -mstructure-size-boundary=<n> +@kindex -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. Permissable 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 produced 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. Programmers are encouraged to use the 32 +value as future versions of the toolchain may default to this value. + +@c CYGNUS LOCAL nickc/thumb-pe +@item -mnop-fun-dllimport +@kindex -mnop-fun-dllimport +Disable the support for the @emph{dllimport} attribute. + +@item -mcallee-super-interworking +@kindex -mcallee-super-interworking +Gives all externally visible functions in the file being compiled an ARM +instruction set header which switches to Thumb mode before executing the +rest of the function. This allows these functions to be called from +non-interworking code. + +@item -mcaller-super-interworking +@kindex -mcaller-super-interworking +Allows calls via function pointers (including virtual functions) to +execute correctly regardless of whether the target code has been +compiled for interworking or not. There is a small overhead in the cost +of executing a funciton pointer if this option is enabled. + +@c END CYGNUS LOCAL + +@end table + +@node MN10200 Options +@subsection MN10200 Options +@cindex MN10200 options +These @samp{-m} options are defined for Matsushita MN10200 architectures: +@table @code + +@item -mrelax +Indicate to the linker that it should perform a relaxation optimization pass +to shorten branches, calls and absolute memory addresses. This option only +has an effect when used on the command line for the final link step. + +This option makes symbolic debugging impossible. +@end table + +@node MN10300 Options +@subsection MN10300 Options +@cindex MN10300 options +These @samp{-m} options are defined for Matsushita MN10300 architectures: + +@table @code +@item -mmult-bug +Generate code to avoid bugs in the multiply instructions for the MN10300 +processors. This is the default. + +@item -mno-mult-bug +Do not generate code to avoid bugs in the multiply instructions for the +MN10300 processors. + +@item -mrelax +Indicate to the linker that it should perform a relaxation optimization pass +to shorten branches, calls and absolute memory addresses. This option only +has an effect when used on the command line for the final link step. + +This option makes symbolic debugging impossible. +@end table + + +@node M32R/D/X Options +@subsection M32R/D/X Options +@cindex M32R/D/X options + +These @samp{-m} options are defined for Mitsubishi M32R/D/X architectures: + +@table @code +@item -mcode-model=small +Assume all objects live in the lower 16MB of memory (so that their addresses +can be loaded with the @code{ld24} instruction), and assume all subroutines +are reachable with the @code{bl} instruction. +This is the default. + +The addressability of a particular object can be set with the +@code{model} attribute. + +@item -mcode-model=medium +Assume objects may be anywhere in the 32 bit address space (the compiler +will generate @code{seth/add3} instructions to load their addresses), and +assume all subroutines are reachable with the @code{bl} instruction. + +@item -mcode-model=large +Assume objects may be anywhere in the 32 bit address space (the compiler +will generate @code{seth/add3} instructions to load their addresses), and +assume subroutines may not be reachable with the @code{bl} instruction +(the compiler will generate the much slower @code{seth/add3/jl} +instruction sequence). + +@item -msdata=none +Disable use of the small data area. Variables will be put into +one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the +@code{section} attribute has been specified). +This is the default. + +The small data area consists of sections @samp{.sdata} and @samp{.sbss}. +Objects may be explicitly put in the small data area with the +@code{section} attribute using one of these sections. + +@item -msdata=sdata +Put small global and static data in the small data area, but do not +generate special code to reference them. + +@item -msdata=use +Put small global and static data in the small data area, and generate +special instructions to reference them. + +@item -G @var{num} +@cindex smaller data references +Put global and static objects less than or equal to @var{num} bytes +into the small data or bss sections instead of the normal data or bss +sections. The default value of @var{num} is 8. +The @samp{-msdata} option must be set to one of @samp{sdata} or @samp{use} +for this option to have any effect. + +All modules should be compiled with the same @samp{-G @var{num}} value. +Compiling with different values of @var{num} may or may not work; if it +doesn't the linker will give an error message - incorrect code will not be +generated. + +@item -m32rx +@cindex m32rx instruction set +Enable support for the extended m32rx instruction set. If this option +is given to the compiler then the compile time constant __M32RX__ will +automatically be defined. + +@item -m32r +@cindex m32r instruction set +Disable support for the extended m32rx instruction set, and just use the +ordinary m32r instruction set instead. + +@item -mcond-exec=@var{n} +Specify the maximum number of conditionally executed instructions that +replace a branch. The default is 4. + + +@end table + +@node M88K Options +@subsection M88K Options +@cindex M88k options + +These @samp{-m} options are defined for Motorola 88k architectures: + +@table @code +@item -m88000 +@kindex -m88000 +Generate code that works well on both the m88100 and the +m88110. + +@item -m88100 +@kindex -m88100 +Generate code that works best for the m88100, but that also +runs on the m88110. + +@item -m88110 +@kindex -m88110 +Generate code that works best for the m88110, and may not run +on the m88100. + +@item -mbig-pic +@kindex -mbig-pic +Obsolete option to be removed from the next revision. +Use @samp{-fPIC}. + +@item -midentify-revision +@kindex -midentify-revision +@kindex ident +@cindex identifying source, compiler (88k) +Include an @code{ident} directive in the assembler output recording the +source file name, compiler name and version, timestamp, and compilation +flags used. + +@item -mno-underscores +@kindex -mno-underscores +@cindex underscores, avoiding (88k) +In assembler output, emit symbol names without adding an underscore +character at the beginning of each name. The default is to use an +underscore as prefix on each name. + +@item -mocs-debug-info +@itemx -mno-ocs-debug-info +@kindex -mocs-debug-info +@kindex -mno-ocs-debug-info +@cindex OCS (88k) +@cindex debugging, 88k OCS +Include (or omit) additional debugging information (about registers used +in each stack frame) as specified in the 88open Object Compatibility +Standard, ``OCS''. This extra information allows debugging of code that +has had the frame pointer eliminated. The default for DG/UX, SVr4, and +Delta 88 SVr3.2 is to include this information; other 88k configurations +omit this information by default. + +@item -mocs-frame-position +@kindex -mocs-frame-position +@cindex register positions in frame (88k) +When emitting COFF debugging information for automatic variables and +parameters stored on the stack, use the offset from the canonical frame +address, which is the stack pointer (register 31) on entry to the +function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use +@samp{-mocs-frame-position}; other 88k configurations have the default +@samp{-mno-ocs-frame-position}. + +@item -mno-ocs-frame-position +@kindex -mno-ocs-frame-position +@cindex register positions in frame (88k) +When emitting COFF debugging information for automatic variables and +parameters stored on the stack, use the offset from the frame pointer +register (register 30). When this option is in effect, the frame +pointer is not eliminated when debugging information is selected by the +-g switch. + +@item -moptimize-arg-area +@itemx -mno-optimize-arg-area +@kindex -moptimize-arg-area +@kindex -mno-optimize-arg-area +@cindex arguments in frame (88k) +Control how function arguments are stored in stack frames. +@samp{-moptimize-arg-area} saves space by optimizing them, but this +conflicts with the 88open specifications. The opposite alternative, +@samp{-mno-optimize-arg-area}, agrees with 88open standards. By default +GNU CC does not optimize the argument area. + +@item -mshort-data-@var{num} +@kindex -mshort-data-@var{num} +@cindex smaller data references (88k) +@cindex r0-relative references (88k) +Generate smaller data references by making them relative to @code{r0}, +which allows loading a value using a single instruction (rather than the +usual two). You control which data references are affected by +specifying @var{num} with this option. For example, if you specify +@samp{-mshort-data-512}, then the data references affected are those +involving displacements of less than 512 bytes. +@samp{-mshort-data-@var{num}} is not effective for @var{num} greater +than 64k. + +@item -mserialize-volatile +@kindex -mserialize-volatile +@itemx -mno-serialize-volatile +@kindex -mno-serialize-volatile +@cindex sequential consistency on 88k +Do, or don't, generate code to guarantee sequential consistency +of volatile memory references. By default, consistency is +guaranteed. + +The order of memory references made by the MC88110 processor does +not always match the order of the instructions requesting those +references. In particular, a load instruction may execute before +a preceding store instruction. Such reordering violates +sequential consistency of volatile memory references, when there +are multiple processors. When consistency must be guaranteed, +GNU C generates special instructions, as needed, to force +execution in the proper order. + +The MC88100 processor does not reorder memory references and so +always provides sequential consistency. However, by default, GNU +C generates the special instructions to guarantee consistency +even when you use @samp{-m88100}, so that the code may be run on an +MC88110 processor. If you intend to run your code only on the +MC88100 processor, you may use @samp{-mno-serialize-volatile}. + +The extra code generated to guarantee consistency may affect the +performance of your application. If you know that you can safely +forgo this guarantee, you may use @samp{-mno-serialize-volatile}. + +@item -msvr4 +@itemx -msvr3 +@kindex -msvr4 +@kindex -msvr3 +@cindex assembler syntax, 88k +@cindex SVr4 +Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions +related to System V release 4 (SVr4). This controls the following: + +@enumerate +@item +Which variant of the assembler syntax to emit. +@item +@samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak} +that is used on System V release 4. +@item +@samp{-msvr4} makes GNU CC issue additional declaration directives used in +SVr4. +@end enumerate + +@samp{-msvr4} is the default for the m88k-motorola-sysv4 and +m88k-dg-dgux m88k configurations. @samp{-msvr3} is the default for all +other m88k configurations. + +@item -mversion-03.00 +@kindex -mversion-03.00 +This option is obsolete, and is ignored. +@c ??? which asm syntax better for GAS? option there too? + +@item -mno-check-zero-division +@itemx -mcheck-zero-division +@kindex -mno-check-zero-division +@kindex -mcheck-zero-division +@cindex zero division on 88k +Do, or don't, generate code to guarantee that integer division by +zero will be detected. By default, detection is guaranteed. + +Some models of the MC88100 processor fail to trap upon integer +division by zero under certain conditions. By default, when +compiling code that might be run on such a processor, GNU C +generates code that explicitly checks for zero-valued divisors +and traps with exception number 503 when one is detected. Use of +mno-check-zero-division suppresses such checking for code +generated to run on an MC88100 processor. + +GNU C assumes that the MC88110 processor correctly detects all +instances of integer division by zero. When @samp{-m88110} is +specified, both @samp{-mcheck-zero-division} and +@samp{-mno-check-zero-division} are ignored, and no explicit checks for +zero-valued divisors are generated. + +@item -muse-div-instruction +@kindex -muse-div-instruction +@cindex divide instruction, 88k +Use the div instruction for signed integer division on the +MC88100 processor. By default, the div instruction is not used. + +On the MC88100 processor the signed integer division instruction +div) traps to the operating system on a negative operand. The +operating system transparently completes the operation, but at a +large cost in execution time. By default, when compiling code +that might be run on an MC88100 processor, GNU C emulates signed +integer division using the unsigned integer division instruction +divu), thereby avoiding the large penalty of a trap to the +operating system. Such emulation has its own, smaller, execution +cost in both time and space. To the extent that your code's +important signed integer division operations are performed on two +nonnegative operands, it may be desirable to use the div +instruction directly. + +On the MC88110 processor the div instruction (also known as the +divs instruction) processes negative operands without trapping to +the operating system. When @samp{-m88110} is specified, +@samp{-muse-div-instruction} is ignored, and the div instruction is used +for signed integer division. + +Note that the result of dividing INT_MIN by -1 is undefined. In +particular, the behavior of such a division with and without +@samp{-muse-div-instruction} may differ. + +@item -mtrap-large-shift +@itemx -mhandle-large-shift +@kindex -mtrap-large-shift +@kindex -mhandle-large-shift +@cindex bit shift overflow (88k) +@cindex large bit shifts (88k) +Include code to detect bit-shifts of more than 31 bits; respectively, +trap such shifts or emit code to handle them properly. By default GNU CC +makes no special provision for large bit shifts. + +@item -mwarn-passed-structs +@kindex -mwarn-passed-structs +@cindex structure passing (88k) +Warn when a function passes a struct as an argument or result. +Structure-passing conventions have changed during the evolution of the C +language, and are often the source of portability problems. By default, +GNU CC issues no such warning. +@end table + +@node RS/6000 and PowerPC Options +@subsection IBM RS/6000 and PowerPC Options +@cindex RS/6000 and PowerPC Options +@cindex IBM RS/6000 and PowerPC Options + +These @samp{-m} options are defined for the IBM RS/6000 and PowerPC: +@table @code +@item -mpower +@itemx -mno-power +@itemx -mpower2 +@itemx -mno-power2 +@itemx -mpowerpc +@itemx -mno-powerpc +@itemx -mpowerpc-gpopt +@itemx -mno-powerpc-gpopt +@itemx -mpowerpc-gfxopt +@itemx -mno-powerpc-gfxopt +@itemx -mpowerpc64 +@itemx -mno-powerpc64 +@kindex -mpower +@kindex -mpower2 +@kindex -mpowerpc +@kindex -mpowerpc-gpopt +@kindex -mpowerpc-gfxopt +@kindex -mpowerpc64 +GNU CC supports two related instruction set architectures for the +RS/6000 and PowerPC. The @dfn{POWER} instruction set are those +instructions supported by the @samp{rios} chip set used in the original +RS/6000 systems and the @dfn{PowerPC} instruction set is the +architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and +the IBM 4xx microprocessors. + +Neither architecture is a subset of the other. However there is a +large common subset of instructions supported by both. An MQ +register is included in processors supporting the POWER architecture. + +You use these options to specify which instructions are available on the +processor you are using. The default value of these options is +determined when configuring GNU CC. Specifying the +@samp{-mcpu=@var{cpu_type}} overrides the specification of these +options. We recommend you use the @samp{-mcpu=@var{cpu_type}} option +rather than the options listed above. + +The @samp{-mpower} option allows GNU CC to generate instructions that +are found only in the POWER architecture and to use the MQ register. +Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC +to generate instructions that are present in the POWER2 architecture but +not the original POWER architecture. + +The @samp{-mpowerpc} option allows GNU CC to generate instructions that +are found only in the 32-bit subset of the PowerPC architecture. +Specifying @samp{-mpowerpc-gpopt} implies @samp{-mpowerpc} and also allows +GNU CC to use the optional PowerPC architecture instructions in the +General Purpose group, including floating-point square root. Specifying +@samp{-mpowerpc-gfxopt} implies @samp{-mpowerpc} and also allows GNU CC to +use the optional PowerPC architecture instructions in the Graphics +group, including floating-point select. + +The @samp{-mpowerpc64} option allows GNU CC to generate the additional +64-bit instructions that are found in the full PowerPC64 architecture +and to treat GPRs as 64-bit, doubleword quantities. GNU CC defaults to +@samp{-mno-powerpc64}. + +If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC +will use only the instructions in the common subset of both +architectures plus some special AIX common-mode calls, and will not use +the MQ register. Specifying both @samp{-mpower} and @samp{-mpowerpc} +permits GNU CC to use any instruction from either architecture and to +allow use of the MQ register; specify this for the Motorola MPC601. + +@item -mnew-mnemonics +@itemx -mold-mnemonics +@kindex -mnew-mnemonics +@kindex -mold-mnemonics +Select which mnemonics to use in the generated assembler code. +@samp{-mnew-mnemonics} requests output that uses the assembler mnemonics +defined for the PowerPC architecture, while @samp{-mold-mnemonics} +requests the assembler mnemonics defined for the POWER architecture. +Instructions defined in only one architecture have only one mnemonic; +GNU CC uses that mnemonic irrespective of which of these options is +specified. + +GNU CC defaults to the mnemonics appropriate for the architecture in +use. Specifying @samp{-mcpu=@var{cpu_type}} sometimes overrides the +value of these option. Unless you are building a cross-compiler, you +should normally not specify either @samp{-mnew-mnemonics} or +@samp{-mold-mnemonics}, but should instead accept the default. + +@item -mcpu=@var{cpu_type} +@kindex -mcpu +Set architecture type, register usage, choice of mnemonics, and +instruction scheduling parameters for machine type @var{cpu_type}. +Supported values for @var{cpu_type} are @samp{rs6000}, @samp{rios1}, +@samp{rios2}, @samp{rsc}, @samp{601}, @samp{602}, @samp{603}, +@samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{740}, +@samp{750}, @samp{power}, @samp{power2}, @samp{powerpc}, @samp{403}, +@samp{505}, @samp{801}, @samp{821}, @samp{823}, and @samp{860} and +@samp{common}. @samp{-mcpu=power}, @samp{-mcpu=power2}, and +@samp{-mcpu=powerpc} specify generic POWER, POWER2 and pure PowerPC +(i.e., not MPC601) architecture machine types, with an appropriate, +generic processor model assumed for scheduling purposes.@refill + +@c overfull hbox here --bob 22 jul96 +@c original text between ignore ... end ignore +@ignore +Specifying any of the @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, +@samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} options +enables the @samp{-mpower} option and disables the @samp{-mpowerpc} +option; @samp{-mcpu=601} enables both the @samp{-mpower} and +@samp{-mpowerpc} options; all of @samp{-mcpu=602}, @samp{-mcpu=603}, +@samp{-mcpu=603e}, @samp{-mcpu=604}, @samp{-mcpu=604e}, +@samp{-mcpu=620}, @samp{-mcpu=403}, @samp{-mcpu=505}, @samp{-mcpu=801}, +@c CYGNUS LOCAL vmakarov +@samp{-mcpu=740}, @samp{-mcpu=750}, +@c END CYGNUS LOCAL +@samp{-mcpu=821}, @samp{-mcpu=823}, @samp{-mcpu=860} and +@samp{-mcpu=powerpc} enable the @samp{-mpowerpc} option and disable the +@samp{-mpower} option; @samp{-mcpu=common} disables both the +@samp{-mpower} and @samp{-mpowerpc} options.@refill +@end ignore +@c changed paragraph +Specifying any of the following options: +@samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, +@samp{-mcpu=power}, or @samp{-mcpu=power2} +enables the @samp{-mpower} option and disables the @samp{-mpowerpc} option; +@samp{-mcpu=601} enables both the @samp{-mpower} and @samp{-mpowerpc} options. +All of @samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e}, +@samp{-mcpu=604}, @samp{-mcpu=620}, +enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option. +Exactly similarly, all of @samp{-mcpu=403}, +@samp{-mcpu=505}, @samp{-mcpu=821}, @samp{-mcpu=860} and @samp{-mcpu=powerpc} +enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option. +@samp{-mcpu=common} disables both the +@samp{-mpower} and @samp{-mpowerpc} options.@refill +@c end changes to prevent overfull hboxes + +AIX versions 4 or greater selects @samp{-mcpu=common} by default, so +that code will operate on all members of the RS/6000 and PowerPC +families. In that case, GNU CC will use only the instructions in the +common subset of both architectures plus some special AIX common-mode +calls, and will not use the MQ register. GNU CC assumes a generic +processor model for scheduling purposes. + +Specifying any of the options @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, +@samp{-mcpu=rsc}, @samp{-mcpu=power}, or @samp{-mcpu=power2} also +disables the @samp{new-mnemonics} option. Specifying @samp{-mcpu=601}, +@samp{-mcpu=602}, @samp{-mcpu=603}, @samp{-mcpu=603e}, @samp{-mcpu=604}, +@samp{620}, @samp{403}, or @samp{-mcpu=powerpc} also enables the +@samp{new-mnemonics} option.@refill + +Specifying @samp{-mcpu=403}, @samp{-mcpu=821}, or @samp{-mcpu=860} also +enables the @samp{-msoft-float} option. + +@item -mtune=@var{cpu_type} +Set the instruction scheduling parameters for machine type +@var{cpu_type}, but do not set the architecture type, register usage, +choice of mnemonics like @samp{-mcpu=}@var{cpu_type} would. The same +values for @var{cpu_type} are used for @samp{-mtune=}@var{cpu_type} as +for @samp{-mcpu=}@var{cpu_type}. The @samp{-mtune=}@var{cpu_type} +option overrides the @samp{-mcpu=}@var{cpu_type} option in terms of +instruction scheduling parameters. + +@item -mfull-toc +@itemx -mno-fp-in-toc +@itemx -mno-sum-in-toc +@itemx -mminimal-toc +@kindex -mminimal-toc +Modify generation of the TOC (Table Of Contents), which is created for +every executable file. The @samp{-mfull-toc} option is selected by +default. In that case, GNU CC will allocate at least one TOC entry for +each unique non-automatic variable reference in your program. GNU CC +will also place floating-point constants in the TOC. However, only +16,384 entries are available in the TOC. + +If you receive a linker error message that saying you have overflowed +the available TOC space, you can reduce the amount of TOC space used +with the @samp{-mno-fp-in-toc} and @samp{-mno-sum-in-toc} options. +@samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point +constants in the TOC and @samp{-mno-sum-in-toc} forces GNU CC to +generate code to calculate the sum of an address and a constant at +run-time instead of putting that sum into the TOC. You may specify one +or both of these options. Each causes GNU CC to produce very slightly +slower and larger code at the expense of conserving TOC space. + +If you still run out of space in the TOC even when you specify both of +these options, specify @samp{-mminimal-toc} instead. This option causes +GNU CC to make only one TOC entry for every file. When you specify this +option, GNU CC will produce code that is slower and larger but which +uses extremely little TOC space. You may wish to use this option +only on files that contain less frequently executed code. @refill + +@item -maix64 +@itemx -maix32 +@kindex -maix64 +@kindex -maix32 +Enable AIX 64-bit ABI and calling convention: 64-bit pointers, 64-bit +@code{long} type, and the infrastructure needed to support them. +Specifying @samp{-maix64} implies @samp{-mpowerpc64} and +@samp{-mpowerpc}, while @samp{-maix32} disables the 64-bit ABI and +implies @samp{-mno-powerpc64}. GNU CC defaults to @samp{-maix32}. + +@item -mxl-call +@itemx -mno-xl-call +@kindex -mxl-call +On AIX, pass floating-point arguments to prototyped functions beyond the +register save area (RSA) on the stack in addition to argument FPRs. The +AIX calling convention was extended but not initially documented to +handle an obscure K&R C case of calling a function that takes the +address of its arguments with fewer arguments than declared. AIX XL +compilers access floating point arguments which do not fit in the +RSA from the stack when a subroutine is compiled without +optimization. Because always storing floating-point arguments on the +stack is inefficient and rarely needed, this option is not enabled by +default and only is necessary when calling subroutines compiled by AIX +XL compilers without optimization. + +@item -mthreads +@kindex -mthreads +Support @dfn{AIX Threads}. Link an application written to use +@dfn{pthreads} with special libraries and startup code to enable the +application to run. + +@item -mpe +@kindex -mpe +Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE). Link an +application written to use message passing with special startup code to +enable the application to run. The system must have PE installed in the +standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file +must be overridden with the @samp{-specs=} option to specify the +appropriate directory location. The Parallel Environment does not +support threads, so the @samp{-mpe} option and the @samp{-mthreads} +option are incompatible. + +@item -msoft-float +@itemx -mhard-float +@kindex -msoft-float +Generate code that does not use (uses) the floating-point register set. +Software floating point emulation is provided if you use the +@samp{-msoft-float} option, and pass the option to GNU CC when linking. + +@item -mmultiple +@itemx -mno-multiple +Generate code that uses (does not use) the load multiple word +instructions and the store multiple word instructions. These +instructions are generated by default on POWER systems, and not +generated on PowerPC systems. Do not use @samp{-mmultiple} on little +endian PowerPC systems, since those instructions do not work when the +processor is in little endian mode. The exceptions are PPC740 and +PPC750 which permit the instructions usage in little endian mode. + +@item -mstring +@itemx -mno-string +@kindex -mstring +Generate code that uses (does not use) the load string instructions +and the store string word instructions to save multiple registers and +do small block moves. These instructions are generated by default on +POWER systems, and not generated on PowerPC systems. Do not use +@samp{-mstring} on little endian PowerPC systems, since those +instructions do not work when the processor is in little endian mode. +The exceptions are PPC740 and PPC750 which permit the instructions +usage in little endian mode. + +@item -mupdate +@itemx -mno-update +@kindex -mupdate +Generate code that uses (does not use) the load or store instructions +that update the base register to the address of the calculated memory +location. These instructions are generated by default. If you use +@samp{-mno-update}, there is a small window between the time that the +stack pointer is updated and the address of the previous frame is +stored, which means code that walks the stack frame across interrupts or +signals may get corrupted data. + +@item -mfused-madd +@itemx -mno-fused-madd +@kindex -mfused-madd +Generate code that uses (does not use) the floating point multiply and +accumulate instructions. These instructions are generated by default if +hardware floating is used. + +@item -mno-bit-align +@itemx -mbit-align +@kindex -mbit-align +On System V.4 and embedded PowerPC systems do not (do) force structures +and unions that contain bit fields to be aligned to the base type of the +bit field. + +For example, by default a structure containing nothing but 8 +@code{unsigned} bitfields of length 1 would be aligned to a 4 byte +boundary and have a size of 4 bytes. By using @samp{-mno-bit-align}, +the structure would be aligned to a 1 byte boundary and be one byte in +size. + +@c CYGNUS LOCAL vmakarov +@item -mno-bit-word +@itemx -mbit-word +On System V.4 and embedded PowerPC systems do not (do) force structures +and unions that contain bit fields to align the bit field within the +structure to the base type of the bitfield. Unlike @samp{-mbit-align} +and @samp{-mno-bit-align}, the alignment of the structure itself is not +changed, just the alignment of bitfields within the structure. + +For example, by default, the structure: + +@smallexample +struct A @{ + int :0; + int i2:20; + int i3:17; +@}; +@end smallexample + +would normally put the field @var{i3} starting at bit 20, and it would +cross the word boundary. If you use @samp{-mno-bit-word}, the field +will begin on the next word boundary so that it does not cross a word +boundary. + +@item -mbranch-cost=@var{n} +Set the value of the internal macro @samp{BRANCH_COST} to be @var{n}. +Higher values mean branches are more costly, so the compiler will try +harder to generate code that does not use branches. The default is 3. +@c END CYGNUS LOCAL + +@item -mno-strict-align +@itemx -mstrict-align +@kindex -mstrict-align +On System V.4 and embedded PowerPC systems do not (do) assume that +unaligned memory references will be handled by the system. + +@item -mrelocatable +@itemx -mno-relocatable +@kindex -mrelocatable +On embedded PowerPC systems generate code that allows (does not allow) +the program to be relocated to a different address at runtime. If you +use @samp{-mrelocatable} on any module, all objects linked together must +be compiled with @samp{-mrelocatable} or @samp{-mrelocatable-lib}. + +@item -mrelocatable-lib +@itemx -mno-relocatable-lib +On embedded PowerPC systems generate code that allows (does not allow) +the program to be relocated to a different address at runtime. Modules +compiled with @samp{-mrelocatable-lib} can be linked with either modules +compiled without @samp{-mrelocatable} and @samp{-mrelocatable-lib} or +with modules compiled with the @samp{-mrelocatable} options. + +@item -mno-toc +@itemx -mtoc +On System V.4 and embedded PowerPC systems do not (do) assume that +register 2 contains a pointer to a global area pointing to the addresses +used in the program. + +@item -mlittle +@itemx -mlittle-endian +On System V.4 and embedded PowerPC systems compile code for the +processor in little endian mode. The @samp{-mlittle-endian} option is +the same as @samp{-mlittle}. + +@item -mbig +@itemx -mbig-endian +On System V.4 and embedded PowerPC systems compile code for the +processor in big endian mode. The @samp{-mbig-endian} option is +the same as @samp{-mbig}. + +@item -mcall-sysv +On System V.4 and embedded PowerPC systems compile code using calling +conventions that adheres to the March 1995 draft of the System V +Application Binary Interface, PowerPC processor supplement. This is the +default unless you configured GCC using @samp{powerpc-*-eabiaix}. + +@item -mcall-sysv-eabi +Specify both @samp{-mcall-sysv} and @samp{-meabi} options. + +@item -mcall-sysv-noeabi +Specify both @samp{-mcall-sysv} and @samp{-mno-eabi} options. + +@item -mcall-aix +On System V.4 and embedded PowerPC systems compile code using calling +conventions that are similar to those used on AIX. This is the +default if you configured GCC using @samp{powerpc-*-eabiaix}. + +@item -mcall-solaris +On System V.4 and embedded PowerPC systems compile code for the Solaris +operating system. + +@item -mcall-linux +On System V.4 and embedded PowerPC systems compile code for the +Linux-based GNU system. + +@c CYGNUS LOCAL vmakarov +@item -mcall-i960-old +On System V.4 and embedded PowerPC systems compile code so that +structure layout is compatible with the Intel i960 compiler using the +@samp{-mold-align}, @samp{-mno-strict-align}, and @samp{-mca} switches. +The @samp{-mcall-i960-old} option sets the @samp{-mlittle}, +@samp{-meabi}, @samp{-mno-bit-word}, and @samp{-mno-strict-align} +PowerPC options, and also forces the type @code{wchar_t} to be an +@code{int} instead of @code{long int}. +@c END CYGNUS LOCAL + +@item -mprototype +@itemx -mno-prototype +On System V.4 and embedded PowerPC systems assume that all calls to +variable argument functions are properly prototyped. Otherwise, the +compiler must insert an instruction before every non prototyped call to +set or clear bit 6 of the condition code register (@var{CR}) to +indicate whether floating point values were passed in the floating point +registers in case the function takes a variable arguments. With +@samp{-mprototype}, only calls to prototyped variable argument functions +will set or clear the bit. + +@c CYGNUS LOCAL -- vmakarov/prolog-epilog instruction scheduling +@item -msched-epilog +@itemx -mno-sched-epilog +Generate RTL instructions for function epilogue which permits to make +epilogue instruction scheduling for @samp{eabi}. By default assembler +code is generated and epilogue instruction scheduling is not possible. + +@item -msched-prolog +@itemx -mno-sched-prolog +Generate RTL instructions for function prologue which permits to make +prologue instruction scheduling for @samp{eabi}. By default assembler +code is generated and prologue instruction scheduling is not possible. +@c END CYGNUS LOCAL + +@item -msim +On embedded PowerPC systems, assume that the startup module is called +@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and +@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}. +configurations. + +@item -mmvme +On embedded PowerPC systems, assume that the startup module is called +@file{crt0.o} and the standard C libraries are @file{libmvme.a} and +@file{libc.a}. + +@item -mads +On embedded PowerPC systems, assume that the startup module is called +@file{crt0.o} and the standard C libraries are @file{libads.a} and +@file{libc.a}. + +@item -myellowknife +On embedded PowerPC systems, assume that the startup module is called +@file{crt0.o} and the standard C libraries are @file{libyk.a} and +@file{libc.a}. + +@item -memb +On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags +header to indicate that @samp{eabi} extended relocations are used. + +@item -meabi +@itemx -mno-eabi +On System V.4 and embedded PowerPC systems do (do not) adhere to the +Embedded Applications Binary Interface (eabi) which is a set of +modifications to the System V.4 specifications. Selecting @code{-meabi} +means that the stack is aligned to an 8 byte boundary, a function +@code{__eabi} is called to from @code{main} to set up the eabi +environment, and the @samp{-msdata} option can use both @code{r2} and +@code{r13} to point to two separate small data areas. Selecting +@code{-mno-eabi} means that the stack is aligned to a 16 byte boundary, +do not call an initialization function from @code{main}, and the +@samp{-msdata} option will only use @code{r13} to point to a single +small data area. The @samp{-meabi} option is on by default if you +configured GCC using one of the @samp{powerpc*-*-eabi*} options. + +@item -msdata=eabi +On System V.4 and embedded PowerPC systems, put small initialized +@code{const} global and static data in the @samp{.sdata2} section, which +is pointed to by register @code{r2}. Put small initialized +non-@code{const} global and static data in the @samp{.sdata} section, +which is pointed to by register @code{r13}. Put small uninitialized +global and static data in the @samp{.sbss} section, which is adjacent to +the @samp{.sdata} section. The @samp{-msdata=eabi} option is +incompatible with the @samp{-mrelocatable} option. The +@samp{-msdata=eabi} option also sets the @samp{-memb} option. + +@item -msdata=sysv +On System V.4 and embedded PowerPC systems, put small global and static +data in the @samp{.sdata} section, which is pointed to by register +@code{r13}. Put small uninitialized global and static data in the +@samp{.sbss} section, which is adjacent to the @samp{.sdata} section. +The @samp{-msdata=sysv} option is incompatible with the +@samp{-mrelocatable} option. + +@item -msdata=default +@itemx -msdata +On System V.4 and embedded PowerPC systems, if @samp{-meabi} is used, +compile code the same as @samp{-msdata=eabi}, otherwise compile code the +same as @samp{-msdata=sysv}. + +@item -msdata-data +On System V.4 and embedded PowerPC systems, put small global and static +data in the @samp{.sdata} section. Put small uninitialized global and +static data in the @samp{.sbss} section. Do not use register @code{r13} +to address small data however. This is the default behavior unless +other @samp{-msdata} options are used. + +@item -msdata=none +@itemx -mno-sdata +On embedded PowerPC systems, put all initialized global and static data +in the @samp{.data} section, and all uninitialized data in the +@samp{.bss} section. + +@item -G @var{num} +@cindex smaller data references (PowerPC) +@cindex .sdata/.sdata2 references (PowerPC) +On embedded PowerPC systems, put global and static items less than or +equal to @var{num} bytes into the small data or bss sections instead of +the normal data or bss section. By default, @var{num} is 8. The +@samp{-G @var{num}} switch is also passed to the linker. +All modules should be compiled with the same @samp{-G @var{num}} value. + +@item -mregnames +@itemx -mno-regnames +On System V.4 and embedded PowerPC systems do (do not) emit register +names in the assembly language output using symbolic forms. + +@c CYGNUS LOCAL vmakarov +@item -mvxworks +On System V.4 and embedded PowerPC systems, specify that you are +compiling for a VxWorks system. +@c END CYGNUS LOCAL +@c CYGNUS LOCAL jlemke + +@item -mmpc860c0[=@var{num}] +@kindex mmpc860c0 +This option is only applicable to MPC860 chips when producing ELF +executables with the GNU linker. It does not cause any changes to +the .o files but causes the linker to perform a check for +"problematic" conditional branches and implement a work around. + +The problem is that some chips may treat the target instruction +as a no-op, given the following conditions: + +@smallexample +1/ The processor is an MPC860, version C0 or earlier. +2/ A forward conditional branch is executed. +3/ The branch is predicted as not taken. +4/ The branch is taken. +5/ The branch is located in the last 5 words of a page. +6/ The branch target is located on a subsequent page. +@end smallexample + +The optional argument is the number of words that are checked +at the end of each text page. It may be any value from 1 to 10 +and defaults to 5. +@c END CYGNUS LOCAL +@end table +@node RT Options +@subsection IBM RT Options +@cindex RT options +@cindex IBM RT options + +These @samp{-m} options are defined for the IBM RT PC: + +@table @code +@item -min-line-mul +Use an in-line code sequence for integer multiplies. This is the +default. + +@item -mcall-lib-mul +Call @code{lmul$$} for integer multiples. + +@item -mfull-fp-blocks +Generate full-size floating point data blocks, including the minimum +amount of scratch space recommended by IBM. This is the default. + +@item -mminimum-fp-blocks +Do not include extra scratch space in floating point data blocks. This +results in smaller code, but slower execution, since scratch space must +be allocated dynamically. + +@cindex @file{varargs.h} and RT PC +@cindex @file{stdarg.h} and RT PC +@item -mfp-arg-in-fpregs +Use a calling sequence incompatible with the IBM calling convention in +which floating point arguments are passed in floating point registers. +Note that @code{varargs.h} and @code{stdargs.h} will not work with +floating point operands if this option is specified. + +@item -mfp-arg-in-gregs +Use the normal calling convention for floating point arguments. This is +the default. + +@item -mhc-struct-return +Return structures of more than one word in memory, rather than in a +register. This provides compatibility with the MetaWare HighC (hc) +compiler. Use the option @samp{-fpcc-struct-return} for compatibility +with the Portable C Compiler (pcc). + +@item -mnohc-struct-return +Return some structures of more than one word in registers, when +convenient. This is the default. For compatibility with the +IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the +option @samp{-mhc-struct-return}. +@end table + +@node MIPS Options +@subsection MIPS Options +@cindex MIPS options + +These @samp{-m} options are defined for the MIPS family of computers: + +@table @code +@item -mcpu=@var{cpu type} +Assume the defaults for the machine type @var{cpu type} when scheduling +instructions. The choices for @var{cpu type} are @samp{r2000}, @samp{r3000}, +@samp{r4000}, @samp{r4400}, @samp{r4600}, and @samp{r6000}. While picking a +specific @var{cpu type} will schedule things appropriately for that +particular chip, the compiler will not generate any code that does not +meet level 1 of the MIPS ISA (instruction set architecture) without +the @samp{-mips2} or @samp{-mips3} switches being used. + +@item -mips1 +Issue instructions from level 1 of the MIPS ISA. This is the default. +@samp{r3000} is the default @var{cpu type} at this ISA level. + +@item -mips2 +Issue instructions from level 2 of the MIPS ISA (branch likely, square +root instructions). @samp{r6000} is the default @var{cpu type} at this +ISA level. + +@item -mips3 +Issue instructions from level 3 of the MIPS ISA (64 bit instructions). +@samp{r4000} is the default @var{cpu type} at this ISA level. +This option does not change the sizes of any of the C data types. + +@item -mips4 +Issue instructions from level 4 of the MIPS ISA. @samp{r8000} is the +default @var{cpu type} at this ISA level. + +@item -mfp32 +Assume that 32 32-bit floating point registers are available. This is +the default. + +@item -mfp64 +Assume that 32 64-bit floating point registers are available. This is +the default when the @samp{-mips3} option is used. + +@item -mgp32 +Assume that 32 32-bit general purpose registers are available. This is +the default. + +@item -mgp64 +Assume that 32 64-bit general purpose registers are available. This is +the default when the @samp{-mips3} option is used. + +@item -mint64 +Types long, int, and pointer are 64 bits. This works only if @samp{-mips3} +is also specified. + +@item -mlong64 +Types long and pointer are 64 bits, and type int is 32 bits. +This works only if @samp{-mips3} is also specified. + +@itemx -mabi=32 +@itemx -mabi=n32 +@itemx -mabi=64 +@itemx -mabi=eabi +Generate code for the indicated ABI. + +@item -mmips-as +Generate code for the MIPS assembler, and invoke @file{mips-tfile} to +add normal debug information. This is the default for all +platforms except for the OSF/1 reference platform, using the OSF/rose +object format. If the either of the @samp{-gstabs} or @samp{-gstabs+} +switches are used, the @file{mips-tfile} program will encapsulate the +stabs within MIPS ECOFF. + +@item -mgas +Generate code for the GNU assembler. This is the default on the OSF/1 +reference platform, using the OSF/rose object format. Also, this is +the default if the configure option @samp{--with-gnu-as} is used. + +@item -msplit-addresses +@itemx -mno-split-addresses +Generate code to load the high and low parts of address constants separately. +This allows @code{gcc} to optimize away redundant loads of the high order +bits of addresses. This optimization requires GNU as and GNU ld. +This optimization is enabled by default for some embedded targets where +GNU as and GNU ld are standard. + +@item -mrnames +@itemx -mno-rnames +The @samp{-mrnames} switch says to output code using the MIPS software +names for the registers, instead of the hardware names (ie, @var{a0} +instead of @var{$4}). The only known assembler that supports this option +is the Algorithmics assembler. + +@item -mgpopt +@itemx -mno-gpopt +The @samp{-mgpopt} switch says to write all of the data declarations +before the instructions in the text section, this allows the MIPS +assembler to generate one word memory references instead of using two +words for short global or static data items. This is on by default if +optimization is selected. + +@item -mstats +@itemx -mno-stats +For each non-inline function processed, the @samp{-mstats} switch +causes the compiler to emit one line to the standard error file to +print statistics about the program (number of registers saved, stack +size, etc.). + +@item -mmemcpy +@itemx -mno-memcpy +The @samp{-mmemcpy} switch makes all block moves call the appropriate +string function (@samp{memcpy} or @samp{bcopy}) instead of possibly +generating inline code. + +@item -mmips-tfile +@itemx -mno-mips-tfile +The @samp{-mno-mips-tfile} switch causes the compiler not +postprocess the object file with the @file{mips-tfile} program, +after the MIPS assembler has generated it to add debug support. If +@file{mips-tfile} is not run, then no local variables will be +available to the debugger. In addition, @file{stage2} and +@file{stage3} objects will have the temporary file names passed to the +assembler embedded in the object file, which means the objects will +not compare the same. The @samp{-mno-mips-tfile} switch should only +be used when there are bugs in the @file{mips-tfile} program that +prevents compilation. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GNU CC. +Normally the facilities of the machine's usual C compiler are used, but +this can't be done directly in cross-compilation. You must make your +own arrangements to provide suitable library functions for +cross-compilation. + +@item -mhard-float +Generate output containing floating point instructions. This is the +default if you use the unmodified sources. + +@item -mabicalls +@itemx -mno-abicalls +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 -mlong-calls +@itemx -mno-long-calls +Do all calls with the @samp{JALR} instruction, which requires +loading up a function's address into a register before the call. +You need to use this switch, if you call outside of the current +512 megabyte segment to functions that are not through pointers. + +@item -mhalf-pic +@itemx -mno-half-pic +Put pointers to extern references into the data section and load them +up, rather than put the references in the text section. + +@item -membedded-pic +@itemx -mno-embedded-pic +Generate PIC code suitable for some embedded systems. All calls are +made using PC relative address, 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. This currently +only works on targets which use ECOFF; it does not work with ELF. + +@item -membedded-data +@itemx -mno-embedded-data +Allocate variables to the read-only data section first if possible, then +next in the small data section if possible, otherwise in data. This gives +slightly slower code than the default, but reduces the amount of RAM required +when executing, and thus may be preferred for some embedded systems. + +@item -msingle-float +@itemx -mdouble-float +The @samp{-msingle-float} switch tells gcc to assume that the floating +point coprocessor only supports single precision operations, as on the +@samp{r4650} chip. The @samp{-mdouble-float} switch permits gcc to use +double precision operations. This is the default. + +@item -mmad +@itemx -mno-mad +Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions, +as on the @samp{r4650} chip. + +@item -m4650 +Turns on @samp{-msingle-float}, @samp{-mmad}, and, at least for now, +@samp{-mcpu=r4650}. + +@item -EL +Compile code for the processor in little endian mode. +The requisite libraries are assumed to exist. + +@item -EB +Compile code for the processor in big endian mode. +The requisite libraries are assumed to exist. + +@item -G @var{num} +@cindex smaller data references (MIPS) +@cindex gp-relative references (MIPS) +Put global and static items less than or equal to @var{num} bytes into +the small data or bss sections instead of the normal data or bss +section. This allows the assembler to emit one word memory reference +instructions based on the global pointer (@var{gp} or @var{$28}), +instead of the normal two words used. By default, @var{num} is 8 when +the MIPS assembler is used, and 0 when the GNU assembler is used. The +@samp{-G @var{num}} switch is also passed to the assembler and linker. +All modules should be compiled with the same @samp{-G @var{num}} +value. + +@item -nocpp +Tell the MIPS assembler to not run its preprocessor over user +assembler files (with a @samp{.s} suffix) when assembling them. + +@c CYGNUS LOCAL law +@item -malign-loops=@var{num} +Align loops to a 2 raised to a @var{num} byte boundary. If +@samp{-malign-loops} is not specified, the default is 2. Note specific +MIPS targets may override the default value. + +@item -malign-jumps=@var{num} +Align instructions that are only jumped to to a 2 raised to a @var{num} +byte boundary. If @samp{-malign-jumps} is not specified, the default is 2. +Note specific MIPS targets may override the default value. + +@item -malign-functions=@var{num} +Align the start of functions to a 2 raised to @var{num} byte boundary. +If @samp{-malign-functions} is not specified, the default is 2. +Note specific MIPS targets may override the default value. + +@item -mmax-skip-loops=@var{num} +Maximum number of padding bytes allowed to satisfy a loop alignment +request. The default value is zero which specifies no limit on the number +of padding bytes. +Note specific MIPS targets may override the default value. + +@item -mmax-skip-jumps=@var{num} +Maximum number of padding bytes allowed to satisfy a loop alignment +request. The default value is zero which specifies no limit on the number +of padding bytes. +Note specific MIPS targets may override the default value. + +@item -mmax-skip-functions=@var{num} +Maximum number of padding bytes allowed to satisfy a loop alignment +request. The default value is zero which specifies no limit on the number +of padding bytes. This option may have no effect when combined with other +options such as @samp{-ffunction-sections}. +Note specific MIPS targets may override the default value. +@c END CYGNUS LOCAL +@end table + +@ifset INTERNALS +These options are defined by the macro +@code{TARGET_SWITCHES} in the machine description. The default for the +options is also defined by that macro, which enables you to change the +defaults. +@end ifset + +@node i386 Options +@subsection Intel 386 Options +@cindex i386 Options +@cindex Intel 386 Options + +These @samp{-m} options are defined for the i386 family of computers: + +@table @code +@item -mcpu=@var{cpu type} +Assume the defaults for the machine type @var{cpu type} when scheduling +instructions. The choices for @var{cpu type} are: @samp{i386}, +@samp{i486}, @samp{i586} (@samp{pentium}), @samp{pentium}, @samp{i686} +(@samp{pentiumpro}) and @samp{pentiumpro}. While picking a specific +@var{cpu type} will schedule things appropriately for that particular +chip, the compiler will not generate any code that does not run on the +i386 without the @samp{-march=@var{cpu type}} option being used. + +@item -march=@var{cpu type} +Generate instructions for the machine type @var{cpu type}. The choices +for @var{cpu type} are: @samp{i386}, @samp{i486}, @samp{pentium}, and +@samp{pentiumpro}. Specifying @samp{-march=@var{cpu type}} implies +@samp{-mcpu=@var{cpu type}}. + +@item -m386 +@itemx -m486 +@itemx -mpentium +@itemx -mpentiumpro +Synonyms for -mcpu=i386, -mcpu=i486, -mcpu=pentium, and -mcpu=pentiumpro +respectively. + +@item -mieee-fp +@itemx -mno-ieee-fp +Control whether or not the compiler uses IEEE floating point +comparisons. These handle correctly the case where the result of a +comparison is unordered. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GNU CC. +Normally the facilities of the machine's usual C compiler are used, but +this can't be done directly in cross-compilation. You must make your +own arrangements to provide suitable library functions for +cross-compilation. + +On machines where a function returns floating point results in the 80387 +register stack, some floating point opcodes may be emitted even if +@samp{-msoft-float} is used. + +@item -mno-fp-ret-in-387 +Do not use the FPU registers for return values of functions. + +The usual calling convention has functions return values of types +@code{float} and @code{double} in an FPU register, even if there +is no FPU. The idea is that the operating system should emulate +an FPU. + +The option @samp{-mno-fp-ret-in-387} causes such values to be returned +in ordinary CPU registers instead. + +@item -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 @samp{-ffast-math} switch. + +@item -malign-double +@itemx -mno-align-double +Control whether GNU CC aligns @code{double}, @code{long double}, and +@code{long long} variables on a two word boundary or a one word +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 -msvr3-shlib +@itemx -mno-svr3-shlib +Control whether GNU CC places uninitialized locals into @code{bss} or +@code{data}. @samp{-msvr3-shlib} places these locals into @code{bss}. +These options are meaningful only on System V Release 3. + +@item -mno-wide-multiply +@itemx -mwide-multiply +Control whether GNU CC uses the @code{mul} and @code{imul} that produce +64 bit results in @code{eax:edx} from 32 bit operands to do @code{long +long} multiplies and 32-bit division by constants. + +@item -mrtd +Use a different function-calling convention, in which functions that +take a fixed number of arguments return with the @code{ret} @var{num} +instruction, which pops their arguments while returning. This saves one +instruction in the caller since there is no need to pop the arguments +there. + +You can specify that an individual function is called with this calling +sequence with the function attribute @samp{stdcall}. You can also +override the @samp{-mrtd} option by using the function attribute +@samp{cdecl}. @xref{Function Attributes} + +@strong{Warning:} this calling convention is incompatible with the one +normally used on Unix, so you cannot use it if you need to call +libraries compiled with the Unix compiler. + +Also, you must provide function prototypes for all functions that +take variable numbers of arguments (including @code{printf}); +otherwise incorrect code will be generated for calls to those +functions. + +In addition, seriously incorrect code will result if you call a +function with too many arguments. (Normally, extra arguments are +harmlessly ignored.) + +@item -mreg-alloc=@var{regs} +Control the default allocation order of integer registers. The +string @var{regs} is a series of letters specifying a register. The +supported letters are: @code{a} allocate EAX; @code{b} allocate EBX; +@code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI; +@code{D} allocate EDI; @code{B} allocate EBP. + +@item -mregparm=@var{num} +Control how many registers are used to pass integer arguments. By +default, no registers are used to pass arguments, and at most 3 +registers can be used. You can control this behavior for a specific +function by using the function attribute @samp{regparm}. @xref{Function Attributes} + +@strong{Warning:} if you use this switch, and +@var{num} is nonzero, then you must build all modules with the same +value, including any libraries. This includes the system libraries and +startup modules. + +@item -malign-loops=@var{num} +Align loops to a 2 raised to a @var{num} byte boundary. If +@samp{-malign-loops} is not specified, the default is 2 unless +gas 2.8 (or later) is being used in which case the default is +to align the loop on a 16 byte boundary if it is less than 8 +bytes away. + +@item -malign-jumps=@var{num} +Align instructions that are only jumped to to a 2 raised to a @var{num} +byte boundary. If @samp{-malign-jumps} is not specified, the default is +2 if optimizing for a 386, and 4 if optimizing for a 486 unless +gas 2.8 (or later) is being used in which case the default is +to align the instruction on a 16 byte boundary if it is less +than 8 bytes away. + +@item -malign-functions=@var{num} +Align the start of functions to a 2 raised to @var{num} byte boundary. +If @samp{-malign-functions} is not specified, the default is 2 if optimizing +for a 386, and 4 if optimizing for a 486. +@end table + +@node HPPA Options +@subsection HPPA Options +@cindex HPPA Options + +These @samp{-m} options are defined for the HPPA family of computers: + +@table @code +@item -mpa-risc-1-0 +Generate code for a PA 1.0 processor. + +@item -mpa-risc-1-1 +Generate code for a PA 1.1 processor. + +@item -mbig-switch +Generate code suitable for big switch tables. Use this option only if +the assembler/linker complain about out of range branches within a switch +table. + +@item -mjump-in-delay +Fill delay slots of function calls with unconditional jump instructions +by modifying the return pointer for the function call to be the target +of the conditional jump. + +@item -mdisable-fpregs +Prevent floating point registers from being used in any manner. This is +necessary for compiling kernels which perform lazy context switching of +floating point registers. If you use this option and attempt to perform +floating point operations, the compiler will abort. + +@item -mdisable-indexing +Prevent the compiler from using indexing address modes. This avoids some +rather obscure problems when compiling MIG generated code under MACH. + +@item -mno-space-regs +Generate code that assumes the target has no space registers. This allows +GCC to generate faster indirect calls and use unscaled index address modes. + +Such code is suitable for level 0 PA systems and kernels. + +@item -mfast-indirect-calls +Generate code that assumes calls never cross space boundaries. This +allows GCC to emit code which performs faster indirect calls. + +This option will not work in the presense of shared libraries or nested +functions. + +@item -mspace +Optimize for space rather than execution time. Currently this only +enables out of line function prologues and epilogues. This option is +incompatible with PIC code generation and profiling. + +@item -mlong-load-store +Generate 3-instruction load and store sequences as sometimes required by +the HP-UX 10 linker. This is equivalent to the @samp{+k} option to +the HP compilers. + +@item -mportable-runtime +Use the portable calling conventions proposed by HP for ELF systems. + +@item -mgas +Enable the use of assembler directives only GAS understands. + +@item -mschedule=@var{cpu type} +Schedule code according to the constraints for the machine type +@var{cpu type}. The choices for @var{cpu type} are @samp{700} for +7@var{n}0 machines, @samp{7100} for 7@var{n}5 machines, and @samp{7100LC} +for 7@var{n}2 machines. @samp{7100} is the default for @var{cpu type}. + +Note the @samp{7100LC} scheduling information is incomplete and using +@samp{7100LC} often leads to bad schedules. For now it's probably best +to use @samp{7100} instead of @samp{7100LC} for the 7@var{n}2 machines. + +@item -mlinker-opt +Enable the optimization pass in the HPUX linker. Note this makes symbolic +debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers +in which they give bogus error messages when linking some programs. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not available for all HPPA +targets. Normally the facilities of the machine's usual C compiler are +used, but this cannot be done directly in cross-compilation. You must make +your own arrangements to provide suitable library functions for +cross-compilation. The embedded target @samp{hppa1.1-*-pro} +does provide software floating point support. + +@samp{-msoft-float} changes the calling convention in the output file; +therefore, it is only useful if you compile @emph{all} of a program with +this option. In particular, you need to compile @file{libgcc.a}, the +library that comes with GNU CC, with @samp{-msoft-float} in order for +this to work. +@end table + +@node Intel 960 Options +@subsection Intel 960 Options + +These @samp{-m} options are defined for the Intel 960 implementations: + +@table @code +@item -m@var{cpu type} +Assume the defaults for the machine type @var{cpu type} for some of +the other options, including instruction scheduling, floating point +support, and addressing modes. The choices for @var{cpu type} are +@samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf}, +@samp{sa}, and @samp{sb}. +The default is +@samp{kb}. + +@item -mnumerics +@itemx -msoft-float +The @samp{-mnumerics} option indicates that the processor does support +floating-point instructions. The @samp{-msoft-float} option indicates +that floating-point support should not be assumed. + +@item -mleaf-procedures +@itemx -mno-leaf-procedures +Do (or do not) attempt to alter leaf procedures to be callable with the +@code{bal} instruction as well as @code{call}. This will result in more +efficient code for explicit calls when the @code{bal} instruction can be +substituted by the assembler or linker, but less efficient code in other +cases, such as calls via function pointers, or using a linker that doesn't +support this optimization. + +@item -mtail-call +@itemx -mno-tail-call +Do (or do not) make additional attempts (beyond those of the +machine-independent portions of the compiler) to optimize tail-recursive +calls into branches. You may not want to do this because the detection of +cases where this is not valid is not totally complete. The default is +@samp{-mno-tail-call}. + +@item -mcomplex-addr +@itemx -mno-complex-addr +Assume (or do not assume) that the use of a complex addressing mode is a +win on this implementation of the i960. Complex addressing modes may not +be worthwhile on the K-series, but they definitely are on the C-series. +The default is currently @samp{-mcomplex-addr} for all processors except +the CB and CC. + +@item -mcode-align +@itemx -mno-code-align +Align code to 8-byte boundaries for faster fetching (or don't bother). +Currently turned on by default for C-series implementations only. + +@ignore +@item -mclean-linkage +@itemx -mno-clean-linkage +These options are not fully implemented. +@end ignore + +@item -mic-compat +@itemx -mic2.0-compat +@itemx -mic3.0-compat +Enable compatibility with iC960 v2.0 or v3.0. + +@item -masm-compat +@itemx -mintel-asm +Enable compatibility with the iC960 assembler. + +@item -mstrict-align +@itemx -mno-strict-align +Do not permit (do permit) unaligned accesses. + +@item -mold-align +Enable structure-alignment compatibility with Intel's gcc release version +1.3 (based on gcc 1.37). This option implies @samp{-mstrict-align}. + +@item -mlong-double-64 +Implement type @samp{long double} as 64-bit floating point numbers. +Without the option @samp{long double} is implemented by 80-bit +floating point numbers. The only reason we have it because there is +no 128-bit @samp{long double} support in @samp{fp-bit.c} yet. So it +is only useful for people using soft-float targets. Otherwise, we +should recommend against use of it. + +@c CYGNUS LOCAL move coalescence +@item -mmove-coalescence +@itemx -mno-move-coalescence +Enable (or disable) coalescing several move instructions in one move +instruction. This optimization is on only when unaligned access is +permitted. By default the optimization is off. +@c END CYGNUS LOCAL move coalescence +@end table + +@node DEC Alpha Options +@subsection DEC Alpha Options + +These @samp{-m} options are defined for the DEC Alpha implementations: + +@table @code +@item -mno-soft-float +@itemx -msoft-float +Use (do not use) the hardware floating-point instructions for +floating-point operations. When @code{-msoft-float} is specified, +functions in @file{libgcc1.c} will be used to perform floating-point +operations. Unless they are replaced by routines that emulate the +floating-point operations, or compiled in such a way as to call such +emulations routines, these routines will issue floating-point +operations. If you are compiling for an Alpha without floating-point +operations, you must ensure that the library is built so as not to call +them. + +Note that Alpha implementations without floating-point operations are +required to have floating-point registers. + +@item -mfp-reg +@itemx -mno-fp-regs +Generate code that uses (does not use) the floating-point register set. +@code{-mno-fp-regs} implies @code{-msoft-float}. If the floating-point +register set is not used, floating point operands are passed in integer +registers as if they were integers and floating-point results are passed +in $0 instead of $f0. This is a non-standard calling sequence, so any +function with a floating-point argument or return value called by code +compiled with @code{-mno-fp-regs} must also be compiled with that +option. + +A typical use of this option is building a kernel that does not use, +and hence need not save and restore, any floating-point registers. + +@item -mieee +The Alpha architecture implements floating-point hardware optimized for +maximum performance. It is mostly compliant with the IEEE floating +point standard. However, for full compliance, software assistance is +required. This option generates code fully IEEE compliant code +@emph{except} that the @var{inexact flag} is not maintained (see below). +If this option is turned on, the CPP macro @code{_IEEE_FP} is defined +during compilation. The option is a shorthand for: @samp{-D_IEEE_FP +-mfp-trap-mode=su -mtrap-precision=i -mieee-conformant}. The resulting +code is less efficient but is able to correctly support denormalized +numbers and exceptional IEEE values such as not-a-number and plus/minus +infinity. Other Alpha compilers call this option +@code{-ieee_with_no_inexact}. + +@item -mieee-with-inexact +@c overfull hbox here --bob 22 jul96 +@c original text between ignore ... end ignore +@ignore +This is like @samp{-mieee} except the generated code also maintains the +IEEE @var{inexact flag}. Turning on this option causes the generated +code to implement fully-compliant IEEE math. The option is a shorthand +for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus @samp{-mieee-conformant}, +@samp{-mfp-trap-mode=sui}, and @samp{-mtrap-precision=i}. On some Alpha +implementations the resulting code may execute significantly slower than +the code generated by default. Since there is very little code that +depends on the @var{inexact flag}, you should normally not specify this +option. Other Alpha compilers call this option +@samp{-ieee_with_inexact}. +@end ignore +@c changed paragraph +This is like @samp{-mieee} except the generated code also maintains the +IEEE @var{inexact flag}. Turning on this option causes the generated +code to implement fully-compliant IEEE math. The option is a shorthand +for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus the three following: +@samp{-mieee-conformant}, +@samp{-mfp-trap-mode=sui}, +and @samp{-mtrap-precision=i}. +On some Alpha implementations the resulting code may execute +significantly slower than the code generated by default. Since there +is very little code that depends on the @var{inexact flag}, you should +normally not specify this option. Other Alpha compilers call this +option @samp{-ieee_with_inexact}. +@c end changes to prevent overfull hboxes + +@item -mfp-trap-mode=@var{trap mode} +This option controls what floating-point related traps are enabled. +Other Alpha compilers call this option @samp{-fptm }@var{trap mode}. +The trap mode can be set to one of four values: + +@table @samp +@item n +This is the default (normal) setting. The only traps that are enabled +are the ones that cannot be disabled in software (e.g., division by zero +trap). + +@item u +In addition to the traps enabled by @samp{n}, underflow traps are enabled +as well. + +@item su +Like @samp{su}, but the instructions are marked to be safe for software +completion (see Alpha architecture manual for details). + +@item sui +Like @samp{su}, but inexact traps are enabled as well. +@end table + +@item -mfp-rounding-mode=@var{rounding mode} +Selects the IEEE rounding mode. Other Alpha compilers call this option +@samp{-fprm }@var{rounding mode}. The @var{rounding mode} can be one +of: + +@table @samp +@item n +Normal IEEE rounding mode. Floating point numbers are rounded towards +the nearest machine number or towards the even machine number in case +of a tie. + +@item m +Round towards minus infinity. + +@item c +Chopped rounding mode. Floating point numbers are rounded towards zero. + +@item d +Dynamic rounding mode. A field in the floating point control register +(@var{fpcr}, see Alpha architecture reference manual) controls the +rounding mode in effect. The C library initializes this register for +rounding towards plus infinity. Thus, unless your program modifies the +@var{fpcr}, @samp{d} corresponds to round towards plus infinity.@end table + +@item -mtrap-precision=@var{trap precision} +In the Alpha architecture, floating point traps are imprecise. This +means without software assistance it is impossible to recover from a +floating trap and program execution normally needs to be terminated. +GNU CC can generate code that can assist operating system trap handlers +in determining the exact location that caused a floating point trap. +Depending on the requirements of an application, different levels of +precisions can be selected: + +@table @samp +@item p +Program precision. This option is the default and means a trap handler +can only identify which program caused a floating point exception. + +@item f +Function precision. The trap handler can determine the function that +caused a floating point exception. + +@item i +Instruction precision. The trap handler can determine the exact +instruction that caused a floating point exception. +@end table + +Other Alpha compilers provide the equivalent options called +@samp{-scope_safe} and @samp{-resumption_safe}. + +@item -mieee-conformant +This option marks the generated code as IEEE conformant. You must not +use this option unless you also specify @samp{-mtrap-precision=i} and either +@samp{-mfp-trap-mode=su} or @samp{-mfp-trap-mode=sui}. Its only effect +is to emit the line @samp{.eflag 48} in the function prologue of the +generated assembly file. Under DEC Unix, this has the effect that +IEEE-conformant math library routines will be linked in. + +@item -mbuild-constants +Normally GNU CC examines a 32- or 64-bit integer constant to +see if it can construct it from smaller constants in two or three +instructions. If it cannot, it will output the constant as a literal and +generate code to load it from the data segment at runtime. + +Use this option to require GNU CC to construct @emph{all} integer constants +using code, even if it takes more instructions (the maximum is six). + +You would typically use this option to build a shared library dynamic +loader. Itself a shared library, it must relocate itself in memory +before it can find the variables and constants in its own data segment. + +@item -malpha-as +@itemx -mgas +Select whether to generate code to be assembled by the vendor-supplied +assembler (@samp{-malpha-as}) or by the GNU assembler @samp{-mgas}. + +@item -mbwx +@itemx -mno-bwx +@itemx -mcix +@itemx -mno-cix +@itemx -mmax +@itemx -mno-max +Indicate whether GNU CC should generate code to use the optional BWX, +CIX, and MAX instruction sets. The default is to use the instruction sets +supported by the CPU type specified via @samp{-mcpu=} option or that +of the CPU on which GNU CC was built if none was specified. + +@item -mcpu=@var{cpu_type} +Set the instruction set, register set, and instruction scheduling +parameters for machine type @var{cpu_type}. You can specify either the +@samp{EV} style name or the corresponding chip number. GNU CC +supports scheduling parameters for the EV4 and EV5 family of processors +and will choose the default values for the instruction set from +the processor you specify. If you do not specify a processor type, +GNU CC will default to the processor on which the compiler was built. + +Supported values for @var{cpu_type} are + +@table @samp +@item ev4 +@itemx 21064 +Schedules as an EV4 and has no instruction set extensions. + +@item ev5 +@itemx 21164 +Schedules as an EV5 and has no instruction set extensions. + +@item ev56 +@itemx 21164a +Schedules as an EV5 and supports the BWX extension. + +@item pca56 +@itemx 21164pc +@itemx 21164PC +Schedules as an EV5 and supports the BWX and MAX extensions. + +@item ev6 +@itemx 21264 +Schedules as an EV5 (until Digital releases the scheduling parameters +for the EV6) and supports the BWX, CIX, and MAX extensions. +@end table + +@item -mmemory-latency=@var{time} +Sets the latency the scheduler should assume for typical memory +references as seen by the application. This number is highly +dependant on the memory access patterns used by the application +and the size of the external cache on the machine. + +Valid options for @var{time} are + +@table @samp +@item @var{number} +A decimal number representing clock cycles. + +@item L1 +@itemx L2 +@itemx L3 +@itemx main +The compiler contains estimates of the number of clock cycles for +``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches +(also called Dcache, Scache, and Bcache), as well as to main memory. +Note that L3 is only valid for EV5. + +@end table +@end table + +@node Clipper Options +@subsection Clipper Options + +These @samp{-m} options are defined for the Clipper implementations: + +@table @code +@item -mc300 +Produce code for a C300 Clipper processor. This is the default. + +@itemx -mc400 +Produce code for a C400 Clipper processor i.e. use floating point +registers f8..f15. +@end table + +@node H8/300 Options +@subsection H8/300 Options + +These @samp{-m} options are defined for the H8/300 implementations: + +@table @code +@item -mrelax +Shorten some address references at link time, when possible; uses the +linker option @samp{-relax}. @xref{H8/300,, @code{ld} and the H8/300, +ld.info, Using ld}, for a fuller description. + +@item -mh +Generate code for the H8/300H. + +@item -ms +Generate code for the H8/S. + +@item -mint32 +Make @code{int} data 32 bits by default. + +@item -malign-300 +On the h8/300h, use the same alignment rules as for the h8/300. +The default for the h8/300h is to align longs and floats on 4 byte boundaries. +@samp{-malign-300} causes them to be aligned on 2 byte boundaries. +This option has no effect on the h8/300. +@end table + +@node SH Options +@subsection SH Options + +These @samp{-m} options are defined for the SH implementations: + +@table @code +@item -m1 +Generate code for the SH1. + +@item -m2 +Generate code for the SH2. + +@item -m3 +Generate code for the SH3. + +@item -m3e +Generate code for the SH3e. + +@item -mb +Compile code for the processor in big endian mode. + +@item -ml +Compile code for the processor in little endian mode. + +@item -mdalign +Align doubles at 64 bit boundaries. Note that this changes the calling +conventions, and thus some functions from the standard C library will +not work unless you recompile it first with -mdalign. + +@item -mrelax +Shorten some address references at link time, when possible; uses the +linker option @samp{-relax}. +@end table + +@node System V Options +@subsection Options for System V + +These additional options are available on System V Release 4 for +compatibility with other compilers on those systems: + +@table @code +@item -G +Create a shared object. +It is recommended that @samp{-symbolic} or @samp{-shared} be used instead. + +@item -Qy +Identify the versions of each tool used by the compiler, in a +@code{.ident} assembler directive in the output. + +@item -Qn +Refrain from adding @code{.ident} directives to the output file (this is +the default). + +@item -YP,@var{dirs} +Search the directories @var{dirs}, and no others, for libraries +specified with @samp{-l}. + +@item -Ym,@var{dir} +Look in the directory @var{dir} to find the M4 preprocessor. +The assembler uses this option. +@c This is supposed to go with a -Yd for predefined M4 macro files, but +@c the generic assembler that comes with Solaris takes just -Ym. +@end table + +@c CYGNUS LOCAL: z8k docs +@c (not yet submitted to FSF) +@node Z8000 Option +@subsection Zilog Z8000 Option + +GNU CC recognizes one special option when configured to generate +code for the Z8000 family: + +@table @code +@item -mz8001 +Generate code for the segmented variant of the Z8000 architecture. +(Without this option, @code{gcc} generates unsegmented Z8000 code; +suitable, for example, for the Z8002.) +@end table +@c END CYGNUS LOCAL + +@node V850 Options +@subsection V850 Options +@cindex V850 Options + +These @samp{-m} options are defined for V850 implementations: + +@table @code +@item -mlong-calls +@itemx -mno-long-calls +Treat all calls as being far away (near). If calls are assumed to be +far away, the compiler will always load the functions address up into a +register, and call indirect through the pointer. + +@item -mno-ep +@itemx -mep +Do not optimize (do optimize) basic blocks that use the same index +pointer 4 or more times to copy pointer into the @code{ep} register, and +use the shorter @code{sld} and @code{sst} instructions. The @samp{-mep} +option is on by default if you optimize. + +@item -mno-prolog-function +@itemx -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 @samp{-mprolog-function} option is on by default if +you optimize. + +@item -mspace +Try to make the code as small as possible. At present, this just turns +on the @samp{-mep} and @samp{-mprolog-function} options. + +@item -mtda=@var{n} +Put static or global variables whose size is @var{n} bytes or less into +the tiny data area that register @code{ep} points to. The tiny data +area can hold up to 256 bytes in total (128 bytes for byte references). + +@item -msda=@var{n} +Put static or global variables whose size is @var{n} bytes or less into +the small data area that register @code{gp} points to. The small data +area can hold up to 64 kilobytes. + +@item -mzda=@var{n} +Put static or global variables whose size is @var{n} bytes or less into +the first 32 kilobytes of memory. + +@item -mv850 +Specify that the target processor is the V850. + +@item -mbig-switch +Generate code suitable for big switch tables. Use this option only if +the assembler/linker complain about out of range branches within a switch +table. + +@item -mapp-regs +This option will cause r2 and r5 to be used in the code generated by +the compiler. This setting is the default. + +@item -mno-app-regs +This option will cause r2 and r5 to be treated as fixed registers. + +@c CYGNUS LOCAL v850e +@item -mv850e +Specify that the target processor is the V850E. The preprocessor +constant @samp{__v850e__} will be defined if this option is used. + +If neither @samp{-mv850} nor @samp{-mv850e} 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. + +@item -mdisable-callt +This option will suppress generation of the CALLT instruction for the +v850e flavors of the v850 architecture. The default is +@samp{-mno-disable-callt} which allows the CALLT instruction to be used. + +@c END CYGNUS LOCAL + +@end table + +@node ARC Options +@subsection ARC Options +@cindex ARC Options + +These options are defined for ARC implementations: + +@table @code +@item -EL +Compile code for little endian mode. This is the default. + +@item -EB +Compile code for big endian mode. + +@item -mmangle-cpu +Prepend the name of the cpu to all public symbol names. +In multiple-processor systems, there are many ARC variants with different +instruction and register set characteristics. This flag prevents code +compiled for one cpu to be linked with code compiled for another. +No facility exists for handling variants that are "almost identical". +This is an all or nothing option. + +@item -mcpu=@var{cpu} +Compile code for ARC variant @var{cpu}. +Which variants are supported depend on the configuration. +All variants support @samp{-mcpu=base}, this is the default. + +@item -mtext=@var{text section} +@item -mdata=@var{data section} +@item -mrodata=@var{readonly data section} +Put functions, data, and readonly data in @var{text section}, +@var{data section}, and @var{readonly data section} respectively +by default. This can be overridden with the @code{section} attribute. +@xref{Variable Attributes} + +@end table + +@c CYGNUS LOCAL -- meissner/d10v +@node D10V Options +@subsection D10V Options +@cindex D10V Options + +These @samp{-m} options are defined for D10V implementations: + +@table @code +@item -mint32 +@itemx -mint16 +Make @code{int} data 32 (or 16) bits by default. The default is +@samp{-mint16}. + +@item -mdouble64 +@itemx -mdouble32 +Make @code{double} data 64 (or 32) bits by default. The default is +@samp{-mdouble32}. + +@item -maddac3 +@itemx -mno-addac3 +Enable (disable) the use of @code{addac3} and @code{subac3} +instructions. The @samp{-maddac3} instruction also enables the +@samp{-maccum} instruction. + +@item -maccum +@itemx -mno-accum +Enable (disable) the use of the 32-bit accumulators in compiler generated +code. + +@item -mno-asm-optimize +@itemx -masm-optimize +Disable (enable) passing @samp{-O} to the assembler when optimizing. +The assembler uses the @samp{-O} option to automatically parallelize +adjacent short instructions where possible. + +@item -mno-small-insns +@itemx -msmall-insns +Disable (enable) converting some long instructions into two short +instructions, which can eliminate some nops and enable more code to be +conditionally executed. + +@item -mno-cond-move +@itemx -mcond-move +Disable (enable) conditional move instructions, which eliminates short +branches. + +@item -mbranch-cost=@var{n} +Increase the internal costs of branches to @var{n}. Higher costs means +that the compiler will issue more instructions to avoid doing a branch. +The default is 1. + +@item -mcond-exec=@var{n} +Specify the maximum number of conditionally executed instructions that +replace a branch. The default is 4. +@end table +@c END CYGNUS LOCAL -- meissner/d10v + +@c CYGNUS LOCAL d30v +@node D30V Options +@subsection D30V Options +@cindex D30V Options + +These @samp{-m} options are defined for D30V implementations: + +@table @code +@item -mextmem +Link the @samp{.text}, @samp{.data}, @samp{.bss}, @samp{.strings}, +@samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections into external +memory, which starts at location @code{0x80000000}. + +@item -mextmemory +Same as the @samp{-mextmem} switch. + +@item -monchip +Link the @samp{.text} section into onchip text memory, which starts at +location @code{0x0}. Also link @samp{.data}, @samp{.bss}, +@samp{.strings}, @samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections +into onchip data memory, which starts at location @code{0x20000000}. + +@item -mno-asm-optimize +@itemx -masm-optimize +Disable (enable) passing @samp{-O} to the assembler when optimizing. +The assembler uses the @samp{-O} option to automatically parallelize +adjacent short instructions where possible. + +@item -mbranch-cost=@var{n} +Increase the internal costs of branches to @var{n}. Higher costs means +that the compiler will issue more instructions to avoid doing a branch. +The default is 2. + +@item -mcond-exec=@var{n} +Specify the maximum number of conditionally executed instructions that +replace a branch. The default is 4. +@end table +@c END CYGNUS LOCAL d30v + +@node NS32K Options +@subsection NS32K Options +@cindex NS32K options + +These are the @samp{-m} options defined for the 32000 series. The default +values for these options depends on which style of 32000 was selected when +the compiler was configured; the defaults for the most common choices are +given below. + +@table @code +@item -m32032 +@itemx -m32032 +Generate output for a 32032. This is the default +when the compiler is configured for 32032 and 32016 based systems. + +@item -m32332 +@itemx -m32332 +Generate output for a 32332. This is the default +when the compiler is configured for 32332-based systems. + +@item -m32532 +@itemx -m32532 +Generate output for a 32532. This is the default +when the compiler is configured for 32532-based systems. + +@item -m32081 +Generate output containing 32081 instructions for floating point. +This is the default for all systems. + +@item -m32381 +Generate output containing 32381 instructions for floating point. This +also implies @samp{-m32081}. The 32381 is only compatible with the 32332 +and 32532 cpus. This is the default for the pc532-netbsd configuration. + +@item -mmulti-add +Try and generate multiply-add floating point instructions @code{polyF} +and @code{dotF}. This option is only available if the @samp{-m32381} +option is in effect. Using these instructions requires changes to to +register allocation which generally has a negative impact on +performance. This option should only be enabled when compiling code +particularly likely to make heavy use of multiply-add instructions. + +@item -mnomulti-add +Do not try and generate multiply-add floating point instructions +@code{polyF} and @code{dotF}. This is the default on all platforms. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries may not be available. + +@item -mnobitfield +Do not use the bit-field instructions. On some machines it is faster to +use shifting and masking operations. This is the default for the pc532. + +@item -mbitfield +Do use the bit-field instructions. This is the default for all platforms +except the pc532. + +@item -mrtd +Use a different function-calling convention, in which functions +that take a fixed number of arguments return pop their +arguments on return with the @code{ret} instruction. + +This calling convention is incompatible with the one normally +used on Unix, so you cannot use it if you need to call libraries +compiled with the Unix compiler. + +Also, you must provide function prototypes for all functions that +take variable numbers of arguments (including @code{printf}); +otherwise incorrect code will be generated for calls to those +functions. + +In addition, seriously incorrect code will result if you call a +function with too many arguments. (Normally, extra arguments are +harmlessly ignored.) + +This option takes its name from the 680x0 @code{rtd} instruction. + + +@item -mregparam +Use a different function-calling convention where the first two arguments +are passed in registers. + +This calling convention is incompatible with the one normally +used on Unix, so you cannot use it if you need to call libraries +compiled with the Unix compiler. + +@item -mnoregparam +Do not pass any arguments in registers. This is the default for all +targets. + +@item -msb +It is OK to use the sb as an index register which is always loaded with +zero. This is the default for the pc532-netbsd target. + +@item -mnosb +The sb register is not available for use or has not been initialized to +zero by the run time system. This is the default for all targets except +the pc532-netbsd. It is also implied whenever @samp{-mhimem} or +@samp{-fpic} is set. + +@item -mhimem +Many ns32000 series addressing modes use displacements of up to 512MB. +If an address is above 512MB then displacements from zero can not be used. +This option causes code to be generated which can be loaded above 512MB. +This may be useful for operating systems or ROM code. + +@item -mnohimem +Assume code will be loaded in the first 512MB of virtual address space. +This is the default for all platforms. + + +@end table + + + +@node Code Gen Options +@section Options for Code Generation Conventions +@cindex code generation conventions +@cindex options, code generation +@cindex run-time options + +These machine-independent options control the interface conventions +used in code generation. + +Most of them have both positive and negative forms; the negative form +of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only +one of the forms is listed---the one which is not the default. You +can figure out the other form by either removing @samp{no-} or adding +it. + +@table @code +@item -fexceptions +Enable exception handling. Generates extra code needed to propagate +exceptions. For some targets, this implies generation of frame unwind +information for all functions. This can produce significant data size +overhead, although it does not affect execution. +If you do not specify this option, it is enabled by +default for languages like C++ which normally require exception handling, +and disabled for languages like C that do not normally require it. +However, when compiling C code that needs to interoperate properly with +exception handlers written in C++, you may need to enable this option. +You may also wish to disable this option is you are compiling older C++ +programs that don't use exception handling. + +@item -fpcc-struct-return +Return ``short'' @code{struct} and @code{union} values in memory like +longer ones, rather than in registers. This convention is less +efficient, but it has the advantage of allowing intercallability between +GNU CC-compiled files and files compiled with other compilers. + +The precise convention for returning structures in memory depends +on the target configuration macros. + +Short structures and unions are those whose size and alignment match +that of some integer type. + +@item -freg-struct-return +Use the convention that @code{struct} and @code{union} values are +returned in registers when possible. This is more efficient for small +structures than @samp{-fpcc-struct-return}. + +If you specify neither @samp{-fpcc-struct-return} nor its contrary +@samp{-freg-struct-return}, GNU CC defaults to whichever convention is +standard for the target. If there is no standard convention, GNU CC +defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC +is the principal compiler. In those cases, we can choose the standard, +and we chose the more efficient register return alternative. + +@item -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. + +@item -fshort-double +Use the same size for @code{double} as for @code{float}. + +@item -fshared-data +Requests that the data and non-@code{const} variables of this +compilation be shared data rather than private data. The distinction +makes sense only on certain operating systems, where shared data is +shared between processes running the same program, while private data +exists in one copy per process. + +@item -fno-common +Allocate even uninitialized global variables in the bss section of the +object file, rather than generating them as common blocks. This has the +effect that if the same variable is declared (without @code{extern}) in +two different compilations, you will get an error when you link them. +The only reason this might be useful is if you wish to verify that the +program will work on other systems which always work this way. + +@item -fno-ident +Ignore the @samp{#ident} directive. + +@item -fno-gnu-linker +Do not output global initializations (such as C++ constructors and +destructors) in the form used by the GNU linker (on systems where the GNU +linker is the standard method of handling them). Use this option when +you want to use a non-GNU linker, which also requires using the +@code{collect2} program to make sure the system linker includes +constructors and destructors. (@code{collect2} is included in the GNU CC +distribution.) For systems which @emph{must} use @code{collect2}, the +compiler driver @code{gcc} is configured to do this automatically. + +@item -finhibit-size-directive +Don't output a @code{.size} assembler directive, or anything else that +would cause trouble if the function is split in the middle, and the +two halves are placed at locations far apart in memory. This option is +used when compiling @file{crtstuff.c}; you should not need to use it +for anything else. + +@item -fverbose-asm +Put extra commentary information in the generated assembly code to +make it more readable. This option is generally only of use to those +who actually need to read the generated assembly code (perhaps while +debugging the compiler itself). + +@samp{-fno-verbose-asm}, the default, causes the +extra information to be omitted and is useful when comparing two assembler +files. + +@item -fvolatile +Consider all memory references through pointers to be volatile. + +@item -fvolatile-global +Consider all memory references to extern and global data items to +be volatile. + +@item -fpic +@cindex global offset table +@cindex PIC +Generate position-independent code (PIC) suitable for use in a shared +library, if supported for the target machine. Such code accesses all +constant addresses through a global offset table (GOT). The dynamic +loader resolves the GOT entries when the program starts (the dynamic +loader is not part of GNU CC; it is part of the operating system). If +the GOT size for the linked executable exceeds a machine-specific +maximum size, you get an error message from the linker indicating that +@samp{-fpic} does not work; in that case, recompile with @samp{-fPIC} +instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k +on the m68k and RS/6000. The 386 has no such limit.) + +Position-independent code requires special support, and therefore works +only on certain machines. For the 386, GNU CC supports PIC for System V +but not for the Sun 386i. Code generated for the IBM RS/6000 is always +position-independent. + +@item -fPIC +If supported for the target machine, emit position-independent code, +suitable for dynamic linking and avoiding any limit on the size of the +global offset table. This option makes a difference on the m68k, m88k, +and the Sparc. + +Position-independent code requires special support, and therefore works +only on certain machines. + +@item -ffixed-@var{reg} +Treat the register named @var{reg} as a fixed register; generated code +should never refer to it (except perhaps as a stack pointer, frame +pointer or in some other fixed role). + +@var{reg} must be the name of a register. The register names accepted +are machine-specific and are defined in the @code{REGISTER_NAMES} +macro in the machine description macro file. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fcall-used-@var{reg} +Treat the register named @var{reg} as an allocable register that is +clobbered by function calls. It may be allocated for temporaries or +variables that do not live across a call. Functions compiled this way +will not save and restore the register @var{reg}. + +It is an error to used this flag with the frame pointer or stack pointer. +Use of this flag for other registers that have fixed pervasive roles in +the machine's execution model will produce disastrous results. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fcall-saved-@var{reg} +Treat the register named @var{reg} as an allocable register saved by +functions. It may be allocated even for temporaries or variables that +live across a call. Functions compiled this way will save and restore +the register @var{reg} if they use it. + +It is an error to used this flag with the frame pointer or stack pointer. +Use of this flag for other registers that have fixed pervasive roles in +the machine's execution model will produce disastrous results. + +A different sort of disaster will result from the use of this flag for +a register in which function values may be returned. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -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. + +@item -fcheck-memory-usage +Generate extra code to check each memory access. GNU CC will generate +code that is suitable for a detector of bad memory accesses such as +@file{Checker}. + +You must also specify this option when you compile functions you call that +have side effects. If you do not, you may get erroneous messages from +the detector. Normally, you should compile all your code with this option. +If you use functions from a library that have side-effects (such as +@code{read}), you may not be able to recompile the library and +specify this option. In that case, you can enable the +@samp{-fprefix-function-name} option, which requests GNU CC to encapsulate +your code and make other functions look as if they were compiled with +@samp{-fcheck-memory-usage}. This is done by calling ``stubs'', +which are provided by the detector. If you cannot find or build +stubs for every function you call, you may have to specify +@samp{-fcheck-memory-usage} without @samp{-fprefix-function-name}. + +If you specify this option, you can not use the @code{asm} or +@code{__asm__} keywords in functions with memory checking enabled. The +compiler cannot understand what the @code{asm} statement will do, and +therefore cannot generate the appropriate code, so it is rejected. +However, the function attribute @code{no_check_memory_usage} will +disable memory checking within a function, and @code{asm} statements can +be put inside such functions. Inline expansion of a non-checked +function within a checked function is permitted; the inline function's +memory accesses won't be checked, but the rest will. + +If you move your @code{asm} statements to non-checked inline functions, +but they do access memory, you can add calls to the support code in your +inline function, to indicate any reads, writes, or copies being done. +These calls would be similar to those done in the stubs described above. + +@c FIXME: The support-routine interface is defined by the compiler and +@c should be documented! + +@item -fprefix-function-name +Request GNU CC to add a prefix to the symbols generated for function names. +GNU CC adds a prefix to the names of functions defined as well as +functions called. Code compiled with this option and code compiled +without the option can't be linked together, unless or stubs are used. + +If you compile the following code with @samp{-fprefix-function-name} +@example +extern void bar (int); +void +foo (int a) +@{ + return bar (a + 5); + +@} +@end example + +@noindent +GNU CC will compile the code as if it was written: +@example +extern void prefix_bar (int); +void +prefix_foo (int a) +@{ + return prefix_bar (a + 5); +@} +@end example +This option is designed to be used with @samp{-fcheck-memory-usage}. + +@item -finstrument-functions +Generate instrumentation calls for entry and exit to functions. Just +after function entry and just before function exit, the following +profiling functions will be called with the address of the current +function and its call site. (On some platforms, +@code{__builtin_return_address} does not work beyond the current +function, so the call site information may not be available to the +profiling functions otherwise.) + +@example +void __cyg_profile_func_enter (void *this_fn, void *call_site); +void __cyg_profile_func_exit (void *this_fn, void *call_site); +@end example + +The first argument is the address of the start of the current function, +which may be looked up exactly in the symbol table. + +This instrumentation is also done for functions expanded inline in other +functions. The profiling calls will indicate where, conceptually, the +inline function is entered and exited. This means that addressable +versions of such functions must be available. If all your uses of a +function are expanded inline, this may mean an additional expansion of +code size. If you use @samp{extern inline} in your C code, an +addressable version of such functions must be provided. (This is +normally the case anyways, but if you get lucky and the optimizer always +expands the functions inline, you might have gotten away without +providing static copies.) + +A function may be given the attribute @code{no_instrument_function}, in +which case this instrumentation will not be done. This can be used, for +example, for the profiling functions listed above, high-priority +interrupt routines, and any functions from which the profiling functions +cannot safely be called (perhaps signal handlers, if the profiling +routines generate output or allocate memory). + +@item -fstack-check +Generate code to verify that you do not go beyond the boundary of the +stack. You should specify this flag if you are running in an +environment with multiple threads, but only rarely need to specify it in +a single-threaded environment since stack overflow is automatically +detected on nearly all systems if there is only one stack. + +@c CYGNUS LOCAL unaligned-pointers +@item -funaligned-pointers +Assume that all pointers contain unaligned addresses. On machines where +unaligned memory accesses trap, this will result in much larger and slower +code for all pointer dereferences, but the code will work even if addresses +are unaligned. +@c END CYGNUS LOCAL + +@c CYGNUS LOCAL unaligned-struct-hack +@item -funaligned-struct-hack +Always access structure fields using loads and stores of the declared size. +This option is useful for code that derefences pointers to unaligned +structures, but only accesses fields that are themselves aligned. Without +this option, gcc may try to use a memory access larger than the field. +This might give an unaligned access fault on some hardware. + +This option makes some invalid code work at the expense of disabling +some optimizations. It is strongly recommended that this option not be +used. +@c END CYGNUS LOCAL + +@c CYGNUS LOCAL -- meissner/nortel +@item -foptimize-comparisons +Optimize multiple comparisons better within @code{&&} and @code{||} +expressions. This is an experimental option. In some cases it can +result in worse code. It depends on many factors. Now it is known +only that the optimization works well for PPC740 and PPC750. This +option switches on the following transformations: +@example + (a != 0 || b != 0) => ((a | b) != 0) + (a == 0 && b == 0) => ((a | b) == 0) + (a != b || c != d) => (((a ^ b) | (c ^ d)) != 0) + (a == b && c == d) => (((a ^ b) | (c ^ d)) == 0) + (a != 0 && b != 0) => (((a | -a) & (b | -b)) < 0) + (a != b && c != d) => x = a ^ b; y = c ^ d; (((x | -x) & (y | -y)) < 0) + (a < 0 || b < 0) => ((a | b) < 0) + (a < 0 && b < 0) => ((a & b) < 0) + (a >= 0 || b >= 0) => ((a & b) >= 0) + (a >= 0 && b >= 0) => ((a | b) >= 0) + (a < 0 || b >= 0) => ((a | ~b) < 0) + (a < 0 && b >= 0) => ((a & ~b) < 0) + (a >= 0 || b < 0) => ((~a | b) < 0) + (a >= 0 && b < 0) => ((~a & b) < 0) + (a != 0 && b < 0) => (((a | -a) & b) < 0) + (a != 0 && b >= 0) => (((a | -a) & ~b) < 0) + (a < 0 && b != 0) => (((b | -b) & a) < 0) + (a >= 0 && b != 0) => (((b | -b) & ~a) < 0) +@end example +@c END CYGNUS LOCAL -- meissner/nortel +@end table + +@c CYGNUS LOCAL v850/law +@node Offset info Option +@section Offset info Option + +@code{-offset-info output-file} + +This option simplifys access to C struct's from assembler. +For each member of each structure the compiler +will output a @code{.equ} directive to associate a symbol +with the member's offset in bytes into the structure. The +symbol itself is the concatenation of the structure's tag name and +the member's name, separated by an underscore. + +This option will output to the specified @code{output-file} an +assembler @code{.equ} directive for each member of each structure +found in each compilation. The @code{.equ} directives for the +structures in a single header file can be obtained as follows: + +@example +gcc -fsyntax-only -offset-info m.s -x c m.h +@end example + +@noindent +Where @code{m.h} is the header containing the structures, and +@code{m.s} is where the directives are output. + +The following is a short example of output produced by +@code{-offset-info}. + +@example +input file (for example m.h): + + struct W @{ + double d; + int i; + @}; + + struct X @{ + int a; + int b; + + struct Y @{ + int a; + int b; + @}; + + struct Y y; + struct Y yy[10]; + struct Y* p; + @}; + +output file (for example m.s): + .equ W_d,0 + .equ W_i,8 + .equ Y_a,0 + .equ Y_b,4 + .equ X_a,0 + .equ X_b,4 + .equ X_y,8 + .equ X_yy,16 + .equ X_p,96 +@end example + +@noindent +The @code{-offset-info} option has the following caveats: + +@table @bullet +@item +No directives are output for bit-field members. + +@item +No directives are output for members who's offsets +(as measured in bits) is greater than the word size of the host. + +@item +No directives are output for members who's offsets are not +constants. This can happened only in structures which use some +gcc specific extensions which allow for variable sized members. + +@end table +@c END CYGNUS LOCAL + +@cindex aliasing of parameters +@cindex parameters, aliased +@table @code +@item -fargument-alias +@itemx -fargument-noalias +@itemx -fargument-noalias-global +Specify the possible relationships among parameters and between +parameters and global data. + +@samp{-fargument-alias} specifies that arguments (parameters) may +alias each other and may alias global storage. +@samp{-fargument-noalias} specifies that arguments do not alias +each other, but may alias global storage. +@samp{-fargument-noalias-global} specifies that arguments do not +alias each other and do not alias global storage. + +Each language will automatically use whatever option is required by +the language standard. You should not need to use these options yourself. + +@item -fleading-underscore +This option and its counterpart, -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. +@end table + +@node Environment Variables +@section Environment Variables Affecting GNU CC +@cindex environment variables + +This section describes several environment variables that affect how GNU +CC operates. Some of them work by specifying directories or prefixes to use +when searching for various kinds of files. Some are used to specify other +aspects of the compilation environment. + +@ifclear INTERNALS +Note that you can also specify places to search using options such as +@samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These +take precedence over places specified using environment variables, which +in turn take precedence over those specified by the configuration of GNU +CC. +@end ifclear +@ifset INTERNALS +Note that you can also specify places to search using options such as +@samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These +take precedence over places specified using environment variables, which +in turn take precedence over those specified by the configuration of GNU +CC. @xref{Driver}. +@end ifset + +@table @code +@item TMPDIR +@findex TMPDIR +If @code{TMPDIR} is set, it specifies the directory to use for temporary +files. GNU CC uses temporary files to hold the output of one stage of +compilation which is to be used as input to the next stage: for example, +the output of the preprocessor, which is the input to the compiler +proper. + +@item GCC_EXEC_PREFIX +@findex GCC_EXEC_PREFIX +If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the +names of the subprograms executed by the compiler. No slash is added +when this prefix is combined with the name of a subprogram, but you can +specify a prefix that ends with a slash if you wish. + +@c CYGNUS LOCAL -- meissner/relative pathnames +If @code{GCC_EXEC_PREFIX} is not set, GNU CC will attempt to figure out +an appropriate prefix to use based on the pathname it was invoked with. +@c END CYGNUS LOCAL -- meissner/relative pathnames + +If GNU CC cannot find the subprogram using the specified prefix, it +tries looking in the usual places for the subprogram. + +The default value of @code{GCC_EXEC_PREFIX} is +@file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value +of @code{prefix} when you ran the @file{configure} script. + +Other prefixes specified with @samp{-B} take precedence over this prefix. + +This prefix is also used for finding files such as @file{crt0.o} that are +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} +(more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries +replacing that beginning with the specified prefix to produce an +alternate directory name. Thus, with @samp{-Bfoo/}, GNU CC will search +@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}. +These alternate directories are searched first; the standard directories +come next. + +@item COMPILER_PATH +@findex COMPILER_PATH +The value of @code{COMPILER_PATH} is a colon-separated list of +directories, much like @code{PATH}. GNU CC tries the directories thus +specified when searching for subprograms, if it can't find the +subprograms using @code{GCC_EXEC_PREFIX}. + +@item LIBRARY_PATH +@findex LIBRARY_PATH +The value of @code{LIBRARY_PATH} is a colon-separated list of +directories, much like @code{PATH}. When configured as a native compiler, +GNU CC tries the directories thus specified when searching for special +linker files, if it can't find them using @code{GCC_EXEC_PREFIX}. Linking +using GNU CC also uses these directories when searching for ordinary +libraries for the @samp{-l} option (but directories specified with +@samp{-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 +@code{PATH}. When GNU CC searches for header files, it tries the +directories listed in the variable for the language you are using, after +the directories specified with @samp{-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 @samp{-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 @code{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 +This variable is used to pass locale information to the compiler. One way in +which this information is used is to determine the character set to be used +when character literals, string literals and comments are parsed in C and C++. +When the compiler is configured to allow multibyte characters, +the following values for @code{LANG} are recognized: + +@table @code +@item C-JIS +Recognize JIS characters. +@item C-SJIS +Recognize SJIS characters. +@item C-EUCJP +Recognize EUCJP characters. +@end table + +If @code{LANG} is not defined, or if it has some other value, then the +compiler will use mblen and mbtowc as defined by the default locale to +recognize and translate multibyte characters. +@end table + +@node Running Protoize +@section Running Protoize + +The program @code{protoize} is an optional part of GNU C. You can use +it to add prototypes to a program, thus converting the program to ANSI +C in one respect. The companion program @code{unprotoize} does the +reverse: it removes argument types from any prototypes that are found. + +When you run these programs, you must specify a set of source files as +command line arguments. The conversion programs start out by compiling +these files to see what functions they define. The information gathered +about a file @var{foo} is saved in a file named @file{@var{foo}.X}. + +After scanning comes actual conversion. The specified files are all +eligible to be converted; any files they include (whether sources or +just headers) are eligible as well. + +But not all the eligible files are converted. By default, +@code{protoize} and @code{unprotoize} convert only source and header +files in the current directory. You can specify additional directories +whose files should be converted with the @samp{-d @var{directory}} +option. You can also specify particular files to exclude with the +@samp{-x @var{file}} option. A file is converted if it is eligible, its +directory name matches one of the specified directory names, and its +name within the directory has not been excluded. + +Basic conversion with @code{protoize} consists of rewriting most +function definitions and function declarations to specify the types of +the arguments. The only ones not rewritten are those for varargs +functions. + +@code{protoize} optionally inserts prototype declarations at the +beginning of the source file, to make them available for any calls that +precede the function's definition. Or it can insert prototype +declarations with block scope in the blocks where undeclared functions +are called. + +Basic conversion with @code{unprotoize} consists of rewriting most +function declarations to remove any argument types, and rewriting +function definitions to the old-style pre-ANSI form. + +Both conversion programs print a warning for any function declaration or +definition that they can't convert. You can suppress these warnings +with @samp{-q}. + +The output from @code{protoize} or @code{unprotoize} replaces the +original source file. The original file is renamed to a name ending +with @samp{.save}. If the @samp{.save} file already exists, then +the source file is simply discarded. + +@code{protoize} and @code{unprotoize} both depend on GNU CC itself to +scan the program and collect information about the functions it uses. +So neither of these programs will work until GNU CC is installed. + +Here is a table of the options you can use with @code{protoize} and +@code{unprotoize}. Each option works with both programs unless +otherwise stated. + +@table @code +@item -B @var{directory} +Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the +usual directory (normally @file{/usr/local/lib}). This file contains +prototype information about standard system functions. This option +applies only to @code{protoize}. + +@item -c @var{compilation-options} +Use @var{compilation-options} as the options when running @code{gcc} to +produce the @samp{.X} files. The special option @samp{-aux-info} is +always passed in addition, to tell @code{gcc} to write a @samp{.X} file. + +Note that the compilation options must be given as a single argument to +@code{protoize} or @code{unprotoize}. If you want to specify several +@code{gcc} options, you must quote the entire set of compilation options +to make them a single word in the shell. + +There are certain @code{gcc} arguments that you cannot use, because they +would produce the wrong kind of output. These include @samp{-g}, +@samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in +the @var{compilation-options}, they are ignored. + +@item -C +Rename files to end in @samp{.C} instead of @samp{.c}. +This is convenient if you are converting a C program to C++. +This option applies only to @code{protoize}. + +@item -g +Add explicit global declarations. This means inserting explicit +declarations at the beginning of each source file for each function +that is called in the file and was not declared. These declarations +precede the first function definition that contains a call to an +undeclared function. This option applies only to @code{protoize}. + +@item -i @var{string} +Indent old-style parameter declarations with the string @var{string}. +This option applies only to @code{protoize}. + +@code{unprotoize} converts prototyped function definitions to old-style +function definitions, where the arguments are declared between the +argument list and the initial @samp{@{}. By default, @code{unprotoize} +uses five spaces as the indentation. If you want to indent with just +one space instead, use @samp{-i " "}. + +@item -k +Keep the @samp{.X} files. Normally, they are deleted after conversion +is finished. + +@item -l +Add explicit local declarations. @code{protoize} with @samp{-l} inserts +a prototype declaration for each function in each block which calls the +function without any declaration. This option applies only to +@code{protoize}. + +@item -n +Make no real changes. This mode just prints information about the conversions +that would have been done without @samp{-n}. + +@item -N +Make no @samp{.save} files. The original files are simply deleted. +Use this option with caution. + +@item -p @var{program} +Use the program @var{program} as the compiler. Normally, the name +@file{gcc} is used. + +@item -q +Work quietly. Most warnings are suppressed. + +@item -v +Print the version number, just like @samp{-v} for @code{gcc}. +@end table + +If you need special compiler options to compile one of your program's +source files, then you should generate that file's @samp{.X} file +specially, by running @code{gcc} on that source file with the +appropriate options and the option @samp{-aux-info}. Then run +@code{protoize} on the entire set of files. @code{protoize} will use +the existing @samp{.X} file because it is newer than the source file. +For example: + +@example +gcc -Dfoo=bar file1.c -aux-info +protoize *.c +@end example + +@noindent +You need to include the special files along with the rest in the +@code{protoize} command, even though their @samp{.X} files already +exist, because otherwise they won't get converted. + +@xref{Protoize Caveats}, for more information on how to use +@code{protoize} successfully. + |