diff options
Diffstat (limited to 'contrib/gcc/invoke.texi')
| -rw-r--r-- | contrib/gcc/invoke.texi | 4492 |
1 files changed, 4492 insertions, 0 deletions
diff --git a/contrib/gcc/invoke.texi b/contrib/gcc/invoke.texi new file mode 100644 index 0000000..17b94dc --- /dev/null +++ b/contrib/gcc/invoke.texi @@ -0,0 +1,4492 @@ +@c Copyright (C) 1988, 89, 92, 93, 94, 1995 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. + +@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. +* 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 -x @var{language} +@end smallexample + +@item C Language Options +@xref{C Dialect Options,,Options Controlling C Dialect}. +@smallexample +-ansi -fallow-single-precision -fcond-mismatch -fno-asm +-fno-builtin -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 +-fall-virtual -fdollars-in-identifiers -felide-constructors +-fenum-int-equiv -fexternal-templates -ffor-scope -fno-for-scope +-fhandle-signatures -fmemoize-lookups -fno-default-inline -fno-gnu-keywords +-fnonnull-objects -foperator-names -fstrict-prototype +-fthis-is-variable -nostdinc++ -traditional +e@var{n} +@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-subscript -Wcomment +-Wconversion -Wenum-clash -Werror -Wformat +-Wid-clash-@var{len} -Wimplicit -Wimport -Winline +-Wlarger-than-@var{len} -Wmissing-declarations +-Wmissing-prototypes -Wnested-externs +-Wno-import -Woverloaded-virtual -Wparentheses +-Wpointer-arith -Wredundant-decls -Wreorder -Wreturn-type -Wshadow +-Wstrict-prototypes -Wswitch -Wsynth -Wtemplate-debugging +-Wtraditional -Wtrigraphs -Wuninitialized -Wunused +-Wwrite-strings +@end smallexample + +@item Debugging Options +@xref{Debugging Options,,Options for Debugging Your Program or GCC}. +@smallexample +-a -d@var{letters} -fpretend-float +-g -g@var{level} -gcoff -gdwarf -gdwarf+ +-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 +-fcaller-saves -fcse-follow-jumps -fcse-skip-blocks +-fdelayed-branch -fexpensive-optimizations +-ffast-math -ffloat-store -fforce-addr -fforce-mem +-finline-functions -fkeep-inline-functions +-fno-default-inline -fno-defer-pop -fno-function-cse +-fno-inline -fno-peephole -fomit-frame-pointer +-frerun-cse-after-loop -fschedule-insns +-fschedule-insns2 -fstrength-reduce -fthread-jumps +-funroll-all-loops -funroll-loops +-O -O0 -O1 -O2 -O3 +@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} +-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} +@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 -m68030 -m68040 -m68881 +-mbitfield -mc68000 -mc68020 -mfpa -mnobitfield +-mrtd -mshort -msoft-float + +@emph{VAX Options} +-mg -mgnu -munix + +@emph{SPARC Options} +-mapp-regs -mcypress -mepilogue -mflat -mfpu -mhard-float +-mhard-quad-float -mno-app-regs -mno-flat -mno-fpu +-mno-epilogue -mno-unaligned-doubles +-msoft-float -msoft-quad-float +-msparclite -msupersparc -munaligned-doubles -mv8 + +SPARC V9 compilers support the following options +in addition to the above: + +-mmedlow -mmedany +-mint32 -mint64 -mlong32 -mlong64 +-mno-stack-bias -mstack-bias + +@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 -m2 -m3 -m6 -mbsd -mxopen -mno-symrename + +@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} +-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 +-msoft-float -mhard-float -mmultiple -mno-multiple +-mstring -mno-string -mbit-align -mno-bit-align +-mstrict-align -mno-strict-align -mrelocatable -mno-relocatable +-mtoc -mno-toc -mtraceback -mno-traceback +-mlittle -mlittle-endian -mbig -mbig-endian +-mcall-aix -mcall-sysv -mprototype + +@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 -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 + +@emph{i386 Options} +-m486 -m386 -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} +-mdisable-fpregs -mdisable-indexing -mfast-indirect-calls +-mgas -mjump-in-delay -mlong-millicode-calls -mno-disable-fpregs +-mno-disable-indexing -mno-fast-indirect-calls -mno-gas +-mno-jump-in-delay -mno-millicode-long-calls +-mno-portable-runtime -mno-soft-float -msoft-float +-mpa-risc-1-0 -mpa-risc-1-1 -mportable-runtime -mschedule=@var{list} + +@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 + +@emph{Clipper Options} +-mc300 -mc400 + +@emph{H8/300 Options} +-mrelax -mh + +@emph{System V Options} +-Qy -Qn -YP,@var{paths} -Ym,@var{dir} +@end smallexample + +@item Code Generation Options +@xref{Code Gen Options,,Options for Code Generation Conventions}. +@smallexample +-fcall-saved-@var{reg} -fcall-used-@var{reg} +-ffixed-@var{reg} -finhibit-size-directive +-fno-common -fno-ident -fno-gnu-linker +-fpcc-struct-return -fpic -fPIC +-freg-struct-return -fshared-data -fshort-enums +-fshort-double -fvolatile -fvolatile-global +-fverbose-asm -fpack-struct +e0 +e1 +@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. +@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}, 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 GNU class +library libg++. +@cindex @code{g++ 1.@var{xx}} +@cindex @code{g++}, separate compiler +@cindex @code{g++} older version +@footnote{Prior to release 2 of the compiler, +there was a separate @code{g++} compiler. That version was based on GNU +CC, but not integrated with it. Versions of @code{g++} with a +@samp{1.@var{xx}} version number---for example, @code{g++} version 1.37 +or 1.42---are much less reliable than the versions integrated with GCC +2. Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will +simply not work.} 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, disallows @samp{$} as part of +identifiers, and 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 -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 two leading +underscores. 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 -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. + +@item +In C++ programs, assignment to @code{this} is permitted with +@samp{-traditional}. (The option @samp{-fthis-is-variable} also has +this effect.) +@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. + +@item +In the preprocessor, comments convert to nothing at all, rather than +to a space. This allows traditional token concatenation. + +@item +In preprocessing directive, the @samp{#} symbol must appear as the first +character of a line. + +@item +In the preprocessor, 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.) + +@item -traditional-cpp +Attempt to support some aspects of traditional C preprocessors. +This includes the last five items in the table immediately above, +but none of the other effects of @samp{-traditional}. + +@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}. + +@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 -felide-constructors -O -c firstClass.C +@end example + +@noindent +In this example, only @samp{-felide-constructors} 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 -fall-virtual +Treat all possible member functions as virtual, implicitly. +All member functions (except for constructor functions and @code{new} or +@code{delete} member operators) are treated as virtual functions of the +class where they appear. + +This does not mean that all calls to these member functions will be made +through the internal table of virtual functions. Under some +circumstances, the compiler can determine that a call to a given virtual +function can be made directly; in these cases the calls are direct in +any case. + +@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. + +@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. + +@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 some target systems but not others.) +Traditional C allowed the character @samp{$} to form part of +identifiers. However, ANSI C and C++ forbid @samp{$} in identifiers. + +@item -fenum-int-equiv +Anachronistically permit implicit conversion of @code{int} to +enumeration types. Current C++ allows conversion of @code{enum} to +@code{int}, but not the other way around. + +@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. + +@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. + +@item -ffor-scope +@item -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 -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 -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. If you +compile any of your code with this flag, you must compile @emph{all} of +your code with this flag (including libg++, if you use it). + +This flag is not useful when compiling with -fvtable-thunks. + +@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 -fmemoize-lookups +@itemx -fsave-memoized +Use heuristics to compile faster. These heuristics are not enabled by +default, since they are only effective for certain input files. Other +input files compile more slowly. + +The first time the compiler must build a call to a member function (or +reference to a data member), it must (1) determine whether the class +implements member functions of that name; (2) resolve which member +function to call (which involves figuring out what sorts of type +conversions need to be made); and (3) check the visibility of the member +function to the caller. All of this adds up to slower compilation. +Normally, the second time a call is made to that member function (or +reference to that data member), it must go through the same lengthy +process again. This means that code like this: + +@smallexample +cout << "This " << p << " has " << n << " legs.\n"; +@end smallexample + +@noindent +makes six passes through all three steps. By using a software cache, a +``hit'' significantly reduces this cost. Unfortunately, using the cache +introduces another layer of mechanisms which must be implemented, and so +incurs its own overhead. @samp{-fmemoize-lookups} enables the software +cache. + +Because access privileges (visibility) to members and member functions +may differ from one function context to the next, G++ may need to flush +the cache. With the @samp{-fmemoize-lookups} flag, the cache is flushed +after every function that is compiled. The @samp{-fsave-memoized} flag +enables the same software cache, but when the compiler determines that +the context of the last function compiled would yield the same access +privileges of the next function to compile, it preserves the cache. +This is most helpful when defining many member functions for the same +class: with the exception of member functions which are friends of other +classes, each member function has exactly the same access privileges as +every other, and the cache need not be flushed. + +The code that implements these flags has rotted; you should probably +avoid using them. + +@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}. + +This flag no longer affects declarations with C++ linkage. + +@item -fno-nonnull-objects +Don't assume that a reference is initialized to refer to a valid object. +Although the current C++ Working Paper prohibits null references, some +old code may rely on them, and you can use @samp{-fno-nonnull-objects} +to turn on checking. + +At the moment, the compiler only does this checking for conversions to +virtual base classes. + +@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 -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. + +@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 libg++.) + +@item -traditional +For C++ programs (in addition to the effects that apply to both C and +C++), this has the same effect as @samp{-fthis-is-variable}. +@xref{C Dialect Options,, Options Controlling C Dialect}. +@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}. + +@item -Wenum-clash +@itemx -Woverloaded-virtual +@itemx -Wtemplate-debugging +Warnings that apply only to C++ programs. @xref{Warning +Options,,Options to Request or Suppress Warnings}. + +@item +e@var{n} +Control how virtual function definitions are used, in a fashion +compatible with @code{cfront} 1.x. @xref{Code Gen Options,,Options for +Code Generation Conventions}. +@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 standard C; reject +all programs that use forbidden extensions. + +Valid ANSI standard 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 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 recommend, rather, that +users take advantage of the extensions of GNU C and disregard the +limitations of other compilers. Aside from certain supercomputers and +obsolete small machines, there is less and less reason ever to use any +other C compiler other than for bootstrapping GNU CC. + +@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 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 +Warn whenever a function or parameter is implicitly declared. + +@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. + +@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. + +To suppress this warning for an expression, simply cast it to void. For +unused variables and parameters, 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 -Wenum-clash +@cindex enumeration clash warnings +@cindex warning for enumeration conversions +Warn about conversion between different enumeration types. +(C++ only). + +@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. + +@item -Wtemplate-debugging +@cindex template debugging +When using templates in a C++ program, warn if debugging is not yet +fully available (C++ only). + +@item -Wall +All of the above @samp{-W} options combined. These are all the +options which pertain to usage that we recommend avoiding and that we +believe is easy to avoid, even in conjunction with macros. +@end table + +The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall} +because they warn about constructions that we consider reasonable to +use, on occasion, in clean programs. + +@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 +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 +@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 -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 help you 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 -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 -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 -Woverloaded-virtual +@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 (C++ only). 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 -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 =}. + +@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+}, or @samp{-gdwarf} +(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 in the native format (if that is 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 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 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 -g@var{level} +@itemx -ggdb@var{level} +@itemx -gstabs@var{level} +@itemx -gcoff@var{level} +@itemx -gxcoff@var{level} +@itemx -gdwarf@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 -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 M +Dump all macro definitions, at the end of preprocessing, and write no +output. +@item N +Dump all macro names, at the end of preprocessing. +@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 L +Dump after loop optimization, to @file{@var{file}.loop}. +@item t +Dump after the second CSE pass (including the jump optimization that +sometimes follows CSE), to @file{@var{file}.cse2}. +@item f +Dump after flow analysis, to @file{@var{file}.flow}. +@item c +Dump after instruction combination, to the file +@file{@var{file}.combine}. +@item S +Dump after the first instruction scheduling pass, to +@file{@var{file}.sched}. +@item l +Dump after local register allocation, to +@file{@var{file}.lreg}. +@item g +Dump after global register allocation, to +@file{@var{file}.greg}. +@item R +Dump after the second instruction scheduling pass, to +@file{@var{file}.sched2}. +@item J +Dump after last jump optimization, to @file{@var{file}.jump2}. +@item d +Dump after delayed branch scheduling, to @file{@var{file}.dbr}. +@item k +Dump after conversion from registers to stack, to @file{@var{file}.stack}. +@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. +@end table + +@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. + +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. + +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. 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. + +@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. + +@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 -fexpensive-optimizations +Perform a number of minor optimizations that are relatively expensive. + +@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 -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 enabled by default on certain machines, usually those +which have no call-preserved registers to use instead. + +@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 -fno-peephole +Disable any machine-specific peephole optimizations. +@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 -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. + +@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. + +@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. Only a few systems support 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{directory} 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}. +@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 + +@menu +* M680x0 Options:: +* VAX Options:: +* SPARC Options:: +* Convex Options:: +* AMD29K Options:: +* ARM 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:: +* System V Options:: +@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. + +@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. If your 68040 does not have code to +emulate those instructions, use @samp{-m68040}. + +@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 -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} option +implies @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 and 68020 +processors, but not by the 68000. +@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 although +debugger support is still incomplete. 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. + +@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. +@end table + +In a future version of GCC, these options will very likely be +renamed to @samp{-mcpu=cypress} and @samp{-mcpu=supersparc}. + +These @samp{-m} switches are supported in addition to the above +on SPARC V9 processors: + +@table @code +@item -mmedlow +Generate code for the Medium/Low code model: assume a 32 bit address space. +Programs are statically linked, PIC is not supported. Pointers are still +64 bits. + +It is very likely that a future version of GCC will rename this option. + +@item -mmedany +Generate code for the Medium/Anywhere code model: assume a 32 bit text +segment starting at offset 0, and a 32 bit data segment starting anywhere +(determined at link time). Programs are statically linked, PIC is not +supported. Pointers are still 64 bits. + +It is very likely that a future version of GCC will rename this option. + +@item -mint64 +Types long and int are 64 bits. + +@item -mlong32 +Types long and int are 32 bits. + +@item -mlong64 +@itemx -mint32 +Type long is 64 bits, and type int is 32 bits. + +@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 -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 -m2 +@itemx -m3 +@kindex -m2 +@kindex -m3 +These options are identical. Generate code for the ARM2 and ARM3 +processors. This option is the default. You should also use this +option to generate code for ARM6 processors that are running with a +26-bit program counter. + +@item -m6 +@kindex -m6 +Generate code for the ARM6 processor when running with a 32-bit program +counter. + +@item -mapcs +@kindex -mapcs +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. + +@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. +@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 +@kindex -mpower +@kindex -mpower2 +@kindex -mpowerpc +@kindex -mpowerpc-gpopt +@kindex -mpowerpc-gfxopt +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 MPC6xx microprocessors. The PowerPC +architecture defines 64-bit instructions, but they are not supported by +any current processors. + +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 that option rather than these. + +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. + +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. + +PowerPC assemblers support both the old and new mnemonics, as will later +POWER assemblers. Current POWER assemblers only support the old +mnemonics. Specify @samp{-mnew-mnemonics} if you have an assembler that +supports them, otherwise specify @samp{-mold-mnemonics}. + +The default value of these options depends on how GNU CC was configured. +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} +Set architecture type, register usage, choice of mnemonics, and instruction +scheduling parameters for machine type @var{cpu_type}. By default, +@var{cpu_type} is the target system defined when GNU CC was configured. +Supported values for @var{cpu_type} are @samp{rios1}, @samp{rios2}, @samp{rsc}, +@samp{601}, @samp{603}, @samp{604}, @samp{power}, @samp{powerpc}, @samp{403}, +and @samp{common}. @samp{-mcpu=power} and @samp{-mcpu=powerpc} specify generic +POWER and pure PowerPC (i.e., not MPC601) architecture machine types, with an +appropriate, generic processor model assumed for scheduling purposes.@refill + +Specifying @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, or +@samp{-mcpu=power} enables the @samp{-mpower} option and disables the +@samp{-mpowerpc} option; @samp{-mcpu=601} enables both the @samp{-mpower} and +@samp{-mpowerpc} options; @samp{-mcpu=603}, @samp{-mcpu=604}, @samp{-mcpu=403}, +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 + +To generate code that will operate on all members of the RS/6000 and +PowerPC families, specify @samp{-mcpu=common}. 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 @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, or +@samp{-mcpu=power} also disables the @samp{new-mnemonics} option. +Specifying @samp{-mcpu=601}, @samp{-mcpu=603}, @samp{-mcpu=604}, +@samp{403}, or @samp{-mcpu=powerpc} also enables the @samp{new-mnemonics} +option.@refill + +@item -mfull-toc +@itemx -mno-fp-in-toc +@itemx -mno-sum-in-toc +@itemx -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 -msoft-float +@itemx -mhard-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. + +@item -mstring +@itemx -mno-string +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, anod 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. + +@item -mno-bit-align +@itemx -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. + +@item -mno-strict-align +@itemx -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 +On embedded PowerPC systems generate code that allows (does not allow) +the program to be relocated to a different address at runtime. + +@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 -mno-traceback +@itemx -mtraceback +On embedded PowerPC systems do not (do) generate a traceback tag before +the start of the function. This tag can be used by the debugger to +identify where the start of a function is. + +@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-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 -mprototype +@item -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. +@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 -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. + +@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. + +@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. +This requires GNU as and GNU ld which do most of the work. + +@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 it's preprocessor over user +assembler files (with a @samp{.s} suffix) when assembling them. +@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 -m486 +@itemx -m386 +Control whether or not code is optimized for a 486 instead of an +386. Code generated for an 486 will run on a 386 and vice versa. + +@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. + +@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. + +@item -malign-functions=@var{num} +Align the start of functions to a 2 raised to @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. +@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 -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 -mmillicode-long-calls +Generate code which assumes millicode routines can not be reached +by the standard millicode call sequence, linker-generated long-calls, +or linker-modified millicode calls. In practice this should only be +needed for dynamicly linked executables with extremely large SHLIB_INFO +sections. + +@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 -mfast-indirect-calls +Generate code which performs faster indirect calls. Such code is suitable +for kernels and for static linking. The fast indirect call code will fail +miserably if it's part of a dynamically linked executable and in the presense +of nested functions. + +@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{7100} +for 7@var{n}2 machines. @samp{700} 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 -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). Currently this is buggy in that @samp{#pragma +align 1} is always assumed as well, and cannot be turned off. +@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. +@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. +@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 +@ignore +This should say *what the option does* and only then say +"For compatibility only..." +@item -G +On SVr4 systems, @code{gcc} accepts the option @samp{-G} (and passes +it to the system linker), for compatibility with other compilers. +However, we suggest you use @samp{-symbolic} or @samp{-shared} as +appropriate, instead of supplying linker options on the @code{gcc} +command line. +@end ignore + +@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 + +@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 -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). + +@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). 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. + +The GNU assembler does not fully support PIC. Currently, you must use +some other assembler in order for PIC to work. We would welcome +volunteers to upgrade GAS to handle this; the first part of the job is +to figure out what the assembler must do differently. + +@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 allocatable 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}. + +Use of this flag for a register that has a fixed pervasive role in the +machine's execution model, such as the stack pointer or frame pointer, +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 allocatable 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. + +Use of this flag for a register that has a fixed pervasive role in the +machine's execution model, such as the stack pointer or frame pointer, +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 +e0 +@itemx +e1 +Control whether virtual function definitions in classes are used to +generate code, or only to define interfaces for their callers. (C++ +only). + +These options are provided for compatibility with @code{cfront} 1.x +usage; the recommended alternative GNU C++ usage is in flux. @xref{C++ +Interface,,Declarations and Definitions in One Header}. + +With @samp{+e0}, virtual function definitions in classes are declared +@code{extern}; the declaration is used only as an interface +specification, not to generate code for the virtual functions (in this +compilation). + +With @samp{+e1}, G++ actually generates the code implementing virtual +functions defined in the code, and makes them publicly visible. +@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. They work by specifying directories or prefixes to use +when searching for various kinds of files. + +@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. + +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. +@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. + |
