OSDN Git Service

0f32b02433de8492d4a933d0f116031f463fce7e
[pf3gnuchains/gcc-fork.git] / gcc / invoke.texi
1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 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 @ignore
6 @c man begin COPYRIGHT
7 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997,
8 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
9
10 Permission is granted to make and distribute verbatim copies of this
11 manual provided the copyright notice and this permission notice are
12 preserved on all copies.
13
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided also that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
18
19 Permission is granted to copy and distribute translations of this manual
20 into another language, under the above conditions for modified versions,
21 except that this permission notice may be included in translations
22 approved by the Free Software Foundation instead of in the original
23 English.
24 @c man end
25 @c Set file name and title for the man page.
26 @setfilename gcc
27 @settitle GNU project C and C++ compiler
28 @c man begin SYNOPSIS
29 gcc [@samp{-c}|@samp{-S}|@samp{-E}] [@samp{-std=}@var{standard}]
30     [@samp{-g}] [@samp{-pg}] [@samp{-O}@var{level}]
31     [@samp{-W}@var{warn}...] [@samp{-pedantic}]
32     [@samp{-I}@var{dir}...] [@samp{-L}@var{dir}...]
33     [@samp{-D}@var{macro}[=@var{defn}]...] [@samp{-U}@var{macro}]
34     [@samp{-f}@var{option}...] [@samp{-m}@var{machine-option}...]
35     [@samp{-o} @var{outfile}] @var{infile}...
36
37 Only the most useful options are listed here; see below for the
38 remainder.  @samp{g++} accepts mostly the same options as @samp{gcc}.
39 @c man end
40 @c man begin SEEALSO
41 cpp(1), gcov(1), g77(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
42 and the Info entries for @file{gcc}, @file{cpp}, @file{g77}, @file{as},
43 @file{ld}, @file{binutils} and @file{gdb}.
44 @c man end
45 @end ignore
46
47 @node Invoking GCC
48 @chapter GCC Command Options
49 @cindex GCC command options
50 @cindex command options
51 @cindex options, GCC command
52
53 @c man begin DESCRIPTION
54
55 When you invoke GCC, it normally does preprocessing, compilation,
56 assembly and linking.  The ``overall options'' allow you to stop this
57 process at an intermediate stage.  For example, the @samp{-c} option
58 says not to run the linker.  Then the output consists of object files
59 output by the assembler.
60
61 Other options are passed on to one stage of processing.  Some options
62 control the preprocessor and others the compiler itself.  Yet other
63 options control the assembler and linker; most of these are not
64 documented here, since you rarely need to use any of them.
65
66 @cindex C compilation options
67 Most of the command line options that you can use with GCC are useful
68 for C programs; when an option is only useful with another language
69 (usually C++), the explanation says so explicitly.  If the description
70 for a particular option does not mention a source language, you can use
71 that option with all supported languages.
72
73 @cindex C++ compilation options
74 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
75 options for compiling C++ programs.
76
77 @cindex grouping options
78 @cindex options, grouping
79 The @code{gcc} program accepts options and file names as operands.  Many
80 options have multi-letter names; therefore multiple single-letter options
81 may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d
82 -r}}.
83
84 @cindex order of options
85 @cindex options, order
86 You can mix options and other arguments.  For the most part, the order
87 you use doesn't matter.  Order does matter when you use several options
88 of the same kind; for example, if you specify @samp{-L} more than once,
89 the directories are searched in the order specified.
90
91 Many options have long names starting with @samp{-f} or with
92 @samp{-W}---for example, @samp{-fforce-mem},
93 @samp{-fstrength-reduce}, @samp{-Wformat} and so on.  Most of
94 these have both positive and negative forms; the negative form of
95 @samp{-ffoo} would be @samp{-fno-foo}.  This manual documents
96 only one of these two forms, whichever one is not the default.
97
98 @c man end
99
100 @menu
101 * Option Summary::      Brief list of all options, without explanations.
102 * Overall Options::     Controlling the kind of output:
103                         an executable, object files, assembler files,
104                         or preprocessed source.
105 * Invoking G++::        Compiling C++ programs.
106 * C Dialect Options::   Controlling the variant of C language compiled.
107 * C++ Dialect Options:: Variations on C++.
108 * Language Independent Options:: Controlling how diagnostics should be
109                         formatted. 
110 * Warning Options::     How picky should the compiler be?
111 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
112 * Optimize Options::    How much optimization?
113 * Preprocessor Options:: Controlling header files and macro definitions.
114                          Also, getting dependency information for Make.
115 * Assembler Options::   Passing options to the assembler.
116 * Link Options::        Specifying libraries and so on.
117 * Directory Options::   Where to find header files and libraries.
118                         Where to find the compiler executable files.
119 * Spec Files::          How to pass switches to sub-processes.
120 * Target Options::      Running a cross-compiler, or an old version of GCC.
121 * Submodel Options::    Specifying minor hardware or convention variations,
122                         such as 68010 vs 68020.
123 * Code Gen Options::    Specifying conventions for function calls, data layout
124                         and register usage.
125 * Environment Variables:: Env vars that affect GCC.
126 * Running Protoize::    Automatically adding or removing function prototypes.
127 @end menu
128
129 @node Option Summary
130 @section Option Summary
131
132 Here is a summary of all the options, grouped by type.  Explanations are
133 in the following sections.
134
135 @table @emph
136 @item Overall Options
137 @xref{Overall Options,,Options Controlling the Kind of Output}.
138 @smallexample
139 -c  -S  -E  -o @var{file}  -pipe  -pass-exit-codes  -x @var{language}
140 -v  --target-help  --help
141 @end smallexample
142
143 @item C Language Options
144 @xref{C Dialect Options,,Options Controlling C Dialect}.
145 @smallexample
146 -ansi  -std=@var{standard}  -fno-asm  -fno-builtin
147 -fhosted  -ffreestanding
148 -trigraphs  -traditional  -traditional-cpp
149 -fallow-single-precision  -fcond-mismatch
150 -fsigned-bitfields  -fsigned-char
151 -funsigned-bitfields  -funsigned-char
152 -fwritable-strings  -fshort-wchar
153 @end smallexample
154
155 @item C++ Language Options
156 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
157 @smallexample
158 -fno-access-control  -fcheck-new  -fconserve-space
159 -fdollars-in-identifiers  -fno-elide-constructors
160 -fno-enforce-eh-specs  -fexternal-templates
161 -falt-external-templates
162 -ffor-scope  -fno-for-scope  -fno-gnu-keywords  -fhonor-std
163 -fhuge-objects  -fno-implicit-templates
164 -fno-implicit-inline-templates
165 -fno-implement-inlines  -fms-extensions
166 -fname-mangling-version-@var{n}  -fno-operator-names
167 -fno-optional-diags  -fpermissive
168 -frepo  -fno-rtti  -fsquangle  -ftemplate-depth-@var{n}
169 -fuse-cxa-atexit  -fvtable-thunks  -nostdinc++
170 -fno-default-inline  -Wctor-dtor-privacy
171 -Wnon-virtual-dtor  -Wreorder
172 -Weffc++  -Wno-deprecated
173 -Wno-non-template-friend  -Wold-style-cast
174 -Woverloaded-virtual  -Wno-pmf-conversions
175 -Wsign-promo  -Wsynth
176 @end smallexample
177
178 @item Language Independent Options
179 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
180 @smallexample
181 -fmessage-length=@var{n} 
182 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}
183 @end smallexample
184
185 @item Warning Options
186 @xref{Warning Options,,Options to Request or Suppress Warnings}.
187 @smallexample
188 -fsyntax-only  -pedantic  -pedantic-errors
189 -w  -W  -Wall  -Waggregate-return
190 -Wcast-align  -Wcast-qual  -Wchar-subscripts  -Wcomment
191 -Wconversion  -Wdisabled-optimization -Werror
192 -Wfloat-equal  -Wformat  -Wformat=2
193 -Wformat-nonliteral -Wformat-security
194 -Wid-clash-@var{len}  -Wimplicit -Wimplicit-int 
195 -Wimplicit-function-declaration
196 -Werror-implicit-function-declaration
197 -Wimport  -Winline
198 -Wlarger-than-@var{len}  -Wlong-long
199 -Wmain  -Wmissing-declarations
200 -Wmissing-format-attribute  -Wmissing-noreturn
201 -Wmultichar  -Wno-format-extra-args -Wno-format-y2k
202 -Wno-import  -Wpacked  -Wpadded
203 -Wparentheses -Wpointer-arith  -Wredundant-decls
204 -Wreturn-type  -Wsequence-point  -Wshadow
205 -Wsign-compare  -Wswitch  -Wsystem-headers
206 -Wtrigraphs  -Wundef  -Wuninitialized
207 -Wunknown-pragmas  -Wunreachable-code
208 -Wunused  -Wunused-function  -Wunused-label  -Wunused-parameter
209 -Wunused-value  -Wunused-variable  -Wwrite-strings
210 @end smallexample
211
212 @item C-only Warning Options
213 @smallexample
214 -Wbad-function-cast -Wmissing-prototypes -Wnested-externs
215 -Wstrict-prototypes -Wtraditional
216 @end smallexample
217
218 @item Debugging Options
219 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
220 @smallexample
221 -a  -ax  -d@var{letters}  -fdump-unnumbered -fdump-translation-unit-@var{file}
222 -fpretend-float -fprofile-arcs  -ftest-coverage
223 -g  -g@var{level}  -gcoff  -gdwarf  -gdwarf-1  -gdwarf-1+  -gdwarf-2
224 -ggdb  -gstabs  -gstabs+  -gxcoff  -gxcoff+
225 -p  -pg  -print-file-name=@var{library}  -print-libgcc-file-name
226 -print-prog-name=@var{program}  -print-search-dirs  -Q
227 -save-temps  -time
228 @end smallexample
229
230 @item Optimization Options
231 @xref{Optimize Options,,Options that Control Optimization}.
232 @smallexample
233 -falign-functions=@var{n}  -falign-jumps=@var{n}
234 -falign-labels=@var{n}  -falign-loops=@var{n} 
235 -fbranch-probabilities  -fcaller-saves
236 -fcse-follow-jumps  -fcse-skip-blocks  -fdata-sections  -fdce
237 -fdelayed-branch  -fdelete-null-pointer-checks
238 -fexpensive-optimizations  -ffast-math  -ffloat-store
239 -fforce-addr  -fforce-mem  -ffunction-sections  -fgcse 
240 -finline-functions  -finline-limit=@var{n}  -fkeep-inline-functions
241 -fkeep-static-consts  -fmove-all-movables
242 -fno-default-inline  -fno-defer-pop
243 -fno-function-cse  -fno-inline  -fno-math-errno  -fno-peephole
244 -fomit-frame-pointer  -foptimize-register-move
245 -foptimize-sibling-calls  -freduce-all-givs
246 -fregmove  -frename-registers
247 -frerun-cse-after-loop  -frerun-loop-opt
248 -fschedule-insns  -fschedule-insns2
249 -fsingle-precision-constant  -fssa
250 -fstrength-reduce  -fstrict-aliasing  -fthread-jumps  -ftrapv
251 -funroll-all-loops  -funroll-loops 
252 -O  -O0  -O1  -O2  -O3  -Os
253 @end smallexample
254
255 @item Preprocessor Options
256 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
257 @smallexample
258 -$  -A@var{question}=@var{answer}  -A-@var{question}[=@var{answer}]
259 -C  -dD  -dI  -dM  -dN
260 -D@var{macro}@r{[}=@var{defn}@r{]}  -E  -H
261 -idirafter @var{dir}
262 -include @var{file}  -imacros @var{file}
263 -iprefix @var{file}  -iwithprefix @var{dir}
264 -iwithprefixbefore @var{dir}  -isystem @var{dir} -isystem-c++ @var{dir}
265 -M  -MM  -MF  -MG  -MP  -MQ  -MT  -nostdinc  -P  -remap
266 -trigraphs  -undef  -U@var{macro}  -Wp,@var{option}
267 @end smallexample
268
269 @item Assembler Option
270 @xref{Assembler Options,,Passing Options to the Assembler}.
271 @smallexample
272 -Wa,@var{option}
273 @end smallexample
274
275 @item Linker Options
276 @xref{Link Options,,Options for Linking}.
277 @smallexample
278 @var{object-file-name}  -l@var{library}
279 -nostartfiles  -nodefaultlibs  -nostdlib
280 -s  -static  -static-libgcc  -shared  -shared-libgcc  -symbolic
281 -Wl,@var{option}  -Xlinker @var{option}
282 -u @var{symbol}
283 @end smallexample
284
285 @item Directory Options
286 @xref{Directory Options,,Options for Directory Search}.
287 @smallexample
288 -B@var{prefix}  -I@var{dir}  -I-  -L@var{dir}  -specs=@var{file}
289 @end smallexample
290
291 @item Target Options
292 @c I wrote this xref this way to avoid overfull hbox. -- rms
293 @xref{Target Options}.
294 @smallexample
295 -b @var{machine}  -V @var{version}
296 @end smallexample
297
298 @item Machine Dependent Options
299 @xref{Submodel Options,,Hardware Models and Configurations}.
300 @smallexample
301 @emph{M680x0 Options}
302 -m68000  -m68020  -m68020-40  -m68020-60  -m68030  -m68040
303 -m68060  -mcpu32 -m5200  -m68881  -mbitfield  -mc68000  -mc68020  
304 -mfpa -mnobitfield  -mrtd  -mshort  -msoft-float  -mpcrel
305 -malign-int -mstrict-align
306
307 @emph{M68hc1x Options}
308 -m6811  -m6812  -m68hc11  -m68hc12
309 -mauto-incdec  -mshort  -msoft-reg-count=@var{count}
310
311 @emph{VAX Options}
312 -mg  -mgnu  -munix
313
314 @emph{SPARC Options}
315 -mcpu=@var{cpu type}
316 -mtune=@var{cpu type}
317 -mcmodel=@var{code model}
318 -m32  -m64
319 -mapp-regs  -mbroken-saverestore  -mcypress
320 -mepilogue -mfaster-structs -mflat
321 -mfpu  -mhard-float  -mhard-quad-float
322 -mimpure-text  -mlive-g0  -mno-app-regs
323 -mno-epilogue -mno-faster-structs -mno-flat  -mno-fpu
324 -mno-impure-text -mno-stack-bias  -mno-unaligned-doubles
325 -msoft-float  -msoft-quad-float  -msparclite  -mstack-bias
326 -msupersparc  -munaligned-doubles  -mv8
327
328 @emph{Convex Options}
329 -mc1  -mc2  -mc32  -mc34  -mc38
330 -margcount  -mnoargcount
331 -mlong32  -mlong64
332 -mvolatile-cache  -mvolatile-nocache
333
334 @emph{AMD29K Options}
335 -m29000  -m29050  -mbw  -mnbw  -mdw  -mndw
336 -mlarge  -mnormal  -msmall
337 -mkernel-registers  -mno-reuse-arg-regs
338 -mno-stack-check  -mno-storem-bug
339 -mreuse-arg-regs  -msoft-float  -mstack-check
340 -mstorem-bug  -muser-registers
341
342 @emph{ARM Options}
343 -mapcs-frame -mno-apcs-frame
344 -mapcs-26 -mapcs-32
345 -mapcs-stack-check -mno-apcs-stack-check
346 -mapcs-float -mno-apcs-float
347 -mapcs-reentrant -mno-apcs-reentrant
348 -msched-prolog -mno-sched-prolog
349 -mlittle-endian -mbig-endian -mwords-little-endian
350 -malignment-traps -mno-alignment-traps
351 -msoft-float -mhard-float -mfpe
352 -mthumb-interwork -mno-thumb-interwork
353 -mcpu= -march= -mfpe= 
354 -mstructure-size-boundary=
355 -mbsd -mxopen -mno-symrename
356 -mabort-on-noreturn
357 -mlong-calls -mno-long-calls
358 -mnop-fun-dllimport -mno-nop-fun-dllimport
359 -msingle-pic-base -mno-single-pic-base
360 -mpic-register=
361
362 @emph{Thumb Options}
363 -mtpcs-frame -mno-tpcs-frame
364 -mtpcs-leaf-frame -mno-tpcs-leaf-frame
365 -mlittle-endian  -mbig-endian
366 -mthumb-interwork -mno-thumb-interwork
367 -mstructure-size-boundary=
368 -mnop-fun-dllimport -mno-nop-fun-dllimport
369 -mcallee-super-interworking -mno-callee-super-interworking
370 -mcaller-super-interworking -mno-caller-super-interworking
371 -msingle-pic-base -mno-single-pic-base
372 -mpic-register=
373
374 @emph{MN10200 Options}
375 -mrelax
376
377 @emph{MN10300 Options}
378 -mmult-bug
379 -mno-mult-bug
380 -mam33
381 -mno-am33
382 -mrelax
383
384 @emph{M32R/D Options}
385 -mcode-model=@var{model type}  -msdata=@var{sdata type}
386 -G @var{num}
387
388 @emph{M88K Options}
389 -m88000  -m88100  -m88110  -mbig-pic
390 -mcheck-zero-division  -mhandle-large-shift
391 -midentify-revision  -mno-check-zero-division
392 -mno-ocs-debug-info  -mno-ocs-frame-position
393 -mno-optimize-arg-area  -mno-serialize-volatile
394 -mno-underscores  -mocs-debug-info
395 -mocs-frame-position  -moptimize-arg-area
396 -mserialize-volatile  -mshort-data-@var{num}  -msvr3
397 -msvr4  -mtrap-large-shift  -muse-div-instruction
398 -mversion-03.00  -mwarn-passed-structs
399
400 @emph{RS/6000 and PowerPC Options}
401 -mcpu=@var{cpu type}
402 -mtune=@var{cpu type}
403 -mpower  -mno-power  -mpower2  -mno-power2
404 -mpowerpc  -mpowerpc64  -mno-powerpc
405 -mpowerpc-gpopt  -mno-powerpc-gpopt
406 -mpowerpc-gfxopt  -mno-powerpc-gfxopt
407 -mnew-mnemonics  -mold-mnemonics
408 -mfull-toc   -mminimal-toc  -mno-fop-in-toc  -mno-sum-in-toc
409 -m64  -m32  -mxl-call  -mno-xl-call  -mthreads  -mpe
410 -msoft-float  -mhard-float  -mmultiple  -mno-multiple
411 -mstring  -mno-string  -mupdate  -mno-update
412 -mfused-madd  -mno-fused-madd  -mbit-align  -mno-bit-align
413 -mstrict-align  -mno-strict-align  -mrelocatable
414 -mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib
415 -mtoc  -mno-toc -mlittle  -mlittle-endian  -mbig  -mbig-endian
416 -mcall-aix  -mcall-sysv  -mprototype  -mno-prototype
417 -msim  -mmvme  -mads  -myellowknife  -memb -msdata
418 -msdata=@var{opt}  -mvxworks -G @var{num}
419
420 @emph{RT Options}
421 -mcall-lib-mul  -mfp-arg-in-fpregs  -mfp-arg-in-gregs
422 -mfull-fp-blocks  -mhc-struct-return  -min-line-mul
423 -mminimum-fp-blocks  -mnohc-struct-return
424
425 @emph{MIPS Options}
426 -mabicalls  -mcpu=@var{cpu type}
427 -membedded-data  -muninit-const-in-rodata
428 -membedded-pic  -mfp32  -mfp64  -mgas  -mgp32  -mgp64
429 -mgpopt  -mhalf-pic  -mhard-float  -mint64  -mips1
430 -mips2  -mips3 -mips4 -mlong64  -mlong32 -mlong-calls  -mmemcpy
431 -mmips-as  -mmips-tfile  -mno-abicalls
432 -mno-embedded-data  -mno-uninit-const-in-rodata  -mno-embedded-pic
433 -mno-gpopt  -mno-long-calls
434 -mno-memcpy  -mno-mips-tfile  -mno-rnames  -mno-stats
435 -mrnames  -msoft-float
436 -m4650  -msingle-float  -mmad
437 -mstats  -EL  -EB  -G @var{num}  -nocpp
438 -mabi=32 -mabi=n32 -mabi=64 -mabi=eabi
439 -mfix7000 -mno-crt0
440
441 @emph{i386 Options}
442 -mcpu=@var{cpu type} -march=@var{cpu type}
443 -mintel-syntax -mieee-fp  -mno-fancy-math-387
444 -mno-fp-ret-in-387  -msoft-float  -msvr3-shlib
445 -mno-wide-multiply  -mrtd  -malign-double
446 -mreg-alloc=@var{list}  -mregparm=@var{num}
447 -malign-jumps=@var{num}  -malign-loops=@var{num}
448 -malign-functions=@var{num} -mpreferred-stack-boundary=@var{num}
449 -mthreads -mno-align-stringops -minline-all-stringops
450 -mpush-args -maccumulate-outgoing-args -m128bit-long-double
451 -m96bit-long-double
452
453 @emph{HPPA Options}
454 -march=@var{architecture type}
455 -mbig-switch  -mdisable-fpregs  -mdisable-indexing  
456 -mfast-indirect-calls -mgas  -mjump-in-delay  
457 -mlong-load-store  -mno-big-switch  -mno-disable-fpregs
458 -mno-disable-indexing  -mno-fast-indirect-calls  -mno-gas
459 -mno-jump-in-delay  -mno-long-load-store  
460 -mno-portable-runtime  -mno-soft-float
461 -mno-space-regs  -msoft-float  -mpa-risc-1-0  
462 -mpa-risc-1-1  -mpa-risc-2-0 -mportable-runtime
463 -mschedule=@var{cpu type}  -mspace-regs
464
465 @emph{Intel 960 Options}
466 -m@var{cpu type}  -masm-compat  -mclean-linkage
467 -mcode-align  -mcomplex-addr  -mleaf-procedures
468 -mic-compat  -mic2.0-compat  -mic3.0-compat
469 -mintel-asm  -mno-clean-linkage  -mno-code-align
470 -mno-complex-addr  -mno-leaf-procedures
471 -mno-old-align  -mno-strict-align  -mno-tail-call
472 -mnumerics  -mold-align  -msoft-float  -mstrict-align
473 -mtail-call
474
475 @emph{DEC Alpha Options}
476 -mfp-regs  -mno-fp-regs -mno-soft-float  -msoft-float
477 -malpha-as -mgas
478 -mieee  -mieee-with-inexact  -mieee-conformant
479 -mfp-trap-mode=@var{mode}  -mfp-rounding-mode=@var{mode}
480 -mtrap-precision=@var{mode}  -mbuild-constants
481 -mcpu=@var{cpu type}
482 -mbwx -mno-bwx -mcix -mno-cix -mmax -mno-max
483 -mmemory-latency=@var{time}
484
485 @emph{Clipper Options}
486 -mc300  -mc400
487
488 @emph{H8/300 Options}
489 -mrelax  -mh -ms -mint32  -malign-300
490
491 @emph{SH Options}
492 -m1  -m2  -m3  -m3e
493 -m4-nofpu  -m4-single-only  -m4-single  -m4
494 -mb  -ml  -mdalign  -mrelax
495 -mbigtable  -mfmovd  -mhitachi  -mnomacsave
496 -misize  -mpadstruct  -mspace
497 -mprefergot
498 -musermode
499
500 @emph{System V Options}
501 -Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}
502
503 @emph{ARC Options}
504 -EB  -EL
505 -mmangle-cpu  -mcpu=@var{cpu}  -mtext=@var{text section}
506 -mdata=@var{data section}  -mrodata=@var{readonly data section}
507
508 @emph{TMS320C3x/C4x Options}
509 -mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm
510 -mfast-fix -mmpyi -mbk -mti -mdp-isr-reload
511 -mrpts=@var{count}  -mrptb -mdb -mloop-unsigned
512 -mparallel-insns -mparallel-mpy -mpreserve-float
513
514 @emph{V850 Options}
515 -mlong-calls -mno-long-calls -mep -mno-ep
516 -mprolog-function -mno-prolog-function -mspace
517 -mtda=@var{n} -msda=@var{n} -mzda=@var{n}
518 -mv850 -mbig-switch
519
520 @emph{NS32K Options}
521 -m32032 -m32332 -m32532 -m32081 -m32381 -mmult-add -mnomult-add
522 -msoft-float -mrtd -mnortd -mregparam -mnoregparam -msb -mnosb
523 -mbitfield -mnobitfield -mhimem -mnohimem
524
525 @emph{AVR Options}
526 -mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts
527 -mcall-prologues -mno-tablejump -mtiny-stack
528
529 @emph{MCore Options}
530 -mhardlit, -mno-hardlit -mdiv -mno-div -mrelax-immediates 
531 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields
532 -m4byte-functions -mno-4byte-functions -mcallgraph-data
533 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim
534 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment
535 @end smallexample
536
537 @item Code Generation Options
538 @xref{Code Gen Options,,Options for Code Generation Conventions}.
539 @smallexample
540 -fcall-saved-@var{reg}  -fcall-used-@var{reg}
541 -fexceptions  -funwind-tables  -ffixed-@var{reg}
542 -finhibit-size-directive  -finstrument-functions
543 -fcheck-memory-usage  -fprefix-function-name
544 -fno-common  -fno-ident  -fno-gnu-linker
545 -fpcc-struct-return  -fpic  -fPIC
546 -freg-struct-return  -fshared-data  -fshort-enums
547 -fshort-double  -fvolatile  -fvolatile-global -fvolatile-static
548 -fverbose-asm  -fpack-struct  -fstack-check
549 -fstack-limit-register=@var{reg}  -fstack-limit-symbol=@var{sym}
550 -fargument-alias  -fargument-noalias
551 -fargument-noalias-global
552 -fleading-underscore
553 @end smallexample
554 @end table
555
556 @menu
557 * Overall Options::     Controlling the kind of output:
558                         an executable, object files, assembler files,
559                         or preprocessed source.
560 * C Dialect Options::   Controlling the variant of C language compiled.
561 * C++ Dialect Options:: Variations on C++.
562 * Language Independent Options:: Controlling how diagnostics should be
563                         formatted. 
564 * Warning Options::     How picky should the compiler be?
565 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
566 * Optimize Options::    How much optimization?
567 * Preprocessor Options:: Controlling header files and macro definitions.
568                          Also, getting dependency information for Make.
569 * Assembler Options::   Passing options to the assembler.
570 * Link Options::        Specifying libraries and so on.
571 * Directory Options::   Where to find header files and libraries.
572                         Where to find the compiler executable files.
573 * Spec Files::          How to pass switches to sub-processes.
574 * Target Options::      Running a cross-compiler, or an old version of GCC.
575 @end menu
576
577 @c man begin OPTIONS
578
579 @node Overall Options
580 @section Options Controlling the Kind of Output
581
582 Compilation can involve up to four stages: preprocessing, compilation
583 proper, assembly and linking, always in that order.  The first three
584 stages apply to an individual source file, and end by producing an
585 object file; linking combines all the object files (those newly
586 compiled, and those specified as input) into an executable file.
587
588 @cindex file name suffix
589 For any given input file, the file name suffix determines what kind of
590 compilation is done:
591
592 @table @code
593 @item @var{file}.c
594 C source code which must be preprocessed.
595
596 @item @var{file}.i
597 C source code which should not be preprocessed.
598
599 @item @var{file}.ii
600 C++ source code which should not be preprocessed.
601
602 @item @var{file}.m
603 Objective-C source code.  Note that you must link with the library
604 @file{libobjc.a} to make an Objective-C program work.
605
606 @item @var{file}.mi
607 Objective-C source code which should not be preprocessed.
608
609 @item @var{file}.h
610 C header file (not to be compiled or linked).
611
612 @item @var{file}.cc
613 @itemx @var{file}.cp
614 @itemx @var{file}.cxx
615 @itemx @var{file}.cpp
616 @itemx @var{file}.c++
617 @itemx @var{file}.C
618 C++ source code which must be preprocessed.  Note that in @samp{.cxx},
619 the last two letters must both be literally @samp{x}.  Likewise,
620 @samp{.C} refers to a literal capital C.
621
622 @item @var{file}.f
623 @itemx @var{file}.for
624 @itemx @var{file}.FOR
625 Fortran source code which should not be preprocessed.
626
627 @item @var{file}.F
628 @itemx @var{file}.fpp
629 @itemx @var{file}.FPP
630 Fortran source code which must be preprocessed (with the traditional
631 preprocessor).
632
633 @item @var{file}.r
634 Fortran source code which must be preprocessed with a RATFOR
635 preprocessor (not included with GCC).
636
637 @xref{Overall Options,,Options Controlling the Kind of Output, g77,
638 Using and Porting GNU Fortran}, for more details of the handling of
639 Fortran input files.
640
641 @c FIXME: Descriptions of Java file types.
642 @c @var{file}.java
643 @c @var{file}.class
644 @c @var{file}.zip
645 @c @var{file}.jar
646
647 @c GCC also knows about some suffixes for languages not yet included:
648 @c Ada:
649 @c @var{file}.ads
650 @c @var{file}.adb
651 @c @var{file}.ada
652 @c Pascal:
653 @c @var{file}.p
654 @c @var{file}.pas
655
656 @item @var{file}.ch
657 @itemx @var{file}.chi
658 CHILL source code (preprocessed with the traditional preprocessor).
659
660 @item @var{file}.s
661 Assembler code.
662
663 @item @var{file}.S
664 Assembler code which must be preprocessed.
665
666 @item @var{other}
667 An object file to be fed straight into linking.
668 Any file name with no recognized suffix is treated this way.
669 @end table
670
671 You can specify the input language explicitly with the @samp{-x} option:
672
673 @table @code
674 @item -x @var{language}
675 Specify explicitly the @var{language} for the following input files
676 (rather than letting the compiler choose a default based on the file
677 name suffix).  This option applies to all following input files until
678 the next @samp{-x} option.  Possible values for @var{language} are:
679 @example
680 c  c-header  cpp-output
681 c++  c++-cpp-output
682 objective-c  objc-cpp-output
683 assembler  assembler-with-cpp
684 f77  f77-cpp-input  ratfor
685 java  chill
686 @end example
687 @c Also f77-version, for internal use only.
688
689 @item -x none
690 Turn off any specification of a language, so that subsequent files are
691 handled according to their file name suffixes (as they are if @samp{-x}
692 has not been used at all).
693
694 @item -pass-exit-codes
695 Normally the @code{gcc} program will exit with the code of 1 if any
696 phase of the compiler returns a non-success return code.  If you specify
697 @samp{-pass-exit-codes}, the @code{gcc} program will instead return with
698 numerically highest error produced by any phase that returned an error
699 indication.
700 @end table
701
702 If you only want some of the stages of compilation, you can use
703 @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
704 one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
705 @code{gcc} is to stop.  Note that some combinations (for example,
706 @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
707
708 @table @code
709 @item -c
710 Compile or assemble the source files, but do not link.  The linking
711 stage simply is not done.  The ultimate output is in the form of an
712 object file for each source file.
713
714 By default, the object file name for a source file is made by replacing
715 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
716
717 Unrecognized input files, not requiring compilation or assembly, are
718 ignored.
719
720 @item -S
721 Stop after the stage of compilation proper; do not assemble.  The output
722 is in the form of an assembler code file for each non-assembler input
723 file specified.
724
725 By default, the assembler file name for a source file is made by
726 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
727
728 Input files that don't require compilation are ignored.
729
730 @item -E
731 Stop after the preprocessing stage; do not run the compiler proper.  The
732 output is in the form of preprocessed source code, which is sent to the
733 standard output.
734
735 Input files which don't require preprocessing are ignored.
736
737 @cindex output file option
738 @item -o @var{file}
739 Place output in file @var{file}.  This applies regardless to whatever
740 sort of output is being produced, whether it be an executable file,
741 an object file, an assembler file or preprocessed C code.
742
743 Since only one output file can be specified, it does not make sense to
744 use @samp{-o} when compiling more than one input file, unless you are
745 producing an executable file as output.
746
747 If @samp{-o} is not specified, the default is to put an executable file
748 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
749 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
750 all preprocessed C source on standard output.@refill
751
752 @item -v
753 Print (on standard error output) the commands executed to run the stages
754 of compilation.  Also print the version number of the compiler driver
755 program and of the preprocessor and the compiler proper.
756
757 @item -pipe
758 Use pipes rather than temporary files for communication between the
759 various stages of compilation.  This fails to work on some systems where
760 the assembler is unable to read from a pipe; but the GNU assembler has
761 no trouble.
762
763 @item --help
764 Print (on the standard output) a description of the command line options
765 understood by @code{gcc}.  If the @code{-v} option is also specified
766 then @code{--help} will also be passed on to the various processes
767 invoked by @code{gcc}, so that they can display the command line options
768 they accept.  If the @code{-W} option is also specified then command
769 line options which have no documentation associated with them will also
770 be displayed.
771
772 @item --target-help
773 Print (on the standard output) a description of target specific command
774 line options for each tool.
775 @end table
776
777 @node Invoking G++
778 @section Compiling C++ Programs
779
780 @cindex suffixes for C++ source
781 @cindex C++ source file suffixes
782 C++ source files conventionally use one of the suffixes @samp{.C},
783 @samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx};
784 preprocessed C++ files use the suffix @samp{.ii}.  GCC recognizes
785 files with these names and compiles them as C++ programs even if you
786 call the compiler the same way as for compiling C programs (usually with
787 the name @code{gcc}).
788
789 @findex g++
790 @findex c++
791 However, C++ programs often require class libraries as well as a
792 compiler that understands the C++ language---and under some
793 circumstances, you might want to compile programs from standard input,
794 or otherwise without a suffix that flags them as C++ programs.
795 @code{g++} is a program that calls GCC with the default language
796 set to C++, and automatically specifies linking against the C++
797 library.  On many systems, @code{g++} is also
798 installed with the name @code{c++}.
799
800 @cindex invoking @code{g++}
801 When you compile C++ programs, you may specify many of the same
802 command-line options that you use for compiling programs in any
803 language; or command-line options meaningful for C and related
804 languages; or options that are meaningful only for C++ programs.
805 @xref{C Dialect Options,,Options Controlling C Dialect}, for
806 explanations of options for languages related to C.
807 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
808 explanations of options that are meaningful only for C++ programs.
809
810 @node C Dialect Options
811 @section Options Controlling C Dialect
812 @cindex dialect options
813 @cindex language dialect options
814 @cindex options, dialect
815
816 The following options control the dialect of C (or languages derived
817 from C, such as C++ and Objective C) that the compiler accepts:
818
819 @table @code
820 @cindex ANSI support
821 @cindex ISO support
822 @item -ansi
823 In C mode, support all ISO C89 programs.  In C++ mode,
824 remove GNU extensions that conflict with ISO C++.
825
826 This turns off certain features of GCC that are incompatible with ISO
827 C (when compiling C code), or of standard C++ (when compiling C++ code),
828 such as the @code{asm} and @code{typeof} keywords, and
829 predefined macros such as @code{unix} and @code{vax} that identify the
830 type of system you are using.  It also enables the undesirable and
831 rarely used ISO trigraph feature.  For the C compiler, 
832 it disables recognition of C++ style @samp{//} comments as well as
833 the @code{inline} keyword.
834
835 The alternate keywords @code{__asm__}, @code{__extension__},
836 @code{__inline__} and @code{__typeof__} continue to work despite
837 @samp{-ansi}.  You would not want to use them in an ISO C program, of
838 course, but it is useful to put them in header files that might be included
839 in compilations done with @samp{-ansi}.  Alternate predefined macros
840 such as @code{__unix__} and @code{__vax__} are also available, with or
841 without @samp{-ansi}.
842
843 The @samp{-ansi} option does not cause non-ISO programs to be
844 rejected gratuitously.  For that, @samp{-pedantic} is required in
845 addition to @samp{-ansi}.  @xref{Warning Options}.
846
847 The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
848 option is used.  Some header files may notice this macro and refrain
849 from declaring certain functions or defining certain macros that the
850 ISO standard doesn't call for; this is to avoid interfering with any
851 programs that might use these names for other things.
852
853 Functions which would normally be builtin but do not have semantics
854 defined by ISO C (such as @code{alloca} and @code{ffs}) are not builtin
855 functions with @samp{-ansi} is used.  @xref{Other Builtins,,Other
856 built-in functions provided by GNU CC}, for details of the functions
857 affected.
858
859 @item -std=
860 Determine the language standard.  A value for this option must be provided;
861 possible values are 
862
863 @table @samp
864 @item iso9899:1990
865 Same as -ansi
866
867 @item iso9899:199409
868 ISO C as modified in amend. 1
869
870 @item iso9899:1999
871 ISO C99.  Note that this standard is not yet fully supported; see
872 @uref{http://gcc.gnu.org/c99status.html} for more information.
873
874 @item c89
875 same as -std=iso9899:1990
876
877 @item c99
878 same as -std=iso9899:1999
879
880 @item gnu89
881 default, iso9899:1990 + gnu extensions
882
883 @item gnu99
884 iso9899:1999 + gnu extensions
885
886 @item iso9899:199x
887 same as -std=iso9899:1999, deprecated
888
889 @item c9x
890 same as -std=iso9899:1999, deprecated
891
892 @item gnu9x
893 same as -std=gnu99, deprecated
894
895 @end table
896
897 Even when this option is not specified, you can still use some of the
898 features of newer standards in so far as they do not conflict with
899 previous C standards.  For example, you may use @code{__restrict__} even
900 when -std=c99 is not specified.
901
902 @xref{Standards,,Language Standards Supported by GCC}, for details of
903 these standard versions.
904
905 @item -fno-asm
906 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
907 keyword, so that code can use these words as identifiers.  You can use
908 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
909 instead.  @samp{-ansi} implies @samp{-fno-asm}.
910
911 In C++, this switch only affects the @code{typeof} keyword, since
912 @code{asm} and @code{inline} are standard keywords.  You may want to
913 use the @samp{-fno-gnu-keywords} flag instead, which has the same effect.
914
915 @item -fno-builtin
916 @cindex builtin functions
917 Don't recognize builtin functions that do not begin with
918 @samp{__builtin_} as prefix.  @xref{Other Builtins,,Other built-in
919 functions provided by GNU CC}, for details of the functions affected,
920 including those which are not builtin functions when @samp{-ansi} is
921 used because they do not have an ISO standard meaning.
922
923 GCC normally generates special code to handle certain builtin functions
924 more efficiently; for instance, calls to @code{alloca} may become single
925 instructions that adjust the stack directly, and calls to @code{memcpy}
926 may become inline copy loops.  The resulting code is often both smaller
927 and faster, but since the function calls no longer appear as such, you
928 cannot set a breakpoint on those calls, nor can you change the behavior
929 of the functions by linking with a different library.
930
931 @item -fhosted
932 @cindex hosted environment
933
934 Assert that compilation takes place in a hosted environment.  This implies
935 @samp{-fbuiltin}.  A hosted environment is one in which the
936 entire standard library is available, and in which @code{main} has a return
937 type of @code{int}.  Examples are nearly everything except a kernel.
938 This is equivalent to @samp{-fno-freestanding}.
939
940 @item -ffreestanding
941 @cindex hosted environment
942
943 Assert that compilation takes place in a freestanding environment.  This
944 implies @samp{-fno-builtin}.  A freestanding environment
945 is one in which the standard library may not exist, and program startup may
946 not necessarily be at @code{main}.  The most obvious example is an OS kernel.
947 This is equivalent to @samp{-fno-hosted}.
948
949 @xref{Standards,,Language Standards Supported by GCC}, for details of
950 freestanding and hosted environments.
951
952 @item -trigraphs
953 Support ISO C trigraphs.  You don't want to know about this
954 brain-damage.  The @samp{-ansi} option implies @samp{-trigraphs}.
955
956 @cindex traditional C language
957 @cindex C language, traditional
958 @item -traditional
959 Attempt to support some aspects of traditional C compilers.
960 Specifically:
961
962 @itemize @bullet
963 @item
964 All @code{extern} declarations take effect globally even if they
965 are written inside of a function definition.  This includes implicit
966 declarations of functions.
967
968 @item
969 The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
970 and @code{volatile} are not recognized.  (You can still use the
971 alternative keywords such as @code{__typeof__}, @code{__inline__}, and
972 so on.)
973
974 @item
975 Comparisons between pointers and integers are always allowed.
976
977 @item
978 Integer types @code{unsigned short} and @code{unsigned char} promote
979 to @code{unsigned int}.
980
981 @item
982 Out-of-range floating point literals are not an error.
983
984 @item
985 Certain constructs which ISO regards as a single invalid preprocessing
986 number, such as @samp{0xe-0xd}, are treated as expressions instead.
987
988 @item
989 String ``constants'' are not necessarily constant; they are stored in
990 writable space, and identical looking constants are allocated
991 separately.  (This is the same as the effect of
992 @samp{-fwritable-strings}.)
993
994 @cindex @code{longjmp} and automatic variables
995 @item
996 All automatic variables not declared @code{register} are preserved by
997 @code{longjmp}.  Ordinarily, GNU C follows ISO C: automatic variables
998 not declared @code{volatile} may be clobbered.
999
1000 @item
1001 @kindex \x
1002 @kindex \a
1003 @cindex escape sequences, traditional
1004 The character escape sequences @samp{\x} and @samp{\a} evaluate as the
1005 literal characters @samp{x} and @samp{a} respectively.  Without
1006 @w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal
1007 representation of a character, and @samp{\a} produces a bell.
1008 @end itemize
1009
1010 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
1011 if your program uses names that are normally GNU C builtin functions for
1012 other purposes of its own.
1013
1014 You cannot use @samp{-traditional} if you include any header files that
1015 rely on ISO C features.  Some vendors are starting to ship systems with
1016 ISO C header files and you cannot use @samp{-traditional} on such
1017 systems to compile files that include any system headers.
1018
1019 The @samp{-traditional} option also enables @samp{-traditional-cpp},
1020 which is described next.
1021
1022 @item -traditional-cpp
1023 Attempt to support some aspects of traditional C preprocessors.
1024 Specifically:
1025
1026 @itemize @bullet
1027 @item
1028 Comments convert to nothing at all, rather than to a space.  This allows
1029 traditional token concatenation.
1030
1031 @item
1032 In a preprocessing directive, the @samp{#} symbol must appear as the first
1033 character of a line.
1034
1035 @item
1036 Macro arguments are recognized within string constants in a macro
1037 definition (and their values are stringified, though without additional
1038 quote marks, when they appear in such a context).  The preprocessor
1039 always considers a string constant to end at a newline.
1040
1041 @item
1042 @cindex detecting @w{@samp{-traditional}}
1043 The predefined macro @code{__STDC__} is not defined when you use
1044 @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
1045 which @code{__GNUC__} indicates are not affected by
1046 @samp{-traditional}).  If you need to write header files that work
1047 differently depending on whether @samp{-traditional} is in use, by
1048 testing both of these predefined macros you can distinguish four
1049 situations: GNU C, traditional GNU C, other ISO C compilers, and other
1050 old C compilers.  The predefined macro @code{__STDC_VERSION__} is also
1051 not defined when you use @samp{-traditional}.  @xref{Standard
1052 Predefined,,Standard Predefined Macros,cpp.info,The C Preprocessor},
1053 for more discussion of these and other predefined macros.
1054
1055 @item
1056 @cindex string constants vs newline
1057 @cindex newline vs string constants
1058 The preprocessor considers a string constant to end at a newline (unless
1059 the newline is escaped with @samp{\}).  (Without @w{@samp{-traditional}},
1060 string constants can contain the newline character as typed.)
1061 @end itemize
1062
1063 @item -fcond-mismatch
1064 Allow conditional expressions with mismatched types in the second and
1065 third arguments.  The value of such an expression is void.
1066
1067 @item -funsigned-char
1068 Let the type @code{char} be unsigned, like @code{unsigned char}.
1069
1070 Each kind of machine has a default for what @code{char} should
1071 be.  It is either like @code{unsigned char} by default or like
1072 @code{signed char} by default.
1073
1074 Ideally, a portable program should always use @code{signed char} or
1075 @code{unsigned char} when it depends on the signedness of an object.
1076 But many programs have been written to use plain @code{char} and
1077 expect it to be signed, or expect it to be unsigned, depending on the
1078 machines they were written for.  This option, and its inverse, let you
1079 make such a program work with the opposite default.
1080
1081 The type @code{char} is always a distinct type from each of
1082 @code{signed char} or @code{unsigned char}, even though its behavior
1083 is always just like one of those two.
1084
1085 @item -fsigned-char
1086 Let the type @code{char} be signed, like @code{signed char}.
1087
1088 Note that this is equivalent to @samp{-fno-unsigned-char}, which is
1089 the negative form of @samp{-funsigned-char}.  Likewise, the option
1090 @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
1091
1092 You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
1093 if your program uses names that are normally GNU C builtin functions for
1094 other purposes of its own.
1095
1096 You cannot use @samp{-traditional} if you include any header files that
1097 rely on ISO C features.  Some vendors are starting to ship systems with
1098 ISO C header files and you cannot use @samp{-traditional} on such
1099 systems to compile files that include any system headers.
1100
1101 @item -fsigned-bitfields
1102 @itemx -funsigned-bitfields
1103 @itemx -fno-signed-bitfields
1104 @itemx -fno-unsigned-bitfields
1105 These options control whether a bitfield is signed or unsigned, when the
1106 declaration does not use either @code{signed} or @code{unsigned}.  By
1107 default, such a bitfield is signed, because this is consistent: the
1108 basic integer types such as @code{int} are signed types.
1109
1110 However, when @samp{-traditional} is used, bitfields are all unsigned
1111 no matter what.
1112
1113 @item -fwritable-strings
1114 Store string constants in the writable data segment and don't uniquize
1115 them.  This is for compatibility with old programs which assume they can
1116 write into string constants.  The option @samp{-traditional} also has
1117 this effect.
1118
1119 Writing into string constants is a very bad idea; ``constants'' should
1120 be constant.
1121
1122 @item -fallow-single-precision
1123 Do not promote single precision math operations to double precision,
1124 even when compiling with @samp{-traditional}.
1125
1126 Traditional K&R C promotes all floating point operations to double
1127 precision, regardless of the sizes of the operands.   On the
1128 architecture for which you are compiling, single precision may be faster
1129 than double precision.   If you must use @samp{-traditional}, but want
1130 to use single precision operations when the operands are single
1131 precision, use this option.   This option has no effect when compiling
1132 with ISO or GNU C conventions (the default).
1133
1134 @item -fshort-wchar
1135 Override the underlying type for @samp{wchar_t} to be @samp{short
1136 unsigned int} instead of the default for the target.  This option is
1137 useful for building programs to run under WINE.
1138 @end table
1139
1140 @node C++ Dialect Options
1141 @section Options Controlling C++ Dialect
1142
1143 @cindex compiler options, C++
1144 @cindex C++ options, command line
1145 @cindex options, C++
1146 This section describes the command-line options that are only meaningful
1147 for C++ programs; but you can also use most of the GNU compiler options
1148 regardless of what language your program is in.  For example, you
1149 might compile a file @code{firstClass.C} like this:
1150
1151 @example
1152 g++ -g -frepo -O -c firstClass.C
1153 @end example
1154
1155 @noindent
1156 In this example, only @samp{-frepo} is an option meant
1157 only for C++ programs; you can use the other options with any
1158 language supported by GCC.
1159
1160 Here is a list of options that are @emph{only} for compiling C++ programs:
1161
1162 @table @code
1163 @item -fno-access-control
1164 Turn off all access checking.  This switch is mainly useful for working
1165 around bugs in the access control code.
1166
1167 @item -fcheck-new
1168 Check that the pointer returned by @code{operator new} is non-null
1169 before attempting to modify the storage allocated.  The current Working
1170 Paper requires that @code{operator new} never return a null pointer, so
1171 this check is normally unnecessary.
1172
1173 An alternative to using this option is to specify that your
1174 @code{operator new} does not throw any exceptions; if you declare it
1175 @samp{throw()}, g++ will check the return value.  See also @samp{new
1176 (nothrow)}.
1177
1178 @item -fconserve-space
1179 Put uninitialized or runtime-initialized global variables into the
1180 common segment, as C does.  This saves space in the executable at the
1181 cost of not diagnosing duplicate definitions.  If you compile with this
1182 flag and your program mysteriously crashes after @code{main()} has
1183 completed, you may have an object that is being destroyed twice because
1184 two definitions were merged.
1185
1186 This option is no longer useful on most targets, now that support has
1187 been added for putting variables into BSS without making them common.
1188
1189 @item -fdollars-in-identifiers
1190 Accept @samp{$} in identifiers.  You can also explicitly prohibit use of
1191 @samp{$} with the option @samp{-fno-dollars-in-identifiers}.  (GNU C allows
1192 @samp{$} by default on most target systems, but there are a few exceptions.)
1193 Traditional C allowed the character @samp{$} to form part of
1194 identifiers.  However, ISO C and C++ forbid @samp{$} in identifiers.
1195
1196 @item -fno-elide-constructors
1197 The C++ standard allows an implementation to omit creating a temporary
1198 which is only used to initialize another object of the same type.
1199 Specifying this option disables that optimization, and forces g++ to
1200 call the copy constructor in all cases.
1201
1202 @item -fno-enforce-eh-specs
1203 Don't check for violation of exception specifications at runtime.  This
1204 option violates the C++ standard, but may be useful for reducing code
1205 size in production builds, much like defining @samp{NDEBUG}.  The compiler
1206 will still optimize based on the exception specifications.
1207
1208 @item -fexternal-templates
1209 Cause template instantiations to obey @samp{#pragma interface} and
1210 @samp{implementation}; template instances are emitted or not according
1211 to the location of the template definition.  @xref{Template
1212 Instantiation}, for more information.
1213
1214 This option is deprecated.
1215
1216 @item -falt-external-templates
1217 Similar to -fexternal-templates, but template instances are emitted or
1218 not according to the place where they are first instantiated.
1219 @xref{Template Instantiation}, for more information.
1220
1221 This option is deprecated.
1222
1223 @item -ffor-scope
1224 @itemx -fno-for-scope
1225 If -ffor-scope is specified, the scope of variables declared in
1226 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1227 as specified by the C++ standard.
1228 If -fno-for-scope is specified, the scope of variables declared in
1229 a @i{for-init-statement} extends to the end of the enclosing scope,
1230 as was the case in old versions of gcc, and other (traditional)
1231 implementations of C++.
1232
1233 The default if neither flag is given to follow the standard,
1234 but to allow and give a warning for old-style code that would
1235 otherwise be invalid, or have different behavior.
1236
1237 @item -fno-gnu-keywords
1238 Do not recognize @code{typeof} as a keyword, so that code can use this
1239 word as an identifier. You can use the keyword @code{__typeof__} instead.  
1240 @samp{-ansi} implies @samp{-fno-gnu-keywords}.
1241
1242 @item -fhonor-std
1243 Treat the @code{namespace std} as a namespace, instead of ignoring
1244 it. For compatibility with earlier versions of g++, the compiler will,
1245 by default, ignore @code{namespace-declarations},
1246 @code{using-declarations}, @code{using-directives}, and
1247 @code{namespace-names}, if they involve @code{std}.
1248
1249 @item -fhuge-objects
1250 Support virtual function calls for objects that exceed the size
1251 representable by a @samp{short int}.  Users should not use this flag by
1252 default; if you need to use it, the compiler will tell you so.
1253
1254 This flag is not useful when compiling with -fvtable-thunks.
1255
1256 Like all options that change the ABI, all C++ code, @emph{including
1257 libgcc} must be built with the same setting of this option.
1258
1259 @item -fno-implicit-templates
1260 Never emit code for non-inline templates which are instantiated
1261 implicitly (i.e. by use); only emit code for explicit instantiations.
1262 @xref{Template Instantiation}, for more information.
1263
1264 @item -fno-implicit-inline-templates
1265 Don't emit code for implicit instantiations of inline templates, either.
1266 The default is to handle inlines differently so that compiles with and
1267 without optimization will need the same set of explicit instantiations.
1268
1269 @item -fno-implement-inlines
1270 To save space, do not emit out-of-line copies of inline functions
1271 controlled by @samp{#pragma implementation}.  This will cause linker
1272 errors if these functions are not inlined everywhere they are called.
1273
1274 @item -fms-extensions
1275 Disable pedantic warnings about constructs used in MFC, such as implicit
1276 int and getting a pointer to member function via non-standard syntax.
1277
1278 @item -fname-mangling-version-@var{n}
1279 Control the way in which names are mangled.  Version 0 is compatible
1280 with versions of g++ before 2.8.  Version 1 is the default.  Version 1
1281 will allow correct mangling of function templates.  For example, 
1282 version 0 mangling does not mangle foo<int, double> and foo<int, char>
1283 given this declaration:
1284
1285 @example
1286 template <class T, class U> void foo(T t);
1287 @end example
1288
1289 Like all options that change the ABI, all C++ code, @emph{including
1290 libgcc} must be built with the same setting of this option.
1291
1292 @item -fno-operator-names
1293 Do not treat the operator name keywords @code{and}, @code{bitand},
1294 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1295 synonyms as keywords.
1296
1297 @item -fno-optional-diags
1298 Disable diagnostics that the standard says a compiler does not need to
1299 issue.  Currently, the only such diagnostic issued by g++ is the one for
1300 a name having multiple meanings within a class.
1301
1302 @item -fpermissive
1303 Downgrade messages about nonconformant code from errors to warnings.  By
1304 default, g++ effectively sets @samp{-pedantic-errors} without
1305 @samp{-pedantic}; this option reverses that.  This behavior and this
1306 option are superseded by @samp{-pedantic}, which works as it does for GNU C.
1307
1308 @item -frepo
1309 Enable automatic template instantiation.  This option also implies
1310 @samp{-fno-implicit-templates}.  @xref{Template Instantiation}, for more
1311 information.
1312
1313 @item -fno-rtti
1314 Disable generation of information about every class with virtual
1315 functions for use by the C++ runtime type identification features
1316 (@samp{dynamic_cast} and @samp{typeid}).  If you don't use those parts
1317 of the language, you can save some space by using this flag.  Note that
1318 exception handling uses the same information, but it will generate it as
1319 needed.
1320
1321 @item -fsquangle
1322 @itemx -fno-squangle
1323 @samp{-fsquangle} will enable a compressed form of name mangling for
1324 identifiers. In particular, it helps to shorten very long names by recognizing
1325 types and class names which occur more than once, replacing them with special
1326 short ID codes.  This option also requires any C++ libraries being used to
1327 be compiled with this option as well.  The compiler has this disabled (the
1328 equivalent of @samp{-fno-squangle}) by default.
1329
1330 Like all options that change the ABI, all C++ code, @emph{including
1331 libgcc.a} must be built with the same setting of this option.
1332
1333 @item -ftemplate-depth-@var{n}
1334 Set the maximum instantiation depth for template classes to @var{n}.
1335 A limit on the template instantiation depth is needed to detect
1336 endless recursions during template class instantiation. ANSI/ISO C++
1337 conforming programs must not rely on a maximum depth greater than 17.
1338
1339 @item -fuse-cxa-atexit
1340 Register destructors for objects with static storage duration with the
1341 @code{__cxa_atexit} function rather than the @code{atexit} function.
1342 This option is required for fully standards-compliant handling of static
1343 destructors, but will only work if your C library supports
1344 @code{__cxa_atexit}.
1345
1346 @item -fvtable-thunks
1347 Use @samp{thunks} to implement the virtual function dispatch table
1348 (@samp{vtable}).  The traditional (cfront-style) approach to
1349 implementing vtables was to store a pointer to the function and two
1350 offsets for adjusting the @samp{this} pointer at the call site.  Newer
1351 implementations store a single pointer to a @samp{thunk} function which
1352 does any necessary adjustment and then calls the target function.
1353
1354 This option also enables a heuristic for controlling emission of
1355 vtables; if a class has any non-inline virtual functions, the vtable
1356 will be emitted in the translation unit containing the first one of
1357 those.
1358
1359 Like all options that change the ABI, all C++ code, @emph{including
1360 libgcc.a} must be built with the same setting of this option.
1361
1362 @item -nostdinc++
1363 Do not search for header files in the standard directories specific to
1364 C++, but do still search the other standard directories.  (This option
1365 is used when building the C++ library.)
1366 @end table
1367
1368 In addition, these optimization, warning, and code generation options
1369 have meanings only for C++ programs:
1370
1371 @table @code
1372 @item -fno-default-inline
1373 Do not assume @samp{inline} for functions defined inside a class scope.
1374 @xref{Optimize Options,,Options That Control Optimization}.  Note that these
1375 functions will have linkage like inline functions; they just won't be
1376 inlined by default.
1377
1378 @item -Wctor-dtor-privacy (C++ only)
1379 Warn when a class seems unusable, because all the constructors or
1380 destructors in a class are private and the class has no friends or
1381 public static member functions.
1382
1383 @item -Wnon-virtual-dtor (C++ only)
1384 Warn when a class declares a non-virtual destructor that should probably
1385 be virtual, because it looks like the class will be used polymorphically.
1386
1387 @item -Wreorder (C++ only)
1388 @cindex reordering, warning
1389 @cindex warning for reordering of member initializers
1390 Warn when the order of member initializers given in the code does not
1391 match the order in which they must be executed.  For instance:
1392
1393 @smallexample
1394 struct A @{
1395   int i;
1396   int j;
1397   A(): j (0), i (1) @{ @}
1398 @};
1399 @end smallexample
1400
1401 Here the compiler will warn that the member initializers for @samp{i}
1402 and @samp{j} will be rearranged to match the declaration order of the
1403 members.
1404 @end table
1405
1406 The following @samp{-W@dots{}} options are not affected by @samp{-Wall}.
1407
1408 @table @code
1409 @item -Weffc++ (C++ only)
1410 Warn about violations of various style guidelines from Scott Meyers'
1411 @cite{Effective C++} books.  If you use this option, you should be aware
1412 that the standard library headers do not obey all of these guidelines;
1413 you can use @samp{grep -v} to filter out those warnings.
1414
1415 @item -Wno-deprecated (C++ only)
1416 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1417
1418 @item -Wno-non-template-friend (C++ only)
1419 Disable warnings when non-templatized friend functions are declared
1420 within a template. With the advent of explicit template specification
1421 support in g++, if the name of the friend is an unqualified-id (ie,
1422 @samp{friend foo(int)}), the C++ language specification demands that the
1423 friend declare or define an ordinary, nontemplate function. (Section
1424 14.5.3). Before g++ implemented explicit specification, unqualified-ids
1425 could be interpreted as a particular specialization of a templatized
1426 function. Because this non-conforming behavior is no longer the default
1427 behavior for g++, @samp{-Wnon-template-friend} allows the compiler to
1428 check existing code for potential trouble spots, and is on by default.
1429 This new compiler behavior can be turned off with
1430 @samp{-Wno-non-template-friend} which keeps the conformant compiler code
1431 but disables the helpful warning.
1432
1433 @item -Wold-style-cast (C++ only)
1434 Warn if an old-style (C-style) cast is used within a C++ program.  The
1435 new-style casts (@samp{static_cast}, @samp{reinterpret_cast}, and
1436 @samp{const_cast}) are less vulnerable to unintended effects.
1437
1438 @item -Woverloaded-virtual (C++ only)
1439 @cindex overloaded virtual fn, warning
1440 @cindex warning for overloaded virtual fn
1441 Warn when a derived class function declaration may be an error in
1442 defining a virtual function.  In a derived class, the
1443 definitions of virtual functions must match the type signature of a
1444 virtual function declared in the base class.  With this option, the
1445 compiler warns when you define a function with the same name as a
1446 virtual function, but with a type signature that does not match any
1447 declarations from the base class.
1448
1449 @item -Wno-pmf-conversions (C++ only)
1450 Disable the diagnostic for converting a bound pointer to member function
1451 to a plain pointer.
1452
1453 @item -Wsign-promo (C++ only)
1454 Warn when overload resolution chooses a promotion from unsigned or
1455 enumeral type to a signed type over a conversion to an unsigned type of
1456 the same size.  Previous versions of g++ would try to preserve
1457 unsignedness, but the standard mandates the current behavior.
1458
1459 @item -Wsynth (C++ only)
1460 @cindex warning for synthesized methods
1461 @cindex synthesized methods, warning
1462 Warn when g++'s synthesis behavior does not match that of cfront.  For
1463 instance:
1464
1465 @smallexample
1466 struct A @{
1467   operator int ();
1468   A& operator = (int);
1469 @};
1470
1471 main ()
1472 @{
1473   A a,b;
1474   a = b;
1475 @}
1476 @end smallexample
1477
1478 In this example, g++ will synthesize a default @samp{A& operator =
1479 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1480 @end table
1481
1482 @node Language Independent Options
1483 @section Options to Control Diagnostic Messages Formatting
1484 @cindex options to control diagnostics formatting
1485 @cindex diagnostic messages
1486 @cindex message formatting
1487
1488 Traditionally, diagnostic messages have been formatted irrespective of
1489 the output device's aspect (e.g. its width, ...).  The options described
1490 below can be used to control the diagnostic messages formatting
1491 algorithm, e.g. how many characters per line, how often source location
1492 information should be reported.  Right now, only the C++ front-end can
1493 honor these options.  However it is expected, in the near future, that
1494 the remaining front-ends would be able to digest them correctly. 
1495
1496 @table @code
1497 @item -fmessage-length=@var{n}
1498 Try to format error messages so that they fit on lines of about @var{n}
1499 characters.  The default is 72 characters for g++ and 0 for the rest of
1500 the front-ends supported by GCC.  If @var{n} is zero, then no
1501 line-wrapping will be done; each error message will appear on a single 
1502 line.
1503
1504 @item -fdiagnostics-show-location=once
1505 Only meaningful in line-wrapping mode.  Instructs the diagnostic messages
1506 reporter to emit @emph{once} source location information; that is, in
1507 case the message is too long to fit on a single physical line and has to
1508 be wrapped, the source location won't be emitted (as prefix) again,
1509 over and over, in subsequent continuation lines.  This is the default
1510 behaviour. 
1511
1512 @item -fdiagnostics-show-location=every-line
1513 Only meaningful in line-wrapping mode.  Instructs the diagnostic
1514 messages reporter to emit the same source location information (as
1515 prefix) for physical lines that result from the process of breaking a
1516 a message which is too long to fit on a single line.
1517
1518 @end table
1519
1520 @node Warning Options
1521 @section Options to Request or Suppress Warnings
1522 @cindex options to control warnings
1523 @cindex warning messages
1524 @cindex messages, warning
1525 @cindex suppressing warnings
1526
1527 Warnings are diagnostic messages that report constructions which
1528 are not inherently erroneous but which are risky or suggest there
1529 may have been an error.
1530
1531 You can request many specific warnings with options beginning @samp{-W},
1532 for example @samp{-Wimplicit} to request warnings on implicit
1533 declarations.  Each of these specific warning options also has a
1534 negative form beginning @samp{-Wno-} to turn off warnings;
1535 for example, @samp{-Wno-implicit}.  This manual lists only one of the
1536 two forms, whichever is not the default.
1537
1538 These options control the amount and kinds of warnings produced by GCC:
1539
1540 @table @code
1541 @cindex syntax checking
1542 @item -fsyntax-only
1543 Check the code for syntax errors, but don't do anything beyond that.
1544
1545 @item -pedantic
1546 Issue all the warnings demanded by strict ISO C and ISO C++;
1547 reject all programs that use forbidden extensions, and some other
1548 programs that do not follow ISO C and ISO C++.  For ISO C, follows the
1549 version of the ISO C standard specified by any @samp{-std} option used.
1550
1551 Valid ISO C and ISO C++ programs should compile properly with or without
1552 this option (though a rare few will require @samp{-ansi}).  However,
1553 without this option, certain GNU extensions and traditional C and C++
1554 features are supported as well.  With this option, they are rejected.
1555
1556 @samp{-pedantic} does not cause warning messages for use of the
1557 alternate keywords whose names begin and end with @samp{__}.  Pedantic
1558 warnings are also disabled in the expression that follows
1559 @code{__extension__}.  However, only system header files should use
1560 these escape routes; application programs should avoid them.
1561 @xref{Alternate Keywords}.
1562
1563 Some users try to use @samp{-pedantic} to check programs for strict ISO
1564 C conformance.  They soon find that it does not do quite what they want:
1565 it finds some non-ISO practices, but not all---only those for which
1566 ISO C @emph{requires} a diagnostic, and some others for which
1567 diagnostics have been added.
1568
1569 A feature to report any failure to conform to ISO C might be useful in
1570 some instances, but would require considerable additional work and would
1571 be quite different from @samp{-pedantic}.  We don't have plans to
1572 support such a feature in the near future.
1573
1574 @item -pedantic-errors
1575 Like @samp{-pedantic}, except that errors are produced rather than
1576 warnings.
1577
1578 @item -w
1579 Inhibit all warning messages.
1580
1581 @item -Wno-import
1582 Inhibit warning messages about the use of @samp{#import}.
1583
1584 @item -Wchar-subscripts
1585 Warn if an array subscript has type @code{char}.  This is a common cause
1586 of error, as programmers often forget that this type is signed on some
1587 machines.
1588
1589 @item -Wcomment
1590 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1591 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1592
1593 @item -Wformat
1594 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1595 the arguments supplied have types appropriate to the format string
1596 specified, and that the conversions specified in the format string make
1597 sense.  This includes standard functions, and others specified by format
1598 attributes (@pxref{Function Attributes}), in the @code{printf},
1599 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
1600 not in the C standard) families.
1601
1602 The formats are checked against the format features supported by GNU
1603 libc version 2.2.  These include all ISO C89 and C99 features, as well
1604 as features from the Single Unix Specification and some BSD and GNU
1605 extensions.  Other library implementations may not support all these
1606 features; GCC does not support warning about features that go beyond a
1607 particular library's limitations.  However, if @samp{-pedantic} is used
1608 with @samp{-Wformat}, warnings will be given about format features not
1609 in the selected standard version (but not for @code{strfmon} formats,
1610 since those are not in any version of the C standard).  @xref{C Dialect
1611 Options,,Options Controlling C Dialect}.
1612
1613 @samp{-Wformat} is included in @samp{-Wall}.  For more control over some
1614 aspects of format checking, the options @samp{-Wno-format-y2k},
1615 @samp{-Wno-format-extra-args}, @samp{-Wformat-nonliteral},
1616 @samp{-Wformat-security} and @samp{-Wformat=2} are available, but are
1617 not included in @samp{-Wall}.
1618
1619 @item -Wno-format-y2k
1620 If @samp{-Wformat} is specified, do not warn about @code{strftime}
1621 formats which may yield only a two-digit year.
1622
1623 @item -Wno-format-extra-args
1624 If @samp{-Wformat} is specified, do not warn about excess arguments to a
1625 @code{printf} or @code{scanf} format function.  The C standard specifies
1626 that such arguments are ignored.
1627
1628 @item -Wformat-nonliteral
1629 If @samp{-Wformat} is specified, also warn if the format string is not a
1630 string literal and so cannot be checked, unless the format function
1631 takes its format arguments as a @code{va_list}.
1632
1633 @item -Wformat-security
1634 If @samp{-Wformat} is specified, also warn about uses of format
1635 functions that represent possible security problems.  At present, this
1636 warns about calls to @code{printf} and @code{scanf} functions where the
1637 format string is not a string literal and there are no format arguments,
1638 as in @code{printf (foo);}.  This may be a security hole if the format
1639 string came from untrusted input and contains @samp{%n}.  (This is
1640 currently a subset of what @samp{-Wformat-nonliteral} warns about, but
1641 in future warnings may be added to @samp{-Wformat-security} that are not
1642 included in @samp{-Wformat-nonliteral}.)
1643
1644 @item -Wformat=2
1645 Enable @samp{-Wformat} plus format checks not included in
1646 @samp{-Wformat}.  Currently equivalent to @samp{-Wformat
1647 -Wformat-nonliteral -Wformat-security}.
1648
1649 @item -Wimplicit-int
1650 Warn when a declaration does not specify a type.
1651
1652 @item -Wimplicit-function-declaration
1653 @itemx -Werror-implicit-function-declaration
1654 Give a warning (or error) whenever a function is used before being
1655 declared.
1656
1657 @item -Wimplicit
1658 Same as @samp{-Wimplicit-int} and @samp{-Wimplicit-function-}@*
1659 @samp{declaration}.
1660
1661 @item -Wmain
1662 Warn if the type of @samp{main} is suspicious.  @samp{main} should be a
1663 function with external linkage, returning int, taking either zero
1664 arguments, two, or three arguments of appropriate types.
1665
1666 @item -Wmultichar
1667 Warn if a multicharacter constant (@samp{'FOOF'}) is used.  Usually they
1668 indicate a typo in the user's code, as they have implementation-defined
1669 values, and should not be used in portable code.
1670
1671 @item -Wparentheses
1672 Warn if parentheses are omitted in certain contexts, such
1673 as when there is an assignment in a context where a truth value
1674 is expected, or when operators are nested whose precedence people
1675 often get confused about.
1676
1677 Also warn about constructions where there may be confusion to which
1678 @code{if} statement an @code{else} branch belongs.  Here is an example of
1679 such a case:
1680
1681 @smallexample
1682 @{
1683   if (a)
1684     if (b)
1685       foo ();
1686   else
1687     bar ();
1688 @}
1689 @end smallexample
1690
1691 In C, every @code{else} branch belongs to the innermost possible @code{if}
1692 statement, which in this example is @code{if (b)}.  This is often not
1693 what the programmer expected, as illustrated in the above example by
1694 indentation the programmer chose.  When there is the potential for this
1695 confusion, GNU C will issue a warning when this flag is specified.
1696 To eliminate the warning, add explicit braces around the innermost
1697 @code{if} statement so there is no way the @code{else} could belong to
1698 the enclosing @code{if}.  The resulting code would look like this:
1699
1700 @smallexample
1701 @{
1702   if (a)
1703     @{
1704       if (b)
1705         foo ();
1706       else
1707         bar ();
1708     @}
1709 @}
1710 @end smallexample
1711
1712 @item -Wsequence-point
1713 Warn about code that may have undefined semantics because of violations
1714 of sequence point rules in the C standard.
1715
1716 The C standard defines the order in which expressions in a C program are
1717 evaluated in terms of @dfn{sequence points}, which represent a partial
1718 ordering between the execution of parts of the program: those executed
1719 before the sequence point, and those executed after it.  These occur
1720 after the evaluation of a full expression (one which is not part of a
1721 larger expression), after the evaluation of the first operand of a
1722 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
1723 function is called (but after the evaluation of its arguments and the
1724 expression denoting the called function), and in certain other places.
1725 Other than as expressed by the sequence point rules, the order of
1726 evaluation of subexpressions of an expression is not specified.  All
1727 these rules describe only a partial order rather than a total order,
1728 since, for example, if two functions are called within one expression
1729 with no sequence point between them, the order in which the functions
1730 are called is not specified.  However, the standards committee have
1731 ruled that function calls do not overlap.
1732
1733 It is not specified when between sequence points modifications to the
1734 values of objects take effect.  Programs whose behavior depends on this
1735 have undefined behavior; the C standard specifies that ``Between the
1736 previous and next sequence point an object shall have its stored value
1737 modified at most once by the evaluation of an expression.  Furthermore,
1738 the prior value shall be read only to determine the value to be
1739 stored.''.  If a program breaks these rules, the results on any
1740 particular implementation are entirely unpredictable.
1741
1742 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
1743 = b[n++]} and @code{a[i++] = i;}.  Some more complicated cases are not
1744 diagnosed by this option, and it may give an occasional false positive
1745 result, but in general it has been found fairly effective at detecting
1746 this sort of problem in programs.
1747
1748 The present implementation of this option only works for C programs.  A
1749 future implementation may also work for C++ programs.
1750
1751 There is some controversy over the precise meaning of the sequence point
1752 rules in subtle cases.  Alternative formal definitions may be found in
1753 Clive Feather's ``Annex S''
1754 @uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n925.htm} and in
1755 Michael Norrish's thesis
1756 @uref{http://www.cl.cam.ac.uk/users/mn200/PhD/thesis-report.ps.gz}.
1757 Other discussions are by Raymond Mak
1758 @uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n926.htm} and
1759 D. Hugh Redelmeier
1760 @uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n927.htm}.
1761
1762 @item -Wreturn-type
1763 Warn whenever a function is defined with a return-type that defaults to
1764 @code{int}.  Also warn about any @code{return} statement with no
1765 return-value in a function whose return-type is not @code{void}. 
1766
1767 For C++, a function without return type always produces a diagnostic
1768 message, even when @samp{-Wno-return-type} is specified. The only
1769 exceptions are @samp{main} and functions defined in system headers.
1770
1771 @item -Wswitch
1772 Warn whenever a @code{switch} statement has an index of enumeral type
1773 and lacks a @code{case} for one or more of the named codes of that
1774 enumeration.  (The presence of a @code{default} label prevents this
1775 warning.)  @code{case} labels outside the enumeration range also
1776 provoke warnings when this option is used.
1777
1778 @item -Wtrigraphs
1779 Warn if any trigraphs are encountered that might change the meaning of
1780 the program (trigraphs within comments are not warned about).
1781
1782 @item -Wunused-function
1783 Warn whenever a static function is declared but not defined or a
1784 non\-inline static function is unused.
1785
1786 @item -Wunused-label
1787 Warn whenever a label is declared but not used.
1788
1789 To suppress this warning use the @samp{unused} attribute
1790 (@pxref{Variable Attributes}).
1791
1792 @item -Wunused-parameter
1793 Warn whenever a function parameter is unused aside from its declaration.
1794
1795 To suppress this warning use the @samp{unused} attribute
1796 (@pxref{Variable Attributes}).
1797
1798 @item -Wunused-variable
1799 Warn whenever a local variable or non-constant static variable is unused
1800 aside from its declaration
1801
1802 To suppress this warning use the @samp{unused} attribute
1803 (@pxref{Variable Attributes}).
1804
1805 @item -Wunused-value
1806 Warn whenever a statement computes a result that is explicitly not used.
1807
1808 To suppress this warning cast the expression to @samp{void}.
1809
1810 @item -Wunused
1811 All all the above @samp{-Wunused} options combined.
1812
1813 In order to get a warning about an unused function parameter, you must
1814 either specify @samp{-W -Wunused} or separately specify
1815 @samp{-Wunused-parameter}.
1816
1817 @item -Wuninitialized
1818 Warn if an automatic variable is used without first being initialized or
1819 if a variable may be clobbered by a @code{setjmp} call.
1820
1821 These warnings are possible only in optimizing compilation,
1822 because they require data flow information that is computed only
1823 when optimizing.  If you don't specify @samp{-O}, you simply won't
1824 get these warnings.
1825
1826 These warnings occur only for variables that are candidates for
1827 register allocation.  Therefore, they do not occur for a variable that
1828 is declared @code{volatile}, or whose address is taken, or whose size
1829 is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
1830 structures, unions or arrays, even when they are in registers.
1831
1832 Note that there may be no warning about a variable that is used only
1833 to compute a value that itself is never used, because such
1834 computations may be deleted by data flow analysis before the warnings
1835 are printed.
1836
1837 These warnings are made optional because GCC is not smart
1838 enough to see all the reasons why the code might be correct
1839 despite appearing to have an error.  Here is one example of how
1840 this can happen:
1841
1842 @smallexample
1843 @{
1844   int x;
1845   switch (y)
1846     @{
1847     case 1: x = 1;
1848       break;
1849     case 2: x = 4;
1850       break;
1851     case 3: x = 5;
1852     @}
1853   foo (x);
1854 @}
1855 @end smallexample
1856
1857 @noindent
1858 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
1859 always initialized, but GCC doesn't know this.  Here is
1860 another common case:
1861
1862 @smallexample
1863 @{
1864   int save_y;
1865   if (change_y) save_y = y, y = new_y;
1866   @dots{}
1867   if (change_y) y = save_y;
1868 @}
1869 @end smallexample
1870
1871 @noindent
1872 This has no bug because @code{save_y} is used only if it is set.
1873
1874 @cindex @code{longjmp} warnings
1875 This option also warns when a non-volatile automatic variable might be
1876 changed by a call to @code{longjmp}.  These warnings as well are possible
1877 only in optimizing compilation.
1878
1879 The compiler sees only the calls to @code{setjmp}.  It cannot know
1880 where @code{longjmp} will be called; in fact, a signal handler could
1881 call it at any point in the code.  As a result, you may get a warning
1882 even when there is in fact no problem because @code{longjmp} cannot
1883 in fact be called at the place which would cause a problem.
1884
1885 Some spurious warnings can be avoided if you declare all the functions
1886 you use that never return as @code{noreturn}.  @xref{Function
1887 Attributes}.
1888
1889 @item -Wreorder (C++ only)
1890 @cindex reordering, warning
1891 @cindex warning for reordering of member initializers
1892 Warn when the order of member initializers given in the code does not
1893 match the order in which they must be executed.  For instance:
1894
1895 @item -Wunknown-pragmas
1896 @cindex warning for unknown pragmas
1897 @cindex unknown pragmas, warning
1898 @cindex pragmas, warning of unknown
1899 Warn when a #pragma directive is encountered which is not understood by
1900 GCC.  If this command line option is used, warnings will even be issued
1901 for unknown pragmas in system header files.  This is not the case if
1902 the warnings were only enabled by the @samp{-Wall} command line option.
1903
1904 @item -Wall
1905 All of the above @samp{-W} options combined.  This enables all the
1906 warnings about constructions that some users consider questionable, and
1907 that are easy to avoid (or modify to prevent the warning), even in
1908 conjunction with macros.
1909
1910 @item -Wsystem-headers
1911 @cindex warnings from system headers
1912 @cindex system headers, warnings from
1913 Print warning messages for constructs found in system header files.
1914 Warnings from system headers are normally suppressed, on the assumption
1915 that they usually do not indicate real problems and would only make the
1916 compiler output harder to read.  Using this command line option tells
1917 GCC to emit warnings from system headers as if they occurred in user
1918 code.  However, note that using @samp{-Wall} in conjunction with this
1919 option will @emph{not} warn about unknown pragmas in system
1920 headers---for that, @samp{-Wunknown-pragmas} must also be used.
1921 @end table
1922
1923 The following @samp{-W@dots{}} options are not implied by @samp{-Wall}.
1924 Some of them warn about constructions that users generally do not
1925 consider questionable, but which occasionally you might wish to check
1926 for; others warn about constructions that are necessary or hard to avoid
1927 in some cases, and there is no simple way to modify the code to suppress
1928 the warning.
1929
1930 @table @code
1931 @item -W
1932 Print extra warning messages for these events:
1933
1934 @itemize @bullet
1935 @item
1936 A function can return either with or without a value.  (Falling
1937 off the end of the function body is considered returning without
1938 a value.)  For example, this function would evoke such a
1939 warning:
1940
1941 @smallexample
1942 @group
1943 foo (a)
1944 @{
1945   if (a > 0)
1946     return a;
1947 @}
1948 @end group
1949 @end smallexample
1950
1951 @item
1952 An expression-statement or the left-hand side of a comma expression
1953 contains no side effects.
1954 To suppress the warning, cast the unused expression to void.
1955 For example, an expression such as @samp{x[i,j]} will cause a warning,
1956 but @samp{x[(void)i,j]} will not.
1957
1958 @item
1959 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
1960
1961 @item
1962 A comparison like @samp{x<=y<=z} appears; this is equivalent to
1963 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
1964 that of ordinary mathematical notation.
1965
1966 @item
1967 Storage-class specifiers like @code{static} are not the first things in
1968 a declaration.  According to the C Standard, this usage is obsolescent.
1969
1970 @item
1971 The return type of a function has a type qualifier such as @code{const}.
1972 Such a type qualifier has no effect, since the value returned by a
1973 function is not an lvalue.  (But don't warn about the GNU extension of
1974 @code{volatile void} return types.  That extension will be warned about
1975 if @samp{-pedantic} is specified.)
1976
1977 @item
1978 If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused
1979 arguments.
1980
1981 @item
1982 A comparison between signed and unsigned values could produce an
1983 incorrect result when the signed value is converted to unsigned.
1984 (But don't warn if @samp{-Wno-sign-compare} is also specified.)
1985
1986 @item
1987 An aggregate has a partly bracketed initializer.
1988 For example, the following code would evoke such a warning,
1989 because braces are missing around the initializer for @code{x.h}:
1990
1991 @smallexample
1992 struct s @{ int f, g; @};
1993 struct t @{ struct s h; int i; @};
1994 struct t x = @{ 1, 2, 3 @};
1995 @end smallexample
1996
1997 @item
1998 An aggregate has an initializer which does not initialize all members.
1999 For example, the following code would cause such a warning, because
2000 @code{x.h} would be implicitly initialized to zero:
2001
2002 @smallexample
2003 struct s @{ int f, g, h; @};
2004 struct s x = @{ 3, 4 @};
2005 @end smallexample
2006 @end itemize
2007
2008 @item -Wfloat-equal
2009 Warn if floating point values are used in equality comparisons.
2010
2011 The idea behind this is that sometimes it is convenient (for the
2012 programmer) to consider floating-point values as approximations to
2013 infinitely precise real numbers.  If you are doing this, then you need
2014 to compute (by analysing the code, or in some other way) the maximum or
2015 likely maximum error that the computation introduces, and allow for it
2016 when performing comparisons (and when producing output, but that's a
2017 different problem).  In particular, instead of testing for equality, you
2018 would check to see whether the two values have ranges that overlap; and
2019 this is done with the relational operators, so equality comparisons are
2020 probably mistaken.
2021
2022 @item -Wtraditional (C only)
2023 Warn about certain constructs that behave differently in traditional and
2024 ISO C.
2025
2026 @itemize @bullet
2027 @item
2028 Macro arguments occurring within string constants in the macro body.
2029 These would substitute the argument in traditional C, but are part of
2030 the constant in ISO C.
2031
2032 @item
2033 A function declared external in one block and then used after the end of
2034 the block.
2035
2036 @item
2037 A @code{switch} statement has an operand of type @code{long}.
2038
2039 @item
2040 A non-@code{static} function declaration follows a @code{static} one.
2041 This construct is not accepted by some traditional C compilers.
2042
2043 @item
2044 The ISO type of an integer constant has a different width or
2045 signedness from its traditional type.  This warning is only issued if
2046 the base of the constant is ten.  I.e. hexadecimal or octal values, which
2047 typically represent bit patterns, are not warned about.
2048
2049 @item
2050 Usage of ISO string concatenation is detected.
2051
2052 @item
2053 A function macro appears without arguments.
2054
2055 @item
2056 The unary plus operator.
2057
2058 @item
2059 Initialization of automatic aggregates.
2060
2061 @item
2062 Identifier conflicts with labels.  Traditional C lacks a separate
2063 namespace for labels.
2064
2065 @item
2066 Initialization of unions.  If the initializer is zero, the warning is
2067 omitted.  This is done under the assumption that the zero initializer in
2068 user code appears conditioned on e.g. @code{__STDC__} to avoid missing
2069 initializer warnings and relies on default initialization to zero in the
2070 traditional C case.
2071
2072 @item
2073 The `U' integer constant suffix, or the `F' or `L' floating point
2074 constant suffixes.  (Traditonal C does support the `L' suffix on integer
2075 constants.)  Note, these suffixes appear in macros defined in the system
2076 headers of most modern systems, e.g. the _MIN/_MAX macros in limits.h.
2077 Use of these macros can lead to spurious warnings as they do not
2078 necessarily reflect whether the code in question is any less portable to
2079 traditional C given that suitable backup definitions are provided.
2080 @end itemize
2081
2082 @item -Wundef
2083 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2084
2085 @item -Wshadow
2086 Warn whenever a local variable shadows another local variable.
2087
2088 @item -Wid-clash-@var{len}
2089 Warn whenever two distinct identifiers match in the first @var{len}
2090 characters.  This may help you prepare a program that will compile
2091 with certain obsolete, brain-damaged compilers.
2092
2093 @item -Wlarger-than-@var{len}
2094 Warn whenever an object of larger than @var{len} bytes is defined.
2095
2096 @item -Wpointer-arith
2097 Warn about anything that depends on the ``size of'' a function type or
2098 of @code{void}.  GNU C assigns these types a size of 1, for
2099 convenience in calculations with @code{void *} pointers and pointers
2100 to functions.
2101
2102 @item -Wbad-function-cast (C only)
2103 Warn whenever a function call is cast to a non-matching type.
2104 For example, warn if @code{int malloc()} is cast to @code{anything *}.
2105
2106 @item -Wcast-qual
2107 Warn whenever a pointer is cast so as to remove a type qualifier from
2108 the target type.  For example, warn if a @code{const char *} is cast
2109 to an ordinary @code{char *}.
2110
2111 @item -Wcast-align
2112 Warn whenever a pointer is cast such that the required alignment of the
2113 target is increased.  For example, warn if a @code{char *} is cast to
2114 an @code{int *} on machines where integers can only be accessed at
2115 two- or four-byte boundaries.
2116
2117 @item -Wwrite-strings
2118 Give string constants the type @code{const char[@var{length}]} so that
2119 copying the address of one into a non-@code{const} @code{char *}
2120 pointer will get a warning.  These warnings will help you find at
2121 compile time code that can try to write into a string constant, but
2122 only if you have been very careful about using @code{const} in
2123 declarations and prototypes.  Otherwise, it will just be a nuisance;
2124 this is why we did not make @samp{-Wall} request these warnings.
2125
2126 @item -Wconversion
2127 Warn if a prototype causes a type conversion that is different from what
2128 would happen to the same argument in the absence of a prototype.  This
2129 includes conversions of fixed point to floating and vice versa, and
2130 conversions changing the width or signedness of a fixed point argument
2131 except when the same as the default promotion.
2132
2133 Also, warn if a negative integer constant expression is implicitly
2134 converted to an unsigned type.  For example, warn about the assignment
2135 @code{x = -1} if @code{x} is unsigned.  But do not warn about explicit
2136 casts like @code{(unsigned) -1}.
2137
2138 @item -Wsign-compare
2139 @cindex warning for comparison of signed and unsigned values
2140 @cindex comparison of signed and unsigned values, warning
2141 @cindex signed and unsigned values, comparison warning
2142 Warn when a comparison between signed and unsigned values could produce
2143 an incorrect result when the signed value is converted to unsigned.
2144 This warning is also enabled by @samp{-W}; to get the other warnings
2145 of @samp{-W} without this warning, use @samp{-W -Wno-sign-compare}.
2146
2147 @item -Waggregate-return
2148 Warn if any functions that return structures or unions are defined or
2149 called.  (In languages where you can return an array, this also elicits
2150 a warning.)
2151
2152 @item -Wstrict-prototypes (C only)
2153 Warn if a function is declared or defined without specifying the
2154 argument types.  (An old-style function definition is permitted without
2155 a warning if preceded by a declaration which specifies the argument
2156 types.)
2157
2158 @item -Wmissing-prototypes (C only)
2159 Warn if a global function is defined without a previous prototype
2160 declaration.  This warning is issued even if the definition itself
2161 provides a prototype.  The aim is to detect global functions that fail
2162 to be declared in header files.
2163
2164 @item -Wmissing-declarations
2165 Warn if a global function is defined without a previous declaration.
2166 Do so even if the definition itself provides a prototype.
2167 Use this option to detect global functions that are not declared in
2168 header files.
2169
2170 @item -Wmissing-noreturn
2171 Warn about functions which might be candidates for attribute @code{noreturn}.
2172 Note these are only possible candidates, not absolute ones.  Care should
2173 be taken to manually verify functions actually do not ever return before
2174 adding the @code{noreturn} attribute, otherwise subtle code generation
2175 bugs could be introduced.  You will not get a warning for @code{main} in
2176 hosted C environments.
2177
2178 @item -Wmissing-format-attribute
2179 If @samp{-Wformat} is enabled, also warn about functions which might be
2180 candidates for @code{format} attributes.  Note these are only possible
2181 candidates, not absolute ones.  GCC will guess that @code{format}
2182 attributes might be appropriate for any function that calls a function
2183 like @code{vprintf} or @code{vscanf}, but this might not always be the
2184 case, and some functions for which @code{format} attributes are
2185 appropriate may not be detected.  This option has no effect unless
2186 @samp{-Wformat} is enabled (possibly by @samp{-Wall}).
2187
2188 @item -Wpacked
2189 Warn if a structure is given the packed attribute, but the packed
2190 attribute has no effect on the layout or size of the structure.  
2191 Such structures may be mis-aligned for little benefit.  For
2192 instance, in this code, the variable @code{f.x} in @code{struct bar}
2193 will be misaligned even though @code{struct bar} does not itself
2194 have the packed attribute:
2195
2196 @smallexample
2197 @group
2198 struct foo @{
2199   int x;
2200   char a, b, c, d;
2201 @} __attribute__((packed));
2202 struct bar @{
2203   char z;
2204   struct foo f;
2205 @};
2206 @end group
2207 @end smallexample
2208
2209 @item -Wpadded
2210 Warn if padding is included in a structure, either to align an element
2211 of the structure or to align the whole structure.  Sometimes when this
2212 happens it is possible to rearrange the fields of the structure to
2213 reduce the padding and so make the structure smaller.
2214
2215 @item -Wredundant-decls
2216 Warn if anything is declared more than once in the same scope, even in
2217 cases where multiple declaration is valid and changes nothing.
2218
2219 @item -Wnested-externs (C only)
2220 Warn if an @code{extern} declaration is encountered within a function.
2221
2222 @item -Wunreachable-code
2223 Warn if the compiler detects that code will never be executed.
2224
2225 This option is intended to warn when the compiler detects that at
2226 least a whole line of source code will never be executed, because
2227 some condition is never satisfied or because it is after a
2228 procedure that never returns.
2229
2230 It is possible for this option to produce a warning even though there
2231 are circumstances under which part of the affected line can be executed,
2232 so care should be taken when removing apparently-unreachable code.
2233
2234 For instance, when a function is inlined, a warning may mean that the
2235 line is unreachable in only one inlined copy of the function.  
2236
2237 This option is not made part of @samp{-Wall} because in a debugging
2238 version of a program there is often substantial code which checks
2239 correct functioning of the program and is, hopefully, unreachable
2240 because the program does work.  Another common use of unreachable
2241 code is to provide behaviour which is selectable at compile-time.
2242
2243 @item -Winline
2244 Warn if a function can not be inlined and it was declared as inline.
2245
2246 @item -Wlong-long
2247 Warn if @samp{long long} type is used.  This is default.  To inhibit
2248 the warning messages, use @samp{-Wno-long-long}.  Flags
2249 @samp{-Wlong-long} and @samp{-Wno-long-long} are taken into account
2250 only when @samp{-pedantic} flag is used.
2251
2252 @item -Wdisabled-optimization
2253 Warn if a requested optimization pass is disabled.  This warning does
2254 not generally indicate that there is anything wrong with your code; it
2255 merely indicates that GCC's optimizers were unable to handle the code
2256 effectively.  Often, the problem is that your code is too big or too
2257 complex; GCC will refuse to optimize programs when the optimization
2258 itself is likely to take inordinate amounts of time.
2259
2260 @item -Werror
2261 Make all warnings into errors.
2262 @end table
2263
2264 @node Debugging Options
2265 @section Options for Debugging Your Program or GCC
2266 @cindex options, debugging
2267 @cindex debugging information options
2268
2269 GCC has various special options that are used for debugging
2270 either your program or GCC:
2271
2272 @table @code
2273 @item -g
2274 Produce debugging information in the operating system's native format
2275 (stabs, COFF, XCOFF, or DWARF).  GDB can work with this debugging
2276 information.
2277
2278 On most systems that use stabs format, @samp{-g} enables use of extra
2279 debugging information that only GDB can use; this extra information
2280 makes debugging work better in GDB but will probably make other debuggers
2281 crash or
2282 refuse to read the program.  If you want to control for certain whether
2283 to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs},
2284 @samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf-1+}, or @samp{-gdwarf-1}
2285 (see below).
2286
2287 Unlike most other C compilers, GCC allows you to use @samp{-g} with
2288 @samp{-O}.  The shortcuts taken by optimized code may occasionally
2289 produce surprising results: some variables you declared may not exist
2290 at all; flow of control may briefly move where you did not expect it;
2291 some statements may not be executed because they compute constant
2292 results or their values were already at hand; some statements may
2293 execute in different places because they were moved out of loops.
2294
2295 Nevertheless it proves possible to debug optimized output.  This makes
2296 it reasonable to use the optimizer for programs that might have bugs.
2297
2298 The following options are useful when GCC is generated with the
2299 capability for more than one debugging format.
2300
2301 @item -ggdb
2302 Produce debugging information for use by GDB.  This means to use the
2303 most expressive format available (DWARF 2, stabs, or the native format
2304 if neither of those are supported), including GDB extensions if at all
2305 possible.
2306
2307 @item -gstabs
2308 Produce debugging information in stabs format (if that is supported),
2309 without GDB extensions.  This is the format used by DBX on most BSD
2310 systems.  On MIPS, Alpha and System V Release 4 systems this option
2311 produces stabs debugging output which is not understood by DBX or SDB.
2312 On System V Release 4 systems this option requires the GNU assembler.
2313
2314 @item -gstabs+
2315 Produce debugging information in stabs format (if that is supported),
2316 using GNU extensions understood only by the GNU debugger (GDB).  The
2317 use of these extensions is likely to make other debuggers crash or
2318 refuse to read the program.
2319
2320 @item -gcoff
2321 Produce debugging information in COFF format (if that is supported).
2322 This is the format used by SDB on most System V systems prior to
2323 System V Release 4.
2324
2325 @item -gxcoff
2326 Produce debugging information in XCOFF format (if that is supported).
2327 This is the format used by the DBX debugger on IBM RS/6000 systems.
2328
2329 @item -gxcoff+
2330 Produce debugging information in XCOFF format (if that is supported),
2331 using GNU extensions understood only by the GNU debugger (GDB).  The
2332 use of these extensions is likely to make other debuggers crash or
2333 refuse to read the program, and may cause assemblers other than the GNU
2334 assembler (GAS) to fail with an error.
2335
2336 @item -gdwarf
2337 Produce debugging information in DWARF version 1 format (if that is
2338 supported).  This is the format used by SDB on most System V Release 4
2339 systems.
2340
2341 @item -gdwarf+
2342 Produce debugging information in DWARF version 1 format (if that is
2343 supported), using GNU extensions understood only by the GNU debugger
2344 (GDB).  The use of these extensions is likely to make other debuggers
2345 crash or refuse to read the program.
2346
2347 @item -gdwarf-2
2348 Produce debugging information in DWARF version 2 format (if that is
2349 supported).  This is the format used by DBX on IRIX 6.
2350
2351 @item -g@var{level}
2352 @itemx -ggdb@var{level}
2353 @itemx -gstabs@var{level}
2354 @itemx -gcoff@var{level}
2355 @itemx -gxcoff@var{level}
2356 @itemx -gdwarf@var{level}
2357 @itemx -gdwarf-2@var{level}
2358 Request debugging information and also use @var{level} to specify how
2359 much information.  The default level is 2.
2360
2361 Level 1 produces minimal information, enough for making backtraces in
2362 parts of the program that you don't plan to debug.  This includes
2363 descriptions of functions and external variables, but no information
2364 about local variables and no line numbers.
2365
2366 Level 3 includes extra information, such as all the macro definitions
2367 present in the program.  Some debuggers support macro expansion when
2368 you use @samp{-g3}.
2369
2370 @cindex @code{prof}
2371 @item -p
2372 Generate extra code to write profile information suitable for the
2373 analysis program @code{prof}.  You must use this option when compiling
2374 the source files you want data about, and you must also use it when
2375 linking.
2376
2377 @cindex @code{gprof}
2378 @item -pg
2379 Generate extra code to write profile information suitable for the
2380 analysis program @code{gprof}.  You must use this option when compiling
2381 the source files you want data about, and you must also use it when
2382 linking.
2383
2384 @cindex @code{tcov}
2385 @item -a
2386 Generate extra code to write profile information for basic blocks, which will
2387 record the number of times each basic block is executed, the basic block start
2388 address, and the function name containing the basic block.  If @samp{-g} is
2389 used, the line number and filename of the start of the basic block will also be
2390 recorded.  If not overridden by the machine description, the default action is
2391 to append to the text file @file{bb.out}.
2392
2393 This data could be analyzed by a program like @code{tcov}.  Note,
2394 however, that the format of the data is not what @code{tcov} expects.
2395 Eventually GNU @code{gprof} should be extended to process this data.
2396
2397 @item -Q
2398 Makes the compiler print out each function name as it is compiled, and
2399 print some statistics about each pass when it finishes.
2400
2401 @item -ax
2402 Generate extra code to profile basic blocks.  Your executable will
2403 produce output that is a superset of that produced when @samp{-a} is
2404 used.  Additional output is the source and target address of the basic
2405 blocks where a jump takes place, the number of times a jump is executed,
2406 and (optionally) the complete sequence of basic blocks being executed.
2407 The output is appended to file @file{bb.out}.
2408
2409 You can examine different profiling aspects without recompilation.  Your
2410 executable will read a list of function names from file @file{bb.in}.
2411 Profiling starts when a function on the list is entered and stops when
2412 that invocation is exited.  To exclude a function from profiling, prefix
2413 its name with `-'.  If a function name is not unique, you can
2414 disambiguate it by writing it in the form
2415 @samp{/path/filename.d:functionname}.  Your executable will write the
2416 available paths and filenames in file @file{bb.out}.
2417
2418 Several function names have a special meaning:
2419 @table @code
2420 @item __bb_jumps__
2421 Write source, target and frequency of jumps to file @file{bb.out}.
2422 @item __bb_hidecall__
2423 Exclude function calls from frequency count.
2424 @item __bb_showret__
2425 Include function returns in frequency count.
2426 @item __bb_trace__
2427 Write the sequence of basic blocks executed to file @file{bbtrace.gz}.
2428 The file will be compressed using the program @samp{gzip}, which must
2429 exist in your @code{PATH}.  On systems without the @samp{popen}
2430 function, the file will be named @file{bbtrace} and will not be
2431 compressed.  @strong{Profiling for even a few seconds on these systems
2432 will produce a very large file.}  Note: @code{__bb_hidecall__} and
2433 @code{__bb_showret__} will not affect the sequence written to
2434 @file{bbtrace.gz}.
2435 @end table
2436
2437 Here's a short example using different profiling parameters
2438 in file @file{bb.in}.  Assume function @code{foo} consists of basic blocks
2439 1 and 2 and is called twice from block 3 of function @code{main}.  After
2440 the calls, block 3 transfers control to block 4 of @code{main}.
2441
2442 With @code{__bb_trace__} and @code{main} contained in file @file{bb.in},
2443 the following sequence of blocks is written to file @file{bbtrace.gz}:
2444 0 3 1 2 1 2 4.  The return from block 2 to block 3 is not shown, because
2445 the return is to a point inside the block and not to the top.  The
2446 block address 0 always indicates, that control is transferred
2447 to the trace from somewhere outside the observed functions.  With
2448 @samp{-foo} added to @file{bb.in}, the blocks of function
2449 @code{foo} are removed from the trace, so only 0 3 4 remains.
2450
2451 With @code{__bb_jumps__} and @code{main} contained in file @file{bb.in},
2452 jump frequencies will be written to file @file{bb.out}.  The
2453 frequencies are obtained by constructing a trace of blocks
2454 and incrementing a counter for every neighbouring pair of blocks
2455 in the trace.  The trace 0 3 1 2 1 2 4 displays the following
2456 frequencies:
2457
2458 @example
2459 Jump from block 0x0 to block 0x3 executed 1 time(s)
2460 Jump from block 0x3 to block 0x1 executed 1 time(s)
2461 Jump from block 0x1 to block 0x2 executed 2 time(s)
2462 Jump from block 0x2 to block 0x1 executed 1 time(s)
2463 Jump from block 0x2 to block 0x4 executed 1 time(s)
2464 @end example
2465
2466 With @code{__bb_hidecall__}, control transfer due to call instructions
2467 is removed from the trace, that is the trace is cut into three parts: 0
2468 3 4, 0 1 2 and 0 1 2.  With @code{__bb_showret__}, control transfer due
2469 to return instructions is added to the trace.  The trace becomes: 0 3 1
2470 2 3 1 2 3 4.  Note, that this trace is not the same, as the sequence
2471 written to @file{bbtrace.gz}.  It is solely used for counting jump
2472 frequencies.
2473
2474 @item -fprofile-arcs
2475 Instrument @dfn{arcs} during compilation.  For each function of your
2476 program, GCC creates a program flow graph, then finds a spanning tree
2477 for the graph.  Only arcs that are not on the spanning tree have to be
2478 instrumented: the compiler adds code to count the number of times that these
2479 arcs are executed.  When an arc is the only exit or only entrance to a
2480 block, the instrumentation code can be added to the block; otherwise, a
2481 new basic block must be created to hold the instrumentation code.
2482
2483 Since not every arc in the program must be instrumented, programs
2484 compiled with this option run faster than programs compiled with
2485 @samp{-a}, which adds instrumentation code to every basic block in the
2486 program.  The tradeoff: since @code{gcov} does not have
2487 execution counts for all branches, it must start with the execution
2488 counts for the instrumented branches, and then iterate over the program
2489 flow graph until the entire graph has been solved.  Hence, @code{gcov}
2490 runs a little more slowly than a program which uses information from
2491 @samp{-a}.
2492
2493 @samp{-fprofile-arcs} also makes it possible to estimate branch
2494 probabilities, and to calculate basic block execution counts.  In
2495 general, basic block execution counts do not give enough information to
2496 estimate all branch probabilities.  When the compiled program exits, it
2497 saves the arc execution counts to a file called
2498 @file{@var{sourcename}.da}.  Use the compiler option
2499 @samp{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
2500 Control Optimization}) when recompiling, to optimize using estimated
2501 branch probabilities.
2502
2503 @need 2000
2504 @item -ftest-coverage
2505 Create data files for the @code{gcov} code-coverage utility
2506 (@pxref{Gcov,, @code{gcov}: a GCC Test Coverage Program}).
2507 The data file names begin with the name of your source file:
2508
2509 @table @code
2510 @item @var{sourcename}.bb
2511 A mapping from basic blocks to line numbers, which @code{gcov} uses to
2512 associate basic block execution counts with line numbers.
2513
2514 @item @var{sourcename}.bbg
2515 A list of all arcs in the program flow graph.  This allows @code{gcov}
2516 to reconstruct the program flow graph, so that it can compute all basic
2517 block and arc execution counts from the information in the
2518 @code{@var{sourcename}.da} file (this last file is the output from
2519 @samp{-fprofile-arcs}).
2520 @end table
2521
2522 @item -d@var{letters}
2523 Says to make debugging dumps during compilation at times specified by
2524 @var{letters}.  This is used for debugging the compiler.  The file names
2525 for most of the dumps are made by appending a pass number and a word to
2526 the source file name (e.g.  @file{foo.c.00.rtl} or @file{foo.c.01.sibling}). 
2527 Here are the possible letters for use in @var{letters}, and their meanings:
2528
2529 @table @samp
2530 @item A
2531 Annotate the assembler output with miscellaneous debugging information.
2532 @item b
2533 Dump after computing branch probabilities, to @file{@var{file}.11.bp}.
2534 @item B
2535 Dump after block reordering, to @file{@var{file}.26.bbro}.
2536 @item c
2537 Dump after instruction combination, to the file @file{@var{file}.14.combine}.
2538 @item C
2539 Dump after the first if conversion, to the file @file{@var{file}.15.ce}.
2540 @item d
2541 Dump after delayed branch scheduling, to @file{@var{file}.29.dbr}.
2542 @item D
2543 Dump all macro definitions, at the end of preprocessing, in addition to
2544 normal output.
2545 @item e
2546 Dump after SSA optimizations, to @file{@var{file}.05.ssa} and
2547 @file{@var{file}.06.ussa}.
2548 @item E
2549 Dump after the second if conversion, to @file{@var{file}.24.ce2}.
2550 @item f
2551 Dump after life analysis, to @file{@var{file}.13.life}.
2552 @item F
2553 Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.04.addressof}.
2554 @item g
2555 Dump after global register allocation, to @file{@var{file}.19.greg}.
2556 @item o
2557 Dump after post-reload CSE and other optimizations, to @file{@var{file}.20.postreload}.
2558 @item G      
2559 Dump after GCSE, to @file{@var{file}.08.gcse}.
2560 @item i
2561 Dump after sibling call optimizations, to @file{@var{file}.01.sibling}.
2562 @item j
2563 Dump after the first jump optimization, to @file{@var{file}.02.jump}.
2564 @item J
2565 Dump after the last jump optimization, to @file{@var{file}.27.jump2}.
2566 @item k
2567 Dump after conversion from registers to stack, to @file{@var{file}.29.stack}.
2568 @item l
2569 Dump after local register allocation, to @file{@var{file}.18.lreg}.
2570 @item L
2571 Dump after loop optimization, to @file{@var{file}.09.loop}.
2572 @item M
2573 Dump after performing the machine dependent reorganisation pass, to
2574 @file{@var{file}.28.mach}. 
2575 @item n
2576 Dump after register renumbering, to @file{@var{file}.23.rnreg}.
2577 @item N
2578 Dump after the register move pass, to @file{@var{file}.16.regmove}.
2579 @item r
2580 Dump after RTL generation, to @file{@var{file}.00.rtl}.
2581 @item R
2582 Dump after the second instruction scheduling pass, to
2583 @file{@var{file}.25.sched2}.
2584 @item s
2585 Dump after CSE (including the jump optimization that sometimes follows
2586 CSE), to @file{@var{file}.03.cse}. 
2587 @item S
2588 Dump after the first instruction scheduling pass, to
2589 @file{@var{file}.17.sched}.
2590 @item t
2591 Dump after the second CSE pass (including the jump optimization that
2592 sometimes follows CSE), to @file{@var{file}.10.cse2}.
2593 @item w
2594 Dump after the second flow pass, to @file{@var{file}.21.flow2}.
2595 @item X
2596 Dump after dead code elimination, to @file{@var{file}.06.dce}.
2597 @item z
2598 Dump after the peephole pass, to @file{@var{file}.22.peephole2}.
2599 @item a
2600 Produce all the dumps listed above.
2601 @item m
2602 Print statistics on memory usage, at the end of the run, to
2603 standard error.
2604 @item p
2605 Annotate the assembler output with a comment indicating which
2606 pattern and alternative was used.  The length of each instruction is
2607 also printed.
2608 @item P
2609 Dump the RTL in the assembler output as a comment before each instruction.
2610 Also turns on @samp{-dp} annotation.
2611 @item v
2612 For each of the other indicated dump files (except for
2613 @file{@var{file}.00.rtl}), dump a representation of the control flow graph
2614 suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
2615 @item x
2616 Just generate RTL for a function instead of compiling it.  Usually used
2617 with @samp{r}.
2618 @item y
2619 Dump debugging information during parsing, to standard error.
2620 @end table
2621
2622 @item -fdump-unnumbered
2623 When doing debugging dumps (see -d option above), suppress instruction
2624 numbers and line number note output.  This makes it more feasible to
2625 use diff on debugging dumps for compiler invocations with different
2626 options, in particular with and without -g.
2627
2628 @item -fdump-translation-unit-@var{file} (C and C++ only)
2629 Dump a representation of the tree structure for the entire translation
2630 unit to @var{file}.
2631
2632 @item -fpretend-float
2633 When running a cross-compiler, pretend that the target machine uses the
2634 same floating point format as the host machine.  This causes incorrect
2635 output of the actual floating constants, but the actual instruction
2636 sequence will probably be the same as GCC would make when running on
2637 the target machine.
2638
2639 @item -save-temps
2640 Store the usual ``temporary'' intermediate files permanently; place them
2641 in the current directory and name them based on the source file.  Thus,
2642 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
2643 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.  This creates a
2644 preprocessed @file{foo.i} output file even though the compiler now
2645 normally uses an integrated preprocessor.
2646
2647 @item -time
2648 Report the CPU time taken by each subprocess in the compilation
2649 sequence.  For C source files, this is the compiler proper and assembler
2650 (plus the linker if linking is done).  The output looks like this:
2651
2652 @smallexample
2653 # cc1 0.12 0.01
2654 # as 0.00 0.01
2655 @end smallexample
2656
2657 The first number on each line is the ``user time,'' that is time spent
2658 executing the program itself.  The second number is ``system time,''
2659 time spent executing operating system routines on behalf of the program.
2660 Both numbers are in seconds.
2661
2662 @item -print-file-name=@var{library}
2663 Print the full absolute name of the library file @var{library} that
2664 would be used when linking---and don't do anything else.  With this
2665 option, GCC does not compile or link anything; it just prints the
2666 file name.
2667
2668 @item -print-prog-name=@var{program}
2669 Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}.
2670
2671 @item -print-libgcc-file-name
2672 Same as @samp{-print-file-name=libgcc.a}.
2673
2674 This is useful when you use @samp{-nostdlib} or @samp{-nodefaultlibs}
2675 but you do want to link with @file{libgcc.a}.  You can do
2676
2677 @example
2678 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
2679 @end example
2680
2681 @item -print-search-dirs
2682 Print the name of the configured installation directory and a list of
2683 program and library directories gcc will search---and don't do anything else.
2684
2685 This is useful when gcc prints the error message
2686 @samp{installation problem, cannot exec cpp0: No such file or directory}.
2687 To resolve this you either need to put @file{cpp0} and the other compiler
2688 components where gcc expects to find them, or you can set the environment
2689 variable @code{GCC_EXEC_PREFIX} to the directory where you installed them.
2690 Don't forget the trailing '/'.
2691 @xref{Environment Variables}.
2692 @end table
2693
2694 @node Optimize Options
2695 @section Options That Control Optimization
2696 @cindex optimize options
2697 @cindex options, optimization
2698
2699 These options control various sorts of optimizations:
2700
2701 @table @code
2702 @item -O
2703 @itemx -O1
2704 Optimize.  Optimizing compilation takes somewhat more time, and a lot
2705 more memory for a large function.
2706
2707 Without @samp{-O}, the compiler's goal is to reduce the cost of
2708 compilation and to make debugging produce the expected results.
2709 Statements are independent: if you stop the program with a breakpoint
2710 between statements, you can then assign a new value to any variable or
2711 change the program counter to any other statement in the function and
2712 get exactly the results you would expect from the source code.
2713
2714 Without @samp{-O}, the compiler only allocates variables declared
2715 @code{register} in registers.  The resulting compiled code is a little
2716 worse than produced by PCC without @samp{-O}.
2717
2718 With @samp{-O}, the compiler tries to reduce code size and execution
2719 time.
2720
2721 When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps}
2722 and @samp{-fdefer-pop} on all machines.  The compiler turns on
2723 @samp{-fdelayed-branch} on machines that have delay slots, and
2724 @samp{-fomit-frame-pointer} on machines that can support debugging even
2725 without a frame pointer.  On some machines the compiler also turns
2726 on other flags.@refill
2727
2728 @item -O2
2729 Optimize even more.  GCC performs nearly all supported optimizations
2730 that do not involve a space-speed tradeoff.  The compiler does not
2731 perform loop unrolling or function inlining when you specify @samp{-O2}.
2732 As compared to @samp{-O}, this option increases both compilation time
2733 and the performance of the generated code.
2734
2735 @samp{-O2} turns on all optional optimizations except for loop unrolling,
2736 function inlining, and register renaming.  It also turns on the
2737 @samp{-fforce-mem} option on all machines and frame pointer elimination
2738 on machines where doing so does not interfere with debugging.
2739
2740 @item -O3
2741 Optimize yet more.  @samp{-O3} turns on all optimizations specified by
2742 @samp{-O2} and also turns on the @samp{-finline-functions} and
2743 @samp{-frename-registers} options.
2744
2745 @item -O0
2746 Do not optimize.
2747
2748 @item -Os
2749 Optimize for size.  @samp{-Os} enables all @samp{-O2} optimizations that
2750 do not typically increase code size.  It also performs further
2751 optimizations designed to reduce code size.
2752
2753 If you use multiple @samp{-O} options, with or without level numbers,
2754 the last such option is the one that is effective.
2755 @end table
2756
2757 Options of the form @samp{-f@var{flag}} specify machine-independent
2758 flags.  Most flags have both positive and negative forms; the negative
2759 form of @samp{-ffoo} would be @samp{-fno-foo}.  In the table below,
2760 only one of the forms is listed---the one which is not the default.
2761 You can figure out the other form by either removing @samp{no-} or
2762 adding it.
2763
2764 @table @code
2765 @item -ffloat-store
2766 Do not store floating point variables in registers, and inhibit other
2767 options that might change whether a floating point value is taken from a
2768 register or memory.
2769
2770 @cindex floating point precision
2771 This option prevents undesirable excess precision on machines such as
2772 the 68000 where the floating registers (of the 68881) keep more
2773 precision than a @code{double} is supposed to have.  Similarly for the
2774 x86 architecture.  For most programs, the excess precision does only
2775 good, but a few programs rely on the precise definition of IEEE floating
2776 point.  Use @samp{-ffloat-store} for such programs, after modifying
2777 them to store all pertinent intermediate computations into variables.
2778
2779 @item -fno-default-inline
2780 Do not make member functions inline by default merely because they are
2781 defined inside the class scope (C++ only).  Otherwise, when you specify
2782 @w{@samp{-O}}, member functions defined inside class scope are compiled
2783 inline by default; i.e., you don't need to add @samp{inline} in front of
2784 the member function name.
2785
2786 @item -fno-defer-pop
2787 Always pop the arguments to each function call as soon as that function
2788 returns.  For machines which must pop arguments after a function call,
2789 the compiler normally lets arguments accumulate on the stack for several
2790 function calls and pops them all at once.
2791
2792 @item -fforce-mem
2793 Force memory operands to be copied into registers before doing
2794 arithmetic on them.  This produces better code by making all memory
2795 references potential common subexpressions.  When they are not common
2796 subexpressions, instruction combination should eliminate the separate
2797 register-load.  The @samp{-O2} option turns on this option.
2798
2799 @item -fforce-addr
2800 Force memory address constants to be copied into registers before
2801 doing arithmetic on them.  This may produce better code just as
2802 @samp{-fforce-mem} may.
2803
2804 @item -fomit-frame-pointer
2805 Don't keep the frame pointer in a register for functions that
2806 don't need one.  This avoids the instructions to save, set up and
2807 restore frame pointers; it also makes an extra register available
2808 in many functions.  @strong{It also makes debugging impossible on
2809 some machines.}
2810
2811 @ifset INTERNALS
2812 On some machines, such as the Vax, this flag has no effect, because
2813 the standard calling sequence automatically handles the frame pointer
2814 and nothing is saved by pretending it doesn't exist.  The
2815 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2816 whether a target machine supports this flag.  @xref{Registers}.@refill
2817 @end ifset
2818 @ifclear INTERNALS
2819 On some machines, such as the Vax, this flag has no effect, because
2820 the standard calling sequence automatically handles the frame pointer
2821 and nothing is saved by pretending it doesn't exist.  The
2822 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
2823 whether a target machine supports this flag.  @xref{Registers,,Register
2824 Usage, gcc.info, Using and Porting GCC}.@refill
2825 @end ifclear
2826
2827 @item -foptimize-sibling-calls
2828 Optimize sibling and tail recursive calls.
2829
2830 @item -ftrapv
2831 This option generates traps for signed overflow on addition, subtraction,
2832 multiplication operations.
2833
2834 @item -fno-inline
2835 Don't pay attention to the @code{inline} keyword.  Normally this option
2836 is used to keep the compiler from expanding any functions inline.
2837 Note that if you are not optimizing, no functions can be expanded inline.
2838
2839 @item -finline-functions
2840 Integrate all simple functions into their callers.  The compiler
2841 heuristically decides which functions are simple enough to be worth
2842 integrating in this way.
2843
2844 If all calls to a given function are integrated, and the function is
2845 declared @code{static}, then the function is normally not output as
2846 assembler code in its own right.
2847
2848 @item -finline-limit=@var{n}
2849 By default, gcc limits the size of functions that can be inlined.  This flag
2850 allows the control of this limit for functions that are explicitly marked as
2851 inline (ie marked with the inline keyword or defined within the class 
2852 definition in c++).  @var{n} is the size of functions that can be inlined in 
2853 number of pseudo instructions (not counting parameter handling).  The default
2854 value of n is 10000.  Increasing this value can result in more inlined code at
2855 the cost of compilation time and memory consumption.  Decreasing usually makes
2856 the compilation faster and less code will be inlined (which presumably 
2857 means slower programs).  This option is particularly useful for programs that 
2858 use inlining heavily such as those based on recursive templates with c++.
2859
2860 @emph{Note:} pseudo instruction represents, in this particular context, an
2861 abstract measurement of function's size.  In no way, it represents a count
2862 of assembly instructions and as such its exact meaning might change from one
2863 release to an another.
2864
2865 @item -fkeep-inline-functions
2866 Even if all calls to a given function are integrated, and the function
2867 is declared @code{static}, nevertheless output a separate run-time
2868 callable version of the function.  This switch does not affect
2869 @code{extern inline} functions.
2870
2871 @item -fkeep-static-consts
2872 Emit variables declared @code{static const} when optimization isn't turned
2873 on, even if the variables aren't referenced.
2874
2875 GCC enables this option by default.  If you want to force the compiler to
2876 check if the variable was referenced, regardless of whether or not
2877 optimization is turned on, use the @samp{-fno-keep-static-consts} option.
2878
2879 @item -fno-function-cse
2880 Do not put function addresses in registers; make each instruction that
2881 calls a constant function contain the function's address explicitly.
2882
2883 This option results in less efficient code, but some strange hacks
2884 that alter the assembler output may be confused by the optimizations
2885 performed when this option is not used.
2886
2887 @item -ffast-math
2888 This option allows GCC to violate some ISO or IEEE rules and/or
2889 specifications in the interest of optimizing code for speed.  For
2890 example, it allows the compiler to assume arguments to the @code{sqrt}
2891 function are non-negative numbers and that no floating-point values
2892 are NaNs.
2893
2894 This option should never be turned on by any @samp{-O} option since
2895 it can result in incorrect output for programs which depend on
2896 an exact implementation of IEEE or ISO rules/specifications for
2897 math functions.
2898
2899 @item -fno-math-errno
2900 Do not set ERRNO after calling math functions that are executed
2901 with a single instruction, e.g., sqrt.  A program that relies on
2902 IEEE exceptions for math error handling may want to use this flag
2903 for speed while maintaining IEEE arithmetic compatibility.
2904
2905 The default is @samp{-fmath-errno}.  The @samp{-ffast-math} option
2906 sets @samp{-fno-math-errno}.
2907 @end table
2908
2909 @c following causes underfulls.. they don't look great, but we deal.
2910 @c --mew 26jan93
2911 The following options control specific optimizations.  The @samp{-O2}
2912 option turns on all of these optimizations except @samp{-funroll-loops}
2913 and @samp{-funroll-all-loops}.  On most machines, the @samp{-O} option
2914 turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options,
2915 but specific machines may handle it differently.
2916
2917 You can use the following flags in the rare cases when ``fine-tuning''
2918 of optimizations to be performed is desired.
2919
2920 @table @code
2921 @item -fstrength-reduce
2922 Perform the optimizations of loop strength reduction and
2923 elimination of iteration variables.
2924
2925 @item -fthread-jumps
2926 Perform optimizations where we check to see if a jump branches to a
2927 location where another comparison subsumed by the first is found.  If
2928 so, the first branch is redirected to either the destination of the
2929 second branch or a point immediately following it, depending on whether
2930 the condition is known to be true or false.
2931
2932 @item -fcse-follow-jumps
2933 In common subexpression elimination, scan through jump instructions
2934 when the target of the jump is not reached by any other path.  For
2935 example, when CSE encounters an @code{if} statement with an
2936 @code{else} clause, CSE will follow the jump when the condition
2937 tested is false.
2938
2939 @item -fcse-skip-blocks
2940 This is similar to @samp{-fcse-follow-jumps}, but causes CSE to
2941 follow jumps which conditionally skip over blocks.  When CSE
2942 encounters a simple @code{if} statement with no else clause,
2943 @samp{-fcse-skip-blocks} causes CSE to follow the jump around the
2944 body of the @code{if}.
2945
2946 @item -frerun-cse-after-loop
2947 Re-run common subexpression elimination after loop optimizations has been
2948 performed.
2949
2950 @item -frerun-loop-opt
2951 Run the loop optimizer twice.
2952
2953 @item -fgcse
2954 Perform a global common subexpression elimination pass.
2955 This pass also performs global constant and copy propagation.
2956
2957 @item -fdelete-null-pointer-checks
2958 Use global dataflow analysis to identify and eliminate useless null
2959 pointer checks.  Programs which rely on NULL pointer dereferences @emph{not}
2960 halting the program may not work properly with this option.  Use
2961 -fno-delete-null-pointer-checks to disable this optimizing for programs
2962 which depend on that behavior.
2963
2964 @item -fexpensive-optimizations
2965 Perform a number of minor optimizations that are relatively expensive.
2966
2967 @item -foptimize-register-move
2968 @itemx -fregmove
2969 Attempt to reassign register numbers in move instructions and as
2970 operands of other simple instructions in order to maximize the amount of
2971 register tying.  This is especially helpful on machines with two-operand
2972 instructions.  GCC enables this optimization by default with @samp{-O2}
2973 or higher.
2974
2975 Note @code{-fregmove} and @code{-foptimize-register-move} are the same
2976 optimization.
2977
2978 @item -fdelayed-branch
2979 If supported for the target machine, attempt to reorder instructions
2980 to exploit instruction slots available after delayed branch
2981 instructions.
2982
2983 @item -fschedule-insns
2984 If supported for the target machine, attempt to reorder instructions to
2985 eliminate execution stalls due to required data being unavailable.  This
2986 helps machines that have slow floating point or memory load instructions
2987 by allowing other instructions to be issued until the result of the load
2988 or floating point instruction is required.
2989
2990 @item -fschedule-insns2
2991 Similar to @samp{-fschedule-insns}, but requests an additional pass of
2992 instruction scheduling after register allocation has been done.  This is
2993 especially useful on machines with a relatively small number of
2994 registers and where memory load instructions take more than one cycle.
2995
2996 @item -ffunction-sections
2997 @itemx -fdata-sections
2998 Place each function or data item into its own section in the output
2999 file if the target supports arbitrary sections.  The name of the
3000 function or the name of the data item determines the section's name
3001 in the output file.
3002
3003 Use these options on systems where the linker can perform optimizations
3004 to improve locality of reference in the instruction space.  HPPA
3005 processors running HP-UX and Sparc processors running Solaris 2 have
3006 linkers with such optimizations.  Other systems using the ELF object format
3007 as well as AIX may have these optimizations in the future.
3008
3009 Only use these options when there are significant benefits from doing
3010 so.  When you specify these options, the assembler and linker will
3011 create larger object and executable files and will also be slower.
3012 You will not be able to use @code{gprof} on all systems if you
3013 specify this option and you may have problems with debugging if
3014 you specify both this option and @samp{-g}.
3015
3016 @item -fcaller-saves
3017 Enable values to be allocated in registers that will be clobbered by
3018 function calls, by emitting extra instructions to save and restore the
3019 registers around such calls.  Such allocation is done only when it
3020 seems to result in better code than would otherwise be produced.
3021
3022 This option is always enabled by default on certain machines, usually
3023 those which have no call-preserved registers to use instead.
3024
3025 For all machines, optimization level 2 and higher enables this flag by
3026 default.
3027
3028 @item -funroll-loops
3029 Perform the optimization of loop unrolling.  This is only done for loops
3030 whose number of iterations can be determined at compile time or run time.
3031 @samp{-funroll-loops} implies both @samp{-fstrength-reduce} and
3032 @samp{-frerun-cse-after-loop}.
3033
3034 @item -funroll-all-loops
3035 Perform the optimization of loop unrolling.  This is done for all loops
3036 and usually makes programs run more slowly.  @samp{-funroll-all-loops}
3037 implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}.
3038
3039 @item -fmove-all-movables
3040 Forces all invariant computations in loops to be moved
3041 outside the loop.
3042
3043 @item -freduce-all-givs
3044 Forces all general-induction variables in loops to be
3045 strength-reduced.
3046
3047 @emph{Note:} When compiling programs written in Fortran,
3048 @samp{-fmove-all-movables} and @samp{-freduce-all-givs} are enabled
3049 by default when you use the optimizer.
3050
3051 These options may generate better or worse code; results are highly
3052 dependent on the structure of loops within the source code.
3053
3054 These two options are intended to be removed someday, once
3055 they have helped determine the efficacy of various
3056 approaches to improving loop optimizations.
3057
3058 Please let us (@email{gcc@@gcc.gnu.org} and @email{fortran@@gnu.org})
3059 know how use of these options affects
3060 the performance of your production code.
3061 We're very interested in code that runs @emph{slower}
3062 when these options are @emph{enabled}.
3063
3064 @item -fno-peephole
3065 Disable any machine-specific peephole optimizations.
3066
3067 @item -fbranch-probabilities
3068 After running a program compiled with @samp{-fprofile-arcs}
3069 (@pxref{Debugging Options,, Options for Debugging Your Program or
3070 @code{gcc}}), you can compile it a second time using
3071 @samp{-fbranch-probabilities}, to improve optimizations based on
3072 guessing the path a branch might take.
3073
3074 @ifset INTERNALS
3075 With @samp{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
3076 note on the first instruction of each basic block, and a
3077 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
3078 These can be used to improve optimization.  Currently, they are only
3079 used in one place: in @file{reorg.c}, instead of guessing which path a
3080 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
3081 exactly determine which path is taken more often.
3082 @end ifset
3083
3084 @item -fstrict-aliasing
3085 Allows the compiler to assume the strictest aliasing rules applicable to
3086 the language being compiled.  For C (and C++), this activates
3087 optimizations based on the type of expressions.  In particular, an
3088 object of one type is assumed never to reside at the same address as an
3089 object of a different type, unless the types are almost the same.  For
3090 example, an @code{unsigned int} can alias an @code{int}, but not a
3091 @code{void*} or a @code{double}.  A character type may alias any other
3092 type.  
3093
3094 Pay special attention to code like this:
3095 @example
3096 union a_union @{ 
3097   int i;
3098   double d;
3099 @};
3100
3101 int f() @{
3102   a_union t;
3103   t.d = 3.0;
3104   return t.i;
3105 @}
3106 @end example
3107 The practice of reading from a different union member than the one most
3108 recently written to (called ``type-punning'') is common.  Even with
3109 @samp{-fstrict-aliasing}, type-punning is allowed, provided the memory
3110 is accessed through the union type.  So, the code above will work as
3111 expected.  However, this code might not:
3112 @example
3113 int f() @{ 
3114   a_union t;
3115   int* ip;
3116   t.d = 3.0;
3117   ip = &t.i;
3118   return *ip;
3119 @}
3120 @end example
3121
3122 @ifset INTERNALS
3123 Every language that wishes to perform language-specific alias analysis
3124 should define a function that computes, given an @code{tree}
3125 node, an alias set for the node.  Nodes in different alias sets are not
3126 allowed to alias.  For an example, see the C front-end function
3127 @code{c_get_alias_set}.
3128 @end ifset
3129
3130 @item -falign-functions
3131 @itemx -falign-functions=@var{n}
3132 Align the start of functions to the next power-of-two greater than
3133 @var{n}, skipping up to @var{n} bytes.  For instance,
3134 @samp{-falign-functions=32} aligns functions to the next 32-byte
3135 boundary, but @samp{-falign-functions=24} would align to the next
3136 32-byte boundary only if this can be done by skipping 23 bytes or less.
3137
3138 @samp{-fno-align-functions} and @samp{-falign-functions=1} are
3139 equivalent and mean that functions will not be aligned.
3140
3141 Some assemblers only support this flag when @var{n} is a power of two;
3142 in that case, it is rounded up.
3143
3144 If @var{n} is not specified, use a machine-dependent default.
3145
3146 @item -falign-labels
3147 @itemx -falign-labels=@var{n}
3148 Align all branch targets to a power-of-two boundary, skipping up to
3149 @var{n} bytes like @samp{-falign-functions}.  This option can easily
3150 make code slower, because it must insert dummy operations for when the
3151 branch target is reached in the usual flow of the code.
3152
3153 If @samp{-falign-loops} or @samp{-falign-jumps} are applicable and
3154 are greater than this value, then their values are used instead.
3155
3156 If @var{n} is not specified, use a machine-dependent default which is
3157 very likely to be @samp{1}, meaning no alignment.
3158
3159 @item -falign-loops
3160 @itemx -falign-loops=@var{n}
3161 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
3162 like @samp{-falign-functions}.  The hope is that the loop will be
3163 executed many times, which will make up for any execution of the dummy
3164 operations.
3165
3166 If @var{n} is not specified, use a machine-dependent default.
3167
3168 @item -falign-jumps
3169 @itemx -falign-jumps=@var{n}
3170 Align branch targets to a power-of-two boundary, for branch targets
3171 where the targets can only be reached by jumping, skipping up to @var{n}
3172 bytes like @samp{-falign-functions}.  In this case, no dummy operations
3173 need be executed.
3174
3175 If @var{n} is not specified, use a machine-dependent default.
3176
3177 @item -fssa
3178 Perform optimizations in static single assignment form.  Each function's
3179 flow graph is translated into SSA form, optimizations are performed, and
3180 the flow graph is translated back from SSA form.  User's should not
3181 specify this option, since it is not yet ready for production use.
3182
3183 @item -fdce
3184 Perform dead-code elimination in SSA form.  Requires @samp{-fssa}.  Like
3185 @samp{-fssa}, this is an experimental feature.
3186
3187 @item -fsingle-precision-constant
3188 Treat floating point constant as single precision constant instead of
3189 implicitly converting it to double precision constant.
3190
3191 @item -frename-registers
3192 Attempt to avoid false dependancies in scheduled code by making use
3193 of registers left over after register allocation.  This optimization
3194 will most benefit processors with lots of registers.  It can, however,
3195 make debugging impossible, since variables will no longer stay in
3196 a ``home register''.
3197 @end table
3198
3199 @node Preprocessor Options
3200 @section Options Controlling the Preprocessor
3201 @cindex preprocessor options
3202 @cindex options, preprocessor
3203
3204 These options control the C preprocessor, which is run on each C source
3205 file before actual compilation.
3206
3207 If you use the @samp{-E} option, nothing is done except preprocessing.
3208 Some of these options make sense only together with @samp{-E} because
3209 they cause the preprocessor output to be unsuitable for actual
3210 compilation.
3211
3212 @table @code
3213 @item -include @var{file}
3214 Process @var{file} as input before processing the regular input file.
3215 In effect, the contents of @var{file} are compiled first.  Any @samp{-D}
3216 and @samp{-U} options on the command line are always processed before
3217 @samp{-include @var{file}}, regardless of the order in which they are
3218 written.  All the @samp{-include} and @samp{-imacros} options are
3219 processed in the order in which they are written.
3220
3221 @item -imacros @var{file}
3222 Process @var{file} as input, discarding the resulting output, before
3223 processing the regular input file.  Because the output generated from
3224 @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
3225 is to make the macros defined in @var{file} available for use in the
3226 main input.  All the @samp{-include} and @samp{-imacros} options are
3227 processed in the order in which they are written.
3228
3229 @item -idirafter @var{dir}
3230 @cindex second include path
3231 Add the directory @var{dir} to the second include path.  The directories
3232 on the second include path are searched when a header file is not found
3233 in any of the directories in the main include path (the one that
3234 @samp{-I} adds to).
3235
3236 @item -iprefix @var{prefix}
3237 Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
3238 options.
3239
3240 @item -iwithprefix @var{dir}
3241 Add a directory to the second include path.  The directory's name is
3242 made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
3243 specified previously with @samp{-iprefix}.  If you have not specified a
3244 prefix yet, the directory containing the installed passes of the
3245 compiler is used as the default.
3246
3247 @item -iwithprefixbefore @var{dir}
3248 Add a directory to the main include path.  The directory's name is made
3249 by concatenating @var{prefix} and @var{dir}, as in the case of
3250 @samp{-iwithprefix}.
3251
3252 @item -isystem @var{dir}
3253 Add a directory to the beginning of the second include path, marking it
3254 as a system directory, so that it gets the same special treatment as
3255 is applied to the standard system directories.
3256
3257 @item -nostdinc
3258 Do not search the standard system directories for header files.  Only
3259 the directories you have specified with @samp{-I} options (and the
3260 current directory, if appropriate) are searched.  @xref{Directory
3261 Options}, for information on @samp{-I}.
3262
3263 By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
3264 search path to only those directories you specify explicitly.
3265
3266 @item -remap
3267 @findex -remap
3268 When searching for a header file in a directory, remap file names if a
3269 file named @file{header.gcc} exists in that directory.  This can be used
3270 to work around limitations of file systems with file name restrictions.
3271 The @file{header.gcc} file should contain a series of lines with two
3272 tokens on each line: the first token is the name to map, and the second
3273 token is the actual name to use.
3274
3275 @item -undef
3276 Do not predefine any nonstandard macros.  (Including architecture flags).
3277
3278 @item -E
3279 Run only the C preprocessor.  Preprocess all the C source files
3280 specified and output the results to standard output or to the
3281 specified output file.
3282
3283 @item -C
3284 Tell the preprocessor not to discard comments.  Used with the
3285 @samp{-E} option.
3286
3287 @item -P
3288 Tell the preprocessor not to generate @samp{#line} directives.
3289 Used with the @samp{-E} option.
3290
3291 @cindex make
3292 @cindex dependencies, make
3293 @item -M
3294 @findex -M
3295 Instead of outputting the result of preprocessing, output a rule
3296 suitable for @code{make} describing the dependencies of the main source
3297 file.  The preprocessor outputs one @code{make} rule containing the
3298 object file name for that source file, a colon, and the names of all the
3299 included files.  If there are many included files then the rule is split
3300 into several lines using @samp{\}-newline.
3301
3302 @samp{-M} implies @samp{-E}.
3303
3304 @item -MM
3305 @findex -MM
3306 Like @samp{-M}, but mention only the files included with @samp{#include
3307 "@var{file}"}.  System header files included with @samp{#include
3308 <@var{file}>} are omitted.
3309
3310 @item -MF @var{file}
3311 @findex -MF
3312 When used with @samp{-M} or @samp{-MM}, specifies a file to write the
3313 dependencies to.  This allows the preprocessor to write the preprocessed
3314 file to stdout normally.  If no @samp{-MF} switch is given, CPP sends
3315 the rules to stdout and suppresses normal preprocessed output.
3316
3317 Another way to specify output of a @code{make} rule is by setting
3318 the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
3319 Variables}).
3320
3321 @item -MG
3322 @findex -MG
3323 When used with @samp{-M} or @samp{-MM}, @samp{-MG} says to treat missing
3324 header files as generated files and assume they live in the same
3325 directory as the source file.  It suppresses preprocessed output, as a
3326 missing header file is ordinarily an error.
3327
3328 This feature is used in automatic updating of makefiles.
3329
3330 @item -MP
3331 @findex -MP
3332 This option instructs CPP to add a phony target for each dependency
3333 other than the main file, causing each to depend on nothing.  These
3334 dummy rules work around errors @code{make} gives if you remove header
3335 files without updating the @code{Makefile} to match.
3336
3337 This is typical output:-
3338
3339 @smallexample
3340 /tmp/test.o: /tmp/test.c /tmp/test.h
3341
3342 /tmp/test.h:
3343 @end smallexample
3344
3345 @item -MQ @var{target}
3346 @item -MT @var{target}
3347 @findex -MQ
3348 @findex -MT
3349 By default CPP uses the main file name, including any path, and appends
3350 the object suffix, normally ``.o'', to it to obtain the name of the
3351 target for dependency generation.  With @samp{-MT} you can specify a
3352 target yourself, overriding the default one.
3353
3354 If you want multiple targets, you can specify them as a single argument
3355 to @samp{-MT}, or use multiple @samp{-MT} options.
3356
3357 The targets you specify are output in the order they appear on the
3358 command line.  @samp{-MQ} is identical to @samp{-MT}, except that the
3359 target name is quoted for Make, but with @samp{-MT} it isn't.  For
3360 example, -MT '$(objpfx)foo.o' gives
3361
3362 @smallexample
3363 $(objpfx)foo.o: /tmp/foo.c
3364 @end smallexample
3365
3366 but -MQ '$(objpfx)foo.o' gives
3367
3368 @smallexample
3369 $$(objpfx)foo.o: /tmp/foo.c
3370 @end smallexample
3371
3372 The default target is automatically quoted, as if it were given with
3373 @samp{-MQ}.
3374
3375 @item -H
3376 Print the name of each header file used, in addition to other normal
3377 activities.
3378
3379 @item -A@var{question}(@var{answer})
3380 Assert the answer @var{answer} for @var{question}, in case it is tested
3381 with a preprocessing conditional such as @samp{#if
3382 #@var{question}(@var{answer})}.  @samp{-A-} disables the standard
3383 assertions that normally describe the target machine.
3384
3385 @item -D@var{macro}
3386 Define macro @var{macro} with the string @samp{1} as its definition.
3387
3388 @item -D@var{macro}=@var{defn}
3389 Define macro @var{macro} as @var{defn}.  All instances of @samp{-D} on
3390 the command line are processed before any @samp{-U} options.
3391
3392 Any @samp{-D} and @samp{-U} options on the command line are processed in
3393 order, and always before @samp{-imacros @var{file}}, regardless of the
3394 order in which they are written.
3395
3396 @item -U@var{macro}
3397 Undefine macro @var{macro}.  @samp{-U} options are evaluated after all
3398 @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
3399 options.
3400
3401 Any @samp{-D} and @samp{-U} options on the command line are processed in
3402 order, and always before @samp{-imacros @var{file}}, regardless of the
3403 order in which they are written.
3404
3405 @item -dM
3406 Tell the preprocessor to output only a list of the macro definitions
3407 that are in effect at the end of preprocessing.  Used with the @samp{-E}
3408 option.
3409
3410 @item -dD
3411 Tell the preprocessing to pass all macro definitions into the output, in
3412 their proper sequence in the rest of the output.
3413
3414 @item -dN
3415 Like @samp{-dD} except that the macro arguments and contents are omitted.
3416 Only @samp{#define @var{name}} is included in the output.
3417
3418 @item -dI
3419 @findex -dI
3420 Output @samp{#include} directives in addition to the result of
3421 preprocessing.
3422
3423 @item -trigraphs
3424 @findex -trigraphs
3425 Process ISO standard trigraph sequences.  These are three-character
3426 sequences, all starting with @samp{??}, that are defined by ISO C to
3427 stand for single characters.  For example, @samp{??/} stands for
3428 @samp{\}, so @samp{'??/n'} is a character constant for a newline.  By
3429 default, GCC ignores trigraphs, but in standard-conforming modes it
3430 converts them.  See the @samp{-std} and @samp{-ansi} options.
3431
3432 The nine trigraph sequences are
3433 @table @samp
3434 @item ??(
3435 -> @samp{[}
3436
3437 @item ??)
3438 -> @samp{]}
3439
3440 @item ??<
3441 -> @samp{@{}
3442
3443 @item ??>
3444 -> @samp{@}}
3445
3446 @item ??=
3447 -> @samp{#}
3448
3449 @item ??/
3450 -> @samp{\}
3451
3452 @item ??'
3453 -> @samp{^}
3454
3455 @item ??!
3456 -> @samp{|}
3457
3458 @item ??-
3459 -> @samp{~}
3460
3461 @end table
3462
3463 Trigraph support is not popular, so many compilers do not implement it
3464 properly.  Portable code should not rely on trigraphs being either
3465 converted or ignored.
3466
3467 @item -Wp,@var{option}
3468 Pass @var{option} as an option to the preprocessor.  If @var{option}
3469 contains commas, it is split into multiple options at the commas.
3470 @end table
3471
3472 @node Assembler Options
3473 @section Passing Options to the Assembler
3474
3475 @c prevent bad page break with this line
3476 You can pass options to the assembler.
3477
3478 @table @code
3479 @item -Wa,@var{option}
3480 Pass @var{option} as an option to the assembler.  If @var{option}
3481 contains commas, it is split into multiple options at the commas.
3482 @end table
3483
3484 @node Link Options
3485 @section Options for Linking
3486 @cindex link options
3487 @cindex options, linking
3488
3489 These options come into play when the compiler links object files into
3490 an executable output file.  They are meaningless if the compiler is
3491 not doing a link step.
3492
3493 @table @code
3494 @cindex file names
3495 @item @var{object-file-name}
3496 A file name that does not end in a special recognized suffix is
3497 considered to name an object file or library.  (Object files are
3498 distinguished from libraries by the linker according to the file
3499 contents.)  If linking is done, these object files are used as input
3500 to the linker.
3501
3502 @item -c
3503 @itemx -S
3504 @itemx -E
3505 If any of these options is used, then the linker is not run, and
3506 object file names should not be used as arguments.  @xref{Overall
3507 Options}.
3508
3509 @cindex Libraries
3510 @item -l@var{library}
3511 Search the library named @var{library} when linking.
3512
3513 It makes a difference where in the command you write this option; the
3514 linker searches processes libraries and object files in the order they
3515 are specified.  Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
3516 after file @file{foo.o} but before @file{bar.o}.  If @file{bar.o} refers
3517 to functions in @samp{z}, those functions may not be loaded.
3518
3519 The linker searches a standard list of directories for the library,
3520 which is actually a file named @file{lib@var{library}.a}.  The linker
3521 then uses this file as if it had been specified precisely by name.
3522
3523 The directories searched include several standard system directories
3524 plus any that you specify with @samp{-L}.
3525
3526 Normally the files found this way are library files---archive files
3527 whose members are object files.  The linker handles an archive file by
3528 scanning through it for members which define symbols that have so far
3529 been referenced but not defined.  But if the file that is found is an
3530 ordinary object file, it is linked in the usual fashion.  The only
3531 difference between using an @samp{-l} option and specifying a file name
3532 is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
3533 and searches several directories.
3534
3535 @item -lobjc
3536 You need this special case of the @samp{-l} option in order to
3537 link an Objective C program.
3538
3539 @item -nostartfiles
3540 Do not use the standard system startup files when linking.
3541 The standard system libraries are used normally, unless @code{-nostdlib}
3542 or @code{-nodefaultlibs} is used.
3543
3544 @item -nodefaultlibs
3545 Do not use the standard system libraries when linking.
3546 Only the libraries you specify will be passed to the linker.
3547 The standard startup files are used normally, unless @code{-nostartfiles}
3548 is used.  The compiler may generate calls to memcmp, memset, and memcpy
3549 for System V (and ISO C) environments or to bcopy and bzero for
3550 BSD environments.  These entries are usually resolved by entries in
3551 libc.  These entry points should be supplied through some other
3552 mechanism when this option is specified.
3553
3554 @item -nostdlib
3555 Do not use the standard system startup files or libraries when linking.
3556 No startup files and only the libraries you specify will be passed to
3557 the linker. The compiler may generate calls to memcmp, memset, and memcpy
3558 for System V (and ISO C) environments or to bcopy and bzero for
3559 BSD environments.  These entries are usually resolved by entries in
3560 libc.  These entry points should be supplied through some other
3561 mechanism when this option is specified.
3562
3563 @cindex @code{-lgcc}, use with @code{-nostdlib}
3564 @cindex @code{-nostdlib} and unresolved references
3565 @cindex unresolved references and @code{-nostdlib}
3566 @cindex @code{-lgcc}, use with @code{-nodefaultlibs}
3567 @cindex @code{-nodefaultlibs} and unresolved references
3568 @cindex unresolved references and @code{-nodefaultlibs}
3569 One of the standard libraries bypassed by @samp{-nostdlib} and
3570 @samp{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
3571 that GCC uses to overcome shortcomings of particular machines, or special
3572 needs for some languages.
3573 @ifset INTERNALS
3574 (@xref{Interface,,Interfacing to GCC Output}, for more discussion of
3575 @file{libgcc.a}.)
3576 @end ifset
3577 @ifclear INTERNALS
3578 (@xref{Interface,,Interfacing to GCC Output,gcc.info,Porting GCC},
3579 for more discussion of @file{libgcc.a}.)
3580 @end ifclear
3581 In most cases, you need @file{libgcc.a} even when you want to avoid
3582 other standard libraries.  In other words, when you specify @samp{-nostdlib}
3583 or @samp{-nodefaultlibs} you should usually specify @samp{-lgcc} as well.
3584 This ensures that you have no unresolved references to internal GCC
3585 library subroutines.  (For example, @samp{__main}, used to ensure C++
3586 constructors will be called; @pxref{Collect2,,@code{collect2}}.)
3587
3588 @item -s
3589 Remove all symbol table and relocation information from the executable.
3590
3591 @item -static
3592 On systems that support dynamic linking, this prevents linking with the shared
3593 libraries.  On other systems, this option has no effect.
3594
3595 @item -shared
3596 Produce a shared object which can then be linked with other objects to
3597 form an executable.  Not all systems support this option.  For predictable
3598 results, you must also specify the same set of options that were used to 
3599 generate code (@samp{-fpic}, @samp{-fPIC}, or model suboptions)
3600 when you specify this option.@footnote{On some systems, @code{gcc -shared}
3601 needs to build supplementary stub code for constructors to work. On
3602 multi-libbed systems, @code{gcc -shared} must select the correct support
3603 libraries to link against.  Failing to supply the correct flags may lead
3604 to subtle defects. Supplying them in cases where they are not necessary
3605 is innocuous.}
3606
3607 @item -shared-libgcc
3608 @itemx -static-libgcc
3609 On systems that provide @file{libgcc} as a shared library, these options
3610 force the use of either the shared or static version respectively.
3611 If no shared version of @file{libgcc} was built when the compiler was
3612 configured, these options have no effect.
3613
3614 There are several situations in which an application should use the
3615 shared @file{libgcc} instead of the static version.  The most common
3616 of these is when the application wishes to throw and catch exceptions
3617 across different shared libraries.  In that case, each of the libraries
3618 as well as the application itself should use the shared @file{libgcc}.
3619
3620 At present the GCC driver makes no attempt to recognize the situations
3621 in which the shared @file{libgcc} should be used, and defaults to using
3622 the static @file{libgcc} always.  This will likely change in the future,
3623 at which time @samp{-static-libgcc} becomes useful as a means for 
3624 overriding GCC's choice.
3625
3626 @item -symbolic
3627 Bind references to global symbols when building a shared object.  Warn
3628 about any unresolved references (unless overridden by the link editor
3629 option @samp{-Xlinker -z -Xlinker defs}).  Only a few systems support
3630 this option.
3631
3632 @item -Xlinker @var{option}
3633 Pass @var{option} as an option to the linker.  You can use this to
3634 supply system-specific linker options which GCC does not know how to
3635 recognize.
3636
3637 If you want to pass an option that takes an argument, you must use
3638 @samp{-Xlinker} twice, once for the option and once for the argument.
3639 For example, to pass @samp{-assert definitions}, you must write
3640 @samp{-Xlinker -assert -Xlinker definitions}.  It does not work to write
3641 @samp{-Xlinker "-assert definitions"}, because this passes the entire
3642 string as a single argument, which is not what the linker expects.
3643
3644 @item -Wl,@var{option}
3645 Pass @var{option} as an option to the linker.  If @var{option} contains
3646 commas, it is split into multiple options at the commas.
3647
3648 @item -u @var{symbol}
3649 Pretend the symbol @var{symbol} is undefined, to force linking of
3650 library modules to define it.  You can use @samp{-u} multiple times with
3651 different symbols to force loading of additional library modules.
3652 @end table
3653
3654 @node Directory Options
3655 @section Options for Directory Search
3656 @cindex directory options
3657 @cindex options, directory search
3658 @cindex search path
3659
3660 These options specify directories to search for header files, for
3661 libraries and for parts of the compiler:
3662
3663 @table @code
3664 @item -I@var{dir}
3665 Add the directory @var{dir} to the head of the list of directories to be
3666 searched for header files.  This can be used to override a system header
3667 file, substituting your own version, since these directories are
3668 searched before the system header file directories.  If you use more
3669 than one @samp{-I} option, the directories are scanned in left-to-right
3670 order; the standard system directories come after.
3671
3672 @item -I-
3673 Any directories you specify with @samp{-I} options before the @samp{-I-}
3674 option are searched only for the case of @samp{#include "@var{file}"};
3675 they are not searched for @samp{#include <@var{file}>}.
3676
3677 If additional directories are specified with @samp{-I} options after
3678 the @samp{-I-}, these directories are searched for all @samp{#include}
3679 directives.  (Ordinarily @emph{all} @samp{-I} directories are used
3680 this way.)
3681
3682 In addition, the @samp{-I-} option inhibits the use of the current
3683 directory (where the current input file came from) as the first search
3684 directory for @samp{#include "@var{file}"}.  There is no way to
3685 override this effect of @samp{-I-}.  With @samp{-I.} you can specify
3686 searching the directory which was current when the compiler was
3687 invoked.  That is not exactly the same as what the preprocessor does
3688 by default, but it is often satisfactory.
3689
3690 @samp{-I-} does not inhibit the use of the standard system directories
3691 for header files.  Thus, @samp{-I-} and @samp{-nostdinc} are
3692 independent.
3693
3694 @item -L@var{dir}
3695 Add directory @var{dir} to the list of directories to be searched
3696 for @samp{-l}.
3697
3698 @item -B@var{prefix}
3699 This option specifies where to find the executables, libraries,
3700 include files, and data files of the compiler itself.
3701
3702 The compiler driver program runs one or more of the subprograms
3703 @file{cpp}, @file{cc1}, @file{as} and @file{ld}.  It tries
3704 @var{prefix} as a prefix for each program it tries to run, both with and
3705 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
3706
3707 For each subprogram to be run, the compiler driver first tries the
3708 @samp{-B} prefix, if any.  If that name is not found, or if @samp{-B}
3709 was not specified, the driver tries two standard prefixes, which are
3710 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}.  If neither of
3711 those results in a file name that is found, the unmodified program
3712 name is searched for using the directories specified in your
3713 @samp{PATH} environment variable.
3714
3715 @samp{-B} prefixes that effectively specify directory names also apply
3716 to libraries in the linker, because the compiler translates these
3717 options into @samp{-L} options for the linker.  They also apply to
3718 includes files in the preprocessor, because the compiler translates these
3719 options into @samp{-isystem} options for the preprocessor.  In this case,
3720 the compiler appends @samp{include} to the prefix.
3721
3722 The run-time support file @file{libgcc.a} can also be searched for using
3723 the @samp{-B} prefix, if needed.  If it is not found there, the two
3724 standard prefixes above are tried, and that is all.  The file is left
3725 out of the link if it is not found by those means.
3726
3727 Another way to specify a prefix much like the @samp{-B} prefix is to use
3728 the environment variable @code{GCC_EXEC_PREFIX}.  @xref{Environment
3729 Variables}.
3730
3731 @item -specs=@var{file}
3732 Process @var{file} after the compiler reads in the standard @file{specs}
3733 file, in order to override the defaults that the @file{gcc} driver
3734 program uses when determining what switches to pass to @file{cc1},
3735 @file{cc1plus}, @file{as}, @file{ld}, etc.  More than one
3736 @samp{-specs=}@var{file} can be specified on the command line, and they
3737 are processed in order, from left to right.
3738 @end table
3739
3740 @c man end
3741
3742 @node Spec Files
3743 @section Specifying subprocesses and the switches to pass to them
3744 @cindex Spec Files
3745 @code{GCC} is a driver program.  It performs its job by invoking a
3746 sequence of other programs to do the work of compiling, assembling and
3747 linking.  GCC interprets its command-line parameters and uses these to
3748 deduce which programs it should invoke, and which command-line options
3749 it ought to place on their command lines.  This behaviour is controlled
3750 by @dfn{spec strings}.  In most cases there is one spec string for each
3751 program that GCC can invoke, but a few programs have multiple spec
3752 strings to control their behaviour.  The spec strings built into GCC can
3753 be overridden by using the @samp{-specs=} command-line switch to specify
3754 a spec file.
3755
3756 @dfn{Spec files} are plaintext files that are used to construct spec
3757 strings.  They consist of a sequence of directives separated by blank
3758 lines.  The type of directive is determined by the first non-whitespace
3759 character on the line and it can be one of the following:
3760
3761 @table @code
3762 @item %@var{command}
3763 Issues a @var{command} to the spec file processor.  The commands that can
3764 appear here are: 
3765
3766 @table @code
3767 @item %include <@var{file}>
3768 @cindex %include
3769 Search for @var{file} and insert its text at the current point in the
3770 specs file.
3771
3772 @item %include_noerr <@var{file}>
3773 @cindex %include_noerr
3774 Just like @samp{%include}, but do not generate an error message if the include
3775 file cannot be found.
3776
3777 @item %rename @var{old_name} @var{new_name}
3778 @cindex %rename
3779 Rename the spec string @var{old_name} to @var{new_name}.
3780
3781 @end table
3782
3783 @item *[@var{spec_name}]:
3784 This tells the compiler to create, override or delete the named spec
3785 string.  All lines after this directive up to the next directive or
3786 blank line are considered to be the text for the spec string.  If this
3787 results in an empty string then the spec will be deleted.  (Or, if the
3788 spec did not exist, then nothing will happened.)  Otherwise, if the spec
3789 does not currently exist a new spec will be created.  If the spec does
3790 exist then its contents will be overridden by the text of this
3791 directive, unless the first character of that text is the @samp{+}
3792 character, in which case the text will be appended to the spec.
3793
3794 @item [@var{suffix}]:
3795 Creates a new @samp{[@var{suffix}] spec} pair.  All lines after this directive
3796 and up to the next directive or blank line are considered to make up the
3797 spec string for the indicated suffix.  When the compiler encounters an 
3798 input file with the named suffix, it will processes the spec string in
3799 order to work out how to compile that file.  For example:
3800
3801 @smallexample
3802 .ZZ:
3803 z-compile -input %i
3804 @end smallexample
3805
3806 This says that any input file whose name ends in @samp{.ZZ} should be
3807 passed to the program @samp{z-compile}, which should be invoked with the
3808 command-line switch @samp{-input} and with the result of performing the
3809 @samp{%i} substitution.  (See below.)
3810
3811 As an alternative to providing a spec string, the text that follows a
3812 suffix directive can be one of the following:
3813
3814 @table @code
3815 @item @@@var{language}
3816 This says that the suffix is an alias for a known @var{language}.  This is
3817 similar to using the @code{-x} command-line switch to GCC to specify a
3818 language explicitly.  For example:
3819
3820 @smallexample
3821 .ZZ:
3822 @@c++
3823 @end smallexample
3824
3825 Says that .ZZ files are, in fact, C++ source files.
3826
3827 @item #@var{name}
3828 This causes an error messages saying:
3829
3830 @smallexample
3831 @var{name} compiler not installed on this system.
3832 @end smallexample
3833 @end table
3834
3835 GCC already has an extensive list of suffixes built into it.
3836 This directive will add an entry to the end of the list of suffixes, but
3837 since the list is searched from the end backwards, it is effectively
3838 possible to override earlier entries using this technique.
3839
3840 @end table
3841
3842 GCC has the following spec strings built into it.  Spec files can
3843 override these strings or create their own.  Note that individual
3844 targets can also add their own spec strings to this list. 
3845
3846 @smallexample
3847 asm          Options to pass to the assembler
3848 asm_final    Options to pass to the assembler post-processor
3849 cpp          Options to pass to the C preprocessor
3850 cc1          Options to pass to the C compiler
3851 cc1plus      Options to pass to the C++ compiler
3852 endfile      Object files to include at the end of the link
3853 link         Options to pass to the linker
3854 lib          Libraries to include on the command line to the linker
3855 libgcc       Decides which GCC support library to pass to the linker
3856 linker       Sets the name of the linker
3857 predefines   Defines to be passed to the C preprocessor
3858 signed_char  Defines to pass to CPP to say whether @code{char} is signed by default
3859 startfile    Object files to include at the start of the link
3860 @end smallexample
3861
3862 Here is a small example of a spec file:
3863
3864 @smallexample
3865 %rename lib                 old_lib
3866
3867 *lib:
3868 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
3869 @end smallexample
3870
3871 This example renames the spec called @samp{lib} to @samp{old_lib} and
3872 then overrides the previous definition of @samp{lib} with a new one.
3873 The new definition adds in some extra command-line options before
3874 including the text of the old definition.
3875
3876 @dfn{Spec strings} are a list of command-line options to be passed to their
3877 corresponding program.  In addition, the spec strings can contain
3878 @samp{%}-prefixed sequences to substitute variable text or to
3879 conditionally insert text into the command line.  Using these constructs
3880 it is possible to generate quite complex command lines.
3881
3882 Here is a table of all defined @samp{%}-sequences for spec
3883 strings.  Note that spaces are not generated automatically around the
3884 results of expanding these sequences.  Therefore you can concatenate them
3885 together or combine them with constant text in a single argument. 
3886
3887 @table @code
3888 @item %%
3889 Substitute one @samp{%} into the program name or argument.
3890
3891 @item %i
3892 Substitute the name of the input file being processed.
3893
3894 @item %b
3895 Substitute the basename of the input file being processed.
3896 This is the substring up to (and not including) the last period
3897 and not including the directory.
3898
3899 @item %d
3900 Marks the argument containing or following the @samp{%d} as a
3901 temporary file name, so that that file will be deleted if GCC exits
3902 successfully.  Unlike @samp{%g}, this contributes no text to the
3903 argument. 
3904
3905 @item %g@var{suffix}
3906 Substitute a file name that has suffix @var{suffix} and is chosen
3907 once per compilation, and mark the argument in the same way as
3908 @samp{%d}.  To reduce exposure to denial-of-service attacks, the file
3909 name is now chosen in a way that is hard to predict even when previously 
3910 chosen file names are known.  For example, @samp{%g.s ... %g.o ... %g.s}
3911 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}.  @var{suffix} matches
3912 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
3913 treated exactly as if @samp{%O} had been preprocessed.  Previously, @samp{%g}
3914 was simply substituted with a file name chosen once per compilation,
3915 without regard to any appended suffix (which was therefore treated
3916 just like ordinary text), making such attacks more likely to succeed.
3917
3918 @item %u@var{suffix}
3919 Like @samp{%g}, but generates a new temporary file name even if
3920 @samp{%u@var{suffix}} was already seen.
3921
3922 @item %U@var{suffix}
3923 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
3924 new one if there is no such last file name.  In the absence of any
3925 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
3926 the same suffix @emph{space}, so @samp{%g.s ... %U.s ... %g.s ... %U.s}
3927 would involve the generation of two distinct file names, one
3928 for each @samp{%g.s} and another for each @samp{%U.s}.  Previously, @samp{%U} was
3929 simply substituted with a file name chosen for the previous @samp{%u},
3930 without regard to any appended suffix.
3931
3932 @item %w
3933 Marks the argument containing or following the @samp{%w} as the
3934 designated output file of this compilation.  This puts the argument
3935 into the sequence of arguments that @samp{%o} will substitute later.
3936
3937 @item %o
3938 Substitutes the names of all the output files, with spaces
3939 automatically placed around them.  You should write spaces
3940 around the @samp{%o} as well or the results are undefined.
3941 @samp{%o} is for use in the specs for running the linker.
3942 Input files whose names have no recognized suffix are not compiled
3943 at all, but they are included among the output files, so they will
3944 be linked.
3945
3946 @item %O
3947 Substitutes the suffix for object files.  Note that this is
3948 handled specially when it immediately follows @samp{%g, %u, or %U},
3949 because of the need for those to form complete file names.  The
3950 handling is such that @samp{%O} is treated exactly as if it had already
3951 been substituted, except that @samp{%g, %u, and %U} do not currently
3952 support additional @var{suffix} characters following @samp{%O} as they would
3953 following, for example, @samp{.o}.
3954
3955 @item %p
3956 Substitutes the standard macro predefinitions for the
3957 current target machine.  Use this when running @code{cpp}.
3958
3959 @item %P
3960 Like @samp{%p}, but puts @samp{__} before and after the name of each
3961 predefined macro, except for macros that start with @samp{__} or with
3962 @samp{_@var{L}}, where @var{L} is an uppercase letter.  This is for ISO
3963 C.  
3964
3965 @item %I
3966 Substitute a @samp{-iprefix} option made from GCC_EXEC_PREFIX.
3967
3968 @item %s
3969 Current argument is the name of a library or startup file of some sort.
3970 Search for that file in a standard list of directories and substitute
3971 the full name found. 
3972
3973 @item %e@var{str}
3974 Print @var{str} as an error message.  @var{str} is terminated by a newline.
3975 Use this when inconsistent options are detected.
3976
3977 @item %|
3978 Output @samp{-} if the input for the current command is coming from a pipe.
3979
3980 @item %(@var{name})
3981 Substitute the contents of spec string @var{name} at this point.
3982
3983 @item %[@var{name}]
3984 Like @samp{%(...)} but put @samp{__} around @samp{-D} arguments.
3985
3986 @item %x@{@var{option}@}
3987 Accumulate an option for @samp{%X}.
3988
3989 @item %X
3990 Output the accumulated linker options specified by @samp{-Wl} or a @samp{%x}
3991 spec string.
3992
3993 @item %Y
3994 Output the accumulated assembler options specified by @samp{-Wa}.
3995
3996 @item %Z
3997 Output the accumulated preprocessor options specified by @samp{-Wp}.
3998
3999 @item %v1
4000 Substitute the major version number of GCC.
4001 (For version 2.9.5, this is 2.)
4002
4003 @item %v2
4004 Substitute the minor version number of GCC.
4005 (For version 2.9.5, this is 9.)
4006
4007 @item %a
4008 Process the @code{asm} spec.  This is used to compute the
4009 switches to be passed to the assembler.
4010
4011 @item %A
4012 Process the @code{asm_final} spec.  This is a spec string for
4013 passing switches to an assembler post-processor, if such a program is
4014 needed.
4015
4016 @item %l
4017 Process the @code{link} spec.  This is the spec for computing the
4018 command line passed to the linker.  Typically it will make use of the
4019 @samp{%L %G %S %D and %E} sequences.
4020
4021 @item %D
4022 Dump out a @samp{-L} option for each directory that GCC believes might
4023 contain startup files.  If the target supports multilibs then the
4024 current multilib directory will be prepended to each of these paths. 
4025
4026 @item %L
4027 Process the @code{lib} spec.  This is a spec string for deciding which
4028 libraries should be included on the command line to the linker. 
4029
4030 @item %G
4031 Process the @code{libgcc} spec.  This is a spec string for deciding
4032 which GCC support library should be included on the command line to the linker. 
4033
4034 @item %S
4035 Process the @code{startfile} spec.  This is a spec for deciding which
4036 object files should be the first ones passed to the linker.  Typically
4037 this might be a file named @file{crt0.o}. 
4038
4039 @item %E
4040 Process the @code{endfile} spec.  This is a spec string that specifies
4041 the last object files that will be passed to the linker.  
4042
4043 @item %C
4044 Process the @code{cpp} spec.  This is used to construct the arguments
4045 to be passed to the C preprocessor.
4046
4047 @item %c
4048 Process the @code{signed_char} spec.  This is intended to be used
4049 to tell cpp whether a char is signed.  It typically has the definition: 
4050 @smallexample
4051 %@{funsigned-char:-D__CHAR_UNSIGNED__@}
4052 @end smallexample
4053
4054 @item %1
4055 Process the @code{cc1} spec.  This is used to construct the options to be
4056 passed to the actual C compiler (@samp{cc1}).
4057
4058 @item %2
4059 Process the @code{cc1plus} spec.  This is used to construct the options to be
4060 passed to the actual C++ compiler (@samp{cc1plus}).
4061
4062 @item %*
4063 Substitute the variable part of a matched option.  See below.
4064 Note that each comma in the substituted string is replaced by
4065 a single space.
4066
4067 @item %@{@code{S}@}
4068 Substitutes the @code{-S} switch, if that switch was given to GCC.
4069 If that switch was not specified, this substitutes nothing.  Note that
4070 the leading dash is omitted when specifying this option, and it is
4071 automatically inserted if the substitution is performed.  Thus the spec
4072 string @samp{%@{foo@}} would match the command-line option @samp{-foo}
4073 and would output the command line option @samp{-foo}.
4074
4075 @item %W@{@code{S}@}
4076 Like %@{@code{S}@} but mark last argument supplied within as a file to be
4077 deleted on failure. 
4078
4079 @item %@{@code{S}*@}
4080 Substitutes all the switches specified to GCC whose names start
4081 with @code{-S}, but which also take an argument.  This is used for
4082 switches like @samp{-o, -D, -I}, etc.  GCC considers @samp{-o foo} as being
4083 one switch whose names starts with @samp{o}.  %@{o*@} would substitute this
4084 text, including the space.  Thus two arguments would be generated. 
4085
4086 @item %@{^@code{S}*@}
4087 Like %@{@code{S}*@}, but don't put a blank between a switch and its
4088 argument.  Thus %@{^o*@} would only generate one argument, not two.
4089
4090 @item %@{<@code{S}@}
4091 Remove all occurrences of @code{-S} from the command line.  Note - this
4092 command is position dependent.  @samp{%} commands in the spec string
4093 before this option will see @code{-S}, @samp{%} commands in the spec
4094 string after this option will not.
4095
4096 @item %@{@code{S}*:@code{X}@}
4097 Substitutes @code{X} if one or more switches whose names start with
4098 @code{-S} are specified to GCC.  Note that the tail part of the
4099 @code{-S} option (i.e. the part matched by the @samp{*}) will be substituted
4100 for each occurrence of @samp{%*} within @code{X}. 
4101
4102 @item %@{@code{S}:@code{X}@}
4103 Substitutes @code{X}, but only if the @samp{-S} switch was given to GCC.
4104
4105 @item %@{!@code{S}:@code{X}@}
4106 Substitutes @code{X}, but only if the @samp{-S} switch was @emph{not} given to GCC.
4107
4108 @item %@{|@code{S}:@code{X}@}
4109 Like %@{@code{S}:@code{X}@}, but if no @code{S} switch, substitute @samp{-}.
4110
4111 @item %@{|!@code{S}:@code{X}@}
4112 Like %@{!@code{S}:@code{X}@}, but if there is an @code{S} switch, substitute @samp{-}.
4113
4114 @item %@{.@code{S}:@code{X}@}
4115 Substitutes @code{X}, but only if processing a file with suffix @code{S}.
4116
4117 @item %@{!.@code{S}:@code{X}@}
4118 Substitutes @code{X}, but only if @emph{not} processing a file with suffix @code{S}.
4119
4120 @item %@{@code{S}|@code{P}:@code{X}@}
4121 Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC.  This may be
4122 combined with @samp{!} and @samp{.} sequences as well, although they
4123 have a stronger binding than the @samp{|}.  For example a spec string
4124 like this:
4125
4126 @smallexample
4127 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
4128 @end smallexample
4129
4130 will output the following command-line options from the following input
4131 command-line options:
4132
4133 @smallexample
4134 fred.c        -foo -baz
4135 jim.d         -bar -boggle
4136 -d fred.c     -foo -baz -boggle
4137 -d jim.d      -bar -baz -boggle
4138 @end smallexample
4139
4140 @end table
4141
4142 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or
4143 %@{!@code{S}:@code{X}@} construct may contain other nested @samp{%} constructs
4144 or spaces, or even newlines.  They are processed as usual, as described
4145 above. 
4146
4147 The @samp{-O, -f, -m, and -W} switches are handled specifically in these
4148 constructs.  If another value of @samp{-O} or the negated form of a @samp{-f, -m, or
4149 -W} switch is found later in the command line, the earlier switch
4150 value is ignored, except with @{@code{S}*@} where @code{S} is just one
4151 letter, which passes all matching options.
4152
4153 The character @samp{|} at the beginning of the predicate text is used to indicate
4154 that a command should be piped to the following command, but only if @samp{-pipe}
4155 is specified.
4156
4157 It is built into GCC which switches take arguments and which do not.
4158 (You might think it would be useful to generalize this to allow each
4159 compiler's spec to say which switches take arguments.  But this cannot
4160 be done in a consistent fashion.  GCC cannot even decide which input
4161 files have been specified without knowing which switches take arguments,
4162 and it must know which input files to compile in order to tell which
4163 compilers to run). 
4164
4165 GCC also knows implicitly that arguments starting in @samp{-l} are to be
4166 treated as compiler output files, and passed to the linker in their
4167 proper position among the other output files.
4168
4169 @c man begin OPTIONS
4170
4171 @node Target Options
4172 @section Specifying Target Machine and Compiler Version
4173 @cindex target options
4174 @cindex cross compiling
4175 @cindex specifying machine version
4176 @cindex specifying compiler version and target machine
4177 @cindex compiler version, specifying
4178 @cindex target machine, specifying
4179
4180 By default, GCC compiles code for the same type of machine that you
4181 are using.  However, it can also be installed as a cross-compiler, to
4182 compile for some other type of machine.  In fact, several different
4183 configurations of GCC, for different target machines, can be
4184 installed side by side.  Then you specify which one to use with the
4185 @samp{-b} option.
4186
4187 In addition, older and newer versions of GCC can be installed side
4188 by side.  One of them (probably the newest) will be the default, but
4189 you may sometimes wish to use another.
4190
4191 @table @code
4192 @item -b @var{machine}
4193 The argument @var{machine} specifies the target machine for compilation.
4194 This is useful when you have installed GCC as a cross-compiler.
4195
4196 The value to use for @var{machine} is the same as was specified as the
4197 machine type when configuring GCC as a cross-compiler.  For
4198 example, if a cross-compiler was configured with @samp{configure
4199 i386v}, meaning to compile for an 80386 running System V, then you
4200 would specify @samp{-b i386v} to run that cross compiler.
4201
4202 When you do not specify @samp{-b}, it normally means to compile for
4203 the same type of machine that you are using.
4204
4205 @item -V @var{version}
4206 The argument @var{version} specifies which version of GCC to run.
4207 This is useful when multiple versions are installed.  For example,
4208 @var{version} might be @samp{2.0}, meaning to run GCC version 2.0.
4209
4210 The default version, when you do not specify @samp{-V}, is the last
4211 version of GCC that you installed.
4212 @end table
4213
4214 The @samp{-b} and @samp{-V} options actually work by controlling part of
4215 the file name used for the executable files and libraries used for
4216 compilation.  A given version of GCC, for a given target machine, is
4217 normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
4218
4219 Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by
4220 changing the names of these directories or adding alternate names (or
4221 symbolic links).  If in directory @file{/usr/local/lib/gcc-lib/} the
4222 file @file{80386} is a link to the file @file{i386v}, then @samp{-b
4223 80386} becomes an alias for @samp{-b i386v}.
4224
4225 In one respect, the @samp{-b} or @samp{-V} do not completely change
4226 to a different compiler: the top-level driver program @code{gcc}
4227 that you originally invoked continues to run and invoke the other
4228 executables (preprocessor, compiler per se, assembler and linker)
4229 that do the real work.  However, since no real work is done in the
4230 driver program, it usually does not matter that the driver program
4231 in use is not the one for the specified target.  It is common for the
4232 interface to the other executables to change incompatibly between
4233 compiler versions, so unless the version specified is very close to that
4234 of the driver (for example, @samp{-V 3.0} with a driver program from GCC
4235 version 3.0.1), use of @samp{-V} may not work; for example, using
4236 @samp{-V 2.95.2} will not work with a driver program from GCC 3.0.
4237
4238 The only way that the driver program depends on the target machine is
4239 in the parsing and handling of special machine-specific options.
4240 However, this is controlled by a file which is found, along with the
4241 other executables, in the directory for the specified version and
4242 target machine.  As a result, a single installed driver program adapts
4243 to any specified target machine, and sufficiently similar compiler
4244 versions.
4245
4246 The driver program executable does control one significant thing,
4247 however: the default version and target machine.  Therefore, you can
4248 install different instances of the driver program, compiled for
4249 different targets or versions, under different names.
4250
4251 For example, if the driver for version 2.0 is installed as @code{ogcc}
4252 and that for version 2.1 is installed as @code{gcc}, then the command
4253 @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
4254 2.0 by default.  However, you can choose either version with either
4255 command with the @samp{-V} option.
4256
4257 @node Submodel Options
4258 @section Hardware Models and Configurations
4259 @cindex submodel options
4260 @cindex specifying hardware config
4261 @cindex hardware models and configurations, specifying
4262 @cindex machine dependent options
4263
4264 Earlier we discussed the standard option @samp{-b} which chooses among
4265 different installed compilers for completely different target
4266 machines, such as Vax vs. 68000 vs. 80386.
4267
4268 In addition, each of these target machine types can have its own
4269 special options, starting with @samp{-m}, to choose among various
4270 hardware models or configurations---for example, 68010 vs 68020,
4271 floating coprocessor or none.  A single installed version of the
4272 compiler can compile for any model or configuration, according to the
4273 options specified.
4274
4275 Some configurations of the compiler also support additional special
4276 options, usually for compatibility with other compilers on the same
4277 platform.
4278
4279 @ifset INTERNALS
4280 These options are defined by the macro @code{TARGET_SWITCHES} in the
4281 machine description.  The default for the options is also defined by
4282 that macro, which enables you to change the defaults.
4283 @end ifset
4284
4285 @menu
4286 * M680x0 Options::
4287 * M68hc1x Options::
4288 * VAX Options::
4289 * SPARC Options::
4290 * Convex Options::
4291 * AMD29K Options::
4292 * ARM Options::
4293 * Thumb Options::
4294 * MN10200 Options::
4295 * MN10300 Options::
4296 * M32R/D Options::
4297 * M88K Options::
4298 * RS/6000 and PowerPC Options::
4299 * RT Options::
4300 * MIPS Options::
4301 * i386 Options::
4302 * HPPA Options::
4303 * Intel 960 Options::
4304 * DEC Alpha Options::
4305 * Clipper Options::
4306 * H8/300 Options::
4307 * SH Options::
4308 * System V Options::
4309 * TMS320C3x/C4x Options::
4310 * V850 Options::
4311 * ARC Options::
4312 * NS32K Options::
4313 * AVR Options::
4314 * MCore Options::
4315 * D30V Options::
4316 @end menu
4317
4318 @node M680x0 Options
4319 @subsection M680x0 Options
4320 @cindex M680x0 options
4321
4322 These are the @samp{-m} options defined for the 68000 series.  The default
4323 values for these options depends on which style of 68000 was selected when
4324 the compiler was configured; the defaults for the most common choices are
4325 given below.
4326
4327 @table @code
4328 @item -m68000
4329 @itemx -mc68000
4330 Generate output for a 68000.  This is the default
4331 when the compiler is configured for 68000-based systems.
4332
4333 Use this option for microcontrollers with a 68000 or EC000 core,
4334 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.