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