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