Return to invoke.texi CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/invoke.texi, revision 1.1

1.1     ! root        1: @c Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
        !             2: @c This is part of the GCC manual.
        !             3: @c For copying conditions, see the file gcc.texi.
        !             4: 
        !             5: @node Invoking GCC
        !             6: @chapter GNU CC Command Options
        !             7: @cindex GNU CC command options
        !             8: @cindex command options
        !             9: @cindex options, GNU CC command
        !            10: 
        !            11: When you invoke GNU CC, it normally does preprocessing, compilation,
        !            12: assembly and linking.  The ``overall options'' allow you to stop this
        !            13: process at an intermediate stage.  For example, the @samp{-c} option
        !            14: says not to run the linker.  Then the output consists of object files
        !            15: output by the assembler.
        !            16: 
        !            17: Other options are passed on to one stage of processing.  Some options
        !            18: control the preprocessor and others the compiler itself.  Yet other
        !            19: options control the assembler and linker; most of these are not
        !            20: documented here, since you rarely need to use any of them.
        !            21: 
        !            22: @cindex C compilation options
        !            23: Most of the command line options that you can use with GNU CC are useful
        !            24: for C programs; when an option is only useful with another language
        !            25: (usually C++), the explanation says so explicitly.  If the description
        !            26: for a particular option does not mention a source language, you can use
        !            27: that option with all supported languages.
        !            28: 
        !            29: @cindex C++ compilation options
        !            30: @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
        !            31: options for compiling C++ programs.
        !            32: 
        !            33: @cindex grouping options
        !            34: @cindex options, grouping
        !            35: The @code{gcc} program accepts options and file names as operands.  Many
        !            36: options have multiletter names; therefore multiple single-letter options
        !            37: may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d
        !            38: -r}}.
        !            39: 
        !            40: @cindex order of options
        !            41: @cindex options, order
        !            42: You can mix options and other arguments.  For the most part, the order
        !            43: you use doesn't matter.  Order does matter when you use several options
        !            44: of the same kind; for example, if you specify @samp{-L} more than once,
        !            45: the directories are searched in the order specified.
        !            46: 
        !            47: Many options have long names starting with @samp{-f} or with
        !            48: @samp{-W}---for example, @samp{-fforce-mem},
        !            49: @samp{-fstrength-reduce}, @samp{-Wformat} and so on.  Most of
        !            50: these have both positive and negative forms; the negative form of
        !            51: @samp{-ffoo} would be @samp{-fno-foo}.  This manual documents
        !            52: only one of these two forms, whichever one is not the default.
        !            53: 
        !            54: @menu
        !            55: * Option Summary::     Brief list of all options, without explanations.
        !            56: * Overall Options::     Controlling the kind of output:
        !            57:                         an executable, object files, assembler files,
        !            58:                         or preprocessed source.
        !            59: * Invoking G++::       Compiling C++ programs.
        !            60: * C Dialect Options::   Controlling the variant of C language compiled.
        !            61: * C++ Dialect Options:: Variations on C++.
        !            62: * Warning Options::     How picky should the compiler be?
        !            63: * Debugging Options::   Symbol tables, measurements, and debugging dumps.
        !            64: * Optimize Options::    How much optimization?
        !            65: * Preprocessor Options:: Controlling header files and macro definitions.
        !            66:                          Also, getting dependency information for Make.
        !            67: * Assembler Options::   Passing options to the assembler.
        !            68: * Link Options::        Specifying libraries and so on.
        !            69: * Directory Options::   Where to find header files and libraries.
        !            70:                         Where to find the compiler executable files.
        !            71: * Target Options::      Running a cross-compiler, or an old version of GNU CC.
        !            72: * Submodel Options::    Specifying minor hardware or convention variations,
        !            73:                         such as 68010 vs 68020.
        !            74: * Code Gen Options::    Specifying conventions for function calls, data layout
        !            75:                         and register usage.
        !            76: * Environment Variables:: Env vars that affect GNU CC.
        !            77: * Running Protoize::    Automatically adding or removing function prototypes.
        !            78: @end menu
        !            79: 
        !            80: @node Option Summary
        !            81: @section Option Summary
        !            82: 
        !            83: Here is a summary of all the options, grouped by type.  Explanations are
        !            84: in the following sections.
        !            85: 
        !            86: @table @emph
        !            87: @item Overall Options
        !            88: @xref{Overall Options,,Options Controlling the Kind of Output}.
        !            89: @smallexample
        !            90: -c  -S  -E  -o @var{file}  -pipe  -v  -x @var{language} 
        !            91: @end smallexample
        !            92: 
        !            93: @item C Language Options
        !            94: @xref{C Dialect Options,,Options Controlling C Dialect}.
        !            95: @smallexample
        !            96: -ansi  -fcond-mismatch  -fno-asm  -fno-builtin
        !            97: -fsigned-bitfields  -fsigned-char 
        !            98: -funsigned-bitfields  -funsigned-char  -fwritable-strings
        !            99: -traditional  -traditional-cpp  -trigraphs
        !           100: @end smallexample
        !           101: 
        !           102: @item C++ Language Options
        !           103: @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
        !           104: @smallexample
        !           105: -fall-virtual  -fdollars-in-identifiers
        !           106: -felide-constructors  -fenum-int-equiv
        !           107: -fexternal-templates  -fmemoize-lookups
        !           108: -fno-strict-prototype  -fnonnull-objects
        !           109: -fthis-is-variable  -nostdinc++
        !           110: @end smallexample
        !           111: 
        !           112: @item Warning Options
        !           113: @xref{Warning Options,,Options to Request or Suppress Warnings}.
        !           114: @smallexample
        !           115: -fsyntax-only  -pedantic  -pedantic-errors
        !           116: -w  -W  -Wall  -Waggregate-return  -Wcast-align  
        !           117: -Wcast-qual  -Wchar-subscript  -Wcomment  -Wconversion
        !           118: -Wenum-clash  -Werror  -Wformat  -Wid-clash-@var{len}
        !           119: -Wimplicit  -Wimport  -Winline  -Wmissing-prototypes
        !           120: -Wnested-externs  -Woverloaded-virtual  -Wparentheses
        !           121: -Wpointer-arith  -Wredundant-decls  -Wreturn-type
        !           122: -Wshadow  -Wstrict-prototypes  -Wswitch
        !           123: -Wtemplate-debugging  -Wtraditional  -Wtrigraphs
        !           124: -Wuninitialized  -Wunused  -Wwrite-strings
        !           125: @end smallexample
        !           126: 
        !           127: @item Debugging Options
        !           128: @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
        !           129: @smallexample
        !           130: -a  -d@var{letters}  -fpretend-float 
        !           131: -g  -g@var{level} -ggdb  -gdwarf -gdwarf+
        !           132: -gstabs  -gstabs+  -gcoff -gxcoff  -gxcoff+
        !           133: -p  -pg  -save-temps  -print-libgcc-file-name
        !           134: @end smallexample
        !           135: 
        !           136: @item Optimization Options
        !           137: @xref{Optimize Options,,Options that Control Optimization}.
        !           138: @smallexample
        !           139: -fcaller-saves  -fcse-follow-jumps  -fcse-skip-blocks
        !           140: -fdelayed-branch   -fexpensive-optimizations  
        !           141: -ffast-math  -ffloat-store  -fforce-addr  -fforce-mem
        !           142: -finline-functions  -fkeep-inline-functions  
        !           143: -fno-default-inline  -fno-defer-pop  -fno-function-cse
        !           144: -fno-inline  -fno-peephole  -fomit-frame-pointer  
        !           145: -frerun-cse-after-loop  -fschedule-insns  
        !           146: -fschedule-insns2  -fstrength-reduce  -fthread-jumps 
        !           147: -funroll-all-loops  -funroll-loops
        !           148: -O  -O2
        !           149: @end smallexample
        !           150: 
        !           151: @item Preprocessor Options
        !           152: @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
        !           153: @smallexample
        !           154: -A@var{assertion}  -C  -dD  -dM  -dN
        !           155: -D@var{macro}@r{[}=@var{defn}@r{]}  -E  -H
        !           156: -idirafter @var{dir}
        !           157: -include @var{file}  -imacros @var{file}
        !           158: -iprefix @var{file}  -iwithprefix @var{dir}
        !           159: -iwithprefixbefore @var{dir}
        !           160: -M  -MD  -MM  -MMD  -nostdinc  -P  -trigraphs  -U@var{macro}
        !           161: @end smallexample
        !           162: 
        !           163: @item Assembler Option
        !           164: @xref{Assembler Options,,Passing Options to the Assembler}.
        !           165: @smallexample
        !           166: -Wa,@var{option}
        !           167: @end smallexample
        !           168: 
        !           169: @item Linker Options
        !           170: @xref{Link Options,,Options for Linking}.
        !           171: @smallexample
        !           172: @var{object-file-name}
        !           173: -l@var{library}  -nostartfiles  -nostdlib  
        !           174: -static  -shared  -symbolic  
        !           175: -Wl,@var{option}  -Xlinker @var{option}
        !           176: -u @var{symbol}
        !           177: @end smallexample
        !           178: 
        !           179: @item Directory Options
        !           180: @xref{Directory Options,,Options for Directory Search}.
        !           181: @smallexample
        !           182: -B@var{prefix}  -I@var{dir}  -I-  -L@var{dir}
        !           183: @end smallexample
        !           184: 
        !           185: @item Target Options
        !           186: @c I wrote this xref this way to avoid overfull hbox. -- rms
        !           187: @xref{Target Options}.
        !           188: @smallexample
        !           189: -b @var{machine}  -V @var{version}
        !           190: @end smallexample
        !           191: 
        !           192: @item Machine Dependent Options
        !           193: @xref{Submodel Options,,Hardware Models and Configurations}.
        !           194: @smallexample
        !           195: @emph{M680x0 Options}
        !           196: -m68000  -m68020  -m68020-40  -m68030  -m68040  -m68881  
        !           197: -mbitfield  -mc68000  -mc68020  -mfpa  -mnobitfield  
        !           198: -mrtd  -mshort  -msoft-float 
        !           199: 
        !           200: @emph{VAX Options}
        !           201: -mg  -mgnu  -munix
        !           202: 
        !           203: @emph{SPARC Options}
        !           204: -mepilogue  -mfpu  -mhard-float
        !           205: -mno-fpu  -mno-epilogue  -msoft-float
        !           206: -msparclite  -mv8
        !           207: 
        !           208: @emph{Convex Options}
        !           209: -mc1  -mc2  -mc32  -mc34  -mc38
        !           210: -margcount  -mnoargcount
        !           211: -mlong32  -mlong64
        !           212: -mbolatile-cache  -mvolatile-nocache
        !           213: 
        !           214: @emph{AMD29K Options} 
        !           215: -m29000  -m29050  -mbw  -mdw  -mkernel-registers
        !           216: -mlarge  -mnbw  -mnodw  -mnormal  -msmall  -mstack-check
        !           217: -muser-registers
        !           218: 
        !           219: @emph{M88K Options}
        !           220: -m88000  -m88100  -m88110  -mbig-pic  
        !           221: -mcheck-zero-division  -mhandle-large-shift 
        !           222: -midentify-revision  -mno-check-zero-division 
        !           223: -mno-ocs-debug-info  -mno-ocs-frame-position 
        !           224: -mno-optimize-arg-area  -mno-serialize-volatile
        !           225: -mno-underscores  -mocs-debug-info
        !           226: -mocs-frame-position  -moptimize-arg-area
        !           227: -mserialize-volatile  -mshort-data-@var{num}  -msvr3 
        !           228: -msvr4  -mtrap-large-shift  -muse-div-instruction 
        !           229: -mversion-03.00  -mwarn-passed-structs
        !           230: 
        !           231: @emph{RS/6000 Options and PowerPC}
        !           232: -mcpu=@var{cpu type}
        !           233: -mpower -mno-power -mpower2 -pno-power2
        !           234: -mpowerpc -mno-powerpc -mpowerpcsqr -mno-powerpcsqr
        !           235: -mpowerpc64 -mno-powerpc64
        !           236: -mnew-mnemonics -mno-new-mnemonics
        !           237: -mnormal-toc   -mminimal-toc  -mno-fop-in-toc
        !           238: 
        !           239: @emph{RT Options}
        !           240: -mcall-lib-mul  -mfp-arg-in-fpregs  -mfp-arg-in-gregs
        !           241: -mfull-fp-blocks  -mhc-struct-return  -min-line-mul
        !           242: -mminimum-fp-blocks  -mnohc-struct-return
        !           243: 
        !           244: @emph{MIPS Options}
        !           245: -mcpu=@var{cpu  type}  -mips2  -mips3  -mint64
        !           246: -mlong64  -mlonglong128  -mmips-as  -mgas  -mrnames
        !           247: -mno-rnames  -mgpopt  -mno-gpopt  -mstats  -mno-stats
        !           248: -mmemcpy  -mno-memcpy  -mno-mips-tfile  -mmips-tfile
        !           249: -msoft-float  -mhard-float  -mabicalls  -mno-abicalls
        !           250: -mhalf-pic  -mno-half-pic -mlong-calls -mno-long-calls
        !           251: -G  @var{num}  -nocpp
        !           252: 
        !           253: @emph{i386 Options}
        !           254: -m486  -mno-486  -msoft-float  -msvr3-shlib  -mieee-fp
        !           255: -mno-fp-ret-in-387
        !           256: 
        !           257: @emph{HPPA Options}
        !           258: -mpa-risc-1-0
        !           259: -mpa-risc-1-1
        !           260: -mlong-calls
        !           261: -mdisable-fpregs
        !           262: -mdisable-indexing
        !           263: -mtrailing-colon
        !           264: 
        !           265: @emph{Intel 960 Options}
        !           266: -m@var{cpu type}
        !           267: -mnumerics  -msoft-float
        !           268: -mcode-align  -mno-code-align
        !           269: -mleaf-procedures  -mno-leaf-procedures
        !           270: -mtail-call  -mno-tail-call
        !           271: -mcomplex-addr  -mno-complex-addr
        !           272: -mclean-linkage  -mno-clean-linkage
        !           273: -mic-compat  -mic2.0-compat  -mic3.0-compat
        !           274: -masm-compat  -mintel-asm
        !           275: -mstrict-align  -mno-strict-align
        !           276: -mold-align  -mno-old-align
        !           277: 
        !           278: @emph{DEC Alpha Options}
        !           279: -mfp-regs  -mno-fp-regs  -mno-soft-float
        !           280: -msoft-float
        !           281: 
        !           282: @emph{Clipper Options}
        !           283: -mc300 -mc400
        !           284: 
        !           285: @emph{System V Options}
        !           286: -G  -Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}
        !           287: @end smallexample
        !           288: 
        !           289: @item Code Generation Options
        !           290: @xref{Code Gen Options,,Options for Code Generation Conventions}.
        !           291: @smallexample
        !           292: -fcall-saved-@var{reg}  -fcall-used-@var{reg} 
        !           293: -ffixed-@var{reg}  -finhibit-size-directive 
        !           294: -fno-common  -fno-ident
        !           295: -fno-gnu-linker  -fpcc-struct-return  -fpic  -fPIC 
        !           296: -freg-struct-return  -fshared-data  -fshort-enums
        !           297: -fshort-double  -fvolatile  -fvolatile-global
        !           298: -fverbose-asm
        !           299: @end smallexample
        !           300: @end table
        !           301: 
        !           302: @menu
        !           303: * Overall Options::     Controlling the kind of output:
        !           304:                         an executable, object files, assembler files,
        !           305:                         or preprocessed source.
        !           306: * C Dialect Options::   Controlling the variant of C language compiled.
        !           307: * C++ Dialect Options:: Variations on C++.
        !           308: * Warning Options::     How picky should the compiler be?
        !           309: * Debugging Options::   Symbol tables, measurements, and debugging dumps.
        !           310: * Optimize Options::    How much optimization?
        !           311: * Preprocessor Options:: Controlling header files and macro definitions.
        !           312:                          Also, getting dependency information for Make.
        !           313: * Assembler Options::   Passing options to the assembler.
        !           314: * Link Options::        Specifying libraries and so on.
        !           315: * Directory Options::   Where to find header files and libraries.
        !           316:                         Where to find the compiler executable files.
        !           317: * Target Options::      Running a cross-compiler, or an old version of GNU CC.
        !           318: @end menu
        !           319: 
        !           320: @node Overall Options
        !           321: @section Options Controlling the Kind of Output
        !           322: 
        !           323: Compilation can involve up to four stages: preprocessing, compilation
        !           324: proper, assembly and linking, always in that order.  The first three
        !           325: stages apply to an individual source file, and end by producing an
        !           326: object file; linking combines all the object files (those newly
        !           327: compiled, and those specified as input) into an executable file.
        !           328: 
        !           329: @cindex file name suffix
        !           330: For any given input file, the file name suffix determines what kind of
        !           331: compilation is done:
        !           332: 
        !           333: @table @code
        !           334: @item @var{file}.c
        !           335: C source code which must be preprocessed.
        !           336: 
        !           337: @item @var{file}.i
        !           338: C source code which should not be preprocessed.
        !           339: 
        !           340: @item @var{file}.ii
        !           341: C++ source code which should not be preprocessed.
        !           342: 
        !           343: @item @var{file}.m
        !           344: Objective-C source code.  Note that you must link with the library
        !           345: @file{libobjc.a} to make an Objective-C program work.
        !           346: 
        !           347: @item @var{file}.h
        !           348: C header file (not to be compiled or linked).
        !           349: 
        !           350: @item @var{file}.cc
        !           351: @itemx @var{file}.cxx
        !           352: @itemx @var{file}.C
        !           353: C++ source code which must be preprocessed.  Note that in @samp{.cxx},
        !           354: the last two letters must both be literally @samp{x}.  Likewise,
        !           355: @samp{.C} refers to a literal capital C.
        !           356: 
        !           357: @item @var{file}.s 
        !           358: Assembler code.
        !           359: 
        !           360: @item @var{file}.S
        !           361: Assembler code which must be preprocessed.
        !           362: 
        !           363: @item @var{other}
        !           364: An object file to be fed straight into linking.
        !           365: Any file name with no recognized suffix is treated this way.
        !           366: @end table
        !           367: 
        !           368: You can specify the input language explicitly with the @samp{-x} option:
        !           369: 
        !           370: @table @code
        !           371: @item -x @var{language}
        !           372: Specify explicitly the @var{language} for the following input files
        !           373: (rather than letting the compiler choose a default based on the file
        !           374: name suffix).  This option applies to all following input files until
        !           375: the next @samp{-x} option.  Possible values for @var{language} are:
        !           376: @example
        !           377: c  objective-c  c++
        !           378: c-header  cpp-output  c++-cpp-output
        !           379: assembler  assembler-with-cpp
        !           380: @end example
        !           381: 
        !           382: @item -x none
        !           383: Turn off any specification of a language, so that subsequent files are
        !           384: handled according to their file name suffixes (as they are if @samp{-x}
        !           385: has not been used at all).
        !           386: @end table
        !           387: 
        !           388: If you only want some of the stages of compilation, you can use
        !           389: @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
        !           390: one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
        !           391: @code{gcc} is to stop.  Note that some combinations (for example,
        !           392: @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
        !           393: 
        !           394: @table @code
        !           395: @item -c
        !           396: Compile or assemble the source files, but do not link.  The linking
        !           397: stage simply is not done.  The ultimate output is in the form of an
        !           398: object file for each source file.
        !           399: 
        !           400: By default, the object file name for a source file is made by replacing
        !           401: the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
        !           402: 
        !           403: Unrecognized input files, not requiring compilation or assembly, are
        !           404: ignored.
        !           405: 
        !           406: @item -S
        !           407: Stop after the stage of compilation proper; do not assemble.  The output
        !           408: is in the form of an assembler code file for each non-assembler input
        !           409: file specified.
        !           410: 
        !           411: By default, the assembler file name for a source file is made by
        !           412: replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
        !           413: 
        !           414: Input files that don't require compilation are ignored.
        !           415: 
        !           416: @item -E
        !           417: Stop after the preprocessing stage; do not run the compiler proper.  The
        !           418: output is in the form of preprocessed source code, which is sent to the
        !           419: standard output.
        !           420: 
        !           421: Input files which don't require preprocessing are ignored.
        !           422: 
        !           423: @cindex output file option
        !           424: @item -o @var{file}
        !           425: Place output in file @var{file}.  This applies regardless to whatever
        !           426: sort of output is being produced, whether it be an executable file,
        !           427: an object file, an assembler file or preprocessed C code.
        !           428: 
        !           429: Since only one output file can be specified, it does not make sense to
        !           430: use @samp{-o} when compiling more than one input file, unless you are
        !           431: producing an executable file as output.
        !           432: 
        !           433: If @samp{-o} is not specified, the default is to put an executable file
        !           434: in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
        !           435: @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
        !           436: all preprocessed C source on standard output.@refill
        !           437: 
        !           438: @item -v
        !           439: Print (on standard error output) the commands executed to run the stages
        !           440: of compilation.  Also print the version number of the compiler driver
        !           441: program and of the preprocessor and the compiler proper.
        !           442: 
        !           443: @item -pipe
        !           444: Use pipes rather than temporary files for communication between the
        !           445: various stages of compilation.  This fails to work on some systems where
        !           446: the assembler is unable to read from a pipe; but the GNU assembler has
        !           447: no trouble.
        !           448: @end table
        !           449: 
        !           450: @node Invoking G++
        !           451: @section Compiling C++ Programs
        !           452: 
        !           453: @cindex suffixes for C++ source
        !           454: @cindex C++ source file suffixes
        !           455: C++ source files conventionally use one of the suffixes @samp{.C},
        !           456: @samp{.cc}, or @samp{.cxx}; preprocessed C++ files use the suffix
        !           457: @samp{.ii}.  GNU CC recognizes files with these names and compiles
        !           458: them as C++ programs even if you call the compiler the same way as for
        !           459: compiling C programs (usually with the name @code{gcc}).
        !           460: 
        !           461: @findex g++
        !           462: @findex c++
        !           463: However, C++ programs often require class libraries as well as a
        !           464: compiler that understands the C++ language---and under some
        !           465: circumstances, you might want to compile programs from standard input,
        !           466: or otherwise without a suffix that flags them as C++ programs.
        !           467: @code{g++} is a shell script that calls GNU CC with the default language
        !           468: set to C++, and automatically specifies linking against the GNU class
        !           469: library libg++.
        !           470: @cindex @code{g++ 1.@var{xx}}
        !           471: @cindex @code{g++}, separate compiler
        !           472: @cindex @code{g++} older version
        !           473: @footnote{Prior to release 2 of the compiler,
        !           474: there was a separate @code{g++} compiler.  That version was based on GNU
        !           475: CC, but not integrated with it.  Versions of @code{g++} with a
        !           476: @samp{1.@var{xx}} version number---for example, @code{g++} version 1.37
        !           477: or 1.42---are much less reliable than the versions integrated with GCC
        !           478: 2.  Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will
        !           479: simply not work.} On many systems, the script @code{g++} is also
        !           480: installed with the name @code{c++}.
        !           481: 
        !           482: @cindex invoking @code{g++}
        !           483: When you compile C++ programs, you may specify many of the same
        !           484: command-line options that you use for compiling programs in any
        !           485: language; or command-line options meaningful for C and related
        !           486: languages; or options that are meaningful only for C++ programs.
        !           487: @xref{C Dialect Options,,Options Controlling C Dialect}, for
        !           488: explanations of options for languages related to C.
        !           489: @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
        !           490: explanations of options that are meaningful only for C++ programs.
        !           491: 
        !           492: @node C Dialect Options
        !           493: @section Options Controlling C Dialect
        !           494: @cindex dialect options
        !           495: @cindex language dialect options
        !           496: @cindex options, dialect
        !           497: 
        !           498: The following options control the dialect of C (or languages derived
        !           499: from C, such as C++ and Objective C) that the compiler accepts:
        !           500: 
        !           501: @table @code
        !           502: @cindex ANSI support
        !           503: @item -ansi
        !           504: Support all ANSI standard C programs.
        !           505: 
        !           506: This turns off certain features of GNU C that are incompatible with ANSI
        !           507: C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and
        !           508: predefined macros such as @code{unix} and @code{vax} that identify the
        !           509: type of system you are using.  It also enables the undesirable and
        !           510: rarely used ANSI trigraph feature, and disallows @samp{$} as part of
        !           511: identifiers.
        !           512: 
        !           513: The alternate keywords @code{__asm__}, @code{__extension__},
        !           514: @code{__inline__} and @code{__typeof__} continue to work despite
        !           515: @samp{-ansi}.  You would not want to use them in an ANSI C program, of
        !           516: course, but it useful to put them in header files that might be included
        !           517: in compilations done with @samp{-ansi}.  Alternate predefined macros
        !           518: such as @code{__unix__} and @code{__vax__} are also available, with or
        !           519: without @samp{-ansi}.
        !           520: 
        !           521: The @samp{-ansi} option does not cause non-ANSI programs to be
        !           522: rejected gratuitously.  For that, @samp{-pedantic} is required in
        !           523: addition to @samp{-ansi}.  @xref{Warning Options}.
        !           524: 
        !           525: The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
        !           526: option is used.  Some header files may notice this macro and refrain
        !           527: from declaring certain functions or defining certain macros that the
        !           528: ANSI standard doesn't call for; this is to avoid interfering with any
        !           529: programs that might use these names for other things.
        !           530: 
        !           531: The functions @code{alloca}, @code{abort}, @code{exit}, and
        !           532: @code{_exit} are not builtin functions when @samp{-ansi} is used.
        !           533: 
        !           534: @item -fno-asm
        !           535: Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
        !           536: keyword.  These words may then be used as identifiers.  You can use the
        !           537: keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
        !           538: instead.  @samp{-ansi} implies @samp{-fno-asm}.
        !           539: 
        !           540: @item -fno-builtin
        !           541: @cindex builtin functions
        !           542: @findex abort
        !           543: @findex abs
        !           544: @findex alloca
        !           545: @findex cos
        !           546: @findex exit
        !           547: @findex fabs
        !           548: @findex ffs
        !           549: @findex labs
        !           550: @findex memcmp
        !           551: @findex memcpy
        !           552: @findex sin
        !           553: @findex sqrt
        !           554: @findex strcmp
        !           555: @findex strcpy
        !           556: @findex strlen
        !           557: Don't recognize builtin functions that do not begin with two leading
        !           558: underscores.  Currently, the functions affected include @code{abort},
        !           559: @code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs},
        !           560: @code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin},
        !           561: @code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}.
        !           562: 
        !           563: GCC normally generates special code to handle certain builtin functions
        !           564: more efficiently; for instance, calls to @code{alloca} may become single
        !           565: instructions that adjust the stack directly, and calls to @code{memcpy}
        !           566: may become inline copy loops.  The resulting code is often both smaller
        !           567: and faster, but since the function calls no longer appear as such, you
        !           568: cannot set a breakpoint on those calls, nor can you change the behavior
        !           569: of the functions by linking with a different library.
        !           570: 
        !           571: The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being
        !           572: builtin functions, since these functions do not have an ANSI standard
        !           573: meaning.
        !           574: 
        !           575: @item -trigraphs
        !           576: Support ANSI C trigraphs.  You don't want to know about this
        !           577: brain-damage.  The @samp{-ansi} option implies @samp{-trigraphs}.
        !           578: 
        !           579: @cindex traditional C language
        !           580: @cindex C language, traditional
        !           581: @item -traditional
        !           582: Attempt to support some aspects of traditional C compilers.
        !           583: Specifically:
        !           584: 
        !           585: @itemize @bullet
        !           586: @item
        !           587: All @code{extern} declarations take effect globally even if they
        !           588: are written inside of a function definition.  This includes implicit
        !           589: declarations of functions.
        !           590: 
        !           591: @item
        !           592: The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
        !           593: and @code{volatile} are not recognized.  (You can still use the
        !           594: alternative keywords such as @code{__typeof__}, @code{__inline__}, and
        !           595: so on.)
        !           596: 
        !           597: @item
        !           598: Comparisons between pointers and integers are always allowed.
        !           599: 
        !           600: @item
        !           601: Integer types @code{unsigned short} and @code{unsigned char} promote
        !           602: to @code{unsigned int}.
        !           603: 
        !           604: @item
        !           605: Out-of-range floating point literals are not an error.
        !           606: 
        !           607: @item
        !           608: Certain constructs which ANSI regards as a single invalid preprocessing
        !           609: number, such as @samp{0xe-0xd}, are treated as expressions instead.
        !           610: 
        !           611: @item
        !           612: String ``constants'' are not necessarily constant; they are stored in
        !           613: writable space, and identical looking constants are allocated
        !           614: separately.  (This is the same as the effect of
        !           615: @samp{-fwritable-strings}.)
        !           616: 
        !           617: @cindex @code{longjmp} and automatic variables
        !           618: @item
        !           619: All automatic variables not declared @code{register} are preserved by
        !           620: @code{longjmp}.  Ordinarily, GNU C follows ANSI C: automatic variables
        !           621: not declared @code{volatile} may be clobbered.
        !           622: 
        !           623: @item
        !           624: In the preprocessor, comments convert to nothing at all, rather than
        !           625: to a space.  This allows traditional token concatenation.
        !           626: 
        !           627: @item
        !           628: In the preprocessor, macro arguments are recognized within string
        !           629: constants in a macro definition (and their values are stringified,
        !           630: though without additional quote marks, when they appear in such a
        !           631: context).  The preprocessor always considers a string constant to end
        !           632: at a newline.
        !           633: 
        !           634: @item
        !           635: @cindex detecting @w{@samp{-traditional}}
        !           636: The predefined macro @code{__STDC__} is not defined when you use
        !           637: @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
        !           638: which @code{__GNUC__} indicates are not affected by
        !           639: @samp{-traditional}).  If you need to write header files that work
        !           640: differently depending on whether @samp{-traditional} is in use, by
        !           641: testing both of these predefined macros you can distinguish four
        !           642: situations: GNU C, traditional GNU C, other ANSI C compilers, and other
        !           643: old C compilers.  @xref{Standard Predefined,,Standard Predefined
        !           644: Macros,cpp.info,The C Preprocessor}, for more discussion of these and other
        !           645: predefined macros.
        !           646: 
        !           647: @item
        !           648: @cindex string constants vs newline
        !           649: @cindex newline vs string constants
        !           650: The preprocessor considers a string constant to end at a newline (unless
        !           651: the newline is escaped with @samp{\}).  (Without @w{@samp{-traditional}},
        !           652: string constants can contain the newline character as typed.)
        !           653: 
        !           654: @item
        !           655: @kindex \x
        !           656: @kindex \a
        !           657: @cindex escape sequences, traditional
        !           658: The character escape sequences @samp{\x} and @samp{\a} evaluate as the
        !           659: literal characters @samp{x} and @samp{a} respectively.  Without
        !           660: @w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal
        !           661: representation of a character, and @samp{\a} produces a bell.
        !           662: 
        !           663: @item
        !           664: In C++ programs, assignment to @code{this} is permitted with
        !           665: @samp{-traditional}.  (The option @samp{-fthis-is-variable} also has
        !           666: this effect.)
        !           667: @end itemize
        !           668: 
        !           669: You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
        !           670: if your program uses names that are normally GNU C builtin functions for
        !           671: other purposes of its own.
        !           672: 
        !           673: @item -traditional-cpp
        !           674: Attempt to support some aspects of traditional C preprocessors.
        !           675: This includes the last three items in the table immediately above,
        !           676: but none of the other effects of @samp{-traditional}.
        !           677: 
        !           678: @item -fcond-mismatch
        !           679: Allow conditional expressions with mismatched types in the second and
        !           680: third arguments.  The value of such an expression is void.
        !           681: 
        !           682: @item -funsigned-char
        !           683: Let the type @code{char} be unsigned, like @code{unsigned char}.
        !           684: 
        !           685: Each kind of machine has a default for what @code{char} should
        !           686: be.  It is either like @code{unsigned char} by default or like
        !           687: @code{signed char} by default.
        !           688: 
        !           689: Ideally, a portable program should always use @code{signed char} or
        !           690: @code{unsigned char} when it depends on the signedness of an object.
        !           691: But many programs have been written to use plain @code{char} and
        !           692: expect it to be signed, or expect it to be unsigned, depending on the
        !           693: machines they were written for.  This option, and its inverse, let you
        !           694: make such a program work with the opposite default.
        !           695: 
        !           696: The type @code{char} is always a distinct type from each of
        !           697: @code{signed char} or @code{unsigned char}, even though its behavior
        !           698: is always just like one of those two.
        !           699: 
        !           700: @item -fsigned-char
        !           701: Let the type @code{char} be signed, like @code{signed char}.
        !           702: 
        !           703: Note that this is equivalent to @samp{-fno-unsigned-char}, which is
        !           704: the negative form of @samp{-funsigned-char}.  Likewise, the option
        !           705: @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
        !           706: 
        !           707: @item -fsigned-bitfields
        !           708: @itemx -funsigned-bitfields
        !           709: @itemx -fno-signed-bitfields
        !           710: @itemx -fno-unsigned-bitfields
        !           711: These options control whether a bitfield is signed or unsigned, when the
        !           712: declaration does not use either @code{signed} or @code{unsigned}.  By
        !           713: default, such a bitfield is signed, because this is consistent: the
        !           714: basic integer types such as @code{int} are signed types.
        !           715: 
        !           716: However, when @samp{-traditional} is used, bitfields are all unsigned
        !           717: no matter what.
        !           718: 
        !           719: @item -fwritable-strings
        !           720: Store string constants in the writable data segment and don't uniquize
        !           721: them.  This is for compatibility with old programs which assume they can
        !           722: write into string constants.  The option @samp{-traditional} also has
        !           723: this effect.
        !           724: 
        !           725: Writing into string constants is a very bad idea; ``constants'' should
        !           726: be constant.
        !           727: 
        !           728: @item -fallow-single-precision
        !           729: Do not promote single precision math operations to double precision,
        !           730: even when compiling with @samp{-traditional}.
        !           731: 
        !           732: Traditional K&R C promotes all floating point operations to double
        !           733: precision, regardless of the sizes of the operands.   On the
        !           734: architecture for which you are compiling, single precision may be faster
        !           735: than double precision.   If you must use @samp{-traditional}, but want
        !           736: to use single precision operations when the operands are single
        !           737: precision, use this option.   This option has no effect when compiling
        !           738: with ANSI or GNU C conventions (the default).
        !           739: 
        !           740: @end table
        !           741: 
        !           742: @node C++ Dialect Options
        !           743: @section Options Controlling C++ Dialect
        !           744: 
        !           745: @cindex compiler options, C++
        !           746: @cindex C++ options, command line
        !           747: @cindex options, C++
        !           748: This section describes the command-line options that are only meaningful
        !           749: for C++ programs; but you can also use most of the GNU compiler options
        !           750: regardless of what language your program is in.  For example, you
        !           751: might compile a file @code{firstClass.C} like this:
        !           752: 
        !           753: @example
        !           754: g++ -g -felide-constructors -O -c firstClass.C
        !           755: @end example
        !           756: 
        !           757: @noindent
        !           758: In this example, only @samp{-felide-constructors} is an option meant
        !           759: only for C++ programs; you can use the other options with any
        !           760: language supported by GNU CC.
        !           761: 
        !           762: Here is a list of options that are @emph{only} for compiling C++ programs:
        !           763: 
        !           764: @table @code
        !           765: @item -fall-virtual
        !           766: Treat all possible member functions as virtual, implicitly.
        !           767: All member functions (except for constructor functions and @code{new} or
        !           768: @code{delete} member operators) are treated as virtual functions of the
        !           769: class where they appear.
        !           770: 
        !           771: This does not mean that all calls to these member functions will be made
        !           772: through the internal table of virtual functions.  Under some
        !           773: circumstances, the compiler can determine that a call to a given virtual
        !           774: function can be made directly; in these cases the calls are direct in
        !           775: any case.
        !           776: 
        !           777: @item -fdollars-in-identifiers
        !           778: Accept @samp{$} in identifiers.  You can also explicitly prohibit use of
        !           779: @samp{$} with the option @samp{-fno-dollars-in-identifiers}.  (GNU C++
        !           780: allows @samp{$} by default on some target systems but not others.)
        !           781: Traditional C allowed the character @samp{$} to form part of
        !           782: identifiers.  However, ANSI C and C++ forbid @samp{$} in identifiers.
        !           783: 
        !           784: @item -felide-constructors
        !           785: Elide constructors when this seems plausible.  With this option, GNU C++
        !           786: initializes @code{y} directly from the call to @code{foo} without going
        !           787: through a temporary in the following code:
        !           788: 
        !           789: @smallexample
        !           790: A foo ();
        !           791: A y = foo ();
        !           792: @end smallexample
        !           793: 
        !           794: Without this option, GNU C++ (1) initializes @code{y} by calling the
        !           795: appropriate constructor for type @code{A}; (2) assigns the result of
        !           796: @code{foo} to a temporary; and, finally, (3) replaces the initial value of
        !           797: @code{y} with the temporary.
        !           798: 
        !           799: The default behavior (@samp{-fno-elide-constructors}) is specified by
        !           800: the draft ANSI C++ standard.  If your program's constructors have side
        !           801: effects, @samp{-felide-constructors} can change your program's behavior,
        !           802: since some constructor calls may be omitted.
        !           803: 
        !           804: @item -fenum-int-equiv
        !           805: Permit implicit conversion of @code{int} to enumeration types.  Normally
        !           806: GNU C++ allows conversion of @code{enum} to @code{int}, but not the
        !           807: other way around.
        !           808: 
        !           809: @item -fexternal-templates
        !           810: Produce smaller code for template declarations, by generating only a
        !           811: single copy of each template function where it is defined.  To use this
        !           812: option successfully, you must also mark all files that use templates
        !           813: with either @samp{#pragma implementation} (the definition) or
        !           814: @samp{#pragma interface} (declarations).  @xref{C++
        !           815: Interface,,Declarations and Definitions in One Header}, for more
        !           816: discussion of these pragmas.
        !           817: 
        !           818: When your code is compiled with @samp{-fexternal-templates}, all
        !           819: template instantiations are external.  You must arrange for all
        !           820: necessary instantiations to appear in the implementation file; you can
        !           821: do this with a @code{typedef} that references each instantiation needed.
        !           822: Conversely, when you compile using the default option
        !           823: @samp{-fno-external-templates}, all template instantiations are
        !           824: explicitly internal.
        !           825: 
        !           826: You do not need to specify @samp{-fexternal-templates} when compiling a
        !           827: file that does not define and instantiate templates used in other files,
        !           828: even if your file @emph{uses} templates defined in other files that are
        !           829: compiled with @samp{-fexternal-templates}.  The only side effect is an
        !           830: increase in object size for each file that you compile without
        !           831: @samp{-fexternal-templates}.
        !           832: 
        !           833: @item -fmemoize-lookups
        !           834: @itemx -fsave-memoized
        !           835: Use heuristics to compile faster.  These heuristics are not enabled by
        !           836: default, since they are only effective for certain input files.  Other
        !           837: input files compile more slowly.
        !           838: 
        !           839: The first time the compiler must build a call to a member function (or
        !           840: reference to a data member), it must (1) determine whether the class
        !           841: implements member functions of that name; (2) resolve which member
        !           842: function to call (which involves figuring out what sorts of type
        !           843: conversions need to be made); and (3) check the visibility of the member
        !           844: function to the caller.  All of this adds up to slower compilation.
        !           845: Normally, the second time a call is made to that member function (or
        !           846: reference to that data member), it must go through the same lengthy
        !           847: process again.  This means that code like this:
        !           848: 
        !           849: @smallexample
        !           850: cout << "This " << p << " has " << n << " legs.\n";
        !           851: @end smallexample
        !           852: 
        !           853: @noindent
        !           854: makes six passes through all three steps.  By using a software cache, a
        !           855: ``hit'' significantly reduces this cost.  Unfortunately, using the cache
        !           856: introduces another layer of mechanisms which must be implemented, and so
        !           857: incurs its own overhead.  @samp{-fmemoize-lookups} enables the software
        !           858: cache.
        !           859: 
        !           860: Because access privileges (visibility) to members and member functions
        !           861: may differ from one function context to the next, G++ may need to flush
        !           862: the cache.  With the @samp{-fmemoize-lookups} flag, the cache is flushed
        !           863: after every function that is compiled.  The @samp{-fsave-memoized} flag
        !           864: enables the same software cache, but when the compiler determines that
        !           865: the context of the last function compiled would yield the same access
        !           866: privileges of the next function to compile, it preserves the cache.
        !           867: This is most helpful when defining many member functions for the same
        !           868: class: with the exception of member functions which are friends of other
        !           869: classes, each member function has exactly the same access privileges as
        !           870: every other, and the cache need not be flushed.
        !           871: 
        !           872: @item -fno-strict-prototype
        !           873: Treat a function declaration with no arguments, such as @samp{int foo
        !           874: ();}, as C would treat it---as saying nothing about the number of
        !           875: arguments or their types.  Normally, such a declaration in C++ means
        !           876: that the function @code{foo} takes no arguments.
        !           877: 
        !           878: @item -fnonnull-objects
        !           879: Assume that objects reached through references are not null.
        !           880: 
        !           881: Normally, GNU C++ makes conservative assumptions about objects reached
        !           882: through references.  For example, the compiler must check that @code{a}
        !           883: is not null in code like the following:
        !           884: 
        !           885: @example
        !           886: obj &a = g ();
        !           887: a.f (2);
        !           888: @end example
        !           889: 
        !           890: Checking that references of this sort have non-null values requires
        !           891: extra code, however, and it is unnecessary for many programs.  You can
        !           892: use @w{@samp{-fnonnull-objects}} to omit the checks for null, if your
        !           893: program doesn't require checking.
        !           894: 
        !           895: @item -fthis-is-variable
        !           896: Permit assignment to @code{this}.  The incorporation of
        !           897: user-defined free store management into C++ has made assignment to
        !           898: @samp{this} an anachronism.  Therefore, by default it is invalid to
        !           899: assign to @code{this} within a class member function; that is, GNU C++
        !           900: treats the type of @samp{this} in a member function of class @code{X}
        !           901: to be @samp{X *const}.  However, for backwards compatibility, you can
        !           902: make it valid with @samp{-fthis-is-variable}.
        !           903: 
        !           904: @item -nostdinc++
        !           905: Do not search for header files in the standard directories specific to
        !           906: C++, but do still search the other standard directories.  (This option
        !           907: is used when building libg++.)
        !           908: 
        !           909: @item -traditional
        !           910: For C++ programs (in addition to the effects that apply to both C and
        !           911: C++), this has the same effect as @samp{-fthis-is-variable}.
        !           912: @xref{C Dialect Options,, Options Controlling C Dialect}.
        !           913: @end table
        !           914: 
        !           915: In addition, these optimization, warning, and code generation options
        !           916: have meanings only for C++ programs:
        !           917: 
        !           918: @table @code
        !           919: @item -fno-default-inline
        !           920: Do not assume @samp{inline} for functions defined inside a class scope.
        !           921: @xref{Optimize Options,,Options That Control Optimization}.
        !           922: 
        !           923: @item -Wenum-clash
        !           924: @itemx -Woverloaded-virtual
        !           925: @itemx -Wtemplate-debugging
        !           926: Warnings that apply only to C++ programs.  @xref{Warning
        !           927: Options,,Options to Request or Suppress Warnings}.
        !           928: 
        !           929: @item +e@var{n}
        !           930: Control how virtual function definitions are used, in a fashion
        !           931: compatible with @code{cfront} 1.x.  @xref{Code Gen Options,,Options for
        !           932: Code Generation Conventions}.
        !           933: @end table
        !           934: 
        !           935: @node Warning Options
        !           936: @section Options to Request or Suppress Warnings
        !           937: @cindex options to control warnings
        !           938: @cindex warning messages
        !           939: @cindex messages, warning
        !           940: @cindex suppressing warnings
        !           941: 
        !           942: Warnings are diagnostic messages that report constructions which
        !           943: are not inherently erroneous but which are risky or suggest there
        !           944: may have been an error.
        !           945: 
        !           946: You can request many specific warnings with options beginning @samp{-W},
        !           947: for example @samp{-Wimplicit} to request warnings on implicit
        !           948: declarations.  Each of these specific warning options also has a
        !           949: negative form beginning @samp{-Wno-} to turn off warnings;
        !           950: for example, @samp{-Wno-implicit}.  This manual lists only one of the
        !           951: two forms, whichever is not the default.
        !           952: 
        !           953: These options control the amount and kinds of warnings produced by GNU
        !           954: CC:
        !           955: 
        !           956: @table @code
        !           957: @cindex syntax checking
        !           958: @item -fsyntax-only
        !           959: Check the code for syntax errors, but don't do anything beyond that.
        !           960: 
        !           961: @item -w
        !           962: Inhibit all warning messages.
        !           963: 
        !           964: @item -Wno-import
        !           965: Inhibit warning messages about the use of @samp{#import}.
        !           966: 
        !           967: @item -pedantic
        !           968: Issue all the warnings demanded by strict ANSI standard C; reject
        !           969: all programs that use forbidden extensions.  
        !           970: 
        !           971: Valid ANSI standard C programs should compile properly with or without
        !           972: this option (though a rare few will require @samp{-ansi}).  However,
        !           973: without this option, certain GNU extensions and traditional C features
        !           974: are supported as well.  With this option, they are rejected.
        !           975: 
        !           976: @samp{-pedantic} does not cause warning messages for use of the
        !           977: alternate keywords whose names begin and end with @samp{__}.  Pedantic
        !           978: warnings are also disabled in the expression that follows
        !           979: @code{__extension__}.  However, only system header files should use
        !           980: these escape routes; application programs should avoid them.
        !           981: @xref{Alternate Keywords}.
        !           982: 
        !           983: This option is not intended to be @i{useful}; it exists only to satisfy
        !           984: pedants who would otherwise claim that GNU CC fails to support the ANSI
        !           985: standard.
        !           986: 
        !           987: Some users try to use @samp{-pedantic} to check programs for strict ANSI
        !           988: C conformance.  They soon find that it does not do quite what they want:
        !           989: it finds some non-ANSI practices, but not all---only those for which
        !           990: ANSI C @emph{requires} a diagnostic.
        !           991: 
        !           992: A feature to report any failure to conform to ANSI C might be useful in
        !           993: some instances, but would require considerable additional work and would
        !           994: be quite different from @samp{-pedantic}.  We recommend, rather, that
        !           995: users take advantage of the extensions of GNU C and disregard the
        !           996: limitations of other compilers.  Aside from certain supercomputers and
        !           997: obsolete small machines, there is less and less reason ever to use any
        !           998: other C compiler other than for bootstrapping GNU CC.
        !           999: 
        !          1000: @item -pedantic-errors
        !          1001: Like @samp{-pedantic}, except that errors are produced rather than
        !          1002: warnings.
        !          1003: 
        !          1004: @item -W
        !          1005: Print extra warning messages for these events:
        !          1006: 
        !          1007: @itemize @bullet
        !          1008: @cindex @code{longjmp} warnings
        !          1009: @item
        !          1010: A nonvolatile automatic variable might be changed by a call to
        !          1011: @code{longjmp}.  These warnings as well are possible only in
        !          1012: optimizing compilation.
        !          1013: 
        !          1014: The compiler sees only the calls to @code{setjmp}.  It cannot know
        !          1015: where @code{longjmp} will be called; in fact, a signal handler could
        !          1016: call it at any point in the code.  As a result, you may get a warning
        !          1017: even when there is in fact no problem because @code{longjmp} cannot
        !          1018: in fact be called at the place which would cause a problem.
        !          1019: 
        !          1020: @item
        !          1021: A function can return either with or without a value.  (Falling
        !          1022: off the end of the function body is considered returning without
        !          1023: a value.)  For example, this function would evoke such a
        !          1024: warning:
        !          1025: 
        !          1026: @smallexample
        !          1027: @group
        !          1028: foo (a)
        !          1029: @{
        !          1030:   if (a > 0)
        !          1031:     return a;
        !          1032: @}
        !          1033: @end group
        !          1034: @end smallexample
        !          1035: 
        !          1036: @item
        !          1037: An expression-statement contains no side effects.
        !          1038: 
        !          1039: @item
        !          1040: An unsigned value is compared against zero with @samp{>} or @samp{<=}.
        !          1041: 
        !          1042: @item
        !          1043: A comparison like @samp{x<=y<=z} appears; this is equivalent to
        !          1044: @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
        !          1045: that of ordinary mathematical notation.
        !          1046: 
        !          1047: @item
        !          1048: Storage-class specifiers like @code{static} are not the first things in
        !          1049: a declaration.  According to the C Standard, this usage is obsolescent.
        !          1050: 
        !          1051: @item
        !          1052: An aggregate has a partly bracketed initializer.
        !          1053: For example, the following code would evoke such a warning,
        !          1054: because braces are missing around the initializer for @code{x.h}:
        !          1055: 
        !          1056: @smallexample
        !          1057: struct s @{ int f, g; @};
        !          1058: struct t @{ struct s h; int i; @};
        !          1059: struct t x = @{ 1, 2, 3 @};
        !          1060: @end smallexample
        !          1061: @end itemize
        !          1062: 
        !          1063: @item -Wimplicit
        !          1064: Warn whenever a function or parameter is implicitly declared.
        !          1065: 
        !          1066: @item -Wreturn-type
        !          1067: Warn whenever a function is defined with a return-type that defaults
        !          1068: to @code{int}.  Also warn about any @code{return} statement with no
        !          1069: return-value in a function whose return-type is not @code{void}.
        !          1070: 
        !          1071: @item -Wunused
        !          1072: Warn whenever a local variable is unused aside from its declaration,
        !          1073: whenever a function is declared static but never defined, and whenever
        !          1074: a statement computes a result that is explicitly not used.
        !          1075: 
        !          1076: If you want to prevent a warning for a particular variable, you can use
        !          1077: this macro:
        !          1078: 
        !          1079: @smallexample
        !          1080: #define USE(var) \
        !          1081:   static void * use_##var = (&use_##var, (void *) &var)
        !          1082: 
        !          1083: USE (string);
        !          1084: @end smallexample
        !          1085: 
        !          1086: @item -Wswitch
        !          1087: Warn whenever a @code{switch} statement has an index of enumeral type
        !          1088: and lacks a @code{case} for one or more of the named codes of that
        !          1089: enumeration.  (The presence of a @code{default} label prevents this
        !          1090: warning.)  @code{case} labels outside the enumeration range also
        !          1091: provoke warnings when this option is used.
        !          1092: 
        !          1093: @item -Wcomment
        !          1094: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
        !          1095: 
        !          1096: @item -Wtrigraphs
        !          1097: Warn if any trigraphs are encountered (assuming they are enabled).
        !          1098: 
        !          1099: @item -Wformat
        !          1100: Check calls to @code{printf} and @code{scanf}, etc., to make sure that
        !          1101: the arguments supplied have types appropriate to the format string
        !          1102: specified.
        !          1103: 
        !          1104: @item -Wchar-subscripts
        !          1105: Warn if an array subscript has type @code{char}.  This is a common cause
        !          1106: of error, as programmers often forget that this type is signed on some
        !          1107: machines.
        !          1108: 
        !          1109: @item -Wuninitialized
        !          1110: An automatic variable is used without first being initialized.
        !          1111: 
        !          1112: These warnings are possible only in optimizing compilation,
        !          1113: because they require data flow information that is computed only
        !          1114: when optimizing.  If you don't specify @samp{-O}, you simply won't
        !          1115: get these warnings.
        !          1116: 
        !          1117: These warnings occur only for variables that are candidates for
        !          1118: register allocation.  Therefore, they do not occur for a variable that
        !          1119: is declared @code{volatile}, or whose address is taken, or whose size
        !          1120: is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
        !          1121: structures, unions or arrays, even when they are in registers.
        !          1122: 
        !          1123: Note that there may be no warning about a variable that is used only
        !          1124: to compute a value that itself is never used, because such
        !          1125: computations may be deleted by data flow analysis before the warnings
        !          1126: are printed.
        !          1127: 
        !          1128: These warnings are made optional because GNU CC is not smart
        !          1129: enough to see all the reasons why the code might be correct
        !          1130: despite appearing to have an error.  Here is one example of how
        !          1131: this can happen:
        !          1132: 
        !          1133: @smallexample
        !          1134: @{
        !          1135:   int x;
        !          1136:   switch (y)
        !          1137:     @{
        !          1138:     case 1: x = 1;
        !          1139:       break;
        !          1140:     case 2: x = 4;
        !          1141:       break;
        !          1142:     case 3: x = 5;
        !          1143:     @}
        !          1144:   foo (x);
        !          1145: @}
        !          1146: @end smallexample
        !          1147: 
        !          1148: @noindent
        !          1149: If the value of @code{y} is always 1, 2 or 3, then @code{x} is
        !          1150: always initialized, but GNU CC doesn't know this.  Here is
        !          1151: another common case:
        !          1152: 
        !          1153: @smallexample
        !          1154: @{
        !          1155:   int save_y;
        !          1156:   if (change_y) save_y = y, y = new_y;
        !          1157:   @dots{}
        !          1158:   if (change_y) y = save_y;
        !          1159: @}
        !          1160: @end smallexample
        !          1161: 
        !          1162: @noindent
        !          1163: This has no bug because @code{save_y} is used only if it is set.
        !          1164: 
        !          1165: Some spurious warnings can be avoided if you declare all the functions
        !          1166: you use that never return as @code{volatile}.  @xref{Function
        !          1167: Attributes}.
        !          1168: 
        !          1169: @item -Wparentheses
        !          1170: Warn if parentheses are omitted in certain contexts, such
        !          1171: as when there is an assignment in a context where a truth value
        !          1172: is expected, or when operators are nested whose precedence people
        !          1173: often get confused about.
        !          1174: 
        !          1175: @item -Wenum-clash
        !          1176: @cindex enumeration clash warnings
        !          1177: @cindex warning for enumeration conversions
        !          1178: Warn about conversion between different enumeration types.
        !          1179: (C++ only).
        !          1180: 
        !          1181: @item -Wtemplate-debugging
        !          1182: @cindex template debugging
        !          1183: When using templates in a C++ program, warn if debugging is not yet
        !          1184: fully available (C++ only).
        !          1185: 
        !          1186: @item -Wall
        !          1187: All of the above @samp{-W} options combined.  These are all the
        !          1188: options which pertain to usage that we recommend avoiding and that we
        !          1189: believe is easy to avoid, even in conjunction with macros.
        !          1190: @end table
        !          1191: 
        !          1192: The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall}
        !          1193: because they warn about constructions that we consider reasonable to
        !          1194: use, on occasion, in clean programs.
        !          1195: 
        !          1196: @table @code
        !          1197: @item -Wtraditional
        !          1198: Warn about certain constructs that behave differently in traditional and
        !          1199: ANSI C.
        !          1200: 
        !          1201: @itemize @bullet
        !          1202: @item
        !          1203: Macro arguments occurring within string constants in the macro body.
        !          1204: These would substitute the argument in traditional C, but are part of
        !          1205: the constant in ANSI C.
        !          1206: 
        !          1207: @item
        !          1208: A function declared external in one block and then used after the end of
        !          1209: the block.
        !          1210: 
        !          1211: @item
        !          1212: A @code{switch} statement has an operand of type @code{long}.
        !          1213: @end itemize
        !          1214: 
        !          1215: @item -Wshadow
        !          1216: Warn whenever a local variable shadows another local variable.
        !          1217: 
        !          1218: @item -Wid-clash-@var{len}
        !          1219: Warn whenever two distinct identifiers match in the first @var{len}
        !          1220: characters.  This may help you prepare a program that will compile
        !          1221: with certain obsolete, brain-damaged compilers.
        !          1222: 
        !          1223: @item -Wpointer-arith
        !          1224: Warn about anything that depends on the ``size of'' a function type or
        !          1225: of @code{void}.  GNU C assigns these types a size of 1, for
        !          1226: convenience in calculations with @code{void *} pointers and pointers
        !          1227: to functions.
        !          1228: 
        !          1229: @item -Wcast-qual
        !          1230: Warn whenever a pointer is cast so as to remove a type qualifier from
        !          1231: the target type.  For example, warn if a @code{const char *} is cast
        !          1232: to an ordinary @code{char *}.
        !          1233: 
        !          1234: @item -Wcast-align
        !          1235: Warn whenever a pointer is cast such that the required alignment of the
        !          1236: target is increased.  For example, warn if a @code{char *} is cast to
        !          1237: an @code{int *} on machines where integers can only be accessed at
        !          1238: two- or four-byte boundaries.
        !          1239: 
        !          1240: @item -Wwrite-strings
        !          1241: Give string constants the type @code{const char[@var{length}]} so that
        !          1242: copying the address of one into a non-@code{const} @code{char *}
        !          1243: pointer will get a warning.  These warnings will help you find at
        !          1244: compile time code that can try to write into a string constant, but
        !          1245: only if you have been very careful about using @code{const} in
        !          1246: declarations and prototypes.  Otherwise, it will just be a nuisance;
        !          1247: this is why we did not make @samp{-Wall} request these warnings.
        !          1248: 
        !          1249: @item -Wconversion
        !          1250: Warn if a prototype causes a type conversion that is different from what
        !          1251: would happen to the same argument in the absence of a prototype.  This
        !          1252: includes conversions of fixed point to floating and vice versa, and
        !          1253: conversions changing the width or signedness of a fixed point argument
        !          1254: except when the same as the default promotion.
        !          1255: 
        !          1256: Also, warn if a negative integer constant expression is implicitly
        !          1257: converted to an unsigned type.  For example, warn about the assignment
        !          1258: @code{x = -1} if @code{x} is unsigned.  But do not warn about explicit
        !          1259: casts like @code{(unsigned) -1}.
        !          1260: 
        !          1261: @item -Waggregate-return
        !          1262: Warn if any functions that return structures or unions are defined or
        !          1263: called.  (In languages where you can return an array, this also elicits
        !          1264: a warning.)
        !          1265: 
        !          1266: @item -Wstrict-prototypes
        !          1267: Warn if a function is declared or defined without specifying the
        !          1268: argument types.  (An old-style function definition is permitted without
        !          1269: a warning if preceded by a declaration which specifies the argument
        !          1270: types.)
        !          1271: 
        !          1272: @item -Wmissing-prototypes
        !          1273: Warn if a global function is defined without a previous prototype
        !          1274: declaration.  This warning is issued even if the definition itself
        !          1275: provides a prototype.  The aim is to detect global functions that fail
        !          1276: to be declared in header files.
        !          1277: 
        !          1278: @item -Wredundant-decls
        !          1279: Warn if anything is declared more than once in the same scope, even in
        !          1280: cases where multiple declaration is valid and changes nothing.
        !          1281: 
        !          1282: @item -Wnested-externs
        !          1283: Warn if an @code{extern} declaration is encountered within an function.
        !          1284: 
        !          1285: @item -Winline
        !          1286: Warn if a function can not be inlined, and either it was declared as inline,
        !          1287: or else the @samp{-finline-functions} option was given.
        !          1288: 
        !          1289: @item -Woverloaded-virtual
        !          1290: @cindex overloaded virtual fn, warning
        !          1291: @cindex warning for overloaded virtual fn
        !          1292: Warn when a derived class function declaration may be an error in
        !          1293: defining a virtual function (C++ only).  In a derived class, the
        !          1294: definitions of virtual functions must match the type signature of a
        !          1295: virtual function declared in the base class.  With this option, the
        !          1296: compiler warns when you define a function with the same name as a
        !          1297: virtual function, but with a type signature that does not match any
        !          1298: declarations from the base class.
        !          1299: 
        !          1300: @item -Werror
        !          1301: Make all warnings into errors.
        !          1302: @end table
        !          1303: 
        !          1304: @node Debugging Options
        !          1305: @section Options for Debugging Your Program or GNU CC
        !          1306: @cindex options, debugging
        !          1307: @cindex debugging information options
        !          1308: 
        !          1309: GNU CC has various special options that are used for debugging
        !          1310: either your program or GCC:
        !          1311: 
        !          1312: @table @code
        !          1313: @item -g
        !          1314: Produce debugging information in the operating system's native format
        !          1315: (stabs, COFF, XCOFF, or DWARF).  GDB can work with this debugging
        !          1316: information.
        !          1317: 
        !          1318: On most systems that use stabs format, @samp{-g} enables use of extra
        !          1319: debugging information that only GDB can use; this extra information
        !          1320: makes debugging work better in GDB but will probably make other debuggers
        !          1321: crash or
        !          1322: refuse to read the program.  If you want to control for certain whether
        !          1323: to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs},
        !          1324: @samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf+}, or @samp{-gdwarf}
        !          1325: (see below).
        !          1326: 
        !          1327: Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
        !          1328: @samp{-O}.  The shortcuts taken by optimized code may occasionally
        !          1329: produce surprising results: some variables you declared may not exist
        !          1330: at all; flow of control may briefly move where you did not expect it;
        !          1331: some statements may not be executed because they compute constant
        !          1332: results or their values were already at hand; some statements may
        !          1333: execute in different places because they were moved out of loops.
        !          1334: 
        !          1335: Nevertheless it proves possible to debug optimized output.  This makes
        !          1336: it reasonable to use the optimizer for programs that might have bugs.
        !          1337: 
        !          1338: The following options are useful when GNU CC is generated with the
        !          1339: capability for more than one debugging format.
        !          1340: 
        !          1341: @item -ggdb
        !          1342: Produce debugging information in the native format (if that is supported),
        !          1343: including GDB extensions if at all possible.
        !          1344: 
        !          1345: @item -gstabs
        !          1346: Produce debugging information in stabs format (if that is supported),
        !          1347: without GDB extensions.  This is the format used by DBX on most BSD
        !          1348: systems.  On MIPS and Alpha systems this option produces embedded stabs
        !          1349: debugging output which is not understood by DBX.
        !          1350: 
        !          1351: @item -gstabs+
        !          1352: Produce debugging information in stabs format (if that is supported),
        !          1353: using GNU extensions understood only by the GNU debugger (GDB).  The
        !          1354: use of these extensions is likely to make other debuggers crash or
        !          1355: refuse to read the program.
        !          1356: 
        !          1357: @item -gcoff
        !          1358: Produce debugging information in COFF format (if that is supported).
        !          1359: This is the format used by SDB on most System V systems prior to
        !          1360: System V Release 4.
        !          1361: 
        !          1362: @item -gxcoff
        !          1363: Produce debugging information in XCOFF format (if that is supported).
        !          1364: This is the format used by the DBX debugger on IBM RS/6000 systems.
        !          1365: 
        !          1366: @item -gxcoff+
        !          1367: Produce debugging information in XCOFF format (if that is supported),
        !          1368: using GNU extensions understood only by the GNU debugger (GDB).  The
        !          1369: use of these extensions is likely to make other debuggers crash or
        !          1370: refuse to read the program.
        !          1371: 
        !          1372: @item -gdwarf
        !          1373: Produce debugging information in DWARF format (if that is supported).
        !          1374: This is the format used by SDB on most System V Release 4 systems.
        !          1375: 
        !          1376: @item -gdwarf+
        !          1377: Produce debugging information in DWARF format (if that is supported),
        !          1378: using GNU extensions understood only by the GNU debugger (GDB).  The
        !          1379: use of these extensions is likely to make other debuggers crash or
        !          1380: refuse to read the program.
        !          1381: 
        !          1382: @item -g@var{level}
        !          1383: @itemx -ggdb@var{level}
        !          1384: @itemx -gstabs@var{level}
        !          1385: @itemx -gcoff@var{level}
        !          1386: @itemx -gxcoff@var{level}
        !          1387: @itemx -gdwarf@var{level}
        !          1388: Request debugging information and also use @var{level} to specify how
        !          1389: much information.  The default level is 2.
        !          1390: 
        !          1391: Level 1 produces minimal information, enough for making backtraces in
        !          1392: parts of the program that you don't plan to debug.  This includes
        !          1393: descriptions of functions and external variables, but no information
        !          1394: about local variables and no line numbers.
        !          1395: 
        !          1396: Level 3 includes extra information, such as all the macro definitions
        !          1397: present in the program.  Some debuggers support macro expansion when
        !          1398: you use @samp{-g3}.
        !          1399: 
        !          1400: @cindex @code{prof}
        !          1401: @item -p
        !          1402: Generate extra code to write profile information suitable for the
        !          1403: analysis program @code{prof}.  You must use this option when compiling
        !          1404: the source files you want data about, and you must also use it when
        !          1405: linking.
        !          1406: 
        !          1407: @cindex @code{gprof}
        !          1408: @item -pg
        !          1409: Generate extra code to write profile information suitable for the
        !          1410: analysis program @code{gprof}.  You must use this option when compiling
        !          1411: the source files you want data about, and you must also use it when
        !          1412: linking.
        !          1413: 
        !          1414: @cindex @code{tcov}
        !          1415: @item -a
        !          1416: Generate extra code to write profile information for basic blocks, which will
        !          1417: record the number of times each basic block is executed, the basic block start
        !          1418: address, and the function name containing the basic block.  If @samp{-g} is
        !          1419: used, the line number and filename of the start of the basic block will also be
        !          1420: recorded.  If not overridden by the machine description, the default action is
        !          1421: to append to the text file @file{bb.out}.
        !          1422: 
        !          1423: This data could be analyzed by a program like @code{tcov}.  Note,
        !          1424: however, that the format of the data is not what @code{tcov} expects.
        !          1425: Eventually GNU @code{gprof} should be extended to process this data.
        !          1426: 
        !          1427: @item -d@var{letters}
        !          1428: Says to make debugging dumps during compilation at times specified by
        !          1429: @var{letters}.  This is used for debugging the compiler.  The file names
        !          1430: for most of the dumps are made by appending a word to the source file
        !          1431: name (e.g.  @file{foo.c.rtl} or @file{foo.c.jump}).  Here are the
        !          1432: possible letters for use in @var{letters}, and their meanings:
        !          1433: 
        !          1434: @table @samp
        !          1435: @item M
        !          1436: Dump all macro definitions, at the end of preprocessing, and write no
        !          1437: output.
        !          1438: @item N
        !          1439: Dump all macro names, at the end of preprocessing.
        !          1440: @item D
        !          1441: Dump all macro definitions, at the end of preprocessing, in addition to
        !          1442: normal output.
        !          1443: @item y
        !          1444: Dump debugging information during parsing, to standard error.
        !          1445: @item r
        !          1446: Dump after RTL generation, to @file{@var{file}.rtl}.
        !          1447: @item x
        !          1448: Just generate RTL for a function instead of compiling it.  Usually used
        !          1449: with @samp{r}.
        !          1450: @item j
        !          1451: Dump after first jump optimization, to @file{@var{file}.jump}.
        !          1452: @item s
        !          1453: Dump after CSE (including the jump optimization that sometimes
        !          1454: follows CSE), to @file{@var{file}.cse}.
        !          1455: @item L
        !          1456: Dump after loop optimization, to @file{@var{file}.loop}.
        !          1457: @item t
        !          1458: Dump after the second CSE pass (including the jump optimization that
        !          1459: sometimes follows CSE), to @file{@var{file}.cse2}.
        !          1460: @item f
        !          1461: Dump after flow analysis, to @file{@var{file}.flow}.
        !          1462: @item c
        !          1463: Dump after instruction combination, to the file
        !          1464: @file{@var{file}.combine}.
        !          1465: @item S
        !          1466: Dump after the first instruction scheduling pass, to
        !          1467: @file{@var{file}.sched}.
        !          1468: @item l
        !          1469: Dump after local register allocation, to
        !          1470: @file{@var{file}.lreg}.
        !          1471: @item g
        !          1472: Dump after global register allocation, to
        !          1473: @file{@var{file}.greg}.
        !          1474: @item R
        !          1475: Dump after the second instruction scheduling pass, to
        !          1476: @file{@var{file}.sched2}.
        !          1477: @item J
        !          1478: Dump after last jump optimization, to @file{@var{file}.jump2}.
        !          1479: @item d
        !          1480: Dump after delayed branch scheduling, to @file{@var{file}.dbr}.
        !          1481: @item k
        !          1482: Dump after conversion from registers to stack, to @file{@var{file}.stack}.
        !          1483: @item a
        !          1484: Produce all the dumps listed above.
        !          1485: @item m
        !          1486: Print statistics on memory usage, at the end of the run, to
        !          1487: standard error.
        !          1488: @item p
        !          1489: Annotate the assembler output with a comment indicating which
        !          1490: pattern and alternative was used.
        !          1491: @end table
        !          1492: 
        !          1493: @item -fpretend-float
        !          1494: When running a cross-compiler, pretend that the target machine uses the
        !          1495: same floating point format as the host machine.  This causes incorrect
        !          1496: output of the actual floating constants, but the actual instruction
        !          1497: sequence will probably be the same as GNU CC would make when running on
        !          1498: the target machine.
        !          1499: 
        !          1500: @item -save-temps
        !          1501: Store the usual ``temporary'' intermediate files permanently; place them
        !          1502: in the current directory and name them based on the source file.  Thus,
        !          1503: compiling @file{foo.c} with @samp{-c -save-temps} would produce files
        !          1504: @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.
        !          1505: 
        !          1506: @item -print-libgcc-file-name
        !          1507: Print the full absolute name of the library file @file{libgcc.a} that
        !          1508: would be used when linking---and don't do anything else.  With this
        !          1509: option, GNU CC does not compile or link anything; it just prints the
        !          1510: file name.
        !          1511: 
        !          1512: This is useful when you use @samp{-nostdlib} but you do want to link
        !          1513: with @file{libgcc.a}.  You can do
        !          1514: 
        !          1515: @example
        !          1516: gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
        !          1517: @end example
        !          1518: @end table
        !          1519: 
        !          1520: @node Optimize Options
        !          1521: @section Options That Control Optimization
        !          1522: @cindex optimize options
        !          1523: @cindex options, optimization
        !          1524: 
        !          1525: These options control various sorts of optimizations:
        !          1526: 
        !          1527: @table @code
        !          1528: @item -O
        !          1529: @itemx -O1
        !          1530: Optimize.  Optimizing compilation takes somewhat more time, and a lot
        !          1531: more memory for a large function.
        !          1532: 
        !          1533: Without @samp{-O}, the compiler's goal is to reduce the cost of
        !          1534: compilation and to make debugging produce the expected results.
        !          1535: Statements are independent: if you stop the program with a breakpoint
        !          1536: between statements, you can then assign a new value to any variable or
        !          1537: change the program counter to any other statement in the function and
        !          1538: get exactly the results you would expect from the source code.
        !          1539: 
        !          1540: Without @samp{-O}, only variables declared @code{register} are
        !          1541: allocated in registers.  The resulting compiled code is a little worse
        !          1542: than produced by PCC without @samp{-O}.
        !          1543: 
        !          1544: With @samp{-O}, the compiler tries to reduce code size and execution
        !          1545: time.
        !          1546: 
        !          1547: When @samp{-O} is specified, the two options @samp{-fthread-jumps} and
        !          1548: @samp{-fdelayed-branch} are turned on.  On some machines other flags may
        !          1549: also be turned on.
        !          1550: 
        !          1551: @item -O2
        !          1552: Optimize even more.  Nearly all supported optimizations that do not
        !          1553: involve a space-speed tradeoff are performed.  As compared to @samp{-O},
        !          1554: this option increases both compilation time and the performance of the
        !          1555: generated code.
        !          1556: 
        !          1557: @samp{-O2} turns on all optional optimizations except for loop unrolling
        !          1558: and frame pointer elimination.
        !          1559: 
        !          1560: @item -O0
        !          1561: Do not optimize.
        !          1562: 
        !          1563: If you use multiple @samp{-O} options, with or without level numbers,
        !          1564: the last such option is the one that is effective.
        !          1565: @end table
        !          1566: 
        !          1567: Options of the form @samp{-f@var{flag}} specify machine-independent
        !          1568: flags.  Most flags have both positive and negative forms; the negative
        !          1569: form of @samp{-ffoo} would be @samp{-fno-foo}.  In the table below,
        !          1570: only one of the forms is listed---the one which is not the default.
        !          1571: You can figure out the other form by either removing @samp{no-} or
        !          1572: adding it.
        !          1573: 
        !          1574: @table @code
        !          1575: @item -ffloat-store
        !          1576: Do not store floating point variables in registers, and inhibit other
        !          1577: options that might change whether a floating point value is taken from a
        !          1578: register or memory.
        !          1579: 
        !          1580: This option prevents undesirable excess precision on machines such as
        !          1581: the 68000 where the floating registers (of the 68881) keep more
        !          1582: precision than a @code{double} is supposed to have.  For most programs,
        !          1583: the excess precision does only good, but a few programs rely on the
        !          1584: precise definition of IEEE floating point.  Use @samp{-ffloat-store} for
        !          1585: such programs.
        !          1586: 
        !          1587: @item -fno-default-inline
        !          1588: Do not make member functions inline by default merely because they are
        !          1589: defined inside the class scope (C++ only).  Otherwise, when you specify
        !          1590: @w{@samp{-O}}, member functions defined inside class scope are compiled
        !          1591: inline by default; i.e., you don't need to add @samp{inline} in front of
        !          1592: the member function name.
        !          1593: 
        !          1594: @item -fno-defer-pop
        !          1595: Always pop the arguments to each function call as soon as that function
        !          1596: returns.  For machines which must pop arguments after a function call,
        !          1597: the compiler normally lets arguments accumulate on the stack for several
        !          1598: function calls and pops them all at once.
        !          1599: 
        !          1600: @item -fforce-mem
        !          1601: Force memory operands to be copied into registers before doing
        !          1602: arithmetic on them.  This may produce better code by making all
        !          1603: memory references potential common subexpressions.  When they are
        !          1604: not common subexpressions, instruction combination should
        !          1605: eliminate the separate register-load.  I am interested in hearing
        !          1606: about the difference this makes.
        !          1607: 
        !          1608: @item -fforce-addr
        !          1609: Force memory address constants to be copied into registers before
        !          1610: doing arithmetic on them.  This may produce better code just as
        !          1611: @samp{-fforce-mem} may.  I am interested in hearing about the
        !          1612: difference this makes.
        !          1613: 
        !          1614: @item -fomit-frame-pointer
        !          1615: Don't keep the frame pointer in a register for functions that
        !          1616: don't need one.  This avoids the instructions to save, set up and
        !          1617: restore frame pointers; it also makes an extra register available
        !          1618: in many functions.  @strong{It also makes debugging impossible on
        !          1619: some machines.}
        !          1620: 
        !          1621: @ifset INTERNALS
        !          1622: On some machines, such as the Vax, this flag has no effect, because
        !          1623: the standard calling sequence automatically handles the frame pointer
        !          1624: and nothing is saved by pretending it doesn't exist.  The
        !          1625: machine-description macro @code{FRAME_POINTER_REQUIRED} controls
        !          1626: whether a target machine supports this flag.  @xref{Registers}.@refill
        !          1627: @end ifset
        !          1628: @ifclear INTERNALS
        !          1629: On some machines, such as the Vax, this flag has no effect, because
        !          1630: the standard calling sequence automatically handles the frame pointer
        !          1631: and nothing is saved by pretending it doesn't exist.  The
        !          1632: machine-description macro @code{FRAME_POINTER_REQUIRED} controls
        !          1633: whether a target machine supports this flag.  @xref{Registers,,Register
        !          1634: Usage, gcc.info, Using and Porting GCC}.@refill
        !          1635: @end ifclear
        !          1636: 
        !          1637: @item -fno-inline
        !          1638: Don't pay attention to the @code{inline} keyword.  Normally this option
        !          1639: is used to keep the compiler from expanding any functions inline.
        !          1640: Note that if you are not optimizing, no functions can be expanded inline.
        !          1641: 
        !          1642: @item -finline-functions
        !          1643: Integrate all simple functions into their callers.  The compiler
        !          1644: heuristically decides which functions are simple enough to be worth
        !          1645: integrating in this way.
        !          1646: 
        !          1647: If all calls to a given function are integrated, and the function is
        !          1648: declared @code{static}, then the function is normally not output as
        !          1649: assembler code in its own right.
        !          1650: 
        !          1651: @item -fkeep-inline-functions
        !          1652: Even if all calls to a given function are integrated, and the function
        !          1653: is declared @code{static}, nevertheless output a separate run-time
        !          1654: callable version of the function.
        !          1655: 
        !          1656: @item -fno-function-cse
        !          1657: Do not put function addresses in registers; make each instruction that
        !          1658: calls a constant function contain the function's address explicitly.
        !          1659: 
        !          1660: This option results in less efficient code, but some strange hacks
        !          1661: that alter the assembler output may be confused by the optimizations
        !          1662: performed when this option is not used.
        !          1663: 
        !          1664: @item -ffast-math
        !          1665: This option allows GCC to violate some ANSI or IEEE rules and/or
        !          1666: specifications in the interest of optimizing code for speed.  For
        !          1667: example, it allows the compiler to assume arguments to the @code{sqrt}
        !          1668: function are non-negative numbers.
        !          1669: 
        !          1670: This option should never be turned on by any @samp{-O} option since 
        !          1671: it can result in incorrect output for programs which depend on 
        !          1672: an exact implementation of IEEE or ANSI rules/specifications for
        !          1673: math functions.
        !          1674: @end table
        !          1675: 
        !          1676: @c following causes underfulls.. they don't look great, but we deal.
        !          1677: @c --mew 26jan93
        !          1678: The following options control specific optimizations.  The @samp{-O2}
        !          1679: option turns on all of these optimizations except @samp{-funroll-loops}
        !          1680: and @samp{-funroll-all-loops}.  On most machines, the @samp{-O} option
        !          1681: turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options,
        !          1682: but specific machines may handle it differently.
        !          1683: 
        !          1684: You can use the following flags in the rare cases when ``fine-tuning''
        !          1685: of optimizations to be performed is desired.
        !          1686: 
        !          1687: @table @code
        !          1688: @item -fstrength-reduce
        !          1689: Perform the optimizations of loop strength reduction and
        !          1690: elimination of iteration variables.
        !          1691: 
        !          1692: @item -fthread-jumps
        !          1693: Perform optimizations where we check to see if a jump branches to a
        !          1694: location where another comparison subsumed by the first is found.  If
        !          1695: so, the first branch is redirected to either the destination of the
        !          1696: second branch or a point immediately following it, depending on whether
        !          1697: the condition is known to be true or false.
        !          1698: 
        !          1699: @item -fcse-follow-jumps
        !          1700: In common subexpression elimination, scan through jump instructions
        !          1701: when the target of the jump is not reached by any other path.  For
        !          1702: example, when CSE encounters an @code{if} statement with an
        !          1703: @code{else} clause, CSE will follow the jump when the condition
        !          1704: tested is false.
        !          1705: 
        !          1706: @item -fcse-skip-blocks
        !          1707: This is similar to @samp{-fcse-follow-jumps}, but causes CSE to
        !          1708: follow jumps which conditionally skip over blocks.  When CSE
        !          1709: encounters a simple @code{if} statement with no else clause,
        !          1710: @samp{-fcse-skip-blocks} causes CSE to follow the jump around the
        !          1711: body of the @code{if}.
        !          1712: 
        !          1713: @item -frerun-cse-after-loop
        !          1714: Re-run common subexpression elimination after loop optimizations has been
        !          1715: performed.  
        !          1716: 
        !          1717: @item -fexpensive-optimizations
        !          1718: Perform a number of minor optimizations that are relatively expensive.
        !          1719: 
        !          1720: @item -fdelayed-branch
        !          1721: If supported for the target machine, attempt to reorder instructions
        !          1722: to exploit instruction slots available after delayed branch
        !          1723: instructions.
        !          1724: 
        !          1725: @item -fschedule-insns
        !          1726: If supported for the target machine, attempt to reorder instructions to
        !          1727: eliminate execution stalls due to required data being unavailable.  This
        !          1728: helps machines that have slow floating point or memory load instructions
        !          1729: by allowing other instructions to be issued until the result of the load
        !          1730: or floating point instruction is required.
        !          1731: 
        !          1732: @item -fschedule-insns2
        !          1733: Similar to @samp{-fschedule-insns}, but requests an additional pass of
        !          1734: instruction scheduling after register allocation has been done.  This is
        !          1735: especially useful on machines with a relatively small number of
        !          1736: registers and where memory load instructions take more than one cycle.
        !          1737: 
        !          1738: @item -fcaller-saves
        !          1739: Enable values to be allocated in registers that will be clobbered by
        !          1740: function calls, by emitting extra instructions to save and restore the
        !          1741: registers around such calls.  Such allocation is done only when it
        !          1742: seems to result in better code than would otherwise be produced.
        !          1743: 
        !          1744: This option is enabled by default on certain machines, usually those
        !          1745: which have no call-preserved registers to use instead.
        !          1746: 
        !          1747: @item -funroll-loops
        !          1748: Perform the optimization of loop unrolling.  This is only done for loops
        !          1749: whose number of iterations can be determined at compile time or run time.
        !          1750: @samp{-funroll-loop} implies both @samp{-fstrength-reduce} and
        !          1751: @samp{-frerun-cse-after-loop}.
        !          1752: 
        !          1753: @item -funroll-all-loops
        !          1754: Perform the optimization of loop unrolling.  This is done for all loops
        !          1755: and usually makes programs run more slowly.  @samp{-funroll-all-loops}
        !          1756: implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}.
        !          1757: 
        !          1758: @item -fno-peephole
        !          1759: Disable any machine-specific peephole optimizations.
        !          1760: @end table
        !          1761: 
        !          1762: @node Preprocessor Options
        !          1763: @section Options Controlling the Preprocessor
        !          1764: @cindex preprocessor options
        !          1765: @cindex options, preprocessor
        !          1766: 
        !          1767: These options control the C preprocessor, which is run on each C source
        !          1768: file before actual compilation.
        !          1769: 
        !          1770: If you use the @samp{-E} option, nothing is done except preprocessing.
        !          1771: Some of these options make sense only together with @samp{-E} because
        !          1772: they cause the preprocessor output to be unsuitable for actual
        !          1773: compilation.
        !          1774: 
        !          1775: @table @code
        !          1776: @item -include @var{file}
        !          1777: Process @var{file} as input before processing the regular input file.
        !          1778: In effect, the contents of @var{file} are compiled first.  Any @samp{-D}
        !          1779: and @samp{-U} options on the command line are always processed before
        !          1780: @samp{-include @var{file}}, regardless of the order in which they are
        !          1781: written.  All the @samp{-include} and @samp{-imacros} options are
        !          1782: processed in the order in which they are written.
        !          1783: 
        !          1784: @item -imacros @var{file}
        !          1785: Process @var{file} as input, discarding the resulting output, before
        !          1786: processing the regular input file.  Because the output generated from
        !          1787: @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
        !          1788: is to make the macros defined in @var{file} available for use in the
        !          1789: main input.
        !          1790: 
        !          1791: Any @samp{-D} and @samp{-U} options on the command line are always
        !          1792: processed before @samp{-imacros @var{file}}, regardless of the order in
        !          1793: which they are written.  All the @samp{-include} and @samp{-imacros}
        !          1794: options are processed in the order in which they are written.
        !          1795: 
        !          1796: @item -idirafter @var{dir}
        !          1797: @cindex second include path
        !          1798: Add the directory @var{dir} to the second include path.  The directories
        !          1799: on the second include path are searched when a header file is not found
        !          1800: in any of the directories in the main include path (the one that
        !          1801: @samp{-I} adds to).
        !          1802: 
        !          1803: @item -iprefix @var{prefix}
        !          1804: Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
        !          1805: options.
        !          1806: 
        !          1807: @item -iwithprefix @var{dir}
        !          1808: Add a directory to the second include path.  The directory's name is
        !          1809: made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
        !          1810: specified previously with @samp{-iprefix}.  If you have not specified a
        !          1811: prefix yet, the directory containing the installed passes of the
        !          1812: compiler is used as the default.
        !          1813: 
        !          1814: @item -iwithprefixbefore @var{dir}
        !          1815: Add a directory to the main include path.  The directory's name is made
        !          1816: by concatenating @var{prefix} and @var{dir}, as in the case of
        !          1817: @samp{-iwithprefix}.
        !          1818: 
        !          1819: @item -nostdinc
        !          1820: Do not search the standard system directories for header files.  Only
        !          1821: the directories you have specified with @samp{-I} options (and the
        !          1822: current directory, if appropriate) are searched.  @xref{Directory
        !          1823: Options}, for information on @samp{-I}.
        !          1824: 
        !          1825: By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
        !          1826: search path to only those directories you specify explicitly.
        !          1827: 
        !          1828: @item -undef
        !          1829: Do not predefine any nonstandard macros.  (Including architecture flags).
        !          1830: 
        !          1831: @item -E
        !          1832: Run only the C preprocessor.  Preprocess all the C source files
        !          1833: specified and output the results to standard output or to the
        !          1834: specified output file.
        !          1835: 
        !          1836: @item -C
        !          1837: Tell the preprocessor not to discard comments.  Used with the
        !          1838: @samp{-E} option.
        !          1839: 
        !          1840: @item -P
        !          1841: Tell the preprocessor not to generate @samp{#line} commands.
        !          1842: Used with the @samp{-E} option.
        !          1843: 
        !          1844: @cindex make
        !          1845: @cindex dependencies, make
        !          1846: @item -M
        !          1847: Tell the preprocessor to output a rule suitable for @code{make}
        !          1848: describing the dependencies of each object file.  For each source file,
        !          1849: the preprocessor outputs one @code{make}-rule whose target is the object
        !          1850: file name for that source file and whose dependencies are all the
        !          1851: @code{#include} header files it uses.  This rule may be a single line or
        !          1852: may be continued with @samp{\}-newline if it is long.  The list of rules
        !          1853: is printed on standard output instead of the preprocessed C program.
        !          1854: 
        !          1855: @samp{-M} implies @samp{-E}.
        !          1856: 
        !          1857: Another way to specify output of a @code{make} rule is by setting
        !          1858: the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
        !          1859: Variables}).
        !          1860: 
        !          1861: @item -MM
        !          1862: Like @samp{-M} but the output mentions only the user header files
        !          1863: included with @samp{#include "@var{file}"}.  System header files
        !          1864: included with @samp{#include <@var{file}>} are omitted.
        !          1865: 
        !          1866: @item -MD
        !          1867: Like @samp{-M} but the dependency information is written to files with
        !          1868: names made by replacing @samp{.o} with @samp{.d} at the end of the
        !          1869: output file names.  This is in addition to compiling the input files as
        !          1870: specified---@samp{-MD} does not inhibit ordinary compilation the way
        !          1871: @samp{-M} does.
        !          1872: 
        !          1873: The Mach utility @samp{md} can be used to merge the @samp{.d} files
        !          1874: into a single dependency file suitable for using with the @samp{make}
        !          1875: command.
        !          1876: 
        !          1877: @item -MMD
        !          1878: Like @samp{-MD} except mention only user header files, not system
        !          1879: header files.
        !          1880: 
        !          1881: @item -H
        !          1882: Print the name of each header file used, in addition to other normal
        !          1883: activities.
        !          1884: 
        !          1885: @item -A@var{question}(@var{answer})
        !          1886: Assert the answer @var{answer} for @var{question}, in case it is tested
        !          1887: with a preprocessor conditional such as @samp{#if
        !          1888: #@var{question}(@var{answer})}.  @samp{-A-} disables the standard
        !          1889: assertions that normally describe the target machine.
        !          1890: 
        !          1891: @item -D@var{macro}
        !          1892: Define macro @var{macro} with the string @samp{1} as its definition.
        !          1893: 
        !          1894: @item -D@var{macro}=@var{defn}
        !          1895: Define macro @var{macro} as @var{defn}.  All instances of @samp{-D} on
        !          1896: the command line are processed before any @samp{-U} options.
        !          1897: 
        !          1898: @item -U@var{macro}
        !          1899: Undefine macro @var{macro}.  @samp{-U} options are evaluated after all
        !          1900: @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
        !          1901: options.
        !          1902: 
        !          1903: @item -dM
        !          1904: Tell the preprocessor to output only a list of the macro definitions
        !          1905: that are in effect at the end of preprocessing.  Used with the @samp{-E}
        !          1906: option.
        !          1907: 
        !          1908: @item -dD
        !          1909: Tell the preprocessing to pass all macro definitions into the output, in
        !          1910: their proper sequence in the rest of the output.
        !          1911: 
        !          1912: @item -dN
        !          1913: Like @samp{-dD} except that the macro arguments and contents are omitted.
        !          1914: Only @samp{#define @var{name}} is included in the output.
        !          1915: 
        !          1916: @item -trigraphs
        !          1917: Support ANSI C trigraphs.  You don't want to know about this
        !          1918: brain-damage.  The @samp{-ansi} option also has this effect.
        !          1919: @end table
        !          1920: 
        !          1921: @node Assembler Options
        !          1922: @section Passing Options to the Assembler
        !          1923: 
        !          1924: @table @code
        !          1925: @item -Wa,@var{option}
        !          1926: Pass @var{option} as an option to the assembler.  If @var{option}
        !          1927: contains commas, it is split into multiple options at the commas.
        !          1928: @end table
        !          1929: 
        !          1930: @node Link Options
        !          1931: @section Options for Linking
        !          1932: @cindex link options
        !          1933: @cindex options, linking
        !          1934: 
        !          1935: These options come into play when the compiler links object files into
        !          1936: an executable output file.  They are meaningless if the compiler is
        !          1937: not doing a link step.
        !          1938: 
        !          1939: @table @code
        !          1940: @cindex file names
        !          1941: @item @var{object-file-name}
        !          1942: A file name that does not end in a special recognized suffix is
        !          1943: considered to name an object file or library.  (Object files are
        !          1944: distinguished from libraries by the linker according to the file
        !          1945: contents.)  If linking is done, these object files are used as input
        !          1946: to the linker.
        !          1947: 
        !          1948: @item -c
        !          1949: @itemx -S
        !          1950: @itemx -E
        !          1951: If any of these options is used, then the linker is not run, and
        !          1952: object file names should not be used as arguments.  @xref{Overall
        !          1953: Options}.
        !          1954: 
        !          1955: @cindex Libraries
        !          1956: @item -l@var{library}
        !          1957: Search the library named @var{library} when linking.
        !          1958: 
        !          1959: It makes a difference where in the command you write this option; the
        !          1960: linker searches processes libraries and object files in the order they
        !          1961: are specified.  Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
        !          1962: after file @file{foo.o} but before @file{bar.o}.  If @file{bar.o} refers
        !          1963: to functions in @samp{z}, those functions may not be loaded.
        !          1964: 
        !          1965: The linker searches a standard list of directories for the library,
        !          1966: which is actually a file named @file{lib@var{library}.a}.  The linker
        !          1967: then uses this file as if it had been specified precisely by name.
        !          1968: 
        !          1969: The directories searched include several standard system directories
        !          1970: plus any that you specify with @samp{-L}.
        !          1971: 
        !          1972: Normally the files found this way are library files---archive files
        !          1973: whose members are object files.  The linker handles an archive file by
        !          1974: scanning through it for members which define symbols that have so far
        !          1975: been referenced but not defined.  But if the file that is found is an
        !          1976: ordinary object file, it is linked in the usual fashion.  The only
        !          1977: difference between using an @samp{-l} option and specifying a file name
        !          1978: is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
        !          1979: and searches several directories.
        !          1980: 
        !          1981: @item -lobjc
        !          1982: You need this special case of the @samp{-l} option in order to
        !          1983: link an Objective C program.
        !          1984: 
        !          1985: @item -nostartfiles
        !          1986: Do not use the standard system startup files when linking.
        !          1987: The standard libraries are used normally.
        !          1988: 
        !          1989: @item -nostdlib
        !          1990: Don't use the standard system libraries and startup files when linking.
        !          1991: Only the files you specify will be passed to the linker.
        !          1992: 
        !          1993: @item -static
        !          1994: On systems that support dynamic linking, this prevents linking with the shared
        !          1995: libraries.  On other systems, this
        !          1996: option has no effect.
        !          1997: 
        !          1998: @item -shared
        !          1999: Produce a shared object which can then be linked with other objects to
        !          2000: form an executable.  Only a few systems support this option.
        !          2001: 
        !          2002: @item -symbolic
        !          2003: Bind references to global symbols when building a shared object.  Warn
        !          2004: about any unresolved references (unless overridden by the link editor
        !          2005: option @samp{-Xlinker -z -Xlinker defs}).  Only a few systems support
        !          2006: this option.
        !          2007: 
        !          2008: @item -Xlinker @var{option}
        !          2009: Pass @var{option} as an option to the linker.  You can use this to
        !          2010: supply system-specific linker options which GNU CC does not know how to
        !          2011: recognize.
        !          2012: 
        !          2013: If you want to pass an option that takes an argument, you must use
        !          2014: @samp{-Xlinker} twice, once for the option and once for the argument.
        !          2015: For example, to pass @samp{-assert definitions}, you must write
        !          2016: @samp{-Xlinker -assert -Xlinker definitions}.  It does not work to write
        !          2017: @samp{-Xlinker "-assert definitions"}, because this passes the entire
        !          2018: string as a single argument, which is not what the linker expects.
        !          2019: 
        !          2020: @item -Wl,@var{option}
        !          2021: Pass @var{option} as an option to the linker.  If @var{option} contains
        !          2022: commas, it is split into multiple options at the commas.
        !          2023: 
        !          2024: @item -u @var{symbol}
        !          2025: Pretend the symbol @var{symbol} is undefined, to force linking of
        !          2026: library modules to define it.  You can use @samp{-u} multiple times with
        !          2027: different symbols to force loading of additional library modules.
        !          2028: @end table
        !          2029: 
        !          2030: @node Directory Options
        !          2031: @section Options for Directory Search
        !          2032: @cindex directory options
        !          2033: @cindex options, directory search
        !          2034: @cindex search path
        !          2035: 
        !          2036: These options specify directories to search for header files, for
        !          2037: libraries and for parts of the compiler:
        !          2038: 
        !          2039: @table @code
        !          2040: @item -I@var{dir}
        !          2041: Append directory @var{dir} to the list of directories searched for
        !          2042: include files.
        !          2043: 
        !          2044: @item -I-
        !          2045: Any directories you specify with @samp{-I} options before the @samp{-I-}
        !          2046: option are searched only for the case of @samp{#include "@var{file}"};
        !          2047: they are not searched for @samp{#include <@var{file}>}.
        !          2048: 
        !          2049: If additional directories are specified with @samp{-I} options after
        !          2050: the @samp{-I-}, these directories are searched for all @samp{#include}
        !          2051: directives.  (Ordinarily @emph{all} @samp{-I} directories are used
        !          2052: this way.)
        !          2053: 
        !          2054: In addition, the @samp{-I-} option inhibits the use of the current
        !          2055: directory (where the current input file came from) as the first search
        !          2056: directory for @samp{#include "@var{file}"}.  There is no way to
        !          2057: override this effect of @samp{-I-}.  With @samp{-I.} you can specify
        !          2058: searching the directory which was current when the compiler was
        !          2059: invoked.  That is not exactly the same as what the preprocessor does
        !          2060: by default, but it is often satisfactory.
        !          2061: 
        !          2062: @samp{-I-} does not inhibit the use of the standard system directories
        !          2063: for header files.  Thus, @samp{-I-} and @samp{-nostdinc} are
        !          2064: independent.
        !          2065: 
        !          2066: @item -L@var{dir}
        !          2067: Add directory @var{dir} to the list of directories to be searched
        !          2068: for @samp{-l}.
        !          2069: 
        !          2070: @item -B@var{prefix}
        !          2071: This option specifies where to find the executables, libraries and
        !          2072: data files of the compiler itself.
        !          2073: 
        !          2074: The compiler driver program runs one or more of the subprograms
        !          2075: @file{cpp}, @file{cc1}, @file{as} and @file{ld}.  It tries
        !          2076: @var{prefix} as a prefix for each program it tries to run, both with and
        !          2077: without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
        !          2078: 
        !          2079: For each subprogram to be run, the compiler driver first tries the
        !          2080: @samp{-B} prefix, if any.  If that name is not found, or if @samp{-B}
        !          2081: was not specified, the driver tries two standard prefixes, which are
        !          2082: @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}.  If neither of
        !          2083: those results in a file name that is found, the unmodified program
        !          2084: name is searched for using the directories specified in your
        !          2085: @samp{PATH} environment variable.
        !          2086: 
        !          2087: @samp{-B} prefixes that effectively specify directory names also apply
        !          2088: to libraries in the linker, because the compiler translates these
        !          2089: options into @samp{-L} options for the linker.
        !          2090: 
        !          2091: The run-time support file @file{libgcc.a} can also be searched for using
        !          2092: the @samp{-B} prefix, if needed.  If it is not found there, the two
        !          2093: standard prefixes above are tried, and that is all.  The file is left
        !          2094: out of the link if it is not found by those means.
        !          2095: 
        !          2096: Another way to specify a prefix much like the @samp{-B} prefix is to use
        !          2097: the environment variable @code{GCC_EXEC_PREFIX}.  @xref{Environment
        !          2098: Variables}.
        !          2099: @end table
        !          2100: 
        !          2101: @node Target Options
        !          2102: @section Specifying Target Machine and Compiler Version
        !          2103: @cindex target options
        !          2104: @cindex cross compiling
        !          2105: @cindex specifying machine version
        !          2106: @cindex specifying compiler version and target machine
        !          2107: @cindex compiler version, specifying
        !          2108: @cindex target machine, specifying
        !          2109: 
        !          2110: By default, GNU CC compiles code for the same type of machine that you
        !          2111: are using.  However, it can also be installed as a cross-compiler, to
        !          2112: compile for some other type of machine.  In fact, several different
        !          2113: configurations of GNU CC, for different target machines, can be
        !          2114: installed side by side.  Then you specify which one to use with the
        !          2115: @samp{-b} option.
        !          2116: 
        !          2117: In addition, older and newer versions of GNU CC can be installed side
        !          2118: by side.  One of them (probably the newest) will be the default, but
        !          2119: you may sometimes wish to use another.
        !          2120: 
        !          2121: @table @code
        !          2122: @item -b @var{machine}
        !          2123: The argument @var{machine} specifies the target machine for compilation.
        !          2124: This is useful when you have installed GNU CC as a cross-compiler.
        !          2125: 
        !          2126: The value to use for @var{machine} is the same as was specified as the
        !          2127: machine type when configuring GNU CC as a cross-compiler.  For
        !          2128: example, if a cross-compiler was configured with @samp{configure
        !          2129: i386v}, meaning to compile for an 80386 running System V, then you
        !          2130: would specify @samp{-b i386v} to run that cross compiler.
        !          2131: 
        !          2132: When you do not specify @samp{-b}, it normally means to compile for
        !          2133: the same type of machine that you are using.
        !          2134: 
        !          2135: @item -V @var{version}
        !          2136: The argument @var{version} specifies which version of GNU CC to run.
        !          2137: This is useful when multiple versions are installed.  For example,
        !          2138: @var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0.
        !          2139: 
        !          2140: The default version, when you do not specify @samp{-V}, is controlled
        !          2141: by the way GNU CC is installed.  Normally, it will be a version that
        !          2142: is recommended for general use.
        !          2143: @end table
        !          2144: 
        !          2145: The @samp{-b} and @samp{-V} options actually work by controlling part of
        !          2146: the file name used for the executable files and libraries used for
        !          2147: compilation.  A given version of GNU CC, for a given target machine, is
        !          2148: normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
        !          2149: 
        !          2150: Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by
        !          2151: changing the names of these directories or adding alternate names (or
        !          2152: symbolic links).  If in directory @file{/usr/local/lib/gcc-lib/} the
        !          2153: file @file{80386} is a link to the file @file{i386v}, then @samp{-b
        !          2154: 80386} becomes an alias for @samp{-b i386v}.
        !          2155: 
        !          2156: In one respect, the @samp{-b} or @samp{-V} do not completely change
        !          2157: to a different compiler: the top-level driver program @code{gcc}
        !          2158: that you originally invoked continues to run and invoke the other
        !          2159: executables (preprocessor, compiler per se, assembler and linker)
        !          2160: that do the real work.  However, since no real work is done in the
        !          2161: driver program, it usually does not matter that the driver program
        !          2162: in use is not the one for the specified target and version.
        !          2163: 
        !          2164: The only way that the driver program depends on the target machine is
        !          2165: in the parsing and handling of special machine-specific options.
        !          2166: However, this is controlled by a file which is found, along with the
        !          2167: other executables, in the directory for the specified version and
        !          2168: target machine.  As a result, a single installed driver program adapts
        !          2169: to any specified target machine and compiler version.
        !          2170: 
        !          2171: The driver program executable does control one significant thing,
        !          2172: however: the default version and target machine.  Therefore, you can
        !          2173: install different instances of the driver program, compiled for
        !          2174: different targets or versions, under different names.
        !          2175: 
        !          2176: For example, if the driver for version 2.0 is installed as @code{ogcc}
        !          2177: and that for version 2.1 is installed as @code{gcc}, then the command
        !          2178: @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
        !          2179: 2.0 by default.  However, you can choose either version with either
        !          2180: command with the @samp{-V} option.
        !          2181: 
        !          2182: @node Submodel Options
        !          2183: @section Hardware Models and Configurations
        !          2184: @cindex submodel options
        !          2185: @cindex specifying hardware config
        !          2186: @cindex hardware models and configurations, specifying
        !          2187: @cindex machine dependent options
        !          2188: 
        !          2189: Earlier we discussed the standard option @samp{-b} which chooses among
        !          2190: different installed compilers for completely different target
        !          2191: machines, such as Vax vs. 68000 vs. 80386.
        !          2192: 
        !          2193: In addition, each of these target machine types can have its own
        !          2194: special options, starting with @samp{-m}, to choose among various
        !          2195: hardware models or configurations---for example, 68010 vs 68020,
        !          2196: floating coprocessor or none.  A single installed version of the
        !          2197: compiler can compile for any model or configuration, according to the
        !          2198: options specified.
        !          2199: 
        !          2200: Some configurations of the compiler also support additional special
        !          2201: options, usually for compatibility with other compilers on the same
        !          2202: platform.
        !          2203: 
        !          2204: @ifset INTERNALS
        !          2205: These options are defined by the macro @code{TARGET_SWITCHES} in the
        !          2206: machine description.  The default for the options is also defined by
        !          2207: that macro, which enables you to change the defaults.
        !          2208: @end ifset
        !          2209: 
        !          2210: @menu
        !          2211: * M680x0 Options::
        !          2212: * VAX Options::
        !          2213: * SPARC Options::
        !          2214: * Convex Options::
        !          2215: * AMD29K Options::
        !          2216: * M88K Options::
        !          2217: * RS/6000 and PowerPC Options::
        !          2218: * RT Options::
        !          2219: * MIPS Options::
        !          2220: * i386 Options::
        !          2221: * HPPA Options::
        !          2222: * Intel 960 Options::
        !          2223: * DEC Alpha Options::
        !          2224: * Clipper Options::
        !          2225: * System V Options::
        !          2226: @end menu
        !          2227: 
        !          2228: @node M680x0 Options
        !          2229: @subsection M680x0 Options
        !          2230: @cindex M680x0 options
        !          2231: 
        !          2232: These are the @samp{-m} options defined for the 68000 series.  The default
        !          2233: values for these options depends on which style of 68000 was selected when
        !          2234: the compiler was configured; the defaults for the most common choices are
        !          2235: given below.
        !          2236: 
        !          2237: @table @code
        !          2238: @item -m68000
        !          2239: @itemx -mc68000
        !          2240: Generate output for a 68000.  This is the default
        !          2241: when the compiler is configured for 68000-based systems.
        !          2242: 
        !          2243: @item -m68020
        !          2244: @itemx -mc68020
        !          2245: Generate output for a 68020.  This is the default
        !          2246: when the compiler is configured for 68020-based systems.
        !          2247: 
        !          2248: @item -m68881
        !          2249: Generate output containing 68881 instructions for floating point.
        !          2250: This is the default for most 68020 systems unless @samp{-nfp} was
        !          2251: specified when the compiler was configured.
        !          2252: 
        !          2253: @item -m68030
        !          2254: Generate output for a 68030.  This is the default when the compiler is
        !          2255: configured for 68030-based systems.
        !          2256: 
        !          2257: @item -m68040
        !          2258: Generate output for a 68040.  This is the default when the compiler is
        !          2259: configured for 68040-based systems.
        !          2260: 
        !          2261: This option inhibits the use of 68881/68882 instructions that have to be
        !          2262: emulated by software on the 68040.  If your 68040 does not have code to
        !          2263: emulate those instructions, use @samp{-m68040}.
        !          2264: 
        !          2265: @item -m68020-40
        !          2266: Generate output for a 68040, without using any of the new instructions.
        !          2267: This results in code which can run relatively efficiently on either a
        !          2268: 68020/68881 or a 68030 or a 68040.  The generated code does use the
        !          2269: 68881 instructions that are emulated on the 68040.
        !          2270: 
        !          2271: @item -mfpa
        !          2272: Generate output containing Sun FPA instructions for floating point.
        !          2273: 
        !          2274: @item -msoft-float
        !          2275: Generate output containing library calls for floating point.
        !          2276: @strong{Warning:} the requisite libraries are not part of GNU CC.
        !          2277: Normally the facilities of the machine's usual C compiler are used, but
        !          2278: this can't be done directly in cross-compilation.  You must make your
        !          2279: own arrangements to provide suitable library functions for
        !          2280: cross-compilation.
        !          2281: 
        !          2282: @item -mshort
        !          2283: Consider type @code{int} to be 16 bits wide, like @code{short int}.
        !          2284: 
        !          2285: @item -mnobitfield
        !          2286: Do not use the bit-field instructions.  The @samp{-m68000} option
        !          2287: implies @w{@samp{-mnobitfield}}.
        !          2288: 
        !          2289: @item -mbitfield
        !          2290: Do use the bit-field instructions.  The @samp{-m68020} option implies
        !          2291: @samp{-mbitfield}.  This is the default if you use a configuration
        !          2292: designed for a 68020.
        !          2293: 
        !          2294: @item -mrtd
        !          2295: Use a different function-calling convention, in which functions
        !          2296: that take a fixed number of arguments return with the @code{rtd}
        !          2297: instruction, which pops their arguments while returning.  This
        !          2298: saves one instruction in the caller since there is no need to pop
        !          2299: the arguments there.
        !          2300: 
        !          2301: This calling convention is incompatible with the one normally
        !          2302: used on Unix, so you cannot use it if you need to call libraries
        !          2303: compiled with the Unix compiler.
        !          2304: 
        !          2305: Also, you must provide function prototypes for all functions that
        !          2306: take variable numbers of arguments (including @code{printf});
        !          2307: otherwise incorrect code will be generated for calls to those
        !          2308: functions.
        !          2309: 
        !          2310: In addition, seriously incorrect code will result if you call a
        !          2311: function with too many arguments.  (Normally, extra arguments are
        !          2312: harmlessly ignored.)
        !          2313: 
        !          2314: The @code{rtd} instruction is supported by the 68010 and 68020
        !          2315: processors, but not by the 68000.
        !          2316: @end table
        !          2317: 
        !          2318: @node VAX Options
        !          2319: @subsection VAX Options
        !          2320: @cindex VAX options
        !          2321: 
        !          2322: These @samp{-m} options are defined for the Vax:
        !          2323: 
        !          2324: @table @code
        !          2325: @item -munix
        !          2326: Do not output certain jump instructions (@code{aobleq} and so on)
        !          2327: that the Unix assembler for the Vax cannot handle across long
        !          2328: ranges.
        !          2329: 
        !          2330: @item -mgnu
        !          2331: Do output those jump instructions, on the assumption that you
        !          2332: will assemble with the GNU assembler.
        !          2333: 
        !          2334: @item -mg
        !          2335: Output code for g-format floating point numbers instead of d-format.
        !          2336: @end table
        !          2337: 
        !          2338: @node SPARC Options
        !          2339: @subsection SPARC Options
        !          2340: @cindex SPARC options
        !          2341: 
        !          2342: These @samp{-m} switches are supported on the SPARC:
        !          2343: 
        !          2344: @table @code
        !          2345: @item -mfpu
        !          2346: @itemx -mhard-float
        !          2347: Generate output containing floating point instructions.  This is the
        !          2348: default.
        !          2349: 
        !          2350: @item -mno-fpu
        !          2351: @itemx -msoft-float
        !          2352: Generate output containing library calls for floating point.
        !          2353: @strong{Warning:} there is no GNU floating-point library for SPARC.
        !          2354: Normally the facilities of the machine's usual C compiler are used, but
        !          2355: this cannot be done directly in cross-compilation.  You must make your
        !          2356: own arrangements to provide suitable library functions for
        !          2357: cross-compilation.
        !          2358: 
        !          2359: @samp{-msoft-float} changes the calling convention in the output file;
        !          2360: therefore, it is only useful if you compile @emph{all} of a program with
        !          2361: this option.  In particular, you need to compile @file{libgcc.a}, the
        !          2362: library that comes with GNU CC, with @samp{-msoft-float} in order for
        !          2363: this to work.
        !          2364: 
        !          2365: @ignore
        !          2366: @c Jim Wilson says this is obsolete and about to vanish
        !          2367: @item -mforce-align
        !          2368: Make sure all objects of type @code{double} are 8-byte aligned in memory
        !          2369: and use double-word instructions to reference them.
        !          2370: @end ignore
        !          2371: 
        !          2372: @item -mno-epilogue
        !          2373: @itemx -mepilogue
        !          2374: With @samp{-mepilogue} (the default), the compiler always emits code for
        !          2375: function exit at the end of each function.  Any function exit in
        !          2376: the middle of the function (such as a return statement in C) will
        !          2377: generate a jump to the exit code at the end of the function.
        !          2378: 
        !          2379: With @samp{-mno-epilogue}, the compiler tries to emit exit code inline
        !          2380: at every function exit.
        !          2381: 
        !          2382: @item -mv8
        !          2383: @itemx -msparclite
        !          2384: These two options select variations on the SPARC architecture.
        !          2385: 
        !          2386: By default (unless specifically configured for the Fujitsu SPARClite),
        !          2387: GCC generates code for the v7 variant of the SPARC architecture.
        !          2388: 
        !          2389: @samp{-mv8} will give you SPARC v8 code.  The only difference from v7
        !          2390: code is that the compiler emits the integer multiply and integer
        !          2391: divide instructions which exist in SPARC v8 but not in SPARC v7.
        !          2392: 
        !          2393: @samp{-msparclite} will give you SPARClite code.  This adds the integer
        !          2394: multiply, integer divide step and scan (@code{ffs}) instructions which
        !          2395: exist in SPARClite but not in SPARC v7.
        !          2396: @end table
        !          2397: 
        !          2398: @node Convex Options
        !          2399: @subsection Convex Options
        !          2400: @cindex Convex options
        !          2401: 
        !          2402: These @samp{-m} options are defined for Convex:
        !          2403: 
        !          2404: @table @code
        !          2405: @item -mc1
        !          2406: Generate output for C1.  The code will run on any Convex machine.
        !          2407: The preprocessor symbol @code{__convex__c1__} is defined.
        !          2408: 
        !          2409: @item -mc2
        !          2410: Generate output for C2.  Uses instructions not available on C1.
        !          2411: Scheduling and other optimizations are chosen for max performance on C2.
        !          2412: The preprocessor symbol @code{__convex_c2__} is defined.
        !          2413: 
        !          2414: @item -mc32
        !          2415: Generate output for C32xx.  Uses instructions not available on C1.
        !          2416: Scheduling and other optimizations are chosen for max performance on C32.
        !          2417: The preprocessor symbol @code{__convex_c32__} is defined.
        !          2418: 
        !          2419: @item -mc34
        !          2420: Generate output for C34xx.  Uses instructions not available on C1.
        !          2421: Scheduling and other optimizations are chosen for max performance on C34.
        !          2422: The preprocessor symbol @code{__convex_c34__} is defined.
        !          2423: 
        !          2424: @item -mc38
        !          2425: Generate output for C38xx.  Uses instructions not available on C1.
        !          2426: Scheduling and other optimizations are chosen for max performance on C38.
        !          2427: The preprocessor symbol @code{__convex_c38__} is defined.
        !          2428: 
        !          2429: @item -margcount
        !          2430: Generate code which puts an argument count in the word preceding each
        !          2431: argument list.  This is compatible with regular CC, and a few programs
        !          2432: may need the argument count word.  GDB and other source-level debuggers
        !          2433: do not need it; this info is in the symbol table.
        !          2434: 
        !          2435: @item -mnoargcount
        !          2436: Omit the argument count word.  This is the default.
        !          2437: 
        !          2438: @item -mvolatile-cache
        !          2439: Allow volatile references to be cached.  This is the default.
        !          2440: 
        !          2441: @item -mvolatile-nocache
        !          2442: Volatile references bypass the data cache, going all the way to memory.
        !          2443: This is only needed for multi-processor code that does not use standard
        !          2444: synchronization instructions.  Making non-volatile references to volatile
        !          2445: locations will not necessarily work.
        !          2446: 
        !          2447: @item -mlong32
        !          2448: Type long is 32 bits, the same as type int.  This is the default.
        !          2449: 
        !          2450: @item -mlong64
        !          2451: Type long is 64 bits, the same as type long long.  This option is useless,
        !          2452: because no library support exists for it.
        !          2453: @end table
        !          2454: 
        !          2455: @node AMD29K Options
        !          2456: @subsection AMD29K Options
        !          2457: @cindex AMD29K options
        !          2458: 
        !          2459: These @samp{-m} options are defined for the AMD Am29000:
        !          2460: 
        !          2461: @table @code
        !          2462: @item -mdw
        !          2463: @kindex -mdw
        !          2464: @cindex DW bit (29k)
        !          2465: Generate code that assumes the @code{DW} bit is set, i.e., that byte and
        !          2466: halfword operations are directly supported by the hardware.  This is the
        !          2467: default.
        !          2468: 
        !          2469: @item -mnodw
        !          2470: @kindex -mnodw
        !          2471: Generate code that assumes the @code{DW} bit is not set.
        !          2472: 
        !          2473: @item -mbw
        !          2474: @kindex -mbw
        !          2475: @cindex byte writes (29k)
        !          2476: Generate code that assumes the system supports byte and halfword write
        !          2477: operations.  This is the default.
        !          2478: 
        !          2479: @item -mnbw
        !          2480: @kindex -mnbw
        !          2481: Generate code that assumes the systems does not support byte and
        !          2482: halfword write operations.  @samp{-mnbw} implies @samp{-mnodw}.
        !          2483: 
        !          2484: @item -msmall
        !          2485: @kindex -msmall
        !          2486: @cindex memory model (29k)
        !          2487: Use a small memory model that assumes that all function addresses are
        !          2488: either within a single 256 KB segment or at an absolute address of less
        !          2489: than 256k.  This allows the @code{call} instruction to be used instead
        !          2490: of a @code{const}, @code{consth}, @code{calli} sequence.
        !          2491: 
        !          2492: @item -mnormal
        !          2493: @kindex -mnormal
        !          2494: Use the normal memory model: Generate @code{call} instructions only when
        !          2495: calling functions in the same file and @code{calli} instructions
        !          2496: otherwise.  This works if each file occupies less than 256 KB but allows
        !          2497: the entire executable to be larger than 256 KB.  This is the default.
        !          2498: 
        !          2499: @item -mlarge
        !          2500: Always use @code{calli} instructions.  Specify this option if you expect
        !          2501: a single file to compile into more than 256 KB of code.
        !          2502: 
        !          2503: @item -m29050
        !          2504: @kindex -m29050
        !          2505: @cindex processor selection (29k)
        !          2506: Generate code for the Am29050.
        !          2507: 
        !          2508: @item -m29000
        !          2509: @kindex -m29050
        !          2510: Generate code for the Am29000.  This is the default.
        !          2511: 
        !          2512: @item -mkernel-registers
        !          2513: @kindex -mkernel-registers
        !          2514: @cindex kernel and user registers (29k)
        !          2515: Generate references to registers @code{gr64-gr95} instead of to
        !          2516: registers @code{gr96-gr127}.  This option can be used when compiling
        !          2517: kernel code that wants a set of global registers disjoint from that used
        !          2518: by user-mode code.
        !          2519: 
        !          2520: Note that when this option is used, register names in @samp{-f} flags
        !          2521: must use the normal, user-mode, names.
        !          2522: 
        !          2523: @item -muser-registers
        !          2524: @kindex -muser-registers
        !          2525: Use the normal set of global registers, @code{gr96-gr127}.  This is the
        !          2526: default.
        !          2527: 
        !          2528: @item -mstack-check
        !          2529: @kindex -mstack-check
        !          2530: @cindex stack checks (29k)
        !          2531: Insert a call to @code{__msp_check} after each stack adjustment.  This
        !          2532: is often used for kernel code.
        !          2533: @end table
        !          2534: 
        !          2535: @node M88K Options
        !          2536: @subsection M88K Options
        !          2537: @cindex M88k options
        !          2538: 
        !          2539: These @samp{-m} options are defined for Motorola 88k architectures:
        !          2540: 
        !          2541: @table @code
        !          2542: @item -m88000
        !          2543: @kindex -m88000
        !          2544: Generate code that works well on both the m88100 and the
        !          2545: m88110.
        !          2546: 
        !          2547: @item -m88100
        !          2548: @kindex -m88100
        !          2549: Generate code that works best for the m88100, but that also
        !          2550: runs on the m88110.
        !          2551: 
        !          2552: @item -m88110
        !          2553: @kindex -m88110
        !          2554: Generate code that works best for the m88110, and may not run
        !          2555: on the m88100.
        !          2556: 
        !          2557: @item -mbig-pic
        !          2558: @kindex -mbig-pic
        !          2559: Obsolete option to be removed from the next revision.
        !          2560: Use @samp{-fPIC}.
        !          2561: 
        !          2562: @item -midentify-revision
        !          2563: @kindex -midentify-revision
        !          2564: @kindex ident
        !          2565: @cindex identifying source, compiler (88k)
        !          2566: Include an @code{ident} directive in the assembler output recording the
        !          2567: source file name, compiler name and version, timestamp, and compilation
        !          2568: flags used.
        !          2569: 
        !          2570: @item -mno-underscores
        !          2571: @kindex -mno-underscores
        !          2572: @cindex underscores, avoiding (88k)
        !          2573: In assembler output, emit symbol names without adding an underscore
        !          2574: character at the beginning of each name.  The default is to use an
        !          2575: underscore as prefix on each name.
        !          2576: 
        !          2577: @item -mocs-debug-info
        !          2578: @itemx -mno-ocs-debug-info
        !          2579: @kindex -mocs-debug-info
        !          2580: @kindex -mno-ocs-debug-info
        !          2581: @cindex OCS (88k)
        !          2582: @cindex debugging, 88k OCS
        !          2583: Include (or omit) additional debugging information (about registers used
        !          2584: in each stack frame) as specified in the 88open Object Compatibility
        !          2585: Standard, ``OCS''.  This extra information allows debugging of code that
        !          2586: has had the frame pointer eliminated.  The default for DG/UX, SVr4, and
        !          2587: Delta 88 SVr3.2 is to include this information; other 88k configurations
        !          2588: omit this information by default.
        !          2589: 
        !          2590: @item -mocs-frame-position
        !          2591: @kindex -mocs-frame-position
        !          2592: @cindex register positions in frame (88k)
        !          2593: When emitting COFF debugging information for automatic variables and
        !          2594: parameters stored on the stack, use the offset from the canonical frame
        !          2595: address, which is the stack pointer (register 31) on entry to the
        !          2596: function.  The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
        !          2597: @samp{-mocs-frame-position}; other 88k configurations have the default
        !          2598: @samp{-mno-ocs-frame-position}.
        !          2599: 
        !          2600: @item -mno-ocs-frame-position
        !          2601: @kindex -mno-ocs-frame-position
        !          2602: @cindex register positions in frame (88k)
        !          2603: When emitting COFF debugging information for automatic variables and
        !          2604: parameters stored on the stack, use the offset from the frame pointer
        !          2605: register (register 30).  When this option is in effect, the frame
        !          2606: pointer is not eliminated when debugging information is selected by the
        !          2607: -g switch.
        !          2608: 
        !          2609: @item -moptimize-arg-area
        !          2610: @itemx -mno-optimize-arg-area
        !          2611: @kindex -moptimize-arg-area
        !          2612: @kindex -mno-optimize-arg-area
        !          2613: @cindex arguments in frame (88k)
        !          2614: Control how function arguments are stored in stack frames.
        !          2615: @samp{-moptimize-arg-area} saves space by optimizing them, but this
        !          2616: conflicts with the 88open specifications.  The opposite alternative,
        !          2617: @samp{-mno-optimize-arg-area}, agrees with 88open standards.  By default
        !          2618: GNU CC does not optimize the argument area.
        !          2619: 
        !          2620: @item -mshort-data-@var{num}
        !          2621: @kindex -mshort-data-@var{num}
        !          2622: @cindex smaller data references (88k)
        !          2623: @cindex r0-relative references (88k)
        !          2624: Generate smaller data references by making them relative to @code{r0},
        !          2625: which allows loading a value using a single instruction (rather than the
        !          2626: usual two).  You control which data references are affected by
        !          2627: specifying @var{num} with this option.  For example, if you specify
        !          2628: @samp{-mshort-data-512}, then the data references affected are those
        !          2629: involving displacements of less than 512 bytes.
        !          2630: @samp{-mshort-data-@var{num}} is not effective for @var{num} greater
        !          2631: than 64k.
        !          2632: 
        !          2633: @item -mserialize-volatile
        !          2634: @kindex -mserialize-volatile
        !          2635: @itemx -mno-serialize-volatile
        !          2636: @kindex -mno-serialize-volatile
        !          2637: @cindex sequential consistency on 88k
        !          2638: Do, or do not, generate code to guarantee sequential consistency of
        !          2639: volatile memory references.
        !          2640: 
        !          2641: GNU CC always guarantees consistency by default. 
        !          2642: 
        !          2643: The order of memory references made by the m88110 processor does not
        !          2644: always match the order of the instructions requesting those references.
        !          2645: In particular, a load instruction may execute before a preceding store
        !          2646: instruction.  Such reordering violates sequential consistency of
        !          2647: volatile memory references, when there are multiple processors.  
        !          2648: 
        !          2649: The extra code generated to guarantee consistency may affect the
        !          2650: performance of your application.  If you know that you can safely forgo
        !          2651: this guarantee, you may use the option @samp{-mno-serialize-volatile}.
        !          2652: 
        !          2653: @item -msvr4
        !          2654: @itemx -msvr3
        !          2655: @kindex -msvr4
        !          2656: @kindex -msvr3
        !          2657: @cindex assembler syntax, 88k
        !          2658: @cindex SVr4
        !          2659: Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions
        !          2660: related to System V release 4 (SVr4).  This controls the following:
        !          2661: 
        !          2662: @enumerate
        !          2663: @item 
        !          2664: Which variant of the assembler syntax to emit (which you can select
        !          2665: independently using @samp{-mversion-03.00}).  
        !          2666: @item
        !          2667: @samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
        !          2668: that is used on System V release 4.
        !          2669: @item
        !          2670: @samp{-msvr4} makes GNU CC issue additional declaration directives used in
        !          2671: SVr4.  
        !          2672: @end enumerate
        !          2673: 
        !          2674: @samp{-msvr3} is the default for all m88k configurations except
        !          2675: the SVr4 configuration.
        !          2676: 
        !          2677: @item -mversion-03.00
        !          2678: @kindex -mversion-03.00
        !          2679: In the DG/UX configuration, there are two flavors of SVr4.  This option
        !          2680: modifies @samp{-msvr4} to select whether the hybrid-COFF or real-ELF
        !          2681: flavor is used.  All other configurations ignore this option.
        !          2682: @c ??? which asm syntax better for GAS?  option there too?
        !          2683: 
        !          2684: @item -mno-check-zero-division
        !          2685: @itemx -mcheck-zero-division
        !          2686: @kindex -mno-check-zero-division
        !          2687: @kindex -mcheck-zero-division
        !          2688: @cindex zero division on 88k
        !          2689: Early models of the 88k architecture had problems with division by zero;
        !          2690: in particular, many of them didn't trap.  Use these options to avoid
        !          2691: including (or to include explicitly) additional code to detect division
        !          2692: by zero and signal an exception.  All GNU CC configurations for the 88k use
        !          2693: @samp{-mcheck-zero-division} by default.
        !          2694: 
        !          2695: @item -muse-div-instruction
        !          2696: @kindex -muse-div-instruction
        !          2697: @cindex divide instruction, 88k
        !          2698: Do not emit code to check both the divisor and dividend when doing
        !          2699: signed integer division to see if either is negative, and adjust the
        !          2700: signs so the divide is done using non-negative numbers.  Instead, rely
        !          2701: on the operating system to calculate the correct value when the
        !          2702: @code{div} instruction traps.  This results in different behavior when
        !          2703: the most negative number is divided by -1, but is useful when most or
        !          2704: all signed integer divisions are done with positive numbers.
        !          2705: 
        !          2706: @item -mtrap-large-shift
        !          2707: @itemx -mhandle-large-shift
        !          2708: @kindex -mtrap-large-shift
        !          2709: @kindex -mhandle-large-shift
        !          2710: @cindex bit shift overflow (88k)
        !          2711: @cindex large bit shifts (88k)
        !          2712: Include code to detect bit-shifts of more than 31 bits; respectively,
        !          2713: trap such shifts or emit code to handle them properly.  By default GNU CC
        !          2714: makes no special provision for large bit shifts.
        !          2715: 
        !          2716: @item -mwarn-passed-structs
        !          2717: @kindex -mwarn-passed-structs
        !          2718: @cindex structure passing (88k)
        !          2719: Warn when a function passes a struct as an argument or result.
        !          2720: Structure-passing conventions have changed during the evolution of the C
        !          2721: language, and are often the source of portability problems.  By default,
        !          2722: GNU CC issues no such warning.
        !          2723: @end table
        !          2724: 
        !          2725: @node RS/6000 and PowerPC Options
        !          2726: @subsection IBM RS/6000 and PowerPC Options
        !          2727: @cindex RS/6000 and PowerPC Options
        !          2728: @cindex IBM RS/6000 and PowerPC Options
        !          2729: 
        !          2730: These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
        !          2731: @table @code
        !          2732: @item -mpower
        !          2733: @itemx -mno-power
        !          2734: @itemx -mpower2
        !          2735: @itemx -mno-power2
        !          2736: @itemx -mpowerpc
        !          2737: @itemx -mno-powerpc
        !          2738: @itemx -mpowerpcsqr
        !          2739: @itemx -mno-powerpcsqr
        !          2740: @itemx -mpowerpc64
        !          2741: @itemx -mno-powerpc64
        !          2742: @kindex -mpower
        !          2743: @kindex -mpower2
        !          2744: @kindex -mpowerpc
        !          2745: @kindex -mpowerpcsqr
        !          2746: @kindex -mpowerpc64
        !          2747: GNU CC supports two related instruction set architectures for the
        !          2748: RS/6000 and PowerPC.  The @dfn{POWER} instruction set are those
        !          2749: instructions supported by the @samp{rios} chip set used in the original
        !          2750: RS/6000 systems and the @dfn{PowerPC} instruction set is the
        !          2751: architecture of the Motorola MPC6xx microprocessors.  The PowerPC
        !          2752: architecture defines 64-bit instructions, but they are not supported by
        !          2753: any current processors.
        !          2754: 
        !          2755: Neither architecture is a subset of the other.  However there is a
        !          2756: large common subset of instructions supported by both.  An MQ
        !          2757: register is included in processors supporting the POWER architecture.
        !          2758: 
        !          2759: You use these options to specify which instructions are available on the
        !          2760: processor you are using.  The default value of these options is
        !          2761: determined when configuring GNU CC.  Specifying the
        !          2762: @samp{-mcpu=@var{cpu_type}} overrides the specification of these
        !          2763: options.  We recommend you use that option rather than these.
        !          2764: 
        !          2765: The @samp{-mpower} option allows GNU CC to generate instructions that
        !          2766: are found only in the POWER architecture and to use the MQ register.
        !          2767: Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC
        !          2768: to generate instructions that are present in the POWER2 architecture but
        !          2769: not the original POWER architecture.
        !          2770: 
        !          2771: The @samp{-mpowerpc} option allows GNU CC to generate instructions that
        !          2772: are found only in the 32-bit subset of the PowerPC architecture.
        !          2773: Specifying @samp{-mpowerpcsqr} implies @samp{-mpowerpc} and also allows
        !          2774: GNU CC to use the floating point square root instructions in the PowerPC
        !          2775: architecture but not in its first implementation.  Likewise, specifying
        !          2776: @samp{-mpowerpc64} implies @samp{-mpowerpc} and also allows GNU CC to
        !          2777: use the 64-bit instructions in the PowerPC architecture.
        !          2778: 
        !          2779: If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC
        !          2780: will use only the instructions in the common subset of both
        !          2781: architectures and will not use the MQ register.  Specifying both
        !          2782: @samp{-mpower} and @samp{-mpowerpc} permits GNU CC to use any
        !          2783: instruction from either architecture and to allow use of the MQ
        !          2784: register; specify this for the Motorola MPC601.
        !          2785: 
        !          2786: @item -mnew-mnemonics
        !          2787: @itemx -mold-mnemonics
        !          2788: @kindex -mnew-mnemonics
        !          2789: @kindex -mold-mnemonics
        !          2790: Select which mnemonics to use in the generated assembler code.
        !          2791: @samp{-mnew-mnemonics} requests output that uses the assembler mnemonics
        !          2792: defined for the PowerPC architecture, while @samp{-mold-mnemonics}
        !          2793: requests the assembler mnemonics defined for the POWER architecture.
        !          2794: Instructions defined in only one architecture have only one mnemonic;
        !          2795: GNU CC uses that mnemonic irrespective of which of thse options is
        !          2796: specified.
        !          2797: 
        !          2798: PowerPC assemblers support both the old and new mnemonics, as will later
        !          2799: POWER assemblers.  Current POWER assemblers only support the old
        !          2800: mnemonics.  Specify @samp{-mnew-mnemonics} if you have an assembler that
        !          2801: supports them, otherwise specify @samp{-mold-mnemonics}.
        !          2802: 
        !          2803: The default value of these options depends on how GNU CC was configured.
        !          2804: Specifing @samp{-mcpu=@var{cpu_type}} sometimes overrides the value of
        !          2805: these option.  Unless you are building a cross-compiled, you should
        !          2806: normally not specify either @samp{-mnew-mnemonics} or
        !          2807: @samp{-mold-mnemonics}, but should instead accept the default.
        !          2808: 
        !          2809: @item -mcpu=@var{cpu_type}
        !          2810: Set architecture type, register usage, choice of mnemonics, and
        !          2811: instruction scheduling parameters for machine type @var{cpu_type}.  By
        !          2812: default, @var{cpu_type} is the target system defined when GNU CC was
        !          2813: configured.  Supported values for @var{cpu_type} are @samp{rios1},
        !          2814: @samp{rios2}, @samp{rsc1}, @samp{601}, @samp{603}, @samp{604},
        !          2815: @samp{620} and @samp{all}.@refill
        !          2816: 
        !          2817: Specifying @samp{-mcpu=rios1} or @samp{-mcpu=rios2} enables the
        !          2818: @samp{-mpower} option and disables the @samp{-mpowerpc} option,
        !          2819: @samp{-mcpu=601} enables both the @samp{-mpower} and @samp{-mpowerpc}
        !          2820: options, @samp{-mcpu=603} and @samp{-mcpu=604} enable the
        !          2821: @samp{-mpowerpc} option and disables the @samp{-mpower} option, and
        !          2822: @samp{-mcpu=620} enables both the @samp{-mpowerpc} and
        !          2823: @samp{-mpowerpc64} options and also disables the @samp{-mpower}
        !          2824: option.@refill
        !          2825: 
        !          2826: To generate code that will operate on all members of the RS/6000 and
        !          2827: PowerPC family, specify @samp{-mcpu=all}.  In that case, GNU CC will
        !          2828: only use instructions in the common subset and will not use the MQ
        !          2829: register.  The instruction scheduling parameters and choice of mnemonics
        !          2830: are not affected.
        !          2831: 
        !          2832: Specifying @samp{-mcpu=601}, @samp{-mcpu=603}, @samp{-mcpu=604}, or
        !          2833: @samp{-mcpu=620} also enables the @samp{new-mnemonics} option.
        !          2834: 
        !          2835: @item -mnormal-toc
        !          2836: @itemx -mno-fp-in-toc
        !          2837: @itemx -mminimal-toc
        !          2838: Modify generation of the TOC (Table Of Contents), which is created for
        !          2839: every executable file.  The @samp{-mnormal-toc} option is selected by
        !          2840: default.  In that case, GNU CC will allocate at least one TOC entry for
        !          2841: each unique non-automatic variable reference in your program.  GNU CC
        !          2842: will also place floating-point constants in the TOC.  However, only 16K
        !          2843: entries are available in the TOC.
        !          2844: 
        !          2845: If you receive a linker error message that says you have overflowed the
        !          2846: available TOC space, recompile your files with either the
        !          2847: @samp{-mno-fp-in-toc} or @samp{-mminimal-toc} options.
        !          2848: @samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point
        !          2849: constants in the TOC.  @samp{-mminimal-toc} causes GNU CC to make only
        !          2850: one TOC entry for every file.  Using the @samp{-minimal-toc} option
        !          2851: produces slightly slower and larger code than the @samp{-mnormal-toc} or
        !          2852: @samp{-mno-fp-in-toc} options.  If you use floating-point, try the
        !          2853: @samp{-mno-fp-in-toc} option before you specify
        !          2854: @samp{-mminimal-toc}.@refill
        !          2855: @end table
        !          2856: @node RT Options
        !          2857: @subsection IBM RT Options
        !          2858: @cindex RT options
        !          2859: @cindex IBM RT options
        !          2860: 
        !          2861: These @samp{-m} options are defined for the IBM RT PC:
        !          2862: 
        !          2863: @table @code
        !          2864: @item -min-line-mul
        !          2865: Use an in-line code sequence for integer multiplies.  This is the
        !          2866: default.
        !          2867: 
        !          2868: @item -mcall-lib-mul
        !          2869: Call @code{lmul$$} for integer multiples.
        !          2870: 
        !          2871: @item -mfull-fp-blocks
        !          2872: Generate full-size floating point data blocks, including the minimum
        !          2873: amount of scratch space recommended by IBM.  This is the default.
        !          2874: 
        !          2875: @item -mminimum-fp-blocks
        !          2876: Do not include extra scratch space in floating point data blocks.  This
        !          2877: results in smaller code, but slower execution, since scratch space must
        !          2878: be allocated dynamically.
        !          2879: 
        !          2880: @cindex @file{varargs.h} and RT PC
        !          2881: @cindex @file{stdarg.h} and RT PC
        !          2882: @item -mfp-arg-in-fpregs
        !          2883: Use a calling sequence incompatible with the IBM calling convention in
        !          2884: which floating point arguments are passed in floating point registers.
        !          2885: Note that @code{varargs.h} and @code{stdargs.h} will not work with
        !          2886: floating point operands if this option is specified.
        !          2887: 
        !          2888: @item -mfp-arg-in-gregs
        !          2889: Use the normal calling convention for floating point arguments.  This is
        !          2890: the default.
        !          2891: 
        !          2892: @item -mhc-struct-return
        !          2893: Return structures of more than one word in memory, rather than in a
        !          2894: register.  This provides compatibility with the MetaWare HighC (hc)
        !          2895: compiler.  Use the option @samp{-fpcc-struct-return} for compatibility
        !          2896: with the Portable C Compiler (pcc).
        !          2897: 
        !          2898: @item -mnohc-struct-return
        !          2899: Return some structures of more than one word in registers, when
        !          2900: convenient.  This is the default.  For compatibility with the
        !          2901: IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the
        !          2902: option @samp{-mhc-struct-return}.
        !          2903: @end table
        !          2904: 
        !          2905: @node MIPS Options
        !          2906: @subsection MIPS Options
        !          2907: @cindex MIPS options
        !          2908: 
        !          2909: These @samp{-m} options are defined for the MIPS family of computers:
        !          2910: 
        !          2911: @table @code
        !          2912: @item -mcpu=@var{cpu type}
        !          2913: Assume the defaults for the machine type @var{cpu type} when
        !          2914: scheduling instructions.  The default @var{cpu type} is
        !          2915: @samp{default}, which picks the longest cycles times for any of the
        !          2916: machines, in order that the code run at reasonable rates on all MIPS
        !          2917: cpu's.  Other choices for @var{cpu type} are @samp{r2000},
        !          2918: @samp{r3000}, @samp{r4000}, and @samp{r6000}.  While picking a
        !          2919: specific @var{cpu type} will schedule things appropriately for that
        !          2920: particular chip, the compiler will not generate any code that does not
        !          2921: meet level 1 of the MIPS ISA (instruction set architecture) without
        !          2922: the @samp{-mips2} or @samp{-mips3} switches being used.
        !          2923: 
        !          2924: @item -mips2
        !          2925: Issue instructions from level 2 of the MIPS ISA (branch likely, square
        !          2926: root instructions).  The @samp{-mcpu=r4000} or @samp{-mcpu=r6000}
        !          2927: switch must be used in conjunction with @samp{-mips2}.
        !          2928: 
        !          2929: @item -mips3
        !          2930: Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
        !          2931: You must use the @samp{-mcpu=r4000} switch along with @samp{-mips3}.
        !          2932: 
        !          2933: @item -mint64
        !          2934: @itemx -mlong64
        !          2935: @itemx -mlonglong128
        !          2936: These options don't work at present.
        !          2937: 
        !          2938: @item -mmips-as
        !          2939: Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
        !          2940: add normal debug information.  This is the default for all
        !          2941: platforms except for the OSF/1 reference platform, using the OSF/rose
        !          2942: object format.  If the either of the @samp{-gstabs} or @samp{-gstabs+}
        !          2943: switches are used, the @file{mips-tfile} program will encapsulate the
        !          2944: stabs within MIPS ECOFF.
        !          2945: 
        !          2946: @item -mgas
        !          2947: Generate code for the GNU assembler.  This is the default on the OSF/1
        !          2948: reference platform, using the OSF/rose object format.
        !          2949: 
        !          2950: @item -mrnames
        !          2951: @itemx -mno-rnames
        !          2952: The @samp{-mrnames} switch says to output code using the MIPS software
        !          2953: names for the registers, instead of the hardware names (ie, @var{a0}
        !          2954: instead of @var{$4}).  The GNU assembler does not support the
        !          2955: @samp{-mrnames} switch, and the MIPS assembler will be instructed to
        !          2956: run the MIPS C preprocessor over the source file.  The
        !          2957: @samp{-mno-rnames} switch is default.
        !          2958: 
        !          2959: @item -mgpopt
        !          2960: @itemx -mno-gpopt
        !          2961: The @samp{-mgpopt} switch says to write all of the data declarations
        !          2962: before the instructions in the text section, this allows the MIPS
        !          2963: assembler to generate one word memory references instead of using two
        !          2964: words for short global or static data items.  This is on by default if
        !          2965: optimization is selected.
        !          2966: 
        !          2967: @item -mstats
        !          2968: @itemx -mno-stats
        !          2969: For each non-inline function processed, the @samp{-mstats} switch
        !          2970: causes the compiler to emit one line to the standard error file to
        !          2971: print statistics about the program (number of registers saved, stack
        !          2972: size, etc.).
        !          2973: 
        !          2974: @item -mmemcpy
        !          2975: @itemx -mno-memcpy
        !          2976: The @samp{-mmemcpy} switch makes all block moves call the appropriate
        !          2977: string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
        !          2978: generating inline code.
        !          2979: 
        !          2980: @item -mmips-tfile
        !          2981: @itemx -mno-mips-tfile
        !          2982: The @samp{-mno-mips-tfile} switch causes the compiler not
        !          2983: postprocess the object file with the @file{mips-tfile} program,
        !          2984: after the MIPS assembler has generated it to add debug support.  If
        !          2985: @file{mips-tfile} is not run, then no local variables will be
        !          2986: available to the debugger.  In addition, @file{stage2} and
        !          2987: @file{stage3} objects will have the temporary file names passed to the
        !          2988: assembler embedded in the object file, which means the objects will
        !          2989: not compare the same.  The @samp{-mno-mips-tfile} switch should only
        !          2990: be used when there are bugs in the @file{mips-tfile} program that
        !          2991: prevents compilation.
        !          2992: 
        !          2993: @item -msoft-float
        !          2994: Generate output containing library calls for floating point.
        !          2995: @strong{Warning:} the requisite libraries are not part of GNU CC.
        !          2996: Normally the facilities of the machine's usual C compiler are used, but
        !          2997: this can't be done directly in cross-compilation.  You must make your
        !          2998: own arrangements to provide suitable library functions for
        !          2999: cross-compilation.
        !          3000: 
        !          3001: @item -mhard-float
        !          3002: Generate output containing floating point instructions.  This is the
        !          3003: default if you use the unmodified sources.
        !          3004: 
        !          3005: @item -mfp64
        !          3006: Assume that the @var{FR} bit in the status word is on, and that there
        !          3007: are 32 64-bit floating point registers, instead of 32 32-bit floating
        !          3008: point registers.  You must also specify the @samp{-mcpu=r4000} and
        !          3009: @samp{-mips3} switches.
        !          3010: 
        !          3011: @item -mfp32
        !          3012: Assume that there are 32 32-bit floating point registers.  This is the
        !          3013: default.
        !          3014: 
        !          3015: @item -mabicalls
        !          3016: @itemx -mno-abicalls
        !          3017: Emit (or do not emit) the pseudo operations @samp{.abicalls},
        !          3018: @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
        !          3019: position independent code.
        !          3020: 
        !          3021: @item -mlong-calls
        !          3022: @itemx -mlong-calls
        !          3023: Do all calls with the @samp{JALR} instruction, which requires
        !          3024: loading up a function's address into a register before the call.
        !          3025: You need to use this switch, if you call outside of the current
        !          3026: 512 megabyte segment to functions that are not through pointers.
        !          3027: 
        !          3028: @item -mhalf-pic
        !          3029: @itemx -mno-half-pic
        !          3030: Put pointers to extern references into the data section and load them
        !          3031: up, rather than put the references in the text section.
        !          3032: 
        !          3033: @item -G @var{num}
        !          3034: @cindex smaller data references (MIPS)
        !          3035: @cindex gp-relative references (MIPS)
        !          3036: Put global and static items less than or equal to @var{num} bytes into
        !          3037: the small data or bss sections instead of the normal data or bss
        !          3038: section.  This allows the assembler to emit one word memory reference
        !          3039: instructions based on the global pointer (@var{gp} or @var{$28}),
        !          3040: instead of the normal two words used.  By default, @var{num} is 8 when
        !          3041: the MIPS assembler is used, and 0 when the GNU assembler is used.  The
        !          3042: @samp{-G @var{num}} switch is also passed to the assembler and linker.
        !          3043: All modules should be compiled with the same @samp{-G @var{num}}
        !          3044: value.
        !          3045: 
        !          3046: @item -nocpp
        !          3047: Tell the MIPS assembler to not run it's preprocessor over user
        !          3048: assembler files (with a @samp{.s} suffix) when assembling them.
        !          3049: @end table
        !          3050: 
        !          3051: @ifset INTERNALS
        !          3052: These options are defined by the macro
        !          3053: @code{TARGET_SWITCHES} in the machine description.  The default for the
        !          3054: options is also defined by that macro, which enables you to change the
        !          3055: defaults.
        !          3056: @end ifset
        !          3057: 
        !          3058: @node i386 Options
        !          3059: @subsection Intel 386 Options
        !          3060: @cindex i386 Options
        !          3061: @cindex Intel 386 Options
        !          3062: 
        !          3063: These @samp{-m} options are defined for the i386 family of computers:
        !          3064: 
        !          3065: @table @code
        !          3066: @item -m486
        !          3067: @itemx -mno-486
        !          3068: Control whether or not code is optimized for a 486 instead of an
        !          3069: 386.  Code generated for an 486 will run on a 386 and vice versa.
        !          3070: 
        !          3071: @item -msoft-float
        !          3072: Generate output containing library calls for floating point.
        !          3073: @strong{Warning:} the requisite libraries are not part of GNU CC.
        !          3074: Normally the facilities of the machine's usual C compiler are used, but
        !          3075: this can't be done directly in cross-compilation.  You must make your
        !          3076: own arrangements to provide suitable library functions for
        !          3077: cross-compilation.
        !          3078: 
        !          3079: On machines where a function returns floating point results in the 80387
        !          3080: register stack, some floating point opcodes may be emitted even if
        !          3081: @samp{-msoft-float} is used.
        !          3082: 
        !          3083: @item -mno-fp-ret-in-387
        !          3084: Do not use the FPU registers for return values of functions.
        !          3085: 
        !          3086: The usual calling convention has functions return values of types
        !          3087: @code{float} and @code{double} in an FPU register, even if there
        !          3088: is no FPU.  The idea is that the operating system should emulate
        !          3089: an FPU.
        !          3090: 
        !          3091: The option @samp{-mno-fp-ret-in-387} causes such values to be returned
        !          3092: in ordinary CPU registers instead.
        !          3093: @c FIXME!! What about these options listed in @node Option Summary ??
        !          3094: @c -msvr3-shlib -mieee-fp
        !          3095: @end table
        !          3096: 
        !          3097: @node HPPA Options
        !          3098: @subsection HPPA Options
        !          3099: @cindex HPPA Options
        !          3100: 
        !          3101: These @samp{-m} options are defined for the HPPA family of computers:
        !          3102: 
        !          3103: @table @code
        !          3104: @item -mpa-risc-1-0
        !          3105: Generate code for a PA 1.0 processor.
        !          3106: 
        !          3107: @item -mpa-risc-1-1
        !          3108: Generate code for a PA 1.1 processor.
        !          3109: 
        !          3110: @item -mlong-calls
        !          3111: Generate code which allows calls to functions greater than 256k away from
        !          3112: the caller when the caller and callee are in the same source file.  Do
        !          3113: not turn this option on unless code refuses to link with "branch out of
        !          3114: range errors" from the linker.
        !          3115: 
        !          3116: @item -mdisable-fpregs
        !          3117: Prevent floating point registers from being used in any manner.  This is
        !          3118: necessary for compiling kernels which perform lazy context switching of
        !          3119: floating point registers.  If you use this option and attempt to perform
        !          3120: floating point operations, the compiler will abort.
        !          3121: 
        !          3122: @item -mdisable-indexing
        !          3123: Prevent the compiler from using indexing address modes.  This avoids some
        !          3124: rather obscure problems when compiling MIG generated code under MACH.
        !          3125: 
        !          3126: @item -mtrailing-colon
        !          3127: Add a colon to the end of label definitions (for ELF assemblers).
        !          3128: @end table
        !          3129: 
        !          3130: @node Intel 960 Options
        !          3131: @subsection Intel 960 Options
        !          3132: 
        !          3133: These @samp{-m} options are defined for the Intel 960 implementations:
        !          3134: 
        !          3135: @table @code
        !          3136: @item -m@var{cpu type}
        !          3137: Assume the defaults for the machine type @var{cpu type} for some of
        !          3138: the other options, including instruction scheduling, floating point
        !          3139: support, and addressing modes.  The choices for @var{cpu type} are
        !          3140: @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
        !          3141: @samp{sa}, and @samp{sb}.
        !          3142: The default is
        !          3143: @samp{kb}.
        !          3144: 
        !          3145: @item -mnumerics
        !          3146: @itemx -msoft-float
        !          3147: The @samp{-mnumerics} option indicates that the processor does support
        !          3148: floating-point instructions.  The @samp{-msoft-float} option indicates
        !          3149: that floating-point support should not be assumed.
        !          3150: 
        !          3151: @item -mleaf-procedures
        !          3152: @itemx -mno-leaf-procedures
        !          3153: Do (or do not) attempt to alter leaf procedures to be callable with the
        !          3154: @code{bal} instruction as well as @code{call}.  This will result in more
        !          3155: efficient code for explicit calls when the @code{bal} instruction can be
        !          3156: substituted by the assembler or linker, but less efficient code in other
        !          3157: cases, such as calls via function pointers, or using a linker that doesn't
        !          3158: support this optimization.
        !          3159: 
        !          3160: @item -mtail-call
        !          3161: @itemx -mno-tail-call
        !          3162: Do (or do not) make additional attempts (beyond those of the
        !          3163: machine-independent portions of the compiler) to optimize tail-recursive
        !          3164: calls into branches.  You may not want to do this because the detection of
        !          3165: cases where this is not valid is not totally complete.  The default is
        !          3166: @samp{-mno-tail-call}.
        !          3167: 
        !          3168: @item -mcomplex-addr
        !          3169: @itemx -mno-complex-addr
        !          3170: Assume (or do not assume) that the use of a complex addressing mode is a
        !          3171: win on this implementation of the i960.  Complex addressing modes may not
        !          3172: be worthwhile on the K-series, but they definitely are on the C-series.
        !          3173: The default is currently @samp{-mcomplex-addr} for all processors except
        !          3174: the CB and CC.
        !          3175: 
        !          3176: @item -mcode-align
        !          3177: @itemx -mno-code-align
        !          3178: Align code to 8-byte boundaries for faster fetching (or don't bother).
        !          3179: Currently turned on by default for C-series implementations only.
        !          3180: 
        !          3181: @ignore
        !          3182: @item -mclean-linkage
        !          3183: @itemx -mno-clean-linkage
        !          3184: These options are not fully implemented.
        !          3185: @end ignore
        !          3186: 
        !          3187: @item -mic-compat
        !          3188: @itemx -mic2.0-compat
        !          3189: @itemx -mic3.0-compat
        !          3190: Enable compatibility with iC960 v2.0 or v3.0.
        !          3191: 
        !          3192: @item -masm-compat
        !          3193: @itemx -mintel-asm
        !          3194: Enable compatibility with the iC960 assembler.
        !          3195: 
        !          3196: @item -mstrict-align
        !          3197: @itemx -mno-strict-align
        !          3198: Do not permit (do permit) unaligned accesses.
        !          3199: 
        !          3200: @item -mold-align
        !          3201: Enable structure-alignment compatibility with Intel's gcc release version
        !          3202: 1.3 (based on gcc 1.37).  Currently this is buggy in that @samp{#pragma
        !          3203: align 1} is always assumed as well, and cannot be turned off.
        !          3204: @end table
        !          3205: 
        !          3206: @node DEC Alpha Options
        !          3207: @subsection DEC Alpha Options
        !          3208: 
        !          3209: These @samp{-m} options are defined for the DEC Alpha implementations:
        !          3210: 
        !          3211: @table @code
        !          3212: @item -mno-soft-float
        !          3213: @itemx -msoft-float
        !          3214: Use (do not use) the hardware floating-point instructions for
        !          3215: floating-point operations.  When @code{-msoft-float} is specified,
        !          3216: functions in @file{libgcc1.c} will be used to perform floating-point
        !          3217: operations.  Unless they are replaced by routines that emulate the
        !          3218: floating-point operations, or compiled in such a way as to call such
        !          3219: emulations routines, these routines will issue floating-point
        !          3220: operations.   If you are compiling for an Alpha without floating-point
        !          3221: operations, you must ensure that the library is built so as not to call
        !          3222: them.
        !          3223: 
        !          3224: Note that Alpha implementations without floating-point operations are
        !          3225: required to have floating-point registers.
        !          3226: 
        !          3227: @item -mfp-reg
        !          3228: @itemx -mno-fp-regs
        !          3229: Generate code that uses (does not use) the floating-point register set.
        !          3230: @code{-mno-fp-regs} implies @code{-msoft-float}.  If the floating-point
        !          3231: register set is not used, floating point operands are passed in integer
        !          3232: registers as if they were integers and floating-point results are passed
        !          3233: in $0 instead of $f0.  This is a non-standard calling sequence, so any
        !          3234: function with a floating-point argument or return value called by code
        !          3235: compiled with @code{-mno-fp-regs} must also be compiled with that
        !          3236: option.
        !          3237: 
        !          3238: A typical use of this option is building a kernel that does not use,
        !          3239: and hence need not save and restore, any floating-point registers.
        !          3240: @end table
        !          3241: 
        !          3242: @node Clipper Options
        !          3243: @subsection Clipper Options
        !          3244: 
        !          3245: These @samp{-m} options are defined for the Clipper implementations:
        !          3246: 
        !          3247: @table @code
        !          3248: @item -mc300
        !          3249: Produce code for a C300 Clipper processor. This is the default.
        !          3250: 
        !          3251: @itemx -mc400
        !          3252: Produce code for a C400 Clipper processor i.e. use floting point
        !          3253: registers f8..f15.
        !          3254: @end table
        !          3255: 
        !          3256: @node System V Options
        !          3257: @subsection Options for System V
        !          3258: 
        !          3259: These additional options are available on System V Release 4 for
        !          3260: compatibility with other compilers on those systems:
        !          3261: 
        !          3262: @table @code
        !          3263: @ignore
        !          3264: This should say *what the option does* and only then say
        !          3265: "For compatibility only..."
        !          3266: @item -G
        !          3267: On SVr4 systems, @code{gcc} accepts the option @samp{-G} (and passes
        !          3268: it to the system linker), for compatibility with other compilers.
        !          3269: However, we suggest you use @samp{-symbolic} or @samp{-shared} as
        !          3270: appropriate, instead of supplying linker options on the @code{gcc}
        !          3271: command line.
        !          3272: @end ignore
        !          3273: 
        !          3274: @item -Qy
        !          3275: Identify the versions of each tool used by the compiler, in a
        !          3276: @code{.ident} assembler directive in the output.
        !          3277: 
        !          3278: @item -Qn
        !          3279: Refrain from adding @code{.ident} directives to the output file (this is
        !          3280: the default).
        !          3281: 
        !          3282: @item -YP,@var{dirs}
        !          3283: Search the directories @var{dirs}, and no others, for libraries
        !          3284: specified with @samp{-l}.
        !          3285: 
        !          3286: @item -Ym,@var{dir}
        !          3287: Look in the directory @var{dir} to find the M4 preprocessor.
        !          3288: The assembler uses this option.
        !          3289: @c This is supposed to go with a -Yd for predefined M4 macro files, but 
        !          3290: @c the generic assembler that comes with Solaris takes just -Ym.
        !          3291: @end table
        !          3292: 
        !          3293: @node Code Gen Options
        !          3294: @section Options for Code Generation Conventions
        !          3295: @cindex code generation conventions
        !          3296: @cindex options, code generation 
        !          3297: @cindex run-time options
        !          3298: 
        !          3299: These machine-independent options control the interface conventions
        !          3300: used in code generation.
        !          3301: 
        !          3302: Most of them have both positive and negative forms; the negative form
        !          3303: of @samp{-ffoo} would be @samp{-fno-foo}.  In the table below, only
        !          3304: one of the forms is listed---the one which is not the default.  You
        !          3305: can figure out the other form by either removing @samp{no-} or adding
        !          3306: it.
        !          3307: 
        !          3308: @table @code
        !          3309: @item -fpcc-struct-return
        !          3310: Return ``short'' @code{struct} and @code{union} values in memory like
        !          3311: longer ones, rather than in registers.  This convention is less
        !          3312: efficient, but it has the advantage of allowing intercallability between
        !          3313: GNU CC-compiled files and files compiled with other compilers.
        !          3314: 
        !          3315: The precise convention for returning structures in memory depends
        !          3316: on the target configuration macros.
        !          3317: 
        !          3318: Short structures and unions are those whose size and alignment match
        !          3319: that of some integer type.
        !          3320: 
        !          3321: @item -freg-struct-return
        !          3322: Use the convention that @code{struct} and @code{union} values are
        !          3323: returned in registers when possible.  This is more efficient for small
        !          3324: structures than @samp{-fpcc-struct-return}.
        !          3325: 
        !          3326: If you specify neither @samp{-fpcc-struct-return} nor its contrary
        !          3327: @samp{-freg-struct-return}, GNU CC defaults to whichever convention is
        !          3328: standard for the target.  If there is no standard convention, GNU CC
        !          3329: defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC
        !          3330: is the principal compiler.  In those cases, we can choose the standard,
        !          3331: and we chose the more efficient register return alternative.
        !          3332: 
        !          3333: @item -fshort-enums
        !          3334: Allocate to an @code{enum} type only as many bytes as it needs for the
        !          3335: declared range of possible values.  Specifically, the @code{enum} type
        !          3336: will be equivalent to the smallest integer type which has enough room.
        !          3337: 
        !          3338: @item -fshort-double
        !          3339: Use the same size for @code{double} as for @code{float}.
        !          3340: 
        !          3341: @item -fshared-data
        !          3342: Requests that the data and non-@code{const} variables of this
        !          3343: compilation be shared data rather than private data.  The distinction
        !          3344: makes sense only on certain operating systems, where shared data is
        !          3345: shared between processes running the same program, while private data
        !          3346: exists in one copy per process.
        !          3347: 
        !          3348: @item -fno-common
        !          3349: Allocate even uninitialized global variables in the bss section of the
        !          3350: object file, rather than generating them as common blocks.  This has the
        !          3351: effect that if the same variable is declared (without @code{extern}) in
        !          3352: two different compilations, you will get an error when you link them.
        !          3353: The only reason this might be useful is if you wish to verify that the
        !          3354: program will work on other systems which always work this way.
        !          3355: 
        !          3356: @item -fno-ident
        !          3357: Ignore the @samp{#ident} directive.
        !          3358: 
        !          3359: @item -fno-gnu-linker
        !          3360: Do not output global initializations (such as C++ constructors and
        !          3361: destructors) in the form used by the GNU linker (on systems where the GNU
        !          3362: linker is the standard method of handling them).  Use this option when
        !          3363: you want to use a non-GNU linker, which also requires using the
        !          3364: @code{collect2} program to make sure the system linker includes
        !          3365: constructors and destructors.  (@code{collect2} is included in the GNU CC
        !          3366: distribution.)  For systems which @emph{must} use @code{collect2}, the
        !          3367: compiler driver @code{gcc} is configured to do this automatically.
        !          3368: 
        !          3369: @item -finhibit-size-directive
        !          3370: Don't output a @code{.size} assembler directive, or anything else that
        !          3371: would cause trouble if the function is split in the middle, and the 
        !          3372: two halves are placed at locations far apart in memory.  This option is
        !          3373: used when compiling @file{crtstuff.c}; you should not need to use it
        !          3374: for anything else.
        !          3375: 
        !          3376: @item -fverbose-asm
        !          3377: Put extra commentary information in the generated assembly code to
        !          3378: make it more readable.  This option is generally only of use to those
        !          3379: who actually need to read the generated assembly code (perhaps while
        !          3380: debugging the compiler itself).
        !          3381: 
        !          3382: @item -fvolatile
        !          3383: Consider all memory references through pointers to be volatile.
        !          3384: 
        !          3385: @item -fvolatile-global
        !          3386: Consider all memory references to extern and global data items to
        !          3387: be volatile.
        !          3388: 
        !          3389: @item -fpic
        !          3390: @cindex global offset table
        !          3391: @cindex PIC
        !          3392: Generate position-independent code (PIC) suitable for use in a shared
        !          3393: library, if supported for the target machine.  Such code accesses all
        !          3394: constant addresses through a global offset table (GOT).  If the GOT size
        !          3395: for the linked executable exceeds a machine-specific maximum size, you
        !          3396: get an error message from the linker indicating that @samp{-fpic} does
        !          3397: not work; in that case, recompile with @samp{-fPIC} instead.  (These
        !          3398: maximums are 16k on the m88k, 8k on the Sparc, and 32k on the m68k and
        !          3399: RS/6000.  The 386 has no such limit.)
        !          3400: 
        !          3401: Position-independent code requires special support, and therefore works
        !          3402: only on certain machines.  For the 386, GNU CC supports PIC for System V
        !          3403: but not for the Sun 386i.  Code generated for the IBM RS/6000 is always
        !          3404: position-independent.
        !          3405: 
        !          3406: The GNU assembler does not fully support PIC.  Currently, you must use
        !          3407: some other assembler in order for PIC to work.  We would welcome
        !          3408: volunteers to upgrade GAS to handle this; the first part of the job is
        !          3409: to figure out what the assembler must do differently.
        !          3410: 
        !          3411: @item -fPIC
        !          3412: If supported for the target machine, emit position-independent code,
        !          3413: suitable for dynamic linking and avoiding any limit on the size of the
        !          3414: global offset table.  This option makes a difference on the m68k, m88k
        !          3415: and the Sparc.
        !          3416: 
        !          3417: Position-independent code requires special support, and therefore works
        !          3418: only on certain machines.
        !          3419: 
        !          3420: @item -ffixed-@var{reg}
        !          3421: Treat the register named @var{reg} as a fixed register; generated code
        !          3422: should never refer to it (except perhaps as a stack pointer, frame
        !          3423: pointer or in some other fixed role).
        !          3424: 
        !          3425: @var{reg} must be the name of a register.  The register names accepted
        !          3426: are machine-specific and are defined in the @code{REGISTER_NAMES}
        !          3427: macro in the machine description macro file.
        !          3428: 
        !          3429: This flag does not have a negative form, because it specifies a
        !          3430: three-way choice.
        !          3431: 
        !          3432: @item -fcall-used-@var{reg}
        !          3433: Treat the register named @var{reg} as an allocatable register that is
        !          3434: clobbered by function calls.  It may be allocated for temporaries or
        !          3435: variables that do not live across a call.  Functions compiled this way
        !          3436: will not save and restore the register @var{reg}.
        !          3437: 
        !          3438: Use of this flag for a register that has a fixed pervasive role in the
        !          3439: machine's execution model, such as the stack pointer or frame pointer,
        !          3440: will produce disastrous results.
        !          3441: 
        !          3442: This flag does not have a negative form, because it specifies a
        !          3443: three-way choice.
        !          3444: 
        !          3445: @item -fcall-saved-@var{reg}
        !          3446: Treat the register named @var{reg} as an allocatable register saved by
        !          3447: functions.  It may be allocated even for temporaries or variables that
        !          3448: live across a call.  Functions compiled this way will save and restore
        !          3449: the register @var{reg} if they use it.
        !          3450: 
        !          3451: Use of this flag for a register that has a fixed pervasive role in the
        !          3452: machine's execution model, such as the stack pointer or frame pointer,
        !          3453: will produce disastrous results.
        !          3454: 
        !          3455: A different sort of disaster will result from the use of this flag for
        !          3456: a register in which function values may be returned.
        !          3457: 
        !          3458: This flag does not have a negative form, because it specifies a
        !          3459: three-way choice.
        !          3460: 
        !          3461: @item +e0
        !          3462: @itemx +e1
        !          3463: Control whether virtual function definitions in classes are used to
        !          3464: generate code, or only to define interfaces for their callers.  (C++
        !          3465: only).
        !          3466: 
        !          3467: These options are provided for compatibility with @code{cfront} 1.x
        !          3468: usage; the recommended alternative GNU C++ usage is in flux.  @xref{C++
        !          3469: Interface,,Declarations and Definitions in One Header}.
        !          3470: 
        !          3471: With @samp{+e0}, virtual function definitions in classes are declared
        !          3472: @code{extern}; the declaration is used only as an interface
        !          3473: specification, not to generate code for the virtual functions (in this
        !          3474: compilation).
        !          3475: 
        !          3476: With @samp{+e1}, G++ actually generates the code implementing virtual
        !          3477: functions defined in the code, and makes them publicly visible.
        !          3478: @end table
        !          3479: 
        !          3480: @node Environment Variables
        !          3481: @section Environment Variables Affecting GNU CC
        !          3482: @cindex environment variables
        !          3483: 
        !          3484: This section describes several environment variables that affect how GNU
        !          3485: CC operates.  They work by specifying directories or prefixes to use
        !          3486: when searching for various kinds of files.
        !          3487: 
        !          3488: @ifclear INTERNALS
        !          3489: Note that you can also specify places to search using options such as
        !          3490: @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}).  These
        !          3491: take precedence over places specified using environment variables, which
        !          3492: in turn take precedence over those specified by the configuration of GNU
        !          3493: CC. 
        !          3494: @end ifclear
        !          3495: @ifset INTERNALS
        !          3496: Note that you can also specify places to search using options such as
        !          3497: @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}).  These
        !          3498: take precedence over places specified using environment variables, which
        !          3499: in turn take precedence over those specified by the configuration of GNU
        !          3500: CC.  @xref{Driver}.
        !          3501: @end ifset
        !          3502: 
        !          3503: @table @code
        !          3504: @item TMPDIR
        !          3505: @findex TMPDIR
        !          3506: If @code{TMPDIR} is set, it specifies the directory to use for temporary
        !          3507: files.  GNU CC uses temporary files to hold the output of one stage of
        !          3508: compilation which is to be used as input to the next stage: for example,
        !          3509: the output of the preprocessor, which is the input to the compiler
        !          3510: proper.
        !          3511: 
        !          3512: @item GCC_EXEC_PREFIX
        !          3513: @findex GCC_EXEC_PREFIX
        !          3514: If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
        !          3515: names of the subprograms executed by the compiler.  No slash is added
        !          3516: when this prefix is combined with the name of a subprogram, but you can
        !          3517: specify a prefix that ends with a slash if you wish.
        !          3518: 
        !          3519: If GNU CC cannot find the subprogram using the specified prefix, it
        !          3520: tries looking in the usual places for the subprogram.
        !          3521: 
        !          3522: Other prefixes specified with @samp{-B} take precedence over this prefix.
        !          3523: 
        !          3524: This prefix is also used for finding files such as @file{crt0.o} that are
        !          3525: used for linking.
        !          3526: 
        !          3527: In addition, the prefix is used in an unusual way in finding the
        !          3528: directories to search for header files.  For each of the standard
        !          3529: directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
        !          3530: (more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries
        !          3531: replacing that beginning with the specified prefix to produce an
        !          3532: alternate directory name.  Thus, with @samp{-Bfoo/}, GNU CC will search
        !          3533: @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
        !          3534: These alternate directories are searched first; the standard directories
        !          3535: come next.
        !          3536: 
        !          3537: @item COMPILER_PATH
        !          3538: @findex COMPILER_PATH
        !          3539: The value of @code{COMPILER_PATH} is a colon-separated list of
        !          3540: directories, much like @code{PATH}.  GNU CC tries the directories thus
        !          3541: specified when searching for subprograms, if it can't find the
        !          3542: subprograms using @code{GCC_EXEC_PREFIX}.
        !          3543: 
        !          3544: @item LIBRARY_PATH
        !          3545: @findex LIBRARY_PATH
        !          3546: The value of @code{LIBRARY_PATH} is a colon-separated list of
        !          3547: directories, much like @code{PATH}.  GNU CC tries the directories thus
        !          3548: specified when searching for special linker files, if it can't find them
        !          3549: using @code{GCC_EXEC_PREFIX}.  Linking using GNU CC also uses these
        !          3550: directories when searching for ordinary libraries for the @samp{-l}
        !          3551: option (but directories specified with @samp{-L} come first).
        !          3552: 
        !          3553: @item C_INCLUDE_PATH
        !          3554: @itemx CPLUS_INCLUDE_PATH
        !          3555: @itemx OBJC_INCLUDE_PATH
        !          3556: @findex C_INCLUDE_PATH
        !          3557: @findex CPLUS_INCLUDE_PATH
        !          3558: @findex OBJC_INCLUDE_PATH
        !          3559: @c @itemx OBJCPLUS_INCLUDE_PATH
        !          3560: These environment variables pertain to particular languages.  Each
        !          3561: variable's value is a colon-separated list of directories, much like
        !          3562: @code{PATH}.  When GNU CC searches for header files, it tries the
        !          3563: directories listed in the variable for the language you are using, after
        !          3564: the directories specified with @samp{-I} but before the standard header
        !          3565: file directories.
        !          3566: 
        !          3567: @item DEPENDENCIES_OUTPUT
        !          3568: @findex DEPENDENCIES_OUTPUT
        !          3569: @cindex dependencies for make as output 
        !          3570: If this variable is set, its value specifies how to output dependencies
        !          3571: for Make based on the header files processed by the compiler.  This
        !          3572: output looks much like the output from the @samp{-M} option
        !          3573: (@pxref{Preprocessor Options}), but it goes to a separate file, and is
        !          3574: in addition to the usual results of compilation.
        !          3575: 
        !          3576: The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
        !          3577: which case the Make rules are written to that file, guessing the target
        !          3578: name from the source file name.  Or the value can have the form
        !          3579: @samp{@var{file} @var{target}}, in which case the rules are written to
        !          3580: file @var{file} using @var{target} as the target name.
        !          3581: @end table
        !          3582: 
        !          3583: @node Running Protoize
        !          3584: @section Running Protoize
        !          3585: 
        !          3586: The program @code{protoize} is an optional part of GNU C.  You can use
        !          3587: it to add prototypes to a program, thus converting the program to ANSI
        !          3588: C in one respect.  The companion program @code{unprotoize} does the
        !          3589: reverse: it removes argument types from any prototypes that are found.
        !          3590: 
        !          3591: When you run these programs, you must specify a set of source files as
        !          3592: command line arguments.  The conversion programs start out by compiling
        !          3593: these files to see what functions they define.  The information gathered
        !          3594: about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
        !          3595: 
        !          3596: After scanning comes actual conversion.  The specified files are all
        !          3597: eligible to be converted; any files they include (whether sources or
        !          3598: just headers) are eligible as well.
        !          3599: 
        !          3600: But not all the eligible files are converted.  By default,
        !          3601: @code{protoize} and @code{unprotoize} convert only source and header
        !          3602: files in the current directory.  You can specify additional directories
        !          3603: whose files should be converted with the @samp{-d @var{directory}}
        !          3604: option.  You can also specify particular files to exclude with the
        !          3605: @samp{-x @var{file}} option.  A file is converted if it is eligible, its
        !          3606: directory name matches one of the specified directory names, and its
        !          3607: name within the directory has not been excluded.
        !          3608: 
        !          3609: Basic conversion with @code{protoize} consists of rewriting most
        !          3610: function definitions and function declarations to specify the types of
        !          3611: the arguments.  The only ones not rewritten are those for varargs
        !          3612: functions.
        !          3613: 
        !          3614: @code{protoize} optionally inserts prototype declarations at the
        !          3615: beginning of the source file, to make them available for any calls that
        !          3616: precede the function's definition.  Or it can insert prototype
        !          3617: declarations with block scope in the blocks where undeclared functions
        !          3618: are called.
        !          3619: 
        !          3620: Basic conversion with @code{unprotoize} consists of rewriting most
        !          3621: function declarations to remove any argument types, and rewriting
        !          3622: function definitions to the old-style pre-ANSI form.
        !          3623: 
        !          3624: Both conversion programs print a warning for any function declaration or
        !          3625: definition that they can't convert.  You can suppress these warnings
        !          3626: with @samp{-q}.
        !          3627: 
        !          3628: The output from @code{protoize} or @code{unprotoize} replaces the
        !          3629: original source file.  The original file is renamed to a name ending
        !          3630: with @samp{.save}.  If the @samp{.save} file already exists, then 
        !          3631: the source file is simply discarded.
        !          3632: 
        !          3633: @code{protoize} and @code{unprotoize} both depend on GNU CC itself to
        !          3634: scan the program and collect information about the functions it uses.
        !          3635: So neither of these programs will work until GNU CC is installed.
        !          3636: 
        !          3637: Here is a table of the options you can use with @code{protoize} and
        !          3638: @code{unprotoize}.  Each option works with both programs unless
        !          3639: otherwise stated.
        !          3640: 
        !          3641: @table @code
        !          3642: @item -B @var{directory}
        !          3643: Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
        !          3644: usual directory (normally @file{/usr/local/lib}).  This file contains
        !          3645: prototype information about standard system functions.  This option
        !          3646: applies only to @code{protoize}.
        !          3647: 
        !          3648: @item -c @var{compilation-options}
        !          3649: Use  @var{compilation-options} as the options when running @code{gcc} to
        !          3650: produce the @samp{.X} files.  The special option @samp{-aux-info} is
        !          3651: always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
        !          3652: 
        !          3653: Note that the compilation options must be given as a single argument to
        !          3654: @code{protoize} or @code{unprotoize}.  If you want to specify several
        !          3655: @code{gcc} options, you must quote the entire set of compilation options
        !          3656: to make them a single word in the shell.
        !          3657: 
        !          3658: There are certain @code{gcc} arguments that you cannot use, because they
        !          3659: would produce the wrong kind of output.  These include @samp{-g},
        !          3660: @samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in
        !          3661: the @var{compilation-options}, they are ignored.
        !          3662: 
        !          3663: @item -C
        !          3664: Rename files to end in @samp{.C} instead of @samp{.c}.
        !          3665: This is convenient if you are converting a C program to C++.
        !          3666: This option applies only to @code{protoize}.
        !          3667: 
        !          3668: @item -g
        !          3669: Add explicit global declarations.  This means inserting explicit
        !          3670: declarations at the beginning of each source file for each function
        !          3671: that is called in the file and was not declared.  These declarations
        !          3672: precede the first function definition that contains a call to an
        !          3673: undeclared function.  This option applies only to @code{protoize}.
        !          3674: 
        !          3675: @item -i @var{string}
        !          3676: Indent old-style parameter declarations with the string @var{string}.
        !          3677: This option applies only to @code{protoize}.
        !          3678: 
        !          3679: @code{unprotoize} converts prototyped function definitions to old-style
        !          3680: function definitions, where the arguments are declared between the
        !          3681: argument list and the initial @samp{@{}.  By default, @code{unprotoize}
        !          3682: uses five spaces as the indentation.  If you want to indent with just
        !          3683: one space instead, use @samp{-i " "}.
        !          3684: 
        !          3685: @item -k
        !          3686: Keep the @samp{.X} files.  Normally, they are deleted after conversion
        !          3687: is finished.
        !          3688: 
        !          3689: @item -l
        !          3690: Add explicit local declarations.  @code{protoize} with @samp{-l} inserts
        !          3691: a prototype declaration for each function in each block which calls the
        !          3692: function without any declaration.  This option applies only to
        !          3693: @code{protoize}.
        !          3694: 
        !          3695: @item -n
        !          3696: Make no real changes.  This mode just prints information about the conversions
        !          3697: that would have been done without @samp{-n}.
        !          3698: 
        !          3699: @item -N
        !          3700: Make no @samp{.save} files.  The original files are simply deleted.
        !          3701: Use this option with caution.
        !          3702: 
        !          3703: @item -p @var{program}
        !          3704: Use the program @var{program} as the compiler.  Normally, the name
        !          3705: @file{gcc} is used.
        !          3706: 
        !          3707: @item -q
        !          3708: Work quietly.  Most warnings are suppressed.
        !          3709: 
        !          3710: @item -v
        !          3711: Print the version number, just like @samp{-v} for @code{gcc}.
        !          3712: @end table
        !          3713: 
        !          3714: If you need special compiler options to compile one of your program's
        !          3715: source files, then you should generate that file's @samp{.X} file
        !          3716: specially, by running @code{gcc} on that source file with the
        !          3717: appropriate options and the option @samp{-aux-info}.  Then run
        !          3718: @code{protoize} on the entire set of files.  @code{protoize} will use
        !          3719: the existing @samp{.X} file because it is newer than the source file.
        !          3720: For example:
        !          3721: 
        !          3722: @example
        !          3723: gcc -Dfoo=bar file1.c -aux-info
        !          3724: protoize *.c
        !          3725: @end example
        !          3726: 
        !          3727: @noindent
        !          3728: You need to include the special files along with the rest in the
        !          3729: @code{protoize} command, even though their @samp{.X} files already
        !          3730: exist, because otherwise they won't get converted.
        !          3731: 
        !          3732: @xref{Protoize Caveats}, for more information on how to use
        !          3733: @code{protoize} successfully.
        !          3734: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.