![[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:
5: @node Invoking GCC, Installation, Boycott, Top
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
24: The GNU C compiler uses a command syntax much like the Unix C compiler.
25: The @code{gcc} program accepts options and file names as operands.
26: Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is
27: very different from @w{@samp{-d -r}}.
28:
29: @cindex order of options
30: @cindex options, order
31: You can mix options and other arguments. For the most part, the order
32: you use doesn't matter; @code{gcc} reorders the command-line options so
33: that the choices specified by option flags are applied to all input
34: files. Order does matter when you use several options of the same kind;
35: for example, if you specify @samp{-L} more than once, the directories
36: are searched in the order specified.
37:
38: Many options have long names starting with @samp{-f} or with
39: @samp{-W}---for example, @samp{-fforce-mem},
40: @samp{-fstrength-reduce}, @samp{-Wformat} and so on. Most of
41: these have both positive and negative forms; the negative form of
42: @samp{-ffoo} would be @samp{-fno-foo}. This manual documents
43: only one of these two forms, whichever one is not the default.
44:
45: Here is a summary of all the options, grouped by type. Explanations are
46: in the following sections.
47:
48: @table @emph
49: @item Overall Options
50: @xref{Overall Options,,Options Controlling the Kind of Output}.
51: @example
52: -c -S -E -o @var{file} -pipe -v -x @var{language}
53: @end example
54:
55: @item Language Options
56: @xref{Dialect Options,,Options Controlling Dialect}.
57: @example
58: -ansi -fbuiltin -fcond-mismatch -fno-asm
59: -fsigned-bitfields -fsigned-char
60: -funsigned-bitfields -funsigned-char -fwritable-strings
61: -traditional -traditional-cpp -trigraphs
62: @end example
63:
64: @item Warning Options
65: @xref{Warning Options,,Options to Request or Suppress Warnings}.
66: @example
67: -fsyntax-only -pedantic -pedantic-errors
68: -w -W -Wall -Waggregate-return
69: -Wcast-align -Wcast-qual -Wcomment -Wconversion -Werror
1.1.1.2 ! root 70: -Wformat -Wid-clash-@var{len} -Wimplicit -Wimport
! 71: -Winline -Wmissing-prototypes
! 72: -Wparentheses -Wpointer-arith -Wreturn-type -Wshadow
1.1 root 73: -Wstrict-prototypes -Wswitch -Wtraditional -Wtrigraphs
74: -Wuninitialized -Wunused -Wwrite-strings -Wchar-subscripts
75: @end example
76:
77: @item Debugging Options
78: @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
79: @example
80: -a -d@var{letters} -fpretend-float
1.1.1.2 ! root 81: -g -g@var{level} -ggdb -gdwarf
! 82: -gstabs -gstabs+ -gcoff -gxcoff
1.1 root 83: -p -pg -save-temps
84: @end example
85:
86: @item Optimization Options
87: @xref{Optimize Options,,Options that Control Optimization}.
88: @example
89: -fcaller-saves -fcse-follow-jumps -fdelayed-branch
90: -fexpensive-optimizations -ffloat-store -fforce-addr -fforce-mem
91: -finline -finline-functions -fkeep-inline-functions
92: -fno-defer-pop -fno-function-cse -fomit-frame-pointer
93: -frerun-cse-after-loop -fschedule-insns -fschedule-insns2
94: -fstrength-reduce -fthread-jumps
95: -funroll-all-loops -funroll-loops
96: -O -O2
97: @end example
98:
99: @item Preprocessor Options
100: @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
101: @example
102: -C -dD -dM -dN
103: -D@var{macro}@r{[}=@var{defn}@r{]} -E -H
104: -include @var{file} -imacros @var{file}
105: -M -MD -MM -MMD -nostdinc -P -trigraphs -U@var{macro}
106: @end example
107:
108: @item Linker Options
109: @xref{Link Options,,Options for Linking}.
110: @example
111: @var{object-file-name}
112: -l@var{library} -nostdlib -static
113: @end example
114:
115: @item Directory Options
116: @xref{Directory Options,,Options for Directory Search}.
117: @example
118: -B@var{prefix} -I@var{dir} -I- -L@var{dir}
119: @end example
120:
121: @item Target Options
122: @xref{Target Options,,Target Machine and Compiler Version}.
123: @example
124: -b @var{machine} -V @var{version}
125: @end example
126:
127: @item Machine Dependent Options
128: @xref{Submodel Options,,Hardware Models and Configurations}.
129: @example
130: @emph{M680x0 Options}
131: -m68000 -m68020 -m68881 -mbitfield -mc68000 -mc68020 -mfpa
132: -mnobitfield -mrtd -mshort -msoft-float
133:
134: @emph{VAX Options}
135: -mg -mgnu -munix
136:
137: @emph{SPARC Options}
1.1.1.2 ! root 138: -mforce-align -mfpu -mno-epilogue
1.1 root 139:
140: @emph{Convex Options}
141: -margcount -mc1 -mc2 -mnoargcount
142:
143: @emph{AMD29K Options}
144: -m29000 -m29050 -mbw -mdw -mkernel-registers -mlarge
145: -mnbw -mnodw -msmall -mstack-check -muser-registers
146:
147: @emph{M88K Options}
148: -m88000 -m88100 -m88110 -mbig-pic -mcheck-zero-division
149: -mhandle-large-shift -midentify-revision
150: -mno-check-zero-division -mno-ocs-debug-info
151: -mno-ocs-frame-position -mno-optimize-arg-area -mno-underscores
152: -mocs-debug-info -mocs-frame-position -moptimize-arg-area
153: -mshort-data-@var{num} -msvr3 -msvr4 -mtrap-large-shift
154: -muse-div-instruction -mversion-03.00 -mwarn-passed-structs
155:
156: @emph{RS/6000 Options}
157: -mfp-in-toc -mno-fop-in-toc
158:
159: @emph{RT Options}
160: -mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs
161: -mfull-fp-blocks -mhc-struct-return -min-line-mul
162: -mminimum-fp-blocks -mnohc-struct-return
163:
164: @emph{MIPS Options}
165: -mcpu=@var{cpu type} -mips2 -mips3 -mint64 -mlong64 -mlonglong128
166: -mmips-as -mgas -mrnames -mno-rnames -mgpopt -mno-gpopt -mstats
167: -mno-stats -mmemcpy -mno-memcpy -mno-mips-tfile -mmips-tfile
168: -msoft-float -mhard-float -mabicalls -mno-abicalls -mhalf-pic
1.1.1.2 ! root 169: -mno-half-pic -G @var{num} -nocpp
! 170:
! 171: @emph{i386 Options}
! 172: -m486 -msoft-float
1.1 root 173: @end example
174:
175: @item Code Generation Options
176: @xref{Code Gen Options,,Options for Code Generation Conventions}.
177: @example
178: -fcall-saved-@var{reg} -fcall-used-@var{reg} -ffixed-@var{reg}
179: -fno-common -fpcc-struct-return -fpic -fPIC -fshared-data
180: -fshort-enums -fshort-double -fvolatile
181: @end example
182:
183: @end table
184:
185: @menu
186: * Overall Options:: Controlling the kind of output:
187: an executable, object files, assembler files,
188: or preprocessed source.
189: * Dialect Options:: Controlling the variant of C language compiled.
190: * Warning Options:: How picky should the compiler be?
191: * Debugging Options:: Symbol tables, measurements, and debugging dumps.
192: * Optimize Options:: How much optimization?
193: * Preprocessor Options:: Controlling header files and macro definitions.
194: Also, getting dependency information for Make.
195: * Link Options:: Specifying libraries and so on.
196: * Directory Options:: Where to find header files and libraries.
197: Where to find the compiler executable files.
198: * Target Options:: Running a cross-compiler, or an old version of GNU CC.
199: * Submodel Options:: Specifying minor hardware or convention variations,
200: such as 68010 vs 68020.
201: * Code Gen Options:: Specifying conventions for function calls, data layout
202: and register usage.
203: * Environment Variables:: Env vars that affect GNU CC.
204: @end menu
205:
206: @node Overall Options, Dialect Options, Invoking GCC, Invoking GCC
207: @section Options Controlling the Kind of Output
208:
209: Compilation can involve up to four stages: preprocessing, compilation
210: proper, assembly and linking, always in that order. The first three
211: stages apply to an individual source file, and end by producing an
212: object file; linking combines all the object files (those newly
213: compiled, and those specified as input) into an executable file.
214:
215: @cindex file name suffix
216: For any given input file, the file name suffix determines what kind of
217: compilation is done:
218:
219: @table @code
220: @item @var{file}.c
221: C source code which must be preprocessed.
222:
223: @item @var{file}.i
224: C source code which should not be preprocessed.
225:
226: @item @var{file}.m
227: Objective-C source code
228:
229: @item @var{file}.h
230: C header file (not to be compiled or linked).
231:
232: @item @var{file}.cc
233: @itemx @var{file}.cxx
234: @itemx @var{file}.C
235: C++ source code which must be preprocessed.
236:
237: @item @var{file}.s
238: Assembler code.
239:
240: @item @var{file}.S
241: Assembler code which must be preprocessed.
242:
243: @item @var{other}
244: An object file to be fed straight into linking.
245: Any file name with no recognized suffix is treated this way.
246: @end table
247:
248: You can specify the input language explicitly with the @samp{-x} option:
249:
250: @table @code
251: @item -x @var{language}
252: Specify explicitly the @var{language} for the following input files
253: (rather than choosing a default based on the file name suffix).
254: This option applies to all following input files until
255: the next @samp{-x} option. Possible values of @var{language} are
256: @samp{c}, @samp{objective-c}, @samp{c-header}, @samp{c++},
257: @samp{cpp-output}, @samp{assembler}, and @samp{assembler-with-cpp}.
258:
259: @item -x none
260: Turn off any specification of a language, so that subsequent files are
261: handled according to their file name suffixes (as they are if @samp{-x}
262: has not been used at all).
263: @end table
264:
265: If you only want some of the stages of compilation, you can use
266: @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
267: one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
268: @code{gcc} is to stop. Note that some combinations (for example,
269: @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
270:
271: @table @code
272: @item -c
273: Compile or assemble the source files, but do not link. The linking
274: stage simply is not done. The ultimate output is in the form of an
275: object file for each source file.
276:
277: By default, the object file name for a source file is made by replacing
278: the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
279:
280: Unrecognized input files, not requiring compilation or assembly, are
281: ignored.
282:
283: @item -S
284: Stop after the stage of compilation proper; do not assemble. The output
285: is in the form of an assembler code file for each non-assembler input
286: file specified.
287:
288: By default, the assembler file name for a source file is made by
289: replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
290:
291: Input files that don't require compilation are ignored.
292:
293: @item -E
294: Stop after the preprocessing stage; do not run the compiler proper. The
295: output is in the form of preprocessed source code, which is sent to the
296: standard output.
297:
298: Input files which don't require preprocessing are ignored.
299:
300: @cindex output file option
301: @item -o @var{file}
302: Place output in file @var{file}. This applies regardless to whatever
303: sort of output is being produced, whether it be an executable file,
304: an object file, an assembler file or preprocessed C code.
305:
306: Since only one output file can be specified, it does not make sense to
307: use @samp{-o} when compiling more than one input file, unless you are
308: producing an executable file as output.
309:
310: If @samp{-o} is not specified, the default is to put an executable file
311: in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
312: @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
313: all preprocessed C source on standard output.@refill
314:
315: @item -v
316: Print (on standard error output) the commands executed to run the stages
317: of compilation. Also print the version number of the compiler driver
318: program and of the preprocessor and the compiler proper.
319:
320: @item -pipe
321: Use pipes rather than temporary files for communication between the
322: various stages of compilation. This fails to work on some systems where
323: the assembler is unable to read from a pipe; but the GNU assembler has
324: no trouble.
325: @end table
326:
327: @node Dialect Options, Warning Options, Overall Options, Invoking GCC
328: @section Options Controlling Dialect
329: @cindex dialect options
330: @cindex language dialect options
331: @cindex options, dialect
332:
333: The following options control the dialect of C that the compiler
334: accepts:
335:
336: @table @code
337: @cindex ANSI support
338: @item -ansi
339: Support all ANSI standard C programs.
340:
341: This turns off certain features of GNU C that are incompatible with ANSI
342: C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and
343: predefined macros such as @code{unix} and @code{vax} that identify the
344: type of system you are using. It also enables the undesirable and
345: rarely used ANSI trigraph feature, and disallows @samp{$} as part of
346: identifiers.
347:
348: The alternate keywords @code{__asm__}, @code{__extension__},
349: @code{__inline__} and @code{__typeof__} continue to work despite
350: @samp{-ansi}. You would not want to use them in an ANSI C program, of
351: course, but it useful to put them in header files that might be included
352: in compilations done with @samp{-ansi}. Alternate predefined macros
353: such as @code{__unix__} and @code{__vax__} are also available, with or
354: without @samp{-ansi}.
355:
356: The @samp{-ansi} option does not cause non-ANSI programs to be
357: rejected gratuitously. For that, @samp{-pedantic} is required in
358: addition to @samp{-ansi}. @xref{Warning Options}.
359:
360: The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
361: option is used. Some header files may notice this macro and refrain
362: from declaring certain functions or defining certain macros that the
363: ANSI standard doesn't call for; this is to avoid interfering with any
364: programs that might use these names for other things.
365:
366: @item -fno-asm
367: Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
368: keyword. These words may then be used as identifiers. You can
369: use @code{__asm__}, @code{__inline__} and @code{__typeof__} instead.
370: @samp{-ansi} implies @samp{-fno-asm}.
371:
372: @item -fno-builtin
373: Don't recognize non-ANSI built-in functions. @samp{-ansi} also has this
374: effect. Currently, the only function affected is @code{alloca}.
375:
376: @item -trigraphs
377: Support ANSI C trigraphs. You don't want to know about this
378: brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}.
379:
380: @cindex traditional C language
381: @cindex C language, traditional
382: @item -traditional
383: Attempt to support some aspects of traditional C compilers.
384: Specifically:
385:
386: @itemize @bullet
387: @item
388: All @code{extern} declarations take effect globally even if they
389: are written inside of a function definition. This includes implicit
390: declarations of functions.
391:
392: @item
393: The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
394: and @code{volatile} are not recognized. (You can still use the
395: alternative keywords such as @code{__typeof__}, @code{__inline__}, and
396: so on.)
397:
398: @item
399: Comparisons between pointers and integers are always allowed.
400:
401: @item
402: Integer types @code{unsigned short} and @code{unsigned char} promote
403: to @code{unsigned int}.
404:
405: @item
406: Out-of-range floating point literals are not an error.
407:
408: @item
409: String ``constants'' are not necessarily constant; they are stored in
410: writable space, and identical looking constants are allocated
411: separately. (This is the same as the effect of
412: @samp{-fwritable-strings}.)
413:
414: @cindex @code{longjmp} and automatic variables
415: @item
416: All automatic variables not declared @code{register} are preserved by
417: @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
418: not declared @code{volatile} may be clobbered.
419:
420: @item
421: In the preprocessor, comments convert to nothing at all, rather than
422: to a space. This allows traditional token concatenation.
423:
424: @item
425: In the preprocessor, macro arguments are recognized within string
426: constants in a macro definition (and their values are stringified,
427: though without additional quote marks, when they appear in such a
428: context). The preprocessor always considers a string constant to end
429: at a newline.
430:
431: @item
432: The predefined macro @code{__STDC__} is not defined when you use
433: @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
434: which @code{__GNUC__} indicates are not affected by
435: @samp{-traditional}). If you need to write header files that work
436: differently depending on whether @samp{-traditional} is in use, by
437: testing both of these predefined macros you can distinguish four
438: situations: GNU C, traditional GNU C, other ANSI C compilers, and
439: other old C compilers.
440: @end itemize
441:
442: @item -traditional-cpp
443: Attempt to support some aspects of traditional C preprocessors.
444: This includes the last three items in the table immediately above,
445: but none of the other effects of @samp{-traditional}.
446:
447: @item -fcond-mismatch
448: Allow conditional expressions with mismatched types in the second and
449: third arguments. The value of such an expression is void.
450:
451: @item -funsigned-char
452: Let the type @code{char} be unsigned, like @code{unsigned char}.
453:
454: Each kind of machine has a default for what @code{char} should
455: be. It is either like @code{unsigned char} by default or like
456: @code{signed char} by default.
457:
458: Ideally, a portable program should always use @code{signed char} or
459: @code{unsigned char} when it depends on the signedness of an object.
460: But many programs have been written to use plain @code{char} and
461: expect it to be signed, or expect it to be unsigned, depending on the
462: machines they were written for. This option, and its inverse, let you
463: make such a program work with the opposite default.
464:
465: The type @code{char} is always a distinct type from each of
466: @code{signed char} or @code{unsigned char}, even though its behavior
467: is always just like one of those two.
468:
469: @item -fsigned-char
470: Let the type @code{char} be signed, like @code{signed char}.
471:
472: Note that this is equivalent to @samp{-fno-unsigned-char}, which is
473: the negative form of @samp{-funsigned-char}. Likewise,
474: @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
475:
476: @item -fsigned-bitfields
477: @itemx -funsigned-bitfields
478: @itemx -fno-signed-bitfields
479: @itemx -fno-unsigned-bitfields
480: These options control whether a bitfield is signed or unsigned, when the
481: declaration does not use either @code{signed} or @code{unsigned}. By
482: default, such a bitfield is signed, because this is consistent: the
483: basic integer types such as @code{int} are signed types.
484:
485: However, when @samp{-traditional} is used, bitfields are all unsigned
486: no matter what.
487:
488: @item -fwritable-strings
489: Store string constants in the writable data segment and don't uniquize
490: them. This is for compatibility with old programs which assume they
491: can write into string constants. @samp{-traditional} also has this
492: effect.
493:
494: Writing into string constants is a very bad idea; ``constants'' should
495: be constant.
496: @end table
497:
498: @node Warning Options, Debugging Options, Dialect Options, Invoking GCC
499: @section Options to Request or Suppress Warnings
500: @cindex options to control warnings
501: @cindex warning messages
502: @cindex messages, warning
503: @cindex suppressing warnings
504:
505: Warnings are diagnostic messages that report constructions which
506: are not inherently erroneous but which are risky or suggest there
507: may have been an error.
508:
509: You can request many specific warnings with options beginning @samp{-W},
510: for example @samp{-Wimplicit} to request warnings on implicit
511: declarations. Each of these specific warning options also has a
512: negative form beginning @samp{-Wno-} to turn off warnings;
513: for example, @samp{-Wno-implicit}. This manual lists only one of the
514: two forms, whichever is not the default.
515:
516: These options control the amount and kinds of warnings produced by GNU
517: CC:
518:
519: @table @code
520: @cindex syntax checking
521: @item -fsyntax-only
522: Check the code for syntax errors, but don't emit any output.
523:
524: @item -w
525: Inhibit all warning messages.
526:
1.1.1.2 ! root 527: @item -Wno_import
! 528: Inhibit warning messages about the use of @samp{#import}.
! 529:
1.1 root 530: @item -pedantic
531: Issue all the warnings demanded by strict ANSI standard C; reject
532: all programs that use forbidden extensions.
533:
534: Valid ANSI standard C programs should compile properly with or without
535: this option (though a rare few will require @samp{-ansi}). However,
536: without this option, certain GNU extensions and traditional C features
537: are supported as well. With this option, they are rejected.
538:
539: @samp{-pedantic} does not cause warning messages for use of the
540: alternate keywords whose names begin and end with @samp{__}. Pedantic
541: warnings are also disabled in the expression that follows
542: @code{__extension__}. However, only system header files should use
543: these escape routes; application programs should avoid them.
544: @xref{Alternate Keywords}.
545:
546: This option is not intended to be @i{useful}; it exists only to satisfy
547: pedants who would otherwise claim that GNU CC fails to support the ANSI
548: standard.
549:
550: Some users try to use @samp{-pedantic} to check programs for strict ANSI
551: C conformance. They soon find that it does not do quite what they want:
552: it finds some non-ANSI practices, but not all---only those for which
553: ANSI C @emph{requires} a diagnostic.
554:
555: A feature to report any failure to conform to ANSI C might be useful in
556: some instances, but would require considerable additional work and would
557: be quite different from @samp{-pedantic}. We recommend, rather, that
558: users take advantage of the extensions of GNU C and disregard the
559: limitations of other compilers. Aside from certain supercomputers and
560: obsolete small machines, there is less and less reason ever to use any
561: other C compiler other than for bootstrapping GNU CC.
562:
563: @item -pedantic-errors
564: Like @samp{-pedantic}, except that errors are produced rather than
565: warnings.
566:
567: @item -W
568: Print extra warning messages for these events:
569:
570: @itemize @bullet
571: @cindex @code{longjmp} warnings
572: @item
573: A nonvolatile automatic variable might be changed by a call to
574: @code{longjmp}. These warnings as well are possible only in
575: optimizing compilation.
576:
577: The compiler sees only the calls to @code{setjmp}. It cannot know
578: where @code{longjmp} will be called; in fact, a signal handler could
579: call it at any point in the code. As a result, you may get a warning
580: even when there is in fact no problem because @code{longjmp} cannot
581: in fact be called at the place which would cause a problem.
582:
583: @item
584: A function can return either with or without a value. (Falling
585: off the end of the function body is considered returning without
586: a value.) For example, this function would evoke such a
587: warning:
588:
589: @example
590: foo (a)
591: @{
592: if (a > 0)
593: return a;
594: @}
595: @end example
596:
597: @item
598: An expression-statement contains no side effects.
599:
600: @item
601: An unsigned value is compared against zero with @samp{>} or @samp{<=}.
602: @end itemize
603:
604: @item -Wimplicit
605: Warn whenever a function or parameter is implicitly declared.
606:
607: @item -Wreturn-type
608: Warn whenever a function is defined with a return-type that defaults
609: to @code{int}. Also warn about any @code{return} statement with no
610: return-value in a function whose return-type is not @code{void}.
611:
612: @item -Wunused
613: Warn whenever a local variable is unused aside from its declaration,
614: whenever a function is declared static but never defined, and whenever
615: a statement computes a result that is explicitly not used.
616:
617: @item -Wswitch
618: Warn whenever a @code{switch} statement has an index of enumeral type
619: and lacks a @code{case} for one or more of the named codes of that
620: enumeration. (The presence of a @code{default} label prevents this
621: warning.) @code{case} labels outside the enumeration range also
622: provoke warnings when this option is used.
623:
624: @item -Wcomment
625: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
626:
627: @item -Wtrigraphs
628: Warn if any trigraphs are encountered (assuming they are enabled).
629:
630: @item -Wformat
631: Check calls to @code{printf} and @code{scanf}, etc., to make sure that
632: the arguments supplied have types appropriate to the format string
633: specified.
634:
635: @item -Wchar-subscripts
636: Warn if an array subscript has type @code{char}. This is a common cause
637: of error, as programmers often forget that this type is signed on some
638: machines.
639:
640: @item -Wuninitialized
641: An automatic variable is used without first being initialized.
642:
643: These warnings are possible only in optimizing compilation,
644: because they require data flow information that is computed only
645: when optimizing. If you don't specify @samp{-O}, you simply won't
646: get these warnings.
647:
648: These warnings occur only for variables that are candidates for
649: register allocation. Therefore, they do not occur for a variable that
650: is declared @code{volatile}, or whose address is taken, or whose size
651: is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
652: structures, unions or arrays, even when they are in registers.
653:
654: Note that there may be no warning about a variable that is used only
655: to compute a value that itself is never used, because such
656: computations may be deleted by data flow analysis before the warnings
657: are printed.
658:
659: These warnings are made optional because GNU CC is not smart
660: enough to see all the reasons why the code might be correct
661: despite appearing to have an error. Here is one example of how
662: this can happen:
663:
664: @example
665: @{
666: int x;
667: switch (y)
668: @{
669: case 1: x = 1;
670: break;
671: case 2: x = 4;
672: break;
673: case 3: x = 5;
674: @}
675: foo (x);
676: @}
677: @end example
678:
679: @noindent
680: If the value of @code{y} is always 1, 2 or 3, then @code{x} is
681: always initialized, but GNU CC doesn't know this. Here is
682: another common case:
683:
684: @example
685: @{
686: int save_y;
687: if (change_y) save_y = y, y = new_y;
688: @dots{}
689: if (change_y) y = save_y;
690: @}
691: @end example
692:
693: @noindent
694: This has no bug because @code{save_y} is used only if it is set.
695:
696: Some spurious warnings can be avoided if you declare as
697: @code{volatile} all the functions you use that never return.
698: @xref{Function Attributes}.
699:
1.1.1.2 ! root 700: @item -Wparentheses
! 701: Warn if parentheses are omitted in certain contexts.
! 702:
1.1 root 703: @item -Wall
704: All of the above @samp{-W} options combined. These are all the
705: options which pertain to usage that we recommend avoiding and that we
706: believe is easy to avoid, even in conjunction with macros.
707: @end table
708:
709: The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall}
710: because they warn about constructions that we consider reasonable to
711: use, on occasion, in clean programs.
712:
713: @table @code
714: @item -Wtraditional
715: Warn about certain constructs that behave differently in traditional and
716: ANSI C.
717:
718: @itemize @bullet
719: @item
720: Macro arguments occurring within string constants in the macro body.
721: These would substitute the argument in traditional C, but are part of
722: the constant in ANSI C.
723:
724: @item
725: A function declared external in one block and then used after the end of
726: the block.
727:
728: @item
729: A @code{switch} statement has an operand of type @code{long}.
730: @end itemize
731:
732: @item -Wshadow
733: Warn whenever a local variable shadows another local variable.
734:
735: @item -Wid-clash-@var{len}
736: Warn whenever two distinct identifiers match in the first @var{len}
737: characters. This may help you prepare a program that will compile
738: with certain obsolete, brain-damaged compilers.
739:
740: @item -Wpointer-arith
741: Warn about anything that depends on the ``size of'' a function type or
742: of @code{void}. GNU C assigns these types a size of 1, for
743: convenience in calculations with @code{void *} pointers and pointers
744: to functions.
745:
746: @item -Wcast-qual
747: Warn whenever a pointer is cast so as to remove a type qualifier from
748: the target type. For example, warn if a @code{const char *} is cast
749: to an ordinary @code{char *}.
750:
751: @item -Wcast-align
752: Warn whenever a pointer is cast such that the required alignment of the
753: target is increased. For example, warn if a @code{char *} is cast to
754: an @code{int *} on machines where integers can only be accessed at
755: two- or four-byte boundaries.
756:
757: @item -Wwrite-strings
758: Give string constants the type @code{const char[@var{length}]} so that
759: copying the address of one into a non-@code{const} @code{char *}
760: pointer will get a warning. These warnings will help you find at
761: compile time code that can try to write into a string constant, but
762: only if you have been very careful about using @code{const} in
763: declarations and prototypes. Otherwise, it will just be a nuisance;
764: this is why we did not make @samp{-Wall} request these warnings.
765:
766: @item -Wconversion
767: Warn if a prototype causes a type conversion that is different from what
768: would happen to the same argument in the absence of a prototype. This
769: includes conversions of fixed point to floating and vice versa, and
770: conversions changing the width or signedness of a fixed point argument
771: except when the same as the default promotion.
772:
773: @item -Waggregate-return
774: Warn if any functions that return structures or unions are defined or
775: called. (In languages where you can return an array, this also elicits
776: a warning.)
777:
778: @item -Wstrict-prototypes
779: Warn if a function is declared or defined without specifying the
780: argument types. (An old-style function definition is permitted without
781: a warning if preceded by a declaration which specifies the argument
782: types.)
783:
784: @item -Wmissing-prototypes
785: Warn if a global function is defined without a previous prototype
786: declaration. This warning is issued even if the definition itself
787: provides a prototype. The aim is to detect global functions that fail
788: to be declared in header files.
789:
790: @item -Wredundant-decls
791: Warn if anything is declared more than once in the same scope, even in
792: cases where multiple declaration is valid and changes nothing.
793:
794: @item -Wnested-externs
795: Warn if an @code{extern} declaration is encountered within an function.
796:
1.1.1.2 ! root 797: @item -Winline
! 798: Warn if a function can not be inlined, and either it was declared as inline,
! 799: or else the @samp{-finline-functions} option was given.
1.1 root 800:
801: @item -Werror
802: Make all warnings into errors.
803: @end table
804:
805: @node Debugging Options, Optimize Options, Warning Options, Invoking GCC
806: @section Options for Debugging Your Program or GNU CC
807: @cindex options, debugging
808: @cindex debugging information options
809:
810: GNU CC has various special options that are used for debugging
811: either your program or GCC:
812:
813: @table @code
814: @item -g
815: Produce debugging information in the operating system's native format
1.1.1.2 ! root 816: (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging
! 817: information.
1.1 root 818:
819: On most systems that use stabs format, @samp{-g} enables use of extra
820: debugging information that only GDB can use; this extra information
821: makes debugging work better in GDB but will probably make DBX crash or
822: refuse to read the program. If you want to control for certain whether
823: to generate the extra information, use @samp{-gstabs+} or @samp{-gstabs}
824: (see below).
825:
826: Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
827: @samp{-O}. The shortcuts taken by optimized code may occasionally
828: produce surprising results: some variables you declared may not exist
829: at all; flow of control may briefly move where you did not expect it;
830: some statements may not be executed because they compute constant
831: results or their values were already at hand; some statements may
832: execute in different places because they were moved out of loops.
833:
834: Nevertheless it proves possible to debug optimized output. This makes
835: it reasonable to use the optimizer for programs that might have bugs.
836:
837: The following options are useful when GNU CC is generated with the
838: capability for more than one debugging format.
839:
840: @item -ggdb
841: Produce debugging information in the native format (if that is supported),
842: including GDB extensions if at all possible.
843:
844: @item -gstabs
845: Produce debugging information in stabs format (if that is supported),
846: without GDB extensions. This is the format used by DBX on most BSD
847: systems.
848:
849: @item -gstabs+
850: Produce debugging information in stabs format (if that is supported),
851: using GDB extensions. The use of these extensions is likely to make DBX
852: crash or refuse to read the program.
853:
854: @item -gcoff
855: Produce debugging information in COFF format (if that is supported).
856: This is the format used by SDB on COFF systems.
857:
1.1.1.2 ! root 858: @item -gxcoff
! 859: Produce debugging information in XCOFF format (if that is supported).
! 860: This is the format used on IBM RS/6000 systems.
! 861:
1.1 root 862: @item -gdwarf
863: Produce debugging information in DWARF format (if that is supported).
864: This is the format used by SDB on systems that use DWARF.
865:
866: @item -g@var{level}
867: @itemx -ggdb@var{level}
868: @itemx -gstabs@var{level}
869: @itemx -gcoff@var{level}
1.1.1.2 ! root 870: @itemx -gxcoff@var{level}
1.1 root 871: @itemx -gdwarf@var{level}
872: Request debugging information and also use @var{level} to specify how
873: much information. The default level is 2.
874:
875: Level 1 produces minimal information, enough for making backtraces in
876: parts of the program that you don't plan to debug. This includes
877: descriptions of functions and external variables, but no information
878: about local variables and no line numbers.
879:
880: Level 3 includes extra information, such as all the macro definitions
881: present in the program. Some debuggers support macro expansion when
882: you use @samp{-g3}.
883:
884: @cindex @code{prof}
885: @item -p
886: Generate extra code to write profile information suitable for the
887: analysis program @code{prof}.
888: @c ??? looks like -p and -pg are now equivalent. Are they? 11dec91
889:
890: @cindex @code{gprof}
891: @item -pg
892: Generate extra code to write profile information suitable for the
893: analysis program @code{gprof}.
894:
895: @cindex @code{tcov}
896: @item -a
897: Generate extra code to write profile information for basic blocks,
898: which will record the number of times each basic block is executed.
899: This data could be analyzed by a program like @code{tcov}. Note,
900: however, that the format of the data is not what @code{tcov} expects.
901: Eventually GNU @code{gprof} should be extended to process this data.
902:
903: @item -d@var{letters}
904: Says to make debugging dumps during compilation at times specified by
905: @var{letters}. This is used for debugging the compiler. The file names
906: for most of the dumps are made by appending a word to the source file
907: name (e.g. @file{foo.c.rtl} or @file{foo.c.jump}). Here are the
908: possible letters for use in @var{letters}, and their meanings:
909:
910: @table @samp
911: @item M
912: Dump all macro definitions, at the end of preprocessing, and write no
913: output.
914: @item N
915: Dump all macro names, at the end of preprocessing.
916: @item D
917: Dump all macro definitions, at the end of preprocessing, in addition to
918: normal output.
919: @item y
920: Dump debugging information during parsing, to standard error.
921: @item r
922: Dump after RTL generation, to @file{@var{file}.rtl}.
923: @item x
924: Just generate RTL for a function instead of compiling it. Usually used
925: with @samp{r}.
926: @item j
927: Dump after first jump optimization, to @file{@var{file}.jump}.
928: @item s
929: Dump after CSE (including the jump optimization that sometimes
930: follows CSE), to @file{@var{file}.cse}.
931: @item L
932: Dump after loop optimization, to @file{@var{file}.loop}.
933: @item t
934: Dump after the second CSE pass (including the jump optimization that
935: sometimes follows CSE), to @file{@var{file}.cse2}.
936: @item f
937: Dump after flow analysis, to @file{@var{file}.flow}.
938: @item c
939: Dump after instruction combination, to @file{@var{file}.combine}.
940: @item S
941: Dump after the first instruction scheduling pass, to
942: @file{@var{file}.sched}.
943: @item l
944: Dump after local register allocation, to @file{@var{file}.lreg}.
945: @item g
946: Dump after global register allocation, to @file{@var{file}.greg}.
947: @item R
948: Dump after the second instruction scheduling pass, to
949: @file{@var{file}.sched2}.
950: @item J
951: Dump after last jump optimization, to @file{@var{file}.jump2}.
952: @item d
953: Dump after delayed branch scheduling, to @file{@var{file}.dbr}.
954: @item k
955: Dump after conversion from registers to stack, to @file{@var{file}.stack}.
956: @item a
957: Produce all the dumps listed above.
958: @item m
959: Print statistics on memory usage, at the end of the run, to
960: standard error.
961: @item p
962: Annotate the assembler output with a comment indicating which
963: pattern and alternative was used.
964: @end table
965:
966: @item -fpretend-float
967: When running a cross-compiler, pretend that the target machine uses the
968: same floating point format as the host machine. This causes incorrect
969: output of the actual floating constants, but the actual instruction
970: sequence will probably be the same as GNU CC would make when running on
971: the target machine.
972:
973: @item -save-temps
974: Store the usual ``temporary'' intermediate files permanently; place them
975: in the current directory and name them based on the source file. Thus,
976: compiling @file{foo.c} with @samp{-c -save-temps} would produce files
1.1.1.2 ! root 977: @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.
1.1 root 978: @end table
979:
980: @node Optimize Options, Preprocessor Options, Debugging Options, Invoking GCC
981: @section Options That Control Optimization
982: @cindex optimize options
983: @cindex options, optimization
984:
985: These options control various sorts of optimizations:
986:
987: @table @code
988: @item -O
989: Optimize. Optimizing compilation takes somewhat more time, and a lot
990: more memory for a large function.
991:
992: Without @samp{-O}, the compiler's goal is to reduce the cost of
993: compilation and to make debugging produce the expected results.
994: Statements are independent: if you stop the program with a breakpoint
995: between statements, you can then assign a new value to any variable or
996: change the program counter to any other statement in the function and
997: get exactly the results you would expect from the source code.
998:
999: Without @samp{-O}, only variables declared @code{register} are
1000: allocated in registers. The resulting compiled code is a little worse
1001: than produced by PCC without @samp{-O}.
1002:
1003: With @samp{-O}, the compiler tries to reduce code size and execution
1004: time.
1005:
1006: When @samp{-O} is specified, @samp{-fthread-jumps} and
1007: @samp{-fdelayed-branch} are turned on. On some machines other
1008: flags may also be turned on.
1009:
1010: @item -O2
1.1.1.2 ! root 1011: Optimize even more. Nearly all supported optimizations that do not
! 1012: involve a space-speed tradeoff are performed. As compared to @samp{-O},
! 1013: this option increases both compilation time and the performance of the
1.1 root 1014: generated code.
1015:
1.1.1.2 ! root 1016: @samp{-O2} turns on all @samp{-f@var{flag}} options that enable more
! 1017: optimization, except for @samp{-funroll-loops},
! 1018: @samp{-funroll-all-loops} and @samp{-fomit-frame-pointer}.
1.1 root 1019: @end table
1020:
1021: Options of the form @samp{-f@var{flag}} specify machine-independent
1022: flags. Most flags have both positive and negative forms; the negative
1023: form of @samp{-ffoo} would be @samp{-fno-foo}. In the table below,
1024: only one of the forms is listed---the one which is not the default.
1025: You can figure out the other form by either removing @samp{no-} or
1026: adding it.
1027:
1028: @table @code
1029: @item -ffloat-store
1030: Do not store floating point variables in registers. This
1031: prevents undesirable excess precision on machines such as the
1032: 68000 where the floating registers (of the 68881) keep more
1033: precision than a @code{double} is supposed to have.
1034:
1035: For most programs, the excess precision does only good, but a few
1036: programs rely on the precise definition of IEEE floating point.
1037: Use @samp{-ffloat-store} for such programs.
1038:
1039: @item -fno-defer-pop
1040: Always pop the arguments to each function call as soon as that function
1041: returns. For machines which must pop arguments after a function call,
1042: the compiler normally lets arguments accumulate on the stack for several
1043: function calls and pops them all at once.
1044:
1045: @item -fforce-mem
1046: Force memory operands to be copied into registers before doing
1047: arithmetic on them. This may produce better code by making all
1048: memory references potential common subexpressions. When they are
1049: not common subexpressions, instruction combination should
1050: eliminate the separate register-load. I am interested in hearing
1051: about the difference this makes.
1052:
1053: @item -fforce-addr
1054: Force memory address constants to be copied into registers before
1055: doing arithmetic on them. This may produce better code just as
1056: @samp{-fforce-mem} may. I am interested in hearing about the
1057: difference this makes.
1058:
1059: @item -fomit-frame-pointer
1060: Don't keep the frame pointer in a register for functions that
1061: don't need one. This avoids the instructions to save, set up and
1062: restore frame pointers; it also makes an extra register available
1063: in many functions. @strong{It also makes debugging impossible on
1064: some machines.}
1065:
1066: @ifset INTERNALS
1067: On some machines, such as the Vax, this flag has no effect, because
1068: the standard calling sequence automatically handles the frame pointer
1069: and nothing is saved by pretending it doesn't exist. The
1070: machine-description macro @code{FRAME_POINTER_REQUIRED} controls
1071: whether a target machine supports this flag. @xref{Registers}.@refill
1072: @end ifset
1073: @ifclear INTERNALS
1074: On some machines, such as the Vax, this flag has no effect, because
1075: the standard calling sequence automatically handles the frame pointer
1076: and nothing is saved by pretending it doesn't exist. The
1077: machine-description macro @code{FRAME_POINTER_REQUIRED} controls
1078: whether a target machine supports this flag. @xref{Registers,,Register
1079: Usage, gcc.info, Using and Porting GCC}.@refill
1080: @end ifclear
1081:
1082: @item -finline
1083: Pay attention to the @code{inline} keyword. Normally the negation of this
1084: option @samp{-fno-inline} is used to keep the compiler from expanding
1085: any functions inline. However, the opposite effect may be desirable
1086: when compiling without optimization, since inline expansion is turned
1087: off in that case.
1088:
1089: @item -finline-functions
1090: Integrate all simple functions into their callers. The compiler
1091: heuristically decides which functions are simple enough to be worth
1092: integrating in this way.
1093:
1094: If all calls to a given function are integrated, and the function is
1095: declared @code{static}, then the function is normally not output as
1096: assembler code in its own right.
1097:
1098: @item -fcaller-saves
1099: Enable values to be allocated in registers that will be clobbered by
1100: function calls, by emitting extra instructions to save and restore the
1101: registers around such calls. Such allocation is done only when it
1102: seems to result in better code than would otherwise be produced.
1103:
1104: This option is enabled by default on certain machines, usually those
1105: which have no call-preserved registers to use instead.
1106:
1107: @item -fkeep-inline-functions
1108: Even if all calls to a given function are integrated, and the function
1109: is declared @code{static}, nevertheless output a separate run-time
1110: callable version of the function.
1111:
1112: @item -fno-function-cse
1113: Do not put function addresses in registers; make each instruction that
1114: calls a constant function contain the function's address explicitly.
1115:
1116: This option results in less efficient code, but some strange hacks
1117: that alter the assembler output may be confused by the optimizations
1118: performed when this option is not used.
1119: @end table
1120:
1121: The following options control specific optimizations. The @samp{-O2}
1122: option turns on all of these optimizations except @samp{-funroll-loops}
1123: and @samp{-funroll-all-loops}. The @samp{-O} option usually turns on
1124: the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options, but
1125: specific machines may change the default optimizations.
1126:
1127: You can use the following flags in the rare cases when ``fine-tuning''
1128: of optimizations to be performed is desired.
1129:
1130: @table @code
1131: @item -fstrength-reduce
1132: Perform the optimizations of loop strength reduction and
1133: elimination of iteration variables.
1134:
1135: @item -fthread-jumps
1136: Perform optimizations where we check to see if a jump branches to a
1137: location where another comparison subsumed by the first is found. If
1138: so, the first branch is redirected to either the destination of the
1139: second branch or a point immediately following it, depending on whether
1140: the condition is known to be true or false.
1141:
1142: @item -fcse-follow-jumps
1143: In common subexpression elimination, scan through jump instructions in
1144: certain cases. This is not as powerful as completely global CSE, but
1145: not as slow either.
1146:
1147: @item -frerun-cse-after-loop
1148: Re-run common subexpression elimination after loop optimizations has been
1149: performed.
1150:
1151: @item -fexpensive-optimizations
1152: Perform a number of minor optimizations that are relatively expensive.
1153:
1154: @item -fdelayed-branch
1155: If supported for the target machine, attempt to reorder instructions
1156: to exploit instruction slots available after delayed branch
1157: instructions.
1158:
1159: @item -fschedule-insns
1160: If supported for the target machine, attempt to reorder instructions to
1161: eliminate execution stalls due to required data being unavailable. This
1162: helps machines that have slow floating point or memory load instructions
1163: by allowing other instructions to be issued until the result of the load
1164: or floating point instruction is required.
1165:
1166: @item -fschedule-insns2
1167: Similar to @samp{-fschedule-insns}, but requests an additional pass of
1168: instruction scheduling after register allocation has been done. This is
1169: especially useful on machines with a relatively small number of
1170: registers and where memory load instructions take more than one cycle.
1171:
1172: @item -funroll-loops
1173: Perform the optimization of loop unrolling. This is only done for loops
1174: whose number of iterations can be determined at compile time or run time.
1175: @samp{-funroll-loop} implies @samp{-fstrength-reduce} and
1176: @samp{-frerun-cse-after-loop}.
1177:
1178: @item -funroll-all-loops
1179: Perform the optimization of loop unrolling. This is done for all loops
1180: and usually makes programs run more slowly. @samp{-funroll-all-loops}
1181: implies @samp{-fstrength-reduce} and @samp{-frerun-cse-after-loop}.
1182:
1183: @item -fno-peephole
1184: Disable any machine-specific peephole optimizations.
1185: @end table
1186:
1187: @node Preprocessor Options, Link Options, Optimize Options, Invoking GCC
1188: @section Options Controlling the Preprocessor
1189: @cindex preprocessor options
1190: @cindex options, preprocessor
1191:
1192: These options control the C preprocessor, which is run on each C source
1193: file before actual compilation.
1194:
1195: If you use the @samp{-E} option, nothing is done except preprocessing.
1196: Some of these options make sense only together with @samp{-E} because
1197: they cause the preprocessor output to be unsuitable for actual
1198: compilation.
1199:
1200: @table @code
1201: @item -include @var{file}
1202: Process @var{file} as input before processing the regular input file.
1203: In effect, the contents of @var{file} are compiled first. Any @samp{-D}
1204: and @samp{-U} options on the command line are always processed before
1205: @samp{-include @var{file}}, regardless of the order in which they are
1206: written. All the @samp{-include} and @samp{-imacros} options are
1207: processed in the order in which they are written.
1208:
1209: @item -imacros @var{file}
1210: Process @var{file} as input, discarding the resulting output, before
1211: processing the regular input file. Because the output generated from
1212: @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
1213: is to make the macros defined in @var{file} available for use in the
1214: main input.
1215:
1216: Any @samp{-D} and @samp{-U} options on the command line are always
1217: processed before @samp{-imacros @var{file}}, regardless of the order in
1218: which they are written. All the @samp{-include} and @samp{-imacros}
1219: options are processed in the order in which they are written.
1220:
1221: @item -nostdinc
1222: Do not search the standard system directories for header files. Only
1223: the directories you have specified with @samp{-I} options (and the
1224: current directory, if appropriate) are searched. @xref{Directory
1225: Options}, for information on @samp{-I}.
1226:
1227: By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
1228: search path to only those directories you specify explicitly.
1229:
1230: @item -undef
1231: Do not predefine any nonstandard macros. (Including architecture flags).
1232:
1233: @item -E
1234: Run only the C preprocessor. Preprocess all the C source files
1235: specified and output the results to standard output or to the
1236: specified output file.
1237:
1238: @item -C
1239: Tell the preprocessor not to discard comments. Used with the
1240: @samp{-E} option.
1241:
1242: @item -P
1243: Tell the preprocessor not to generate @samp{#line} commands.
1244: Used with the @samp{-E} option.
1245:
1246: @cindex make
1247: @cindex dependencies, make
1248: @item -M
1249: Tell the preprocessor to output a rule suitable for @code{make}
1250: describing the dependencies of each object file. For each source file,
1251: the preprocessor outputs one @code{make}-rule whose target is the object
1252: file name for that source file and whose dependencies are all the files
1253: @samp{#include}d in it. This rule may be a single line or may be
1254: continued with @samp{\}-newline if it is long. The list of rules is
1255: printed on standard output instead of the preprocessed C program.
1256:
1257: @samp{-M} implies @samp{-E}.
1258:
1259: Another way to specify output of a @code{make} rule is by setting
1260: the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
1261: Variables}).
1262:
1263: @item -MM
1264: Like @samp{-M} but the output mentions only the user header files
1265: included with @samp{#include "@var{file}"}. System header files
1266: included with @samp{#include <@var{file}>} are omitted.
1267:
1268: @item -MD
1269: Like @samp{-M} but the dependency information is written to files with
1270: names made by replacing @samp{.c} with @samp{.d} at the end of the
1271: input file names. This is in addition to compiling the file as
1272: specified---@samp{-MD} does not inhibit ordinary compilation the way
1273: @samp{-M} does.
1274:
1275: The Mach utility @samp{md} can be used to merge the @samp{.d} files
1276: into a single dependency file suitable for using with the @samp{make}
1277: command.
1278:
1279: @item -MMD
1280: Like @samp{-MD} except mention only user header files, not system
1281: header files.
1282:
1283: @item -H
1284: Print the name of each header file used, in addition to other normal
1285: activities.
1286:
1287: @item -D@var{macro}
1288: Define macro @var{macro} with the string @samp{1} as its definition.
1289:
1290: @item -D@var{macro}=@var{defn}
1291: Define macro @var{macro} as @var{defn}. All instances of @samp{-D} on
1292: the command line are processed before any @samp{-U} options.
1293:
1294: @item -U@var{macro}
1295: Undefine macro @var{macro}. @samp{-U} options are evaluated after all
1296: @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
1297: options.
1298:
1299: @item -dM
1300: Tell the preprocessor to output only a list of the macro definitions
1301: that are in effect at the end of preprocessing. Used with the @samp{-E}
1302: option.
1303:
1304: @item -dD
1305: Tell the preprocessing to pass all macro definitions into the output, in
1306: their proper sequence in the rest of the output.
1307:
1308: @item -dN
1309: Like @samp{-dD} except that the macro arguments and contents are omitted.
1310: Only @samp{#define @var{name}} is included in the output.
1311:
1312: @item -trigraphs
1313: Support ANSI C trigraphs. You don't want to know about this
1314: brain-damage. The @samp{-ansi} option also has this effect.
1315: @end table
1316:
1317: @node Link Options, Directory Options, Preprocessor Options, Invoking GCC
1318: @section Options for Linking
1319: @cindex link options
1320: @cindex options, linking
1321:
1322: These options come into play when the compiler links object files into
1323: an executable output file. They are meaningless if the compiler is
1324: not doing a link step.
1325:
1326: @table @code
1327: @cindex file names
1328: @item @var{object-file-name}
1329: A file name that does not end in a special recognized suffix is
1330: considered to name an object file or library. (Object files are
1331: distinguished from libraries by the linker according to the file
1332: contents.) If linking is done, these object files are used as input
1333: to the linker.
1334:
1335: @item -c
1336: @itemx -S
1337: @itemx -E
1338: If any of these options is used, then the linker is not run, and
1339: object file names should not be used as arguments. @xref{Overall
1340: Options}.
1341:
1342: @cindex Libraries
1343: @item -l@var{library}
1344: Search the library named @var{library} when linking.
1345:
1346: It makes a difference where in the command you write this option; the
1347: linker searches processes libraries and object files in the order they
1.1.1.2 ! root 1348: are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
1.1 root 1349: after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
1350: to functions in @samp{z}, those functions may not be loaded.
1351:
1352: The linker searches a standard list of directories for the library,
1353: which is actually a file named @file{lib@var{library}.a}. The linker
1354: then uses this file as if it had been specified precisely by name.
1355:
1356: The directories searched include several standard system directories
1357: plus any that you specify with @samp{-L}.
1358:
1359: Normally the files found this way are library files---archive files
1360: whose members are object files. The linker handles an archive file by
1361: scanning through it for members which define symbols that have so far
1362: been referenced but not defined. But if the file that is found is an
1363: ordinary object file, it is linked in the usual fashion. The only
1364: difference between using an @samp{-l} option and specifying a file name
1365: is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
1366: and searches several directories.
1367:
1368: @item -nostdlib
1369: Don't use the standard system libraries and startup files when linking.
1370: Only the files you specify will be passed to the linker.
1371:
1372: @item -static
1373: On systems that support dynamic linking, this prevents linking with the shared
1374: libraries. On other systems, this
1375: option has no effect.
1376:
1377: @item -shared
1378: Produce a shared object which can then be linked with other objects to
1379: form an executable. Only a few systems support this option.
1380:
1381: @item -symbolic
1382: Bind references to global symbols when building a shared object. Warn
1383: about any unresolved references (unless overridden by the link editor
1384: option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
1385: this option.
1386:
1387: @item -Xlinker @var{option}
1388: Pass @var{option} as an option to the linker. You can use this to
1389: supply system-specific linker options which GNU CC does not know how to
1390: recognize.
1391:
1392: If you want to pass an option that takes an argument, you must use
1393: @samp{-Xlinker} twice, once for the option and once for the argument.
1394: For example, to pass @samp{-assert definitions}, you must write
1395: @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
1396: @samp{-Xlinker "-assert definitions"}, because this passes the entire
1397: string as a single argument, which is not what the linker expects.
1398: @end table
1399:
1400: @node Directory Options, Target Options, Link Options, Invoking GCC
1401: @section Options for Directory Search
1402: @cindex directory options
1403: @cindex options, directory search
1404: @cindex search path
1405:
1406: These options specify directories to search for header files, for
1407: libraries and for parts of the compiler:
1408:
1409: @table @code
1410: @item -I@var{dir}
1411: Append directory @var{dir} to the list of directories searched for
1412: include files.
1413:
1414: @item -I-
1415: Any directories you specify with @samp{-I} options before the @samp{-I-}
1416: option are searched only for the case of @samp{#include "@var{file}"};
1417: they are not searched for @samp{#include <@var{file}>}.
1418:
1419: If additional directories are specified with @samp{-I} options after
1420: the @samp{-I-}, these directories are searched for all @samp{#include}
1421: directives. (Ordinarily @emph{all} @samp{-I} directories are used
1422: this way.)
1423:
1424: In addition, the @samp{-I-} option inhibits the use of the current
1425: directory (where the current input file came from) as the first search
1426: directory for @samp{#include "@var{file}"}. There is no way to
1427: override this effect of @samp{-I-}. With @samp{-I.} you can specify
1428: searching the directory which was current when the compiler was
1429: invoked. That is not exactly the same as what the preprocessor does
1430: by default, but it is often satisfactory.
1431:
1432: @samp{-I-} does not inhibit the use of the standard system directories
1433: for header files. Thus, @samp{-I-} and @samp{-nostdinc} are
1434: independent.
1435:
1436: @item -L@var{dir}
1437: Add directory @var{dir} to the list of directories to be searched
1438: for @samp{-l}.
1439:
1440: @item -B@var{prefix}
1441: This option specifies where to find the executables, libraries and
1442: data files of the compiler itself.
1443:
1444: The compiler driver program runs one or more of the subprograms
1445: @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
1446: @var{prefix} as a prefix for each program it tries to run, both with and
1447: without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
1448:
1449: For each subprogram to be run, the compiler driver first tries the
1450: @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
1451: was not specified, the driver tries two standard prefixes, which are
1.1.1.2 ! root 1452: @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of
1.1 root 1453: those results in a file name that is found, the unmodified program
1454: name is searched for using the directories specified in your
1455: @samp{PATH} environment variable.
1456:
1457: @samp{-B} prefixes that effectively specify directory names also apply
1458: to libraries in the linker, because the compiler translates these
1459: options into @samp{-L} options for the linker.
1460:
1461: The run-time support file @file{libgcc.a} can also be searched for using
1462: the @samp{-B} prefix, if needed. If it is not found there, the two
1463: standard prefixes above are tried, and that is all. The file is left
1464: out of the link if it is not found by those means.
1465:
1466: Another way to specify a prefix much like the @samp{-B} prefix is to use
1467: the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment
1468: Variables}.
1469: @end table
1470:
1471: @node Target Options, Submodel Options, Directory Options, Invoking GCC
1472: @section Specifying Target Machine and Compiler Version
1473: @cindex target options
1474: @cindex cross compiling
1475: @cindex specifying machine version
1476: @cindex specifying compiler version and target machine
1477: @cindex compiler version, specifying
1478: @cindex target machine, specifying
1479:
1480: By default, GNU CC compiles code for the same type of machine that you
1481: are using. However, it can also be installed as a cross-compiler, to
1482: compile for some other type of machine. In fact, several different
1483: configurations of GNU CC, for different target machines, can be
1484: installed side by side. Then you specify which one to use with the
1485: @samp{-b} option.
1486:
1487: In addition, older and newer versions of GNU CC can be installed side
1488: by side. One of them (probably the newest) will be the default, but
1489: you may sometimes wish to use another.
1490:
1491: @table @code
1492: @item -b @var{machine}
1493: The argument @var{machine} specifies the target machine for compilation.
1494: This is useful when you have installed GNU CC as a cross-compiler.
1495:
1496: The value to use for @var{machine} is the same as was specified as the
1497: machine type when configuring GNU CC as a cross-compiler. For
1498: example, if a cross-compiler was configured with @samp{configure
1499: i386v}, meaning to compile for an 80386 running System V, then you
1500: would specify @samp{-b i386v} to run that cross compiler.
1501:
1502: When you do not specify @samp{-b}, it normally means to compile for
1503: the same type of machine that you are using.
1504:
1505: @item -V @var{version}
1506: The argument @var{version} specifies which version of GNU CC to run.
1507: This is useful when multiple versions are installed. For example,
1508: @var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0.
1509:
1510: The default version, when you do not specify @samp{-V}, is controlled
1511: by the way GNU CC is installed. Normally, it will be a version that
1512: is recommended for general use.
1513: @end table
1514:
1515: The @samp{-b} and @samp{-V} options actually work by controlling part of
1516: the file name used for the executable files and libraries used for
1517: compilation. A given version of GNU CC, for a given target machine, is
1.1.1.2 ! root 1518: normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
1.1 root 1519:
1520: It follows that sites can customize the effect of @samp{-b} or @samp{-V}
1521: either by changing the names of these directories or adding
1522: alternate names (or symbolic links). Thus, if
1.1.1.2 ! root 1523: @file{/usr/local/lib/gcc-lib/80386} is a link to
! 1524: @file{/usr/local/lib/gcc-lib/i386v}, then @samp{-b 80386} will be an alias
1.1 root 1525: for @samp{-b i386v}.@refill
1526:
1527: In one respect, the @samp{-b} or @samp{-V} do not completely change
1528: to a different compiler: the top-level driver program @code{gcc}
1529: that you originally invoked continues to run and invoke the other
1530: executables (preprocessor, compiler per se, assembler and linker)
1531: that do the real work. However, since no real work is done in the
1532: driver program, it usually does not matter that the driver program
1533: in use is not the one for the specified target and version.
1534:
1535: The only way that the driver program depends on the target machine is
1536: in the parsing and handling of special machine-specific options.
1537: However, this is controlled by a file which is found, along with the
1538: other executables, in the directory for the specified version and
1539: target machine. As a result, a single installed driver program adapts
1540: to any specified target machine and compiler version.
1541:
1542: The driver program executable does control one significant thing,
1543: however: the default version and target machine. Therefore, you can
1544: install different instances of the driver program, compiled for
1545: different targets or versions, under different names.
1546:
1547: For example, if the driver for version 2.0 is installed as @code{ogcc}
1548: and that for version 2.1 is installed as @code{gcc}, then the command
1549: @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
1550: 2.0 by default. However, you can choose either version with either
1551: command with the @samp{-V} option.
1552:
1553: @node Submodel Options, Code Gen Options, Target Options, Invoking GCC
1554: @section Specifying Hardware Models and Configurations
1555: @cindex submodel options
1556: @cindex specifying hardware config
1557: @cindex hardware models and configurations, specifying
1558: @cindex machine dependent options
1559:
1560: Earlier we discussed the standard option @samp{-b} which chooses among
1561: different installed compilers for completely different target
1562: machines, such as Vax vs. 68000 vs. 80386.
1563:
1564: In addition, each of these target machine types can have its own
1565: special options, starting with @samp{-m}, to choose among various
1566: hardware models or configurations---for example, 68010 vs 68020,
1567: floating coprocessor or none. A single installed version of the
1568: compiler can compile for any model or configuration, according to the
1569: options specified.
1570:
1571: @ifset INTERNALS
1572: These options are defined by the macro @code{TARGET_SWITCHES} in the
1573: machine description. The default for the options is also defined by
1574: that macro, which enables you to change the defaults.
1575: @end ifset
1576:
1577: @menu
1578: * M680x0 Options::
1579: * VAX Options::
1580: * SPARC Options::
1581: * Convex Options::
1582: * AMD29K Options::
1583: * M88K Options::
1584: * RS/6000 Options::
1585: * RT Options::
1586: * MIPS Options::
1.1.1.2 ! root 1587: * i386 Options::
1.1 root 1588: @end menu
1589:
1590: @node M680x0 Options, Vax Options, Submodel Options, Submodel Options
1591: @subsection M680x0 Options
1592: @cindex M680x0 options
1593:
1594: These are the @samp{-m} options defined for the 68000 series. The default
1595: values for these options depends on which style of 68000 was selected when
1596: the compiler was configured; the defaults for the most common choices are
1597: given below.
1598:
1599: @table @code
1600: @item -m68020
1601: @itemx -mc68020
1602: Generate output for a 68020 (rather than a 68000). This is the
1603: default when the compiler is configured for 68020-based systems.
1604:
1605: @item -m68000
1606: @itemx -mc68000
1607: Generate output for a 68000 (rather than a 68020). This is the default
1608: when the compiler is configured for a 68000-based systems.
1609:
1610: @item -m68881
1611: Generate output containing 68881 instructions for floating point.
1612: This is the default for most 68020 systems unless @samp{-nfp} was
1613: specified when the compiler was configured.
1614:
1615: @item -mfpa
1616: Generate output containing Sun FPA instructions for floating point.
1617:
1618: @item -msoft-float
1619: Generate output containing library calls for floating point.
1620: @strong{Warning:} the requisite libraries are not part of GNU CC.
1621: Normally the facilities of the machine's usual C compiler are used, but
1622: this can't be done directly in cross-compilation. You must make your
1623: own arrangements to provide suitable library functions for
1624: cross-compilation.
1625:
1626: @item -mshort
1627: Consider type @code{int} to be 16 bits wide, like @code{short int}.
1628:
1629: @item -mnobitfield
1630: Do not use the bit-field instructions. @samp{-m68000} implies
1631: @samp{-mnobitfield}.
1632:
1633: @item -mbitfield
1634: Do use the bit-field instructions. @samp{-m68020} implies
1635: @samp{-mbitfield}. This is the default if you use the unmodified
1636: sources configured for a 68020.
1637:
1638: @item -mrtd
1639: Use a different function-calling convention, in which functions
1640: that take a fixed number of arguments return with the @code{rtd}
1641: instruction, which pops their arguments while returning. This
1642: saves one instruction in the caller since there is no need to pop
1643: the arguments there.
1644:
1645: This calling convention is incompatible with the one normally
1646: used on Unix, so you cannot use it if you need to call libraries
1647: compiled with the Unix compiler.
1648:
1649: Also, you must provide function prototypes for all functions that
1650: take variable numbers of arguments (including @code{printf});
1651: otherwise incorrect code will be generated for calls to those
1652: functions.
1653:
1654: In addition, seriously incorrect code will result if you call a
1655: function with too many arguments. (Normally, extra arguments are
1656: harmlessly ignored.)
1657:
1658: The @code{rtd} instruction is supported by the 68010 and 68020
1659: processors, but not by the 68000.
1660: @end table
1661:
1662: @node VAX Options, Sparc Options, M680x0 Options, Submodel Options
1663: @subsection VAX Options
1664: @cindex VAX options
1665:
1666: These @samp{-m} options are defined for the Vax:
1667:
1668: @table @code
1669: @item -munix
1670: Do not output certain jump instructions (@code{aobleq} and so on)
1671: that the Unix assembler for the Vax cannot handle across long
1672: ranges.
1673:
1674: @item -mgnu
1675: Do output those jump instructions, on the assumption that you
1676: will assemble with the GNU assembler.
1677:
1678: @item -mg
1679: Output code for g-format floating point numbers instead of d-format.
1680: @end table
1681:
1682: @node Sparc Options, Convex Options, Vax Options, Submodel Options
1683: @subsection SPARC Options
1684: @cindex SPARC options
1685:
1686: These @samp{-m} switches are supported on the Sparc:
1687:
1688: @table @code
1689: @ignore
1690: @item -mfpu
1691: Generate output containing floating point instructions. This is the
1692: default if you use the unmodified sources.
1693:
1694: @item -msoft-float
1695: Generate output containing library calls for floating point.
1696: @strong{Warning:} the requisite libraries are not part of GNU CC.
1697: Normally the facilities of the machine's usual C compiler are used, but
1698: this can't be done directly in cross-compilation. You must make your
1699: own arrangements to provide suitable library functions for
1700: cross-compilation.
1701: @end ignore
1.1.1.2 ! root 1702:
! 1703: @item -mforce-align
! 1704: Make sure all objects of type @code{double} are 8-byte aligned in memory
! 1705: and use double-word instructions to reference them.
! 1706:
1.1 root 1707: @item -mno-epilogue
1708: Generate separate return instructions for @code{return} statements.
1709: This has both advantages and disadvantages; I don't recall what they
1710: are.
1711: @end table
1712:
1713: @node Convex Options, AMD29K Options, SPARC Options, Submodel Options
1714: @subsection Convex Options
1715: @cindex Convex options
1716:
1717: These @samp{-m} options are defined for the Convex:
1718:
1719: @table @code
1720: @item -mc1
1721: Generate output for a C1. This is the default when the compiler is
1722: configured for a C1.
1723:
1724: @item -mc2
1725: Generate output for a C2. This is the default when the compiler is
1726: configured for a C2.
1727:
1728: @item -margcount
1729: Generate code which puts an argument count in the word preceding each
1730: argument list. Some nonportable Convex and Vax programs need this word.
1731: (Debuggers don't, except for functions with variable-length argument
1732: lists; this info is in the symbol table.)
1733:
1734: @item -mnoargcount
1735: Omit the argument count word. This is the default if you use the
1736: unmodified sources.
1737: @end table
1738:
1739: @node AMD29K Options, M88K Options, Convex Options, Submodel Options
1740: @subsection AMD29K Options
1741: @cindex AMD29K options
1742:
1743: These @samp{-m} options are defined for the AMD Am29000:
1744:
1745: @table @code
1746: @item -mdw
1747: Generate code that assumes the @code{DW} bit is set, i.e., that byte and
1748: halfword operations are directly supported by the hardware. This is the
1749: default.
1750:
1751: @item -mnodw
1752: Generate code that assumes the @code{DW} bit is not set.
1753:
1754: @item -mbw
1755: Generate code that assumes the system supports byte and halfword write
1756: operations. This is the default.
1757:
1758: @item -mnbw
1759: Generate code that assumes the systems does not support byte and
1760: halfword write operations. @samp{-mnbw} implies @samp{-mnodw}.
1761:
1762: @item -msmall
1763: Use a small memory model that assumes that all function addresses are
1764: either within a single 256 KB segment or at an absolute address of less
1765: than 256K. This allows the @code{call} instruction to be used instead
1766: of a @code{const}, @code{consth}, @code{calli} sequence.
1767:
1768: @item -mlarge
1769: Do not assume that the @code{call} instruction can be used; this is the
1770: default.
1771:
1772: @item -m29050
1773: Generate code for the Am29050.
1774:
1775: @item -m29000
1776: Generate code for the Am29000. This is the default.
1777:
1778: @item -mkernel-registers
1779: Generate references to registers @code{gr64-gr95} instead of
1780: @code{gr96-gr127}. This option can be used when compiling kernel code
1781: that wants a set of global registers disjoint from that used by
1782: user-mode code.
1783:
1784: Note that when this option is used, register names in @samp{-f} flags
1785: must use the normal, user-mode, names.
1786:
1787: @item -muser-registers
1788: Use the normal set of global registers, @code{gr96-gr127}. This is the
1789: default.
1790:
1791: @item -mstack-check
1792: Insert a call to @code{__msp_check} after each stack adjustment. This
1793: is often used for kernel code.
1794: @end table
1795:
1796: @node M88K Options, RS/6000 Options, AMD29K Options, Submodel Options
1797: @subsection M88K Options
1798: @cindex M88k options
1799:
1800: These @samp{-m} options are defined for Motorola 88K architectures:
1801:
1802: @table @code
1803: @item -m88000
1804: @kindex -m88000
1805: Generate code that works well on both the m88100 and the
1806: m88110.
1807:
1808: @item -m88100
1809: @kindex -m88100
1810: Generate code tha
1811: Generate code that works best for the m88100, but that also
1812: runs on the m88110.
1813:
1814: @item -m88110
1815: @kindex -m88110
1816: Generate code that works best for the m88110, and may not run
1817: on the m88100.
1818:
1819: @item -midentify-revision
1820: @kindex -midentify-revision
1821: @kindex ident
1822: @cindex identifying source, compiler (88k)
1823: Include an @code{ident} directive in the assembler output recording the
1824: source file name, compiler name and version, timestamp, and compilation
1825: flags used.
1826:
1827: @item -mno-underscores
1828: @kindex -mno-underscores
1829: @cindex underscores, avoiding (88k)
1830: In assembler output, emit symbol names without adding an underscore
1831: character at the beginning of each name. The default is to use an
1832: underscore as prefix on each name.
1833:
1834: @item -mocs-debug-info
1835: @itemx -mno-ocs-debug-info
1836: @kindex -mocs-debug-info
1837: @kindex -mno-ocs-debug-info
1838: @cindex OCS (88k)
1839: @cindex debugging, 88k OCS
1840: Include (or omit) additional debugging information (about registers used
1841: in each stack frame) as specified in the 88open Object Compatibility
1842: Standard, ``OCS''. This extra information allows debugging of code that
1843: has had the frame pointer eliminated. The default for DG/UX, SVr4, and
1844: Delta 88 SVr3.2 is to include this information; other 88k configurations
1845: omit this information by default.
1846:
1847: @item -mocs-frame-position
1848: @kindex -mocs-frame-position
1849: @cindex register positions in frame (88k)
1850: When emitting COFF debugging information for automatic variables and
1851: parameters stored on the stack, use the offset from the canonical frame
1852: address, which is the stack pointer (register 31) on entry to the
1853: function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
1854: @samp{-mocs-frame-position}; other 88k configurations have the default
1855: @samp{-mno-ocs-frame-position}.
1856:
1857: @item -mno-ocs-frame-position
1858: @kindex -mno-ocs-frame-position
1859: @cindex register positions in frame (88k)
1860: When emitting COFF debugging information for automatic variables and
1861: parameters stored on the stack, use the offset from the frame pointer
1862: register (register 30). When this option is in effect, the frame
1863: pointer is not eliminated when debugging information is selected by the
1864: -g switch.
1865:
1866: @item -moptimize-arg-area
1867: @itemx -mno-optimize-arg-area
1868: @kindex -moptimize-arg-area
1869: @kindex -mno-optimize-arg-area
1870: @cindex arguments in frame (88k)
1871: Control how to store function arguments in stack frames.
1872: @samp{-moptimize-arg-area} saves space, but was ruled illegal by 88open.
1873: @samp{-mno-optimize-arg-area} conforms to the 88open standards. By
1874: default GNU CC does not optimize the argument area.
1875:
1876: @item -mshort-data-@var{num}
1877: @kindex -mshort-data-@var{num}
1878: @cindex smaller data references (88k)
1879: @cindex r0-relative references (88k)
1880: Generate smaller data references by making them relative to @code{r0},
1881: which allows loading a value using a single instruction (rather than the
1882: usual two). You control which data references are affected by
1883: specifying @var{num} with this option. For example, if you specify
1884: @samp{-mshort-data-512}, then the data references affected are those
1885: involving displacements of less than 512 bytes.
1886: @samp{-mshort-data-@var{num}} is not effective for @var{num} greater
1887: than 64K.
1888:
1889: @item -msvr4
1890: @itemx -msvr3
1891: @kindex -msvr4
1892: @kindex -msvr3
1893: @cindex assembler syntax, 88k
1894: @cindex SVr4
1895: Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions
1896: related to System V release 4 (SVr4). This controls the following:
1897:
1898: @enumerate
1899: @item
1900: Which variant of the assembler syntax to emit (which you can select
1901: independently using @samp{-mversion-03.00}).
1902: @item
1903: @samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
1904: that is used on System V release 4.
1905: @item
1906: @samp{-msvr4} makes GNU CC issue additional declaration directives used in
1907: SVr4.
1908: @end enumerate
1909:
1910: @samp{-msvr3} is the default for all m88K configurations except
1911: the SVr4 configuration.
1912:
1913: @item -mversion-03.00
1914: @kindex -mversion-03.00
1915: In the DG/UX configuration, there are two flavors of SVr4. This option
1916: modifies @samp{-msvr4} to select whether the hybrid-COFF or real-ELF
1917: flavor is used. All other configurations ignore this option.
1918: @c ??? which asm syntax better for GAS? option there too?
1919:
1920: @item -mno-check-zero-division
1921: @itemx -mcheck-zero-division
1922: @kindex -mno-check-zero-divixion
1923: @kindex -mcheck-zero-division
1924: @cindex zero division on 88k
1925: Early models of the 88K architecture had problems with division by zero;
1926: in particular, many of them didn't trap. Use these options to avoid
1927: including (or to include explicitly) additional code to detect division
1928: by zero and signal an exception. All GNU CC configurations for the 88K use
1929: @samp{-mcheck-zero-division} by default.
1930:
1931: @item -muse-div-instruction
1932: @kindex -muse-div-instruction
1933: @cindex divide instruction, 88k
1934: Do not emit code to check both the divisor and dividend when doing
1935: signed integer division to see if either is negative, and adjust the
1936: signs so the divide is done using non-negative numbers. Instead, rely
1937: on the operating system to calculate the correct value when the
1938: @code{div} instruction traps. This results in different behavior when
1939: the most negative number is divided by -1, but is useful when most or
1940: all signed integer divisions are done with positive numbers.
1941:
1942: @item -mtrap-large-shift
1943: @itemx -mhandle-large-shift
1944: @kindex -mtrap-large-shift
1945: @kindex -mhandle-large-shift
1946: @cindex bit shift overflow (88k)
1947: @cindex large bit shifts (88k)
1948: Include code to detect bit-shifts of more than 31 bits; respectively,
1949: trap such shifts or emit code to handle them properly. By default GNU CC
1950: makes no special provision for large bit shifts.
1951:
1952: @item -mwarn-passed-structs
1953: @kindex -mwarn-passed-structs
1954: @cindex structure passing (88k)
1955: Warn when a function passes a struct as an argument or result.
1956: Structure-passing conventions have changed during the evolution of the C
1957: language, and are often the source of portability problems. By default,
1958: GNU CC issues no such warning.
1959: @end table
1960:
1961: @node RS/6000 Options, RT Options, M88K Options, Submodel Options
1962: @subsection IBM RS/6000 Options
1963: @cindex RS/6000 Options
1964: @cindex IBM RS/6000 Options
1965:
1966: Only one pair of @samp{-m} options is defined for the IBM RS/6000:
1967:
1968: @table @code
1969: @item -mfp-in-toc
1970: @itemx -mno-fp-in-toc
1971: Control whether or not floating-point constants go in the Table of
1972: Contents (TOC), a table of all global variable and function addresses. By
1973: default GNU CC puts floating-point constants there; if the TOC overflows,
1974: @samp{-mno-fp-in-toc} will reduce the size of the TOC, which may avoid
1975: the overflow.
1976: @end table
1977:
1978: @node RT Options, MIPS Options, RS/6000 Options, Submodel Options
1979: @subsection IBM RT Options
1980: @cindex RT options
1981: @cindex IBM RT options
1982:
1983: These @samp{-m} options are defined for the IBM RT PC:
1984:
1985: @table @code
1986: @item -min-line-mul
1987: Use an in-line code sequence for integer multiplies. This is the
1988: default.
1989:
1990: @item -mcall-lib-mul
1991: Call @code{lmul$$} for integer multiples.
1992:
1993: @item -mfull-fp-blocks
1994: Generate full-size floating point data blocks, including the minimum
1995: amount of scratch space recommended by IBM. This is the default.
1996:
1997: @item -mminimum-fp-blocks
1998: Do not include extra scratch space in floating point data blocks. This
1999: results in smaller code, but slower execution, since scratch space must
2000: be allocated dynamically.
2001:
2002: @cindex @file{varargs.h} and RT PC
2003: @cindex @file{stdarg.h} and RT PC
2004: @item -mfp-arg-in-fpregs
2005: Use a calling sequence incompatible with the IBM calling convention in
2006: which floating point arguments are passed in floating point registers.
2007: Note that @code{varargs.h} and @code{stdargs.h} will not work with
2008: floating point operands if this option is specified.
2009:
2010: @item -mfp-arg-in-gregs
2011: Use the normal calling convention for floating point arguments. This is
2012: the default.
2013:
2014: @item -mhc-struct-return
2015: Return structures of more than one word in memory, rather than in a
2016: register. This provides compatibility with the MetaWare HighC (hc)
2017: compiler. Use @samp{-fpcc-struct-return} for compatibility with the
2018: Portable C Compiler (pcc).
2019:
2020: @item -mnohc-struct-return
2021: Return some structures of more than one word in registers, when
2022: convenient. This is the default. For compatibility with the
2023: IBM-supplied compilers, use either @samp{-fpcc-struct-return} or
2024: @samp{-mhc-struct-return}.
2025: @end table
2026:
1.1.1.2 ! root 2027: @node MIPS Options, i386 Options, RT Options, Submodel Options
1.1 root 2028: @subsection MIPS Options
2029: @cindex MIPS options
2030:
2031: These @samp{-m} options are defined for the MIPS family of computers:
2032:
2033: @table @code
2034: @item -mcpu=@var{cpu type}
2035: Assume the defaults for the machine type @var{cpu type} when
1.1.1.2 ! root 2036: scheduling instructions. The default @var{cpu type} is
1.1 root 2037: @samp{default}, which picks the longest cycles times for any of the
2038: machines, in order that the code run at reasonable rates on all MIPS
2039: cpu's. Other choices for @var{cpu type} are @samp{r2000},
2040: @samp{r3000}, @samp{r4000}, and @samp{r6000}. While picking a
2041: specific @var{cpu type} will schedule things appropriately for that
2042: particular chip, the compiler will not generate any code that does not
2043: meet level 1 of the MIPS ISA (instruction set architecture) without
2044: the @samp{-mips2} or @samp{-mips3} switches being used.
2045:
2046: @item -mips2
2047: Issue instructions from level 2 of the MIPS ISA (branch likely, square
2048: root instructions). The @samp{-mcpu=r4000} or @samp{-mcpu=r6000}
2049: switch must be used in conjuction with @samp{-mips2}.
2050:
2051: @item -mips3
2052: Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
2053: You must use the @samp{-mcpu=r4000} switch along with @samp{-mips3}.
2054:
2055: @item -mint64
2056: @item -mlong64
2057: @item -mlonglong128
2058: These options don't work at present.
2059:
2060: @item -mmips-as
2061: Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
2062: add normal debug information. This is the default for all
2063: platforms except for the OSF/1 reference platform, using the OSF/rose
2064: object format. If the either of the @samp{-gstabs} or @samp{-gstabs+}
2065: switches are used, the @file{mips-tfile} program will encapsulate the
2066: stabs within MIPS ECOFF.
2067:
2068: @item -mgas
2069: Generate code for the GNU assembler. This is the default on the OSF/1
2070: reference platform, using the OSF/rose object format.
2071:
2072: @item -mrnames
2073: @itemx -mno-rnames
2074: The @samp{-mrnames} switch says to output code using the MIPS software
2075: names for the registers, instead of the hardware names (ie, @var{a0}
2076: instead of @var{$4}). The GNU assembler does not support the
2077: @samp{-mrnames} switch, and the MIPS assembler will be instructed to
2078: run the MIPS C preprocessor over the source file. The
2079: @samp{-mno-rnames} switch is default.
2080:
2081: @item -mgpopt
2082: @itemx -mno-gpopt
2083: The @samp{-mgpopt} switch says to write all of the data declarations
1.1.1.2 ! root 2084: before the instructions in the text section, this allows the MIPS
! 2085: assembler to generate one word memory references instead of using two
! 2086: words for short global or static data items. This is on by default if
1.1 root 2087: optimization is selected.
2088:
2089: @item -mstats
2090: @itemx -mno-stats
2091: For each non-inline function processed, the @samp{-mstats} switch
2092: causes the compiler to emit one line to the standard error file to
2093: print statistics about the program (number of registers saved, stack
2094: size, etc.).
2095:
2096: @item -mmemcpy
2097: @itemx -mno-memcpy
2098: The @samp{-mmemcpy} switch makes all block moves call the appropriate
2099: string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
2100: generating inline code.
2101:
2102: @item -mmips-tfile
2103: @itemx -mno-mips-tfile
2104: The @samp{-mno-mips-tfile} switch causes the compiler not
2105: postprocess the object file with the @file{mips-tfile} program,
2106: after the MIPS assembler has generated it to add debug support. If
2107: @file{mips-tfile} is not run, then no local variables will be
2108: available to the debugger. In addition, @file{stage2} and
2109: @file{stage3} objects will have the temporary file names passed to the
2110: assembler embedded in the object file, which means the objects will
1.1.1.2 ! root 2111: not compare the same. The @samp{-mno-mips-tfile} switch should only
! 2112: be used when there are bugs in the @file{mips-tfile} program that
! 2113: prevents compilation.
1.1 root 2114:
2115: @item -msoft-float
2116: Generate output containing library calls for floating point.
2117: @strong{Warning:} the requisite libraries are not part of GNU CC.
2118: Normally the facilities of the machine's usual C compiler are used, but
2119: this can't be done directly in cross-compilation. You must make your
2120: own arrangements to provide suitable library functions for
2121: cross-compilation.
2122:
2123: @item -mhard-float
2124: Generate output containing floating point instructions. This is the
2125: default if you use the unmodified sources.
2126:
2127: @item -mfp64
2128: Assume that the @var{FR} bit in the status word is on, and that there
2129: are 32 64-bit floating point registers, instead of 32 32-bit floating
2130: point registers. You must also specify the @samp{-mcpu=r4000} and
2131: @samp{-mips3} switches.
2132:
2133: @item -mfp32
2134: Assume that there are 32 32-bit floating point registers. This is the
2135: default.
2136:
2137: @item -mabicalls
2138: @itemx -mno-abicalls
2139: Emit the @samp{.abicalls}, @samp{.cpload}, and @samp{.cprestore}
2140: pseudo operations that some System V.4 ports use for position
2141: independent code.
2142:
2143: @item -mhalf-pic
2144: @itemx -mno-half-pic
2145: Put pointers to extern references into the data section and load them
2146: up, rather than put the references in the text section. These options
2147: do not work at present.
2148:
2149: @item -G @var{num}
2150: @cindex smaller data references (MIPS)
2151: @cindex gp-relative references (MIPS)
2152: Put global and static items less than or equal to @var{num} bytes into
2153: the small data or bss sections instead of the normal data or bss
2154: section. This allows the assembler to emit one word memory reference
2155: instructions based on the global pointer (@var{gp} or @var{$28}),
2156: instead of the normal two words used. By default, @var{num} is 8 when
2157: the MIPS assembler is used, and 0 when the GNU assembler is used. The
2158: @samp{-G @var{num}} switch is also passed to the assembler and linker.
1.1.1.2 ! root 2159: All modules should be compiled with the same @samp{-G @var{num}}
! 2160: value.
! 2161:
! 2162: @item -nocpp
! 2163: Tell the MIPS assembler to not run it's preprocessor over user
! 2164: assembler files (with a @samp{.s} suffix) when assembling them.
1.1 root 2165: @end table
2166:
2167: @ifset INTERNALS
2168: These options are defined by the macro
2169: @code{TARGET_SWITCHES} in the machine description. The default for the
2170: options is also defined by that macro, which enables you to change the
2171: defaults.
2172: @end ifset
2173:
1.1.1.2 ! root 2174: @node i386 Options, , MIPS Options, Submodel Options
! 2175: @subsection Intel 386 Options
! 2176: @cindex i386 Options
! 2177: @cindex Intel 386 Options
! 2178:
! 2179: These @samp{-m} options are defined for the i386 family of computers:
! 2180:
! 2181: @table @code
! 2182: @item -m486
! 2183: @itemx -mno486
! 2184: Control whether or not code is optimized for a 486 instead of an
! 2185: 386. Code generated for an 486 will run on a 386 and vice versa.
! 2186:
! 2187: @item -msoft-float
! 2188: Generate output containing library calls for floating point.
! 2189: @strong{Warning:} the requisite libraries are not part of GNU CC.
! 2190: Normally the facilities of the machine's usual C compiler are used, but
! 2191: this can't be done directly in cross-compilation. You must make your
! 2192: own arrangements to provide suitable library functions for
! 2193: cross-compilation.
! 2194:
! 2195: On machines where a function returnings float point results in the 80387
! 2196: register stack, some floating point opcodes may be emitted even if
! 2197: @samp{-msoft-float} is used.
! 2198: @end table
! 2199:
1.1 root 2200: @node Code Gen Options, Environment Variables, Submodel Options, Invoking GCC
2201: @section Options for Code Generation Conventions
2202: @cindex code generation conventions
2203: @cindex options, code generation
2204: @cindex run-time options
2205:
2206: These machine-independent options control the interface conventions
2207: used in code generation.
2208:
2209: Most of them have both positive and negative forms; the negative form
2210: of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only
2211: one of the forms is listed---the one which is not the default. You
2212: can figure out the other form by either removing @samp{no-} or adding
2213: it.
2214:
2215: @table @code
2216: @item -fpcc-struct-return
2217: Use the same convention for returning @code{struct} and @code{union}
2218: values that is used by the usual C compiler on your system. This
2219: convention is less efficient for small structures, and on many
2220: machines it fails to be reentrant; but it has the advantage of
2221: allowing intercallability between GNU CC-compiled code and PCC-compiled
2222: code.
2223:
2224: @item -fshort-enums
2225: Allocate to an @code{enum} type only as many bytes as it needs for the
2226: declared range of possible values. Specifically, the @code{enum} type
2227: will be equivalent to the smallest integer type which has enough room.
2228:
2229: @item -fshort-double
2230: Use the same size for @code{double} as for @code{float}.
2231:
2232: @item -fshared-data
2233: Requests that the data and non-@code{const} variables of this
2234: compilation be shared data rather than private data. The distinction
2235: makes sense only on certain operating systems, where shared data is
2236: shared between processes running the same program, while private data
2237: exists in one copy per process.
2238:
2239: @item -fno-common
2240: Allocate even uninitialized global variables in the bss section of the
2241: object file, rather than generating them as common blocks. This has the
2242: effect that if the same variable is declared (without @code{extern}) in
2243: two different compilations, you will get an error when you link them.
2244: The only reason this might be useful is if you wish to verify that the
2245: program will work on other systems which always work this way.
2246:
2247: @item -fno-ident
2248: Ignore the @samp{#ident} directive.
2249:
2250: @item -fno-gnu-linker
2251: Don't output global initializations such as C++ constructors and
2252: destructors in the form used by the GNU linker (on systems where the GNU
2253: linker is the standard method of handling them). Use this option when
2254: you want to use a ``collect'' program and a non-GNU linker.
2255:
2256: @item -finhibit-size-directive
2257: Don't output a @code{.size} assembler directive, or anything else that
2258: would cause trouble if the function is split in the middle, and the
2259: two halves are placed at locations far apart in memory. This option is
2260: used when compiling @file{crtstuff.c}; you should not need to use it
2261: for anything else.
2262:
2263: @item -fvolatile
2264: Consider all memory references through pointers to be volatile.
2265:
2266: @item -fpic
2267: @cindex global offset table
2268: If supported for the target machines, generate position-independent
2269: code, suitable for use in a shared library. All addresses will be
2270: accessed through a global offset table (GOT). If the GOT size for the
2271: linked executable exceeds a machine-specific maximum size, you will get
2272: an error message from the linker indicating that @samp{-fpic} does not
2273: work; recompile with @samp{-fPIC} instead. (These maximums are 16k on
2274: the m88k, 8k on the Sparc, and 32k on the m68k and RS/6000. The 386 has
2275: no such limit.)
2276:
2277: Position-independent code requires special support, and therefore works
2278: only on certain machines. Code generated for the IBM RS/6000 is always
2279: position-independent.
2280:
1.1.1.2 ! root 2281: The GNU assembler does not fully support PIC. Currently, you must use
! 2282: some other assembler in order for PIC to work. We would welcome
! 2283: volunteers to upgrade GAS to handle this; the first part of the job is
! 2284: to figure out what the assembler must do differently.
! 2285:
1.1 root 2286: @item -fPIC
2287: If supported for the target machine, emit position-independent code,
2288: suitable for dynamic linking and avoiding any limit on the size of the
2289: global offset table. This option makes a difference on the m68k, m88k
2290: and the Sparc.
2291:
2292: Position-independent code requires special support, and therefore works
2293: only on certain machines.
2294:
2295: @item -ffixed-@var{reg}
2296: Treat the register named @var{reg} as a fixed register; generated code
2297: should never refer to it (except perhaps as a stack pointer, frame
2298: pointer or in some other fixed role).
2299:
2300: @var{reg} must be the name of a register. The register names accepted
2301: are machine-specific and are defined in the @code{REGISTER_NAMES}
2302: macro in the machine description macro file.
2303:
2304: This flag does not have a negative form, because it specifies a
2305: three-way choice.
2306:
2307: @item -fcall-used-@var{reg}
2308: Treat the register named @var{reg} as an allocatable register that is
2309: clobbered by function calls. It may be allocated for temporaries or
2310: variables that do not live across a call. Functions compiled this way
2311: will not save and restore the register @var{reg}.
2312:
2313: Use of this flag for a register that has a fixed pervasive role in the
2314: machine's execution model, such as the stack pointer or frame pointer,
2315: will produce disastrous results.
2316:
2317: This flag does not have a negative form, because it specifies a
2318: three-way choice.
2319:
2320: @item -fcall-saved-@var{reg}
2321: Treat the register named @var{reg} as an allocatable register saved by
2322: functions. It may be allocated even for temporaries or variables that
2323: live across a call. Functions compiled this way will save and restore
2324: the register @var{reg} if they use it.
2325:
2326: Use of this flag for a register that has a fixed pervasive role in the
2327: machine's execution model, such as the stack pointer or frame pointer,
2328: will produce disastrous results.
2329:
2330: A different sort of disaster will result from the use of this flag for
2331: a register in which function values may be returned.
2332:
2333: This flag does not have a negative form, because it specifies a
2334: three-way choice.
2335: @end table
2336:
2337: @node Environment Variables,, Code Gen Options, Invoking GCC
2338: @section Environment Variables Affecting GNU CC
2339: @cindex environment variables
2340:
2341: This section describes several environment variables that affect how GNU
2342: CC operates. They work by specifying directories or prefixes to use
2343: when searching for various kinds of files.
2344:
2345: @ifclear INTERNALS
2346: Note that you can also specify places to search using options such as
2347: @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
2348: take precedence over places specified using environment variables, which
2349: in turn take precedence over those specified by the configuration of GNU
2350: CC.
2351: @end ifclear
2352: @ifset INTERNALS
2353: Note that you can also specify places to search using options such as
2354: @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These
2355: take precedence over places specified using environment variables, which
2356: in turn take precedence over those specified by the configuration of GNU
2357: CC. @xref{Driver}.
2358: @end ifset
2359:
2360: @table @code
2361: @item TMPDIR
2362: @findex TMPDIR
2363: If @code{TMPDIR} is set, it specifies the directory to use for temporary
2364: files. GNU CC uses temporary files to hold the output of one stage of
2365: compilation which is to be used as input to the next stage: for example,
2366: the output of the preprocessor, which is the input to the compiler
2367: proper.
2368:
2369: @item GCC_EXEC_PREFIX
2370: @findex GCC_EXEC_PREFIX
2371: If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
2372: names of the subprograms executed by the compiler. No slash is added
2373: when this prefix is combined with the name of a subprogram, but you can
2374: specify a prefix that ends with a slash if you wish.
2375:
2376: If GNU CC cannot find the subprogram using the specified prefix, it
2377: tries looking in the usual places for the subprogram.
2378:
2379: Other prefixes specified with @samp{-B} take precedence over this prefix.
2380:
2381: This prefix is also used for finding files such as @file{crt0.o} that are
2382: used for linking.
2383:
2384: In addition, the prefix is used in an unusual way in finding the
2385: directories to search for header files. For each of the standard
1.1.1.2 ! root 2386: directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
1.1 root 2387: (more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries
2388: replacing that beginning with the specified prefix to produce an
2389: alternate directory name. Thus, with @samp{-Bfoo/}, GNU CC will search
2390: @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
2391: These alternate directories are searched first; the standard directories
2392: come next.
2393:
2394: @item COMPILER_PATH
2395: @findex COMPILER_PATH
2396: The value of @code{COMPILER_PATH} is a colon-separated list of
2397: directories, much like @code{PATH}. GNU CC tries the directories thus
2398: specified when searching for subprograms, if it can't find the
2399: subprograms using @code{GCC_EXEC_PREFIX}.
2400:
2401: @item LIBRARY_PATH
2402: @findex LIBRARY_PATH
2403: The value of @code{LIBRARY_PATH} is a colon-separated list of
2404: directories, much like @code{PATH}. GNU CC tries the directories thus
2405: specified when searching for special linker files, if it can't find them
2406: using @code{GCC_EXEC_PREFIX}. Linking using GNU CC also uses these
2407: directories when searching for ordinary libraries for the @samp{-l}
2408: option (but directories specified with @samp{-L} come first).
2409:
2410: @item C_INCLUDE_PATH
1.1.1.2 ! root 2411: @itemx CPLUS_INCLUDE_PATH
1.1 root 2412: @itemx OBJC_INCLUDE_PATH
2413: @findex C_INCLUDE_PATH
1.1.1.2 ! root 2414: @findex CPLUS_INCLUDE_PATH
1.1 root 2415: @findex OBJC_INCLUDE_PATH
1.1.1.2 ! root 2416: @c @itemx OBJCPLUS_INCLUDE_PATH
1.1 root 2417: These environment variables pertain to particular languages. Each
2418: variable's value is a colon-separated list of directories, much like
2419: @code{PATH}. When GNU CC searches for header files, it tries the
2420: directories listed in the variable for the language you are using, after
2421: the directories specified with @samp{-I} but before the standard header
2422: file directories.
2423:
2424: @item DEPENDENCIES_OUTPUT
2425: @findex DEPENDENCIES_OUTPUT
2426: @cindex dependencies for make as output
2427: If this variable is set, its value specifies how to output dependencies
2428: for Make based on the header files processed by the compiler. This
2429: output looks much like the output from the @samp{-M} option
2430: (@pxref{Preprocessor Options}), but it goes to a separate file, and is
2431: in addition to the usual results of compilation.
2432:
2433: The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
2434: which case the Make rules are written to that file, guessing the target
2435: name from the source file name. Or the value can have the form
2436: @samp{@var{file} @var{target}}, in which case the rules are written to
2437: file @var{file} using @var{target} as the target name.
2438: @end table
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.