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