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