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