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