1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2 @c 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
3 @c Free Software Foundation, Inc.
4 @c This is part of the GCC manual.
5 @c For copying conditions, see the file gcc.texi.
12 @c man begin COPYRIGHT
13 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
14 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
15 Free Software Foundation, Inc.
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.2 or
19 any later version published by the Free Software Foundation; with the
20 Invariant Sections being ``GNU General Public License'' and ``Funding
21 Free Software'', the Front-Cover texts being (a) (see below), and with
22 the Back-Cover Texts being (b) (see below). A copy of the license is
23 included in the gfdl(7) man page.
25 (a) The FSF's Front-Cover Text is:
29 (b) The FSF's Back-Cover Text is:
31 You have freedom to copy and modify this GNU Manual, like GNU
32 software. Copies published by the Free Software Foundation raise
33 funds for GNU development.
35 @c Set file name and title for the man page.
37 @settitle GNU project C and C++ compiler
39 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
40 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
41 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
42 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
43 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
44 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
45 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
47 Only the most useful options are listed here; see below for the
48 remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
51 gpl(7), gfdl(7), fsf-funding(7),
52 cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
53 and the Info entries for @file{gcc}, @file{cpp}, @file{as},
54 @file{ld}, @file{binutils} and @file{gdb}.
57 For instructions on reporting bugs, see
61 See the Info entry for @command{gcc}, or
62 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
63 for contributors to GCC@.
68 @chapter GCC Command Options
69 @cindex GCC command options
70 @cindex command options
71 @cindex options, GCC command
73 @c man begin DESCRIPTION
74 When you invoke GCC, it normally does preprocessing, compilation,
75 assembly and linking. The ``overall options'' allow you to stop this
76 process at an intermediate stage. For example, the @option{-c} option
77 says not to run the linker. Then the output consists of object files
78 output by the assembler.
80 Other options are passed on to one stage of processing. Some options
81 control the preprocessor and others the compiler itself. Yet other
82 options control the assembler and linker; most of these are not
83 documented here, since you rarely need to use any of them.
85 @cindex C compilation options
86 Most of the command line options that you can use with GCC are useful
87 for C programs; when an option is only useful with another language
88 (usually C++), the explanation says so explicitly. If the description
89 for a particular option does not mention a source language, you can use
90 that option with all supported languages.
92 @cindex C++ compilation options
93 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
94 options for compiling C++ programs.
96 @cindex grouping options
97 @cindex options, grouping
98 The @command{gcc} program accepts options and file names as operands. Many
99 options have multi-letter names; therefore multiple single-letter options
100 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
103 @cindex order of options
104 @cindex options, order
105 You can mix options and other arguments. For the most part, the order
106 you use doesn't matter. Order does matter when you use several
107 options of the same kind; for example, if you specify @option{-L} more
108 than once, the directories are searched in the order specified. Also,
109 the placement of the @option{-l} option is significant.
111 Many options have long names starting with @samp{-f} or with
112 @samp{-W}---for example,
113 @option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
114 these have both positive and negative forms; the negative form of
115 @option{-ffoo} would be @option{-fno-foo}. This manual documents
116 only one of these two forms, whichever one is not the default.
120 @xref{Option Index}, for an index to GCC's options.
123 * Option Summary:: Brief list of all options, without explanations.
124 * Overall Options:: Controlling the kind of output:
125 an executable, object files, assembler files,
126 or preprocessed source.
127 * Invoking G++:: Compiling C++ programs.
128 * C Dialect Options:: Controlling the variant of C language compiled.
129 * C++ Dialect Options:: Variations on C++.
130 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
132 * Language Independent Options:: Controlling how diagnostics should be
134 * Warning Options:: How picky should the compiler be?
135 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
136 * Optimize Options:: How much optimization?
137 * Preprocessor Options:: Controlling header files and macro definitions.
138 Also, getting dependency information for Make.
139 * Assembler Options:: Passing options to the assembler.
140 * Link Options:: Specifying libraries and so on.
141 * Directory Options:: Where to find header files and libraries.
142 Where to find the compiler executable files.
143 * Spec Files:: How to pass switches to sub-processes.
144 * Target Options:: Running a cross-compiler, or an old version of GCC.
145 * Submodel Options:: Specifying minor hardware or convention variations,
146 such as 68010 vs 68020.
147 * Code Gen Options:: Specifying conventions for function calls, data layout
149 * Environment Variables:: Env vars that affect GCC.
150 * Precompiled Headers:: Compiling a header once, and using it many times.
151 * Running Protoize:: Automatically adding or removing function prototypes.
157 @section Option Summary
159 Here is a summary of all the options, grouped by type. Explanations are
160 in the following sections.
163 @item Overall Options
164 @xref{Overall Options,,Options Controlling the Kind of Output}.
165 @gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
166 -x @var{language} -v -### --help@r{[}=@var{class}@r{]} --target-help @gol
167 --version @@@var{file}}
169 @item C Language Options
170 @xref{C Dialect Options,,Options Controlling C Dialect}.
171 @gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
172 -aux-info @var{filename} @gol
173 -fno-asm -fno-builtin -fno-builtin-@var{function} @gol
174 -fhosted -ffreestanding -fopenmp -fms-extensions @gol
175 -trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
176 -fallow-single-precision -fcond-mismatch -flax-vector-conversions @gol
177 -fsigned-bitfields -fsigned-char @gol
178 -funsigned-bitfields -funsigned-char}
180 @item C++ Language Options
181 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
182 @gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
183 -fconserve-space -ffriend-injection @gol
184 -fno-elide-constructors @gol
185 -fno-enforce-eh-specs @gol
186 -ffor-scope -fno-for-scope -fno-gnu-keywords @gol
187 -fno-implicit-templates @gol
188 -fno-implicit-inline-templates @gol
189 -fno-implement-inlines -fms-extensions @gol
190 -fno-nonansi-builtins -fno-operator-names @gol
191 -fno-optional-diags -fpermissive @gol
192 -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
193 -fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
194 -fno-default-inline -fvisibility-inlines-hidden @gol
195 -fvisibility-ms-compat @gol
196 -Wabi -Wctor-dtor-privacy @gol
197 -Wnon-virtual-dtor -Wreorder @gol
198 -Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
199 -Wno-non-template-friend -Wold-style-cast @gol
200 -Woverloaded-virtual -Wno-pmf-conversions @gol
203 @item Objective-C and Objective-C++ Language Options
204 @xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
205 Objective-C and Objective-C++ Dialects}.
206 @gccoptlist{-fconstant-string-class=@var{class-name} @gol
207 -fgnu-runtime -fnext-runtime @gol
208 -fno-nil-receivers @gol
209 -fobjc-call-cxx-cdtors @gol
210 -fobjc-direct-dispatch @gol
211 -fobjc-exceptions @gol
213 -freplace-objc-classes @gol
216 -Wassign-intercept @gol
217 -Wno-protocol -Wselector @gol
218 -Wstrict-selector-match @gol
219 -Wundeclared-selector}
221 @item Language Independent Options
222 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
223 @gccoptlist{-fmessage-length=@var{n} @gol
224 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
225 -fdiagnostics-show-option}
227 @item Warning Options
228 @xref{Warning Options,,Options to Request or Suppress Warnings}.
229 @gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
230 -w -Wextra -Wall -Waddress -Waggregate-return -Warray-bounds @gol
231 -Wno-attributes -Wc++-compat -Wc++0x-compat -Wcast-align -Wcast-qual @gol
232 -Wchar-subscripts -Wclobbered -Wcomment @gol
233 -Wconversion -Wcoverage-mismatch -Wno-deprecated-declarations @gol
234 -Wdisabled-optimization -Wno-div-by-zero @gol
235 -Wempty-body -Wno-endif-labels @gol
236 -Werror -Werror=* @gol
237 -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
238 -Wno-format-extra-args -Wformat-nonliteral @gol
239 -Wformat-security -Wformat-y2k -Wignored-qualifiers @gol
240 -Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
241 -Wimport -Wno-import -Winit-self -Winline @gol
242 -Wno-int-to-pointer-cast -Wno-invalid-offsetof @gol
243 -Winvalid-pch -Wlarger-than-@var{len} -Wunsafe-loop-optimizations @gol
244 -Wlogical-op -Wlong-long @gol
245 -Wmain -Wmissing-braces -Wmissing-field-initializers @gol
246 -Wmissing-format-attribute -Wmissing-include-dirs @gol
247 -Wmissing-noreturn @gol
248 -Wno-multichar -Wnonnull -Wno-overflow @gol
249 -Woverlength-strings -Wpacked -Wpadded @gol
250 -Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
251 -Wredundant-decls @gol
252 -Wreturn-type -Wsequence-point -Wshadow @gol
253 -Wsign-compare -Wsign-conversion -Wstack-protector @gol
254 -Wstrict-aliasing -Wstrict-aliasing=n @gol
255 -Wstrict-overflow -Wstrict-overflow=@var{n} @gol
256 -Wswitch -Wswitch-default -Wswitch-enum @gol
257 -Wsystem-headers -Wtrigraphs -Wtype-limits -Wundef -Wuninitialized @gol
258 -Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
259 -Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
260 -Wunused-value -Wunused-variable @gol
261 -Wvariadic-macros -Wvla @gol
262 -Wvolatile-register-var -Wwrite-strings}
264 @item C-only Warning Options
265 @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
266 -Wmissing-parameter-type -Wmissing-prototypes -Wnested-externs @gol
267 -Wold-style-declaration -Wold-style-definition @gol
268 -Wstrict-prototypes -Wtraditional -Wtraditional-conversion @gol
269 -Wdeclaration-after-statement -Wpointer-sign}
271 @item Debugging Options
272 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
273 @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
274 -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
275 -fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
276 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
277 -fdump-ipa-all -fdump-ipa-cgraph @gol
279 -fdump-tree-original@r{[}-@var{n}@r{]} @gol
280 -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
281 -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
282 -fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
284 -fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
285 -fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
286 -fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
287 -fdump-tree-dom@r{[}-@var{n}@r{]} @gol
288 -fdump-tree-dse@r{[}-@var{n}@r{]} @gol
289 -fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
290 -fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
291 -fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
292 -fdump-tree-nrv -fdump-tree-vect @gol
293 -fdump-tree-sink @gol
294 -fdump-tree-sra@r{[}-@var{n}@r{]} @gol
295 -fdump-tree-salias @gol
296 -fdump-tree-fre@r{[}-@var{n}@r{]} @gol
297 -fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
298 -ftree-vectorizer-verbose=@var{n} @gol
299 -fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
300 -feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
301 -feliminate-unused-debug-symbols -femit-class-debug-always @gol
302 -fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol
303 -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
304 -ftest-coverage -ftime-report -fvar-tracking @gol
305 -g -g@var{level} -gcoff -gdwarf-2 @gol
306 -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
307 -fno-merge-debug-strings -fdebug-prefix-map=@var{old}=@var{new} @gol
308 -femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
309 -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
310 -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
311 -print-multi-directory -print-multi-lib @gol
312 -print-prog-name=@var{program} -print-search-dirs -Q @gol
313 -print-sysroot-headers-suffix @gol
316 @item Optimization Options
317 @xref{Optimize Options,,Options that Control Optimization}.
319 -falign-functions[=@var{n}] -falign-jumps[=@var{n}] @gol
320 -falign-labels[=@var{n}] -falign-loops[=@var{n}] -fassociative-math @gol
321 -fauto-inc-dec -fbranch-probabilities -fbranch-target-load-optimize @gol
322 -fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves @gol
323 -fcheck-data-deps -fcprop-registers -fcrossjumping -fcse-follow-jumps @gol
324 -fcse-skip-blocks -fcx-limited-range -fdata-sections -fdce -fdce @gol
325 -fdelayed-branch -fdelete-null-pointer-checks -fdse -fdse @gol
326 -fearly-inlining -fexpensive-optimizations -ffast-math @gol
327 -ffinite-math-only -ffloat-store -fforward-propagate @gol
328 -ffunction-sections -fgcse -fgcse-after-reload -fgcse-las -fgcse-lm @gol
329 -fgcse-sm -fif-conversion -fif-conversion2 -finline-functions @gol
330 -finline-functions-called-once -finline-limit=@var{n} @gol
331 -finline-small-functions -fipa-cp -fipa-marix-reorg -fipa-pta @gol
332 -fipa-pure-const -fipa-reference -fipa-struct-reorg @gol
333 -fipa-type-escape -fivopts -fkeep-inline-functions -fkeep-static-consts @gol
334 -fmerge-all-constants -fmerge-constants -fmodulo-sched @gol
335 -fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap @gol
336 -fmudflapir -fmudflapth -fno-branch-count-reg -fno-default-inline @gol
337 -fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol
338 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
339 -fno-sched-interblock -fno-sched-spec -fno-signed-zeros @gol
340 -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
341 -fomit-frame-pointer -foptimize-register-move -foptimize-sibling-calls @gol
342 -fpeel-loops -fpredictive-commoning -fprefetch-loop-arrays @gol
343 -fprofile-generate -fprofile-use -fprofile-values -freciprocal-math @gol
344 -fregmove -frename-registers -freorder-blocks @gol
345 -freorder-blocks-and-partition -freorder-functions @gol
346 -frerun-cse-after-loop -freschedule-modulo-scheduled-loops @gol
347 -frounding-math -frtl-abstract-sequences -fsched2-use-superblocks @gol
348 -fsched2-use-traces -fsched-spec-load -fsched-spec-load-dangerous @gol
349 -fsched-stalled-insns-dep[=@var{n}] -fsched-stalled-insns[=@var{n}] @gol
350 -fschedule-insns -fschedule-insns2 -fsection-anchors -fsee @gol
351 -fsignaling-nans -fsingle-precision-constant -fsplit-ivs-in-unroller @gol
352 -fsplit-wide-types -fstack-protector -fstack-protector-all @gol
353 -fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer -ftree-ccp @gol
354 -ftree-ch -ftree-copy-prop -ftree-copyrename -ftree-dce @gol
355 -ftree-dominator-opts -ftree-dse -ftree-fre -ftree-loop-im @gol
356 -ftree-loop-ivcanon -ftree-loop-linear -ftree-loop-optimize @gol
357 -ftree-parallelize-loops=@var{n} -ftree-pre -ftree-reassoc -ftree-salias @gol
358 -ftree-sink -ftree-sra -ftree-store-ccp -ftree-ter @gol
359 -ftree-vect-loop-version -ftree-vectorize -ftree-vrp -funit-at-a-time @gol
360 -funroll-all-loops -funroll-loops -funsafe-loop-optimizations @gol
361 -funsafe-math-optimizations -funswitch-loops @gol
362 -fvariable-expansion-in-unroller -fvect-cost-model -fvpt -fweb @gol
364 --param @var{name}=@var{value}
365 -O -O0 -O1 -O2 -O3 -Os}
367 @item Preprocessor Options
368 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
369 @gccoptlist{-A@var{question}=@var{answer} @gol
370 -A-@var{question}@r{[}=@var{answer}@r{]} @gol
371 -C -dD -dI -dM -dN @gol
372 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
373 -idirafter @var{dir} @gol
374 -include @var{file} -imacros @var{file} @gol
375 -iprefix @var{file} -iwithprefix @var{dir} @gol
376 -iwithprefixbefore @var{dir} -isystem @var{dir} @gol
377 -imultilib @var{dir} -isysroot @var{dir} @gol
378 -M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
379 -P -fworking-directory -remap @gol
380 -trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
381 -Xpreprocessor @var{option}}
383 @item Assembler Option
384 @xref{Assembler Options,,Passing Options to the Assembler}.
385 @gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
388 @xref{Link Options,,Options for Linking}.
389 @gccoptlist{@var{object-file-name} -l@var{library} @gol
390 -nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
391 -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
392 -Wl,@var{option} -Xlinker @var{option} @gol
395 @item Directory Options
396 @xref{Directory Options,,Options for Directory Search}.
397 @gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
398 -specs=@var{file} -I- --sysroot=@var{dir}}
401 @c I wrote this xref this way to avoid overfull hbox. -- rms
402 @xref{Target Options}.
403 @gccoptlist{-V @var{version} -b @var{machine}}
405 @item Machine Dependent Options
406 @xref{Submodel Options,,Hardware Models and Configurations}.
407 @c This list is ordered alphanumerically by subsection name.
408 @c Try and put the significant identifier (CPU or system) first,
409 @c so users have a clue at guessing where the ones they want will be.
412 @gccoptlist{-EB -EL @gol
413 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
414 -mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
417 @gccoptlist{-mapcs-frame -mno-apcs-frame @gol
418 -mabi=@var{name} @gol
419 -mapcs-stack-check -mno-apcs-stack-check @gol
420 -mapcs-float -mno-apcs-float @gol
421 -mapcs-reentrant -mno-apcs-reentrant @gol
422 -msched-prolog -mno-sched-prolog @gol
423 -mlittle-endian -mbig-endian -mwords-little-endian @gol
424 -mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
425 -mthumb-interwork -mno-thumb-interwork @gol
426 -mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
427 -mstructure-size-boundary=@var{n} @gol
428 -mabort-on-noreturn @gol
429 -mlong-calls -mno-long-calls @gol
430 -msingle-pic-base -mno-single-pic-base @gol
431 -mpic-register=@var{reg} @gol
432 -mnop-fun-dllimport @gol
433 -mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
434 -mpoke-function-name @gol
436 -mtpcs-frame -mtpcs-leaf-frame @gol
437 -mcaller-super-interworking -mcallee-super-interworking @gol
441 @gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
442 -mcall-prologues -mno-tablejump -mtiny-stack -mint8}
444 @emph{Blackfin Options}
445 @gccoptlist{-mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]} @gol
446 -msim -momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
447 -mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
448 -mlow-64k -mno-low64k -mstack-check-l1 -mid-shared-library @gol
449 -mno-id-shared-library -mshared-library-id=@var{n} @gol
450 -mleaf-id-shared-library -mno-leaf-id-shared-library @gol
451 -msep-data -mno-sep-data -mlong-calls -mno-long-calls @gol
452 -mfast-fp -minline-plt}
455 @gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
456 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
457 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
458 -mstack-align -mdata-align -mconst-align @gol
459 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
460 -melf -maout -melinux -mlinux -sim -sim2 @gol
461 -mmul-bug-workaround -mno-mul-bug-workaround}
464 @gccoptlist{-mmac -mpush-args}
466 @emph{Darwin Options}
467 @gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
468 -arch_only -bind_at_load -bundle -bundle_loader @gol
469 -client_name -compatibility_version -current_version @gol
471 -dependency-file -dylib_file -dylinker_install_name @gol
472 -dynamic -dynamiclib -exported_symbols_list @gol
473 -filelist -flat_namespace -force_cpusubtype_ALL @gol
474 -force_flat_namespace -headerpad_max_install_names @gol
476 -image_base -init -install_name -keep_private_externs @gol
477 -multi_module -multiply_defined -multiply_defined_unused @gol
478 -noall_load -no_dead_strip_inits_and_terms @gol
479 -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
480 -pagezero_size -prebind -prebind_all_twolevel_modules @gol
481 -private_bundle -read_only_relocs -sectalign @gol
482 -sectobjectsymbols -whyload -seg1addr @gol
483 -sectcreate -sectobjectsymbols -sectorder @gol
484 -segaddr -segs_read_only_addr -segs_read_write_addr @gol
485 -seg_addr_table -seg_addr_table_filename -seglinkedit @gol
486 -segprot -segs_read_only_addr -segs_read_write_addr @gol
487 -single_module -static -sub_library -sub_umbrella @gol
488 -twolevel_namespace -umbrella -undefined @gol
489 -unexported_symbols_list -weak_reference_mismatches @gol
490 -whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
491 -mkernel -mone-byte-bool}
493 @emph{DEC Alpha Options}
494 @gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
495 -mieee -mieee-with-inexact -mieee-conformant @gol
496 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
497 -mtrap-precision=@var{mode} -mbuild-constants @gol
498 -mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
499 -mbwx -mmax -mfix -mcix @gol
500 -mfloat-vax -mfloat-ieee @gol
501 -mexplicit-relocs -msmall-data -mlarge-data @gol
502 -msmall-text -mlarge-text @gol
503 -mmemory-latency=@var{time}}
505 @emph{DEC Alpha/VMS Options}
506 @gccoptlist{-mvms-return-codes}
509 @gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
510 -mhard-float -msoft-float @gol
511 -malloc-cc -mfixed-cc -mdword -mno-dword @gol
512 -mdouble -mno-double @gol
513 -mmedia -mno-media -mmuladd -mno-muladd @gol
514 -mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
515 -mlinked-fp -mlong-calls -malign-labels @gol
516 -mlibrary-pic -macc-4 -macc-8 @gol
517 -mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
518 -moptimize-membar -mno-optimize-membar @gol
519 -mscc -mno-scc -mcond-exec -mno-cond-exec @gol
520 -mvliw-branch -mno-vliw-branch @gol
521 -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
522 -mno-nested-cond-exec -mtomcat-stats @gol
526 @emph{GNU/Linux Options}
527 @gccoptlist{-muclibc}
529 @emph{H8/300 Options}
530 @gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
533 @gccoptlist{-march=@var{architecture-type} @gol
534 -mbig-switch -mdisable-fpregs -mdisable-indexing @gol
535 -mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
536 -mfixed-range=@var{register-range} @gol
537 -mjump-in-delay -mlinker-opt -mlong-calls @gol
538 -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
539 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
540 -mno-jump-in-delay -mno-long-load-store @gol
541 -mno-portable-runtime -mno-soft-float @gol
542 -mno-space-regs -msoft-float -mpa-risc-1-0 @gol
543 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
544 -mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
545 -munix=@var{unix-std} -nolibdld -static -threads}
547 @emph{i386 and x86-64 Options}
548 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
549 -mfpmath=@var{unit} @gol
550 -masm=@var{dialect} -mno-fancy-math-387 @gol
551 -mno-fp-ret-in-387 -msoft-float @gol
552 -mno-wide-multiply -mrtd -malign-double @gol
553 -mpreferred-stack-boundary=@var{num} -mcx16 -msahf -mrecip @gol
554 -mmmx -msse -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 @gol
555 -msse4a -m3dnow -mpopcnt -mabm -msse5 @gol
556 -mthreads -mno-align-stringops -minline-all-stringops @gol
557 -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
558 -m96bit-long-double -mregparm=@var{num} -msseregparm @gol
559 -mveclibabi=@var{type} -mpc32 -mpc64 -mpc80 -mstackrealign @gol
560 -momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
561 -mcmodel=@var{code-model} @gol
562 -m32 -m64 -mlarge-data-threshold=@var{num} @gol
563 -mfused-madd -mno-fused-madd}
566 @gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
567 -mvolatile-asm-stop -mregister-names -mno-sdata @gol
568 -mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
569 -minline-float-divide-max-throughput @gol
570 -minline-int-divide-min-latency @gol
571 -minline-int-divide-max-throughput @gol
572 -minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
573 -mno-dwarf2-asm -mearly-stop-bits @gol
574 -mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
575 -mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
576 -mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
577 -msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
578 -msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
579 -mno-sched-prefer-non-data-spec-insns @gol
580 -mno-sched-prefer-non-control-spec-insns @gol
581 -mno-sched-count-spec-in-critical-path}
583 @emph{M32R/D Options}
584 @gccoptlist{-m32r2 -m32rx -m32r @gol
586 -malign-loops -mno-align-loops @gol
587 -missue-rate=@var{number} @gol
588 -mbranch-cost=@var{number} @gol
589 -mmodel=@var{code-size-model-type} @gol
590 -msdata=@var{sdata-type} @gol
591 -mno-flush-func -mflush-func=@var{name} @gol
592 -mno-flush-trap -mflush-trap=@var{number} @gol
596 @gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
598 @emph{M680x0 Options}
599 @gccoptlist{-march=@var{arch} -mcpu=@var{cpu} -mtune=@var{tune}
600 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
601 -m68060 -mcpu32 -m5200 -m5206e -m528x -m5307 -m5407 @gol
602 -mcfv4e -mbitfield -mno-bitfield -mc68000 -mc68020 @gol
603 -mnobitfield -mrtd -mno-rtd -mdiv -mno-div -mshort @gol
604 -mno-short -mhard-float -m68881 -msoft-float -mpcrel @gol
605 -malign-int -mstrict-align -msep-data -mno-sep-data @gol
606 -mshared-library-id=n -mid-shared-library -mno-id-shared-library}
608 @emph{M68hc1x Options}
609 @gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
610 -mauto-incdec -minmax -mlong-calls -mshort @gol
611 -msoft-reg-count=@var{count}}
614 @gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
615 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
616 -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
617 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
618 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
621 @gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
622 -mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
623 -mips16 -mno-mips16 -mflip-mips16 @gol
624 -minterlink-mips16 -mno-interlink-mips16 @gol
625 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
626 -mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
627 -mfp32 -mfp64 -mhard-float -msoft-float @gol
628 -msingle-float -mdouble-float -mdsp -mno-dsp -mdspr2 -mno-dspr2 @gol
629 -msmartmips -mno-smartmips @gol
630 -mpaired-single -mno-paired-single -mdmx -mno-mdmx @gol
631 -mips3d -mno-mips3d -mmt -mno-mt -mllsc -mno-llsc @gol
632 -mlong64 -mlong32 -msym32 -mno-sym32 @gol
633 -G@var{num} -mlocal-sdata -mno-local-sdata @gol
634 -mextern-sdata -mno-extern-sdata -mgpopt -mno-gopt @gol
635 -membedded-data -mno-embedded-data @gol
636 -muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
637 -mcode-readable=@var{setting} @gol
638 -msplit-addresses -mno-split-addresses @gol
639 -mexplicit-relocs -mno-explicit-relocs @gol
640 -mcheck-zero-division -mno-check-zero-division @gol
641 -mdivide-traps -mdivide-breaks @gol
642 -mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
643 -mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
644 -mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
645 -mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 -mno-fix-vr4130 @gol
646 -mfix-sb1 -mno-fix-sb1 @gol
647 -mflush-func=@var{func} -mno-flush-func @gol
648 -mbranch-cost=@var{num} -mbranch-likely -mno-branch-likely @gol
649 -mfp-exceptions -mno-fp-exceptions @gol
650 -mvr4130-align -mno-vr4130-align}
653 @gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
654 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
655 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
656 -mno-base-addresses -msingle-exit -mno-single-exit}
658 @emph{MN10300 Options}
659 @gccoptlist{-mmult-bug -mno-mult-bug @gol
660 -mam33 -mno-am33 @gol
661 -mam33-2 -mno-am33-2 @gol
662 -mreturn-pointer-on-d0 @gol
666 @gccoptlist{-mno-crt0 -mbacc -msim @gol
667 -march=@var{cpu-type} }
669 @emph{PDP-11 Options}
670 @gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
671 -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
672 -mint16 -mno-int32 -mfloat32 -mno-float64 @gol
673 -mfloat64 -mno-float32 -mabshi -mno-abshi @gol
674 -mbranch-expensive -mbranch-cheap @gol
675 -msplit -mno-split -munix-asm -mdec-asm}
677 @emph{PowerPC Options}
678 See RS/6000 and PowerPC Options.
680 @emph{RS/6000 and PowerPC Options}
681 @gccoptlist{-mcpu=@var{cpu-type} @gol
682 -mtune=@var{cpu-type} @gol
683 -mpower -mno-power -mpower2 -mno-power2 @gol
684 -mpowerpc -mpowerpc64 -mno-powerpc @gol
685 -maltivec -mno-altivec @gol
686 -mpowerpc-gpopt -mno-powerpc-gpopt @gol
687 -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
688 -mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
689 -mcmpb -mno-cmpb -mmfpgpr -mno-mfpgpr -mhard-dfp -mno-hard-dfp @gol
690 -mnew-mnemonics -mold-mnemonics @gol
691 -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
692 -m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
693 -malign-power -malign-natural @gol
694 -msoft-float -mhard-float -mmultiple -mno-multiple @gol
695 -mstring -mno-string -mupdate -mno-update @gol
696 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
697 -mstrict-align -mno-strict-align -mrelocatable @gol
698 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
699 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
700 -mdynamic-no-pic -maltivec -mswdiv @gol
701 -mprioritize-restricted-insns=@var{priority} @gol
702 -msched-costly-dep=@var{dependence_type} @gol
703 -minsert-sched-nops=@var{scheme} @gol
704 -mcall-sysv -mcall-netbsd @gol
705 -maix-struct-return -msvr4-struct-return @gol
706 -mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
707 -misel -mno-isel @gol
708 -misel=yes -misel=no @gol
710 -mspe=yes -mspe=no @gol
712 -mvrsave -mno-vrsave @gol
713 -mmulhw -mno-mulhw @gol
714 -mdlmzb -mno-dlmzb @gol
715 -mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
716 -mprototype -mno-prototype @gol
717 -msim -mmvme -mads -myellowknife -memb -msdata @gol
718 -msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
720 @emph{S/390 and zSeries Options}
721 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
722 -mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
723 -mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
724 -msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
725 -m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
726 -mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
727 -mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
730 @gccoptlist{-meb -mel @gol
734 -mscore5 -mscore5u -mscore7 -mscore7d}
737 @gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
738 -m4-nofpu -m4-single-only -m4-single -m4 @gol
739 -m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
740 -m5-64media -m5-64media-nofpu @gol
741 -m5-32media -m5-32media-nofpu @gol
742 -m5-compact -m5-compact-nofpu @gol
743 -mb -ml -mdalign -mrelax @gol
744 -mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
745 -mieee -misize -minline-ic_invalidate -mpadstruct -mspace @gol
746 -mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
747 -mdivsi3_libfunc=@var{name} @gol
748 -madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
752 @gccoptlist{-mcpu=@var{cpu-type} @gol
753 -mtune=@var{cpu-type} @gol
754 -mcmodel=@var{code-model} @gol
755 -m32 -m64 -mapp-regs -mno-app-regs @gol
756 -mfaster-structs -mno-faster-structs @gol
757 -mfpu -mno-fpu -mhard-float -msoft-float @gol
758 -mhard-quad-float -msoft-quad-float @gol
759 -mimpure-text -mno-impure-text -mlittle-endian @gol
760 -mstack-bias -mno-stack-bias @gol
761 -munaligned-doubles -mno-unaligned-doubles @gol
762 -mv8plus -mno-v8plus -mvis -mno-vis
763 -threads -pthreads -pthread}
766 @gccoptlist{-mwarn-reloc -merror-reloc @gol
767 -msafe-dma -munsafe-dma @gol
769 -msmall-mem -mlarge-mem -mstdmain @gol
770 -mfixed-range=@var{register-range}}
772 @emph{System V Options}
773 @gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
775 @emph{TMS320C3x/C4x Options}
776 @gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
777 -mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
778 -mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
779 -mparallel-insns -mparallel-mpy -mpreserve-float}
782 @gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
783 -mprolog-function -mno-prolog-function -mspace @gol
784 -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
785 -mapp-regs -mno-app-regs @gol
786 -mdisable-callt -mno-disable-callt @gol
792 @gccoptlist{-mg -mgnu -munix}
794 @emph{VxWorks Options}
795 @gccoptlist{-mrtp -non-static -Bstatic -Bdynamic @gol
796 -Xbind-lazy -Xbind-now}
798 @emph{x86-64 Options}
799 See i386 and x86-64 Options.
801 @emph{Xstormy16 Options}
804 @emph{Xtensa Options}
805 @gccoptlist{-mconst16 -mno-const16 @gol
806 -mfused-madd -mno-fused-madd @gol
807 -mtext-section-literals -mno-text-section-literals @gol
808 -mtarget-align -mno-target-align @gol
809 -mlongcalls -mno-longcalls}
811 @emph{zSeries Options}
812 See S/390 and zSeries Options.
814 @item Code Generation Options
815 @xref{Code Gen Options,,Options for Code Generation Conventions}.
816 @gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
817 -ffixed-@var{reg} -fexceptions @gol
818 -fnon-call-exceptions -funwind-tables @gol
819 -fasynchronous-unwind-tables @gol
820 -finhibit-size-directive -finstrument-functions @gol
821 -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
822 -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol
823 -fno-common -fno-ident @gol
824 -fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
825 -fno-jump-tables @gol
826 -frecord-gcc-switches @gol
827 -freg-struct-return -fshort-enums @gol
828 -fshort-double -fshort-wchar @gol
829 -fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
830 -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
831 -fno-stack-limit -fargument-alias -fargument-noalias @gol
832 -fargument-noalias-global -fargument-noalias-anything @gol
833 -fleading-underscore -ftls-model=@var{model} @gol
834 -ftrapv -fwrapv -fbounds-check @gol
839 * Overall Options:: Controlling the kind of output:
840 an executable, object files, assembler files,
841 or preprocessed source.
842 * C Dialect Options:: Controlling the variant of C language compiled.
843 * C++ Dialect Options:: Variations on C++.
844 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
846 * Language Independent Options:: Controlling how diagnostics should be
848 * Warning Options:: How picky should the compiler be?
849 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
850 * Optimize Options:: How much optimization?
851 * Preprocessor Options:: Controlling header files and macro definitions.
852 Also, getting dependency information for Make.
853 * Assembler Options:: Passing options to the assembler.
854 * Link Options:: Specifying libraries and so on.
855 * Directory Options:: Where to find header files and libraries.
856 Where to find the compiler executable files.
857 * Spec Files:: How to pass switches to sub-processes.
858 * Target Options:: Running a cross-compiler, or an old version of GCC.
861 @node Overall Options
862 @section Options Controlling the Kind of Output
864 Compilation can involve up to four stages: preprocessing, compilation
865 proper, assembly and linking, always in that order. GCC is capable of
866 preprocessing and compiling several files either into several
867 assembler input files, or into one assembler input file; then each
868 assembler input file produces an object file, and linking combines all
869 the object files (those newly compiled, and those specified as input)
870 into an executable file.
872 @cindex file name suffix
873 For any given input file, the file name suffix determines what kind of
878 C source code which must be preprocessed.
881 C source code which should not be preprocessed.
884 C++ source code which should not be preprocessed.
887 Objective-C source code. Note that you must link with the @file{libobjc}
888 library to make an Objective-C program work.
891 Objective-C source code which should not be preprocessed.
895 Objective-C++ source code. Note that you must link with the @file{libobjc}
896 library to make an Objective-C++ program work. Note that @samp{.M} refers
897 to a literal capital M@.
900 Objective-C++ source code which should not be preprocessed.
903 C, C++, Objective-C or Objective-C++ header file to be turned into a
908 @itemx @var{file}.cxx
909 @itemx @var{file}.cpp
910 @itemx @var{file}.CPP
911 @itemx @var{file}.c++
913 C++ source code which must be preprocessed. Note that in @samp{.cxx},
914 the last two letters must both be literally @samp{x}. Likewise,
915 @samp{.C} refers to a literal capital C@.
919 Objective-C++ source code which must be preprocessed.
922 Objective-C++ source code which should not be preprocessed.
927 @itemx @var{file}.hxx
928 @itemx @var{file}.hpp
929 @itemx @var{file}.HPP
930 @itemx @var{file}.h++
931 @itemx @var{file}.tcc
932 C++ header file to be turned into a precompiled header.
935 @itemx @var{file}.for
936 @itemx @var{file}.FOR
937 Fixed form Fortran source code which should not be preprocessed.
940 @itemx @var{file}.fpp
941 @itemx @var{file}.FPP
942 Fixed form Fortran source code which must be preprocessed (with the traditional
946 @itemx @var{file}.f95
947 Free form Fortran source code which should not be preprocessed.
950 @itemx @var{file}.F95
951 Free form Fortran source code which must be preprocessed (with the
952 traditional preprocessor).
954 @c FIXME: Descriptions of Java file types.
961 Ada source code file which contains a library unit declaration (a
962 declaration of a package, subprogram, or generic, or a generic
963 instantiation), or a library unit renaming declaration (a package,
964 generic, or subprogram renaming declaration). Such files are also
967 @itemx @var{file}.adb
968 Ada source code file containing a library unit body (a subprogram or
969 package body). Such files are also called @dfn{bodies}.
971 @c GCC also knows about some suffixes for languages not yet included:
983 Assembler code which must be preprocessed.
986 An object file to be fed straight into linking.
987 Any file name with no recognized suffix is treated this way.
991 You can specify the input language explicitly with the @option{-x} option:
994 @item -x @var{language}
995 Specify explicitly the @var{language} for the following input files
996 (rather than letting the compiler choose a default based on the file
997 name suffix). This option applies to all following input files until
998 the next @option{-x} option. Possible values for @var{language} are:
1000 c c-header c-cpp-output
1001 c++ c++-header c++-cpp-output
1002 objective-c objective-c-header objective-c-cpp-output
1003 objective-c++ objective-c++-header objective-c++-cpp-output
1004 assembler assembler-with-cpp
1012 Turn off any specification of a language, so that subsequent files are
1013 handled according to their file name suffixes (as they are if @option{-x}
1014 has not been used at all).
1016 @item -pass-exit-codes
1017 @opindex pass-exit-codes
1018 Normally the @command{gcc} program will exit with the code of 1 if any
1019 phase of the compiler returns a non-success return code. If you specify
1020 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
1021 numerically highest error produced by any phase that returned an error
1022 indication. The C, C++, and Fortran frontends return 4, if an internal
1023 compiler error is encountered.
1026 If you only want some of the stages of compilation, you can use
1027 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
1028 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
1029 @command{gcc} is to stop. Note that some combinations (for example,
1030 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
1035 Compile or assemble the source files, but do not link. The linking
1036 stage simply is not done. The ultimate output is in the form of an
1037 object file for each source file.
1039 By default, the object file name for a source file is made by replacing
1040 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
1042 Unrecognized input files, not requiring compilation or assembly, are
1047 Stop after the stage of compilation proper; do not assemble. The output
1048 is in the form of an assembler code file for each non-assembler input
1051 By default, the assembler file name for a source file is made by
1052 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1054 Input files that don't require compilation are ignored.
1058 Stop after the preprocessing stage; do not run the compiler proper. The
1059 output is in the form of preprocessed source code, which is sent to the
1062 Input files which don't require preprocessing are ignored.
1064 @cindex output file option
1067 Place output in file @var{file}. This applies regardless to whatever
1068 sort of output is being produced, whether it be an executable file,
1069 an object file, an assembler file or preprocessed C code.
1071 If @option{-o} is not specified, the default is to put an executable
1072 file in @file{a.out}, the object file for
1073 @file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1074 assembler file in @file{@var{source}.s}, a precompiled header file in
1075 @file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1080 Print (on standard error output) the commands executed to run the stages
1081 of compilation. Also print the version number of the compiler driver
1082 program and of the preprocessor and the compiler proper.
1086 Like @option{-v} except the commands are not executed and all command
1087 arguments are quoted. This is useful for shell scripts to capture the
1088 driver-generated command lines.
1092 Use pipes rather than temporary files for communication between the
1093 various stages of compilation. This fails to work on some systems where
1094 the assembler is unable to read from a pipe; but the GNU assembler has
1099 If you are compiling multiple source files, this option tells the driver
1100 to pass all the source files to the compiler at once (for those
1101 languages for which the compiler can handle this). This will allow
1102 intermodule analysis (IMA) to be performed by the compiler. Currently the only
1103 language for which this is supported is C@. If you pass source files for
1104 multiple languages to the driver, using this option, the driver will invoke
1105 the compiler(s) that support IMA once each, passing each compiler all the
1106 source files appropriate for it. For those languages that do not support
1107 IMA this option will be ignored, and the compiler will be invoked once for
1108 each source file in that language. If you use this option in conjunction
1109 with @option{-save-temps}, the compiler will generate multiple
1111 (one for each source file), but only one (combined) @file{.o} or
1116 Print (on the standard output) a description of the command line options
1117 understood by @command{gcc}. If the @option{-v} option is also specified
1118 then @option{--help} will also be passed on to the various processes
1119 invoked by @command{gcc}, so that they can display the command line options
1120 they accept. If the @option{-Wextra} option has also been specified
1121 (prior to the @option{--help} option), then command line options which
1122 have no documentation associated with them will also be displayed.
1125 @opindex target-help
1126 Print (on the standard output) a description of target-specific command
1127 line options for each tool. For some targets extra target-specific
1128 information may also be printed.
1130 @item --help=@var{class}@r{[},@var{qualifier}@r{]}
1131 Print (on the standard output) a description of the command line
1132 options understood by the compiler that fit into a specific class.
1133 The class can be one of @samp{optimizers}, @samp{warnings}, @samp{target},
1134 @samp{params}, or @var{language}:
1137 @item @samp{optimizers}
1138 This will display all of the optimization options supported by the
1141 @item @samp{warnings}
1142 This will display all of the options controlling warning messages
1143 produced by the compiler.
1146 This will display target-specific options. Unlike the
1147 @option{--target-help} option however, target-specific options of the
1148 linker and assembler will not be displayed. This is because those
1149 tools do not currently support the extended @option{--help=} syntax.
1152 This will display the values recognized by the @option{--param}
1155 @item @var{language}
1156 This will display the options supported for @var{language}, where
1157 @var{language} is the name of one of the languages supported in this
1161 This will display the options that are common to all languages.
1164 It is possible to further refine the output of the @option{--help=}
1165 option by adding a comma separated list of qualifiers after the
1166 class. These can be any from the following list:
1169 @item @samp{undocumented}
1170 Display only those options which are undocumented.
1173 Display options which take an argument that appears after an equal
1174 sign in the same continuous piece of text, such as:
1175 @samp{--help=target}.
1177 @item @samp{separate}
1178 Display options which take an argument that appears as a separate word
1179 following the original option, such as: @samp{-o output-file}.
1182 Thus for example to display all the undocumented target-specific
1183 switches supported by the compiler the following can be used:
1186 --help=target,undocumented
1189 The sense of a qualifier can be inverted by prefixing it with the
1190 @var{^} character, so for example to display all binary warning
1191 options (i.e. ones that are either on or off and that do not take an
1192 argument), which have a description the following can be used:
1195 --help=warnings,^joined,^undocumented
1198 A class can also be used as a qualifier, although this usually
1199 restricts the output by so much that there is nothing to display. One
1200 case where it does work however is when one of the classes is
1201 @var{target}. So for example to display all the target-specific
1202 optimization options the following can be used:
1205 --help=target,optimizers
1208 The @option{--help=} option can be repeated on the command line. Each
1209 successive use will display its requested class of options, skipping
1210 those that have already been displayed.
1212 If the @option{-Q} option appears on the command line before the
1213 @option{--help=} option, then the descriptive text displayed by
1214 @option{--help=} is changed. Instead of describing the displayed
1215 options, an indication is given as to whether the option is enabled,
1216 disabled or set to a specific value (assuming that the compiler
1217 knows this at the point where the @option{--help=} option is used).
1219 Here is a truncated example from the ARM port of @command{gcc}:
1222 % gcc -Q -mabi=2 --help=target -c
1223 The following options are target specific:
1225 -mabort-on-noreturn [disabled]
1229 The output is sensitive to the effects of previous command line
1230 options, so for example it is possible to find out which optimizations
1231 are enabled at @option{-O2} by using:
1234 -O2 --help=optimizers
1237 Alternatively you can discover which binary optimizations are enabled
1238 by @option{-O3} by using:
1241 gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
1242 gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
1243 diff /tmp/O2-opts /tmp/O3-opts | grep enabled
1248 Display the version number and copyrights of the invoked GCC@.
1250 @include @value{srcdir}/../libiberty/at-file.texi
1254 @section Compiling C++ Programs
1256 @cindex suffixes for C++ source
1257 @cindex C++ source file suffixes
1258 C++ source files conventionally use one of the suffixes @samp{.C},
1259 @samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1260 @samp{.cxx}; C++ header files often use @samp{.hh}, @samp{.hpp},
1261 @samp{.H}, or (for shared template code) @samp{.tcc}; and
1262 preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1263 files with these names and compiles them as C++ programs even if you
1264 call the compiler the same way as for compiling C programs (usually
1265 with the name @command{gcc}).
1269 However, the use of @command{gcc} does not add the C++ library.
1270 @command{g++} is a program that calls GCC and treats @samp{.c},
1271 @samp{.h} and @samp{.i} files as C++ source files instead of C source
1272 files unless @option{-x} is used, and automatically specifies linking
1273 against the C++ library. This program is also useful when
1274 precompiling a C header file with a @samp{.h} extension for use in C++
1275 compilations. On many systems, @command{g++} is also installed with
1276 the name @command{c++}.
1278 @cindex invoking @command{g++}
1279 When you compile C++ programs, you may specify many of the same
1280 command-line options that you use for compiling programs in any
1281 language; or command-line options meaningful for C and related
1282 languages; or options that are meaningful only for C++ programs.
1283 @xref{C Dialect Options,,Options Controlling C Dialect}, for
1284 explanations of options for languages related to C@.
1285 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1286 explanations of options that are meaningful only for C++ programs.
1288 @node C Dialect Options
1289 @section Options Controlling C Dialect
1290 @cindex dialect options
1291 @cindex language dialect options
1292 @cindex options, dialect
1294 The following options control the dialect of C (or languages derived
1295 from C, such as C++, Objective-C and Objective-C++) that the compiler
1299 @cindex ANSI support
1303 In C mode, support all ISO C90 programs. In C++ mode,
1304 remove GNU extensions that conflict with ISO C++.
1306 This turns off certain features of GCC that are incompatible with ISO
1307 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1308 such as the @code{asm} and @code{typeof} keywords, and
1309 predefined macros such as @code{unix} and @code{vax} that identify the
1310 type of system you are using. It also enables the undesirable and
1311 rarely used ISO trigraph feature. For the C compiler,
1312 it disables recognition of C++ style @samp{//} comments as well as
1313 the @code{inline} keyword.
1315 The alternate keywords @code{__asm__}, @code{__extension__},
1316 @code{__inline__} and @code{__typeof__} continue to work despite
1317 @option{-ansi}. You would not want to use them in an ISO C program, of
1318 course, but it is useful to put them in header files that might be included
1319 in compilations done with @option{-ansi}. Alternate predefined macros
1320 such as @code{__unix__} and @code{__vax__} are also available, with or
1321 without @option{-ansi}.
1323 The @option{-ansi} option does not cause non-ISO programs to be
1324 rejected gratuitously. For that, @option{-pedantic} is required in
1325 addition to @option{-ansi}. @xref{Warning Options}.
1327 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1328 option is used. Some header files may notice this macro and refrain
1329 from declaring certain functions or defining certain macros that the
1330 ISO standard doesn't call for; this is to avoid interfering with any
1331 programs that might use these names for other things.
1333 Functions which would normally be built in but do not have semantics
1334 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1335 functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1336 built-in functions provided by GCC}, for details of the functions
1341 Determine the language standard. This option is currently only
1342 supported when compiling C or C++. A value for this option must be
1343 provided; possible values are
1348 ISO C90 (same as @option{-ansi}).
1350 @item iso9899:199409
1351 ISO C90 as modified in amendment 1.
1357 ISO C99. Note that this standard is not yet fully supported; see
1358 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The
1359 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1362 Default, ISO C90 plus GNU extensions (including some C99 features).
1366 ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1367 this will become the default. The name @samp{gnu9x} is deprecated.
1370 The 1998 ISO C++ standard plus amendments.
1373 The same as @option{-std=c++98} plus GNU extensions. This is the
1374 default for C++ code.
1377 The working draft of the upcoming ISO C++0x standard. This option
1378 enables experimental features that are likely to be included in
1379 C++0x. The working draft is constantly changing, and any feature that is
1380 enabled by this flag may be removed from future versions of GCC if it is
1381 not part of the C++0x standard.
1384 The same as @option{-std=c++0x} plus GNU extensions. As with
1385 @option{-std=c++0x}, this option enables experimental features that may
1386 be removed in future versions of GCC.
1389 Even when this option is not specified, you can still use some of the
1390 features of newer standards in so far as they do not conflict with
1391 previous C standards. For example, you may use @code{__restrict__} even
1392 when @option{-std=c99} is not specified.
1394 The @option{-std} options specifying some version of ISO C have the same
1395 effects as @option{-ansi}, except that features that were not in ISO C90
1396 but are in the specified version (for example, @samp{//} comments and
1397 the @code{inline} keyword in ISO C99) are not disabled.
1399 @xref{Standards,,Language Standards Supported by GCC}, for details of
1400 these standard versions.
1402 @item -fgnu89-inline
1403 @opindex fgnu89-inline
1404 The option @option{-fgnu89-inline} tells GCC to use the traditional
1405 GNU semantics for @code{inline} functions when in C99 mode.
1406 @xref{Inline,,An Inline Function is As Fast As a Macro}. This option
1407 is accepted and ignored by GCC versions 4.1.3 up to but not including
1408 4.3. In GCC versions 4.3 and later it changes the behavior of GCC in
1409 C99 mode. Using this option is roughly equivalent to adding the
1410 @code{gnu_inline} function attribute to all inline functions
1411 (@pxref{Function Attributes}).
1413 The option @option{-fno-gnu89-inline} explicitly tells GCC to use the
1414 C99 semantics for @code{inline} when in C99 or gnu99 mode (i.e., it
1415 specifies the default behavior). This option was first supported in
1416 GCC 4.3. This option is not supported in C89 or gnu89 mode.
1418 The preprocessor macros @code{__GNUC_GNU_INLINE__} and
1419 @code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1420 in effect for @code{inline} functions. @xref{Common Predefined
1421 Macros,,,cpp,The C Preprocessor}.
1423 @item -aux-info @var{filename}
1425 Output to the given filename prototyped declarations for all functions
1426 declared and/or defined in a translation unit, including those in header
1427 files. This option is silently ignored in any language other than C@.
1429 Besides declarations, the file indicates, in comments, the origin of
1430 each declaration (source file and line), whether the declaration was
1431 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1432 @samp{O} for old, respectively, in the first character after the line
1433 number and the colon), and whether it came from a declaration or a
1434 definition (@samp{C} or @samp{F}, respectively, in the following
1435 character). In the case of function definitions, a K&R-style list of
1436 arguments followed by their declarations is also provided, inside
1437 comments, after the declaration.
1441 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1442 keyword, so that code can use these words as identifiers. You can use
1443 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1444 instead. @option{-ansi} implies @option{-fno-asm}.
1446 In C++, this switch only affects the @code{typeof} keyword, since
1447 @code{asm} and @code{inline} are standard keywords. You may want to
1448 use the @option{-fno-gnu-keywords} flag instead, which has the same
1449 effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1450 switch only affects the @code{asm} and @code{typeof} keywords, since
1451 @code{inline} is a standard keyword in ISO C99.
1454 @itemx -fno-builtin-@var{function}
1455 @opindex fno-builtin
1456 @cindex built-in functions
1457 Don't recognize built-in functions that do not begin with
1458 @samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1459 functions provided by GCC}, for details of the functions affected,
1460 including those which are not built-in functions when @option{-ansi} or
1461 @option{-std} options for strict ISO C conformance are used because they
1462 do not have an ISO standard meaning.
1464 GCC normally generates special code to handle certain built-in functions
1465 more efficiently; for instance, calls to @code{alloca} may become single
1466 instructions that adjust the stack directly, and calls to @code{memcpy}
1467 may become inline copy loops. The resulting code is often both smaller
1468 and faster, but since the function calls no longer appear as such, you
1469 cannot set a breakpoint on those calls, nor can you change the behavior
1470 of the functions by linking with a different library. In addition,
1471 when a function is recognized as a built-in function, GCC may use
1472 information about that function to warn about problems with calls to
1473 that function, or to generate more efficient code, even if the
1474 resulting code still contains calls to that function. For example,
1475 warnings are given with @option{-Wformat} for bad calls to
1476 @code{printf}, when @code{printf} is built in, and @code{strlen} is
1477 known not to modify global memory.
1479 With the @option{-fno-builtin-@var{function}} option
1480 only the built-in function @var{function} is
1481 disabled. @var{function} must not begin with @samp{__builtin_}. If a
1482 function is named this is not built-in in this version of GCC, this
1483 option is ignored. There is no corresponding
1484 @option{-fbuiltin-@var{function}} option; if you wish to enable
1485 built-in functions selectively when using @option{-fno-builtin} or
1486 @option{-ffreestanding}, you may define macros such as:
1489 #define abs(n) __builtin_abs ((n))
1490 #define strcpy(d, s) __builtin_strcpy ((d), (s))
1495 @cindex hosted environment
1497 Assert that compilation takes place in a hosted environment. This implies
1498 @option{-fbuiltin}. A hosted environment is one in which the
1499 entire standard library is available, and in which @code{main} has a return
1500 type of @code{int}. Examples are nearly everything except a kernel.
1501 This is equivalent to @option{-fno-freestanding}.
1503 @item -ffreestanding
1504 @opindex ffreestanding
1505 @cindex hosted environment
1507 Assert that compilation takes place in a freestanding environment. This
1508 implies @option{-fno-builtin}. A freestanding environment
1509 is one in which the standard library may not exist, and program startup may
1510 not necessarily be at @code{main}. The most obvious example is an OS kernel.
1511 This is equivalent to @option{-fno-hosted}.
1513 @xref{Standards,,Language Standards Supported by GCC}, for details of
1514 freestanding and hosted environments.
1518 @cindex openmp parallel
1519 Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1520 @code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1521 compiler generates parallel code according to the OpenMP Application
1522 Program Interface v2.5 @w{@uref{http://www.openmp.org/}}. This option
1523 implies @option{-pthread}, and thus is only supported on targets that
1524 have support for @option{-pthread}.
1526 @item -fms-extensions
1527 @opindex fms-extensions
1528 Accept some non-standard constructs used in Microsoft header files.
1530 Some cases of unnamed fields in structures and unions are only
1531 accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1532 fields within structs/unions}, for details.
1536 Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1537 options for strict ISO C conformance) implies @option{-trigraphs}.
1539 @item -no-integrated-cpp
1540 @opindex no-integrated-cpp
1541 Performs a compilation in two passes: preprocessing and compiling. This
1542 option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1543 @option{-B} option. The user supplied compilation step can then add in
1544 an additional preprocessing step after normal preprocessing but before
1545 compiling. The default is to use the integrated cpp (internal cpp)
1547 The semantics of this option will change if "cc1", "cc1plus", and
1548 "cc1obj" are merged.
1550 @cindex traditional C language
1551 @cindex C language, traditional
1553 @itemx -traditional-cpp
1554 @opindex traditional-cpp
1555 @opindex traditional
1556 Formerly, these options caused GCC to attempt to emulate a pre-standard
1557 C compiler. They are now only supported with the @option{-E} switch.
1558 The preprocessor continues to support a pre-standard mode. See the GNU
1559 CPP manual for details.
1561 @item -fcond-mismatch
1562 @opindex fcond-mismatch
1563 Allow conditional expressions with mismatched types in the second and
1564 third arguments. The value of such an expression is void. This option
1565 is not supported for C++.
1567 @item -flax-vector-conversions
1568 @opindex flax-vector-conversions
1569 Allow implicit conversions between vectors with differing numbers of
1570 elements and/or incompatible element types. This option should not be
1573 @item -funsigned-char
1574 @opindex funsigned-char
1575 Let the type @code{char} be unsigned, like @code{unsigned char}.
1577 Each kind of machine has a default for what @code{char} should
1578 be. It is either like @code{unsigned char} by default or like
1579 @code{signed char} by default.
1581 Ideally, a portable program should always use @code{signed char} or
1582 @code{unsigned char} when it depends on the signedness of an object.
1583 But many programs have been written to use plain @code{char} and
1584 expect it to be signed, or expect it to be unsigned, depending on the
1585 machines they were written for. This option, and its inverse, let you
1586 make such a program work with the opposite default.
1588 The type @code{char} is always a distinct type from each of
1589 @code{signed char} or @code{unsigned char}, even though its behavior
1590 is always just like one of those two.
1593 @opindex fsigned-char
1594 Let the type @code{char} be signed, like @code{signed char}.
1596 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1597 the negative form of @option{-funsigned-char}. Likewise, the option
1598 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1600 @item -fsigned-bitfields
1601 @itemx -funsigned-bitfields
1602 @itemx -fno-signed-bitfields
1603 @itemx -fno-unsigned-bitfields
1604 @opindex fsigned-bitfields
1605 @opindex funsigned-bitfields
1606 @opindex fno-signed-bitfields
1607 @opindex fno-unsigned-bitfields
1608 These options control whether a bit-field is signed or unsigned, when the
1609 declaration does not use either @code{signed} or @code{unsigned}. By
1610 default, such a bit-field is signed, because this is consistent: the
1611 basic integer types such as @code{int} are signed types.
1614 @node C++ Dialect Options
1615 @section Options Controlling C++ Dialect
1617 @cindex compiler options, C++
1618 @cindex C++ options, command line
1619 @cindex options, C++
1620 This section describes the command-line options that are only meaningful
1621 for C++ programs; but you can also use most of the GNU compiler options
1622 regardless of what language your program is in. For example, you
1623 might compile a file @code{firstClass.C} like this:
1626 g++ -g -frepo -O -c firstClass.C
1630 In this example, only @option{-frepo} is an option meant
1631 only for C++ programs; you can use the other options with any
1632 language supported by GCC@.
1634 Here is a list of options that are @emph{only} for compiling C++ programs:
1638 @item -fabi-version=@var{n}
1639 @opindex fabi-version
1640 Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1641 C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1642 the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1643 the version that conforms most closely to the C++ ABI specification.
1644 Therefore, the ABI obtained using version 0 will change as ABI bugs
1647 The default is version 2.
1649 @item -fno-access-control
1650 @opindex fno-access-control
1651 Turn off all access checking. This switch is mainly useful for working
1652 around bugs in the access control code.
1656 Check that the pointer returned by @code{operator new} is non-null
1657 before attempting to modify the storage allocated. This check is
1658 normally unnecessary because the C++ standard specifies that
1659 @code{operator new} will only return @code{0} if it is declared
1660 @samp{throw()}, in which case the compiler will always check the
1661 return value even without this option. In all other cases, when
1662 @code{operator new} has a non-empty exception specification, memory
1663 exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1664 @samp{new (nothrow)}.
1666 @item -fconserve-space
1667 @opindex fconserve-space
1668 Put uninitialized or runtime-initialized global variables into the
1669 common segment, as C does. This saves space in the executable at the
1670 cost of not diagnosing duplicate definitions. If you compile with this
1671 flag and your program mysteriously crashes after @code{main()} has
1672 completed, you may have an object that is being destroyed twice because
1673 two definitions were merged.
1675 This option is no longer useful on most targets, now that support has
1676 been added for putting variables into BSS without making them common.
1678 @item -ffriend-injection
1679 @opindex ffriend-injection
1680 Inject friend functions into the enclosing namespace, so that they are
1681 visible outside the scope of the class in which they are declared.
1682 Friend functions were documented to work this way in the old Annotated
1683 C++ Reference Manual, and versions of G++ before 4.1 always worked
1684 that way. However, in ISO C++ a friend function which is not declared
1685 in an enclosing scope can only be found using argument dependent
1686 lookup. This option causes friends to be injected as they were in
1689 This option is for compatibility, and may be removed in a future
1692 @item -fno-elide-constructors
1693 @opindex fno-elide-constructors
1694 The C++ standard allows an implementation to omit creating a temporary
1695 which is only used to initialize another object of the same type.
1696 Specifying this option disables that optimization, and forces G++ to
1697 call the copy constructor in all cases.
1699 @item -fno-enforce-eh-specs
1700 @opindex fno-enforce-eh-specs
1701 Don't generate code to check for violation of exception specifications
1702 at runtime. This option violates the C++ standard, but may be useful
1703 for reducing code size in production builds, much like defining
1704 @samp{NDEBUG}. This does not give user code permission to throw
1705 exceptions in violation of the exception specifications; the compiler
1706 will still optimize based on the specifications, so throwing an
1707 unexpected exception will result in undefined behavior.
1710 @itemx -fno-for-scope
1712 @opindex fno-for-scope
1713 If @option{-ffor-scope} is specified, the scope of variables declared in
1714 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1715 as specified by the C++ standard.
1716 If @option{-fno-for-scope} is specified, the scope of variables declared in
1717 a @i{for-init-statement} extends to the end of the enclosing scope,
1718 as was the case in old versions of G++, and other (traditional)
1719 implementations of C++.
1721 The default if neither flag is given to follow the standard,
1722 but to allow and give a warning for old-style code that would
1723 otherwise be invalid, or have different behavior.
1725 @item -fno-gnu-keywords
1726 @opindex fno-gnu-keywords
1727 Do not recognize @code{typeof} as a keyword, so that code can use this
1728 word as an identifier. You can use the keyword @code{__typeof__} instead.
1729 @option{-ansi} implies @option{-fno-gnu-keywords}.
1731 @item -fno-implicit-templates
1732 @opindex fno-implicit-templates
1733 Never emit code for non-inline templates which are instantiated
1734 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1735 @xref{Template Instantiation}, for more information.
1737 @item -fno-implicit-inline-templates
1738 @opindex fno-implicit-inline-templates
1739 Don't emit code for implicit instantiations of inline templates, either.
1740 The default is to handle inlines differently so that compiles with and
1741 without optimization will need the same set of explicit instantiations.
1743 @item -fno-implement-inlines
1744 @opindex fno-implement-inlines
1745 To save space, do not emit out-of-line copies of inline functions
1746 controlled by @samp{#pragma implementation}. This will cause linker
1747 errors if these functions are not inlined everywhere they are called.
1749 @item -fms-extensions
1750 @opindex fms-extensions
1751 Disable pedantic warnings about constructs used in MFC, such as implicit
1752 int and getting a pointer to member function via non-standard syntax.
1754 @item -fno-nonansi-builtins
1755 @opindex fno-nonansi-builtins
1756 Disable built-in declarations of functions that are not mandated by
1757 ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1758 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1760 @item -fno-operator-names
1761 @opindex fno-operator-names
1762 Do not treat the operator name keywords @code{and}, @code{bitand},
1763 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1764 synonyms as keywords.
1766 @item -fno-optional-diags
1767 @opindex fno-optional-diags
1768 Disable diagnostics that the standard says a compiler does not need to
1769 issue. Currently, the only such diagnostic issued by G++ is the one for
1770 a name having multiple meanings within a class.
1773 @opindex fpermissive
1774 Downgrade some diagnostics about nonconformant code from errors to
1775 warnings. Thus, using @option{-fpermissive} will allow some
1776 nonconforming code to compile.
1780 Enable automatic template instantiation at link time. This option also
1781 implies @option{-fno-implicit-templates}. @xref{Template
1782 Instantiation}, for more information.
1786 Disable generation of information about every class with virtual
1787 functions for use by the C++ runtime type identification features
1788 (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1789 of the language, you can save some space by using this flag. Note that
1790 exception handling uses the same information, but it will generate it as
1791 needed. The @samp{dynamic_cast} operator can still be used for casts that
1792 do not require runtime type information, i.e. casts to @code{void *} or to
1793 unambiguous base classes.
1797 Emit statistics about front-end processing at the end of the compilation.
1798 This information is generally only useful to the G++ development team.
1800 @item -ftemplate-depth-@var{n}
1801 @opindex ftemplate-depth
1802 Set the maximum instantiation depth for template classes to @var{n}.
1803 A limit on the template instantiation depth is needed to detect
1804 endless recursions during template class instantiation. ANSI/ISO C++
1805 conforming programs must not rely on a maximum depth greater than 17.
1807 @item -fno-threadsafe-statics
1808 @opindex fno-threadsafe-statics
1809 Do not emit the extra code to use the routines specified in the C++
1810 ABI for thread-safe initialization of local statics. You can use this
1811 option to reduce code size slightly in code that doesn't need to be
1814 @item -fuse-cxa-atexit
1815 @opindex fuse-cxa-atexit
1816 Register destructors for objects with static storage duration with the
1817 @code{__cxa_atexit} function rather than the @code{atexit} function.
1818 This option is required for fully standards-compliant handling of static
1819 destructors, but will only work if your C library supports
1820 @code{__cxa_atexit}.
1822 @item -fno-use-cxa-get-exception-ptr
1823 @opindex fno-use-cxa-get-exception-ptr
1824 Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1825 will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1826 if the runtime routine is not available.
1828 @item -fvisibility-inlines-hidden
1829 @opindex fvisibility-inlines-hidden
1830 This switch declares that the user does not attempt to compare
1831 pointers to inline methods where the addresses of the two functions
1832 were taken in different shared objects.
1834 The effect of this is that GCC may, effectively, mark inline methods with
1835 @code{__attribute__ ((visibility ("hidden")))} so that they do not
1836 appear in the export table of a DSO and do not require a PLT indirection
1837 when used within the DSO@. Enabling this option can have a dramatic effect
1838 on load and link times of a DSO as it massively reduces the size of the
1839 dynamic export table when the library makes heavy use of templates.
1841 The behavior of this switch is not quite the same as marking the
1842 methods as hidden directly, because it does not affect static variables
1843 local to the function or cause the compiler to deduce that
1844 the function is defined in only one shared object.
1846 You may mark a method as having a visibility explicitly to negate the
1847 effect of the switch for that method. For example, if you do want to
1848 compare pointers to a particular inline method, you might mark it as
1849 having default visibility. Marking the enclosing class with explicit
1850 visibility will have no effect.
1852 Explicitly instantiated inline methods are unaffected by this option
1853 as their linkage might otherwise cross a shared library boundary.
1854 @xref{Template Instantiation}.
1856 @item -fvisibility-ms-compat
1857 @opindex fvisibility-ms-compat
1858 This flag attempts to use visibility settings to make GCC's C++
1859 linkage model compatible with that of Microsoft Visual Studio.
1861 The flag makes these changes to GCC's linkage model:
1865 It sets the default visibility to @code{hidden}, like
1866 @option{-fvisibility=hidden}.
1869 Types, but not their members, are not hidden by default.
1872 The One Definition Rule is relaxed for types without explicit
1873 visibility specifications which are defined in more than one different
1874 shared object: those declarations are permitted if they would have
1875 been permitted when this option was not used.
1878 In new code it is better to use @option{-fvisibility=hidden} and
1879 export those classes which are intended to be externally visible.
1880 Unfortunately it is possible for code to rely, perhaps accidentally,
1881 on the Visual Studio behavior.
1883 Among the consequences of these changes are that static data members
1884 of the same type with the same name but defined in different shared
1885 objects will be different, so changing one will not change the other;
1886 and that pointers to function members defined in different shared
1887 objects may not compare equal. When this flag is given, it is a
1888 violation of the ODR to define types with the same name differently.
1892 Do not use weak symbol support, even if it is provided by the linker.
1893 By default, G++ will use weak symbols if they are available. This
1894 option exists only for testing, and should not be used by end-users;
1895 it will result in inferior code and has no benefits. This option may
1896 be removed in a future release of G++.
1900 Do not search for header files in the standard directories specific to
1901 C++, but do still search the other standard directories. (This option
1902 is used when building the C++ library.)
1905 In addition, these optimization, warning, and code generation options
1906 have meanings only for C++ programs:
1909 @item -fno-default-inline
1910 @opindex fno-default-inline
1911 Do not assume @samp{inline} for functions defined inside a class scope.
1912 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1913 functions will have linkage like inline functions; they just won't be
1916 @item -Wabi @r{(C++ only)}
1918 Warn when G++ generates code that is probably not compatible with the
1919 vendor-neutral C++ ABI@. Although an effort has been made to warn about
1920 all such cases, there are probably some cases that are not warned about,
1921 even though G++ is generating incompatible code. There may also be
1922 cases where warnings are emitted even though the code that is generated
1925 You should rewrite your code to avoid these warnings if you are
1926 concerned about the fact that code generated by G++ may not be binary
1927 compatible with code generated by other compilers.
1929 The known incompatibilities at this point include:
1934 Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1935 pack data into the same byte as a base class. For example:
1938 struct A @{ virtual void f(); int f1 : 1; @};
1939 struct B : public A @{ int f2 : 1; @};
1943 In this case, G++ will place @code{B::f2} into the same byte
1944 as@code{A::f1}; other compilers will not. You can avoid this problem
1945 by explicitly padding @code{A} so that its size is a multiple of the
1946 byte size on your platform; that will cause G++ and other compilers to
1947 layout @code{B} identically.
1950 Incorrect handling of tail-padding for virtual bases. G++ does not use
1951 tail padding when laying out virtual bases. For example:
1954 struct A @{ virtual void f(); char c1; @};
1955 struct B @{ B(); char c2; @};
1956 struct C : public A, public virtual B @{@};
1960 In this case, G++ will not place @code{B} into the tail-padding for
1961 @code{A}; other compilers will. You can avoid this problem by
1962 explicitly padding @code{A} so that its size is a multiple of its
1963 alignment (ignoring virtual base classes); that will cause G++ and other
1964 compilers to layout @code{C} identically.
1967 Incorrect handling of bit-fields with declared widths greater than that
1968 of their underlying types, when the bit-fields appear in a union. For
1972 union U @{ int i : 4096; @};
1976 Assuming that an @code{int} does not have 4096 bits, G++ will make the
1977 union too small by the number of bits in an @code{int}.
1980 Empty classes can be placed at incorrect offsets. For example:
1990 struct C : public B, public A @{@};
1994 G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1995 it should be placed at offset zero. G++ mistakenly believes that the
1996 @code{A} data member of @code{B} is already at offset zero.
1999 Names of template functions whose types involve @code{typename} or
2000 template template parameters can be mangled incorrectly.
2003 template <typename Q>
2004 void f(typename Q::X) @{@}
2006 template <template <typename> class Q>
2007 void f(typename Q<int>::X) @{@}
2011 Instantiations of these templates may be mangled incorrectly.
2015 @item -Wctor-dtor-privacy @r{(C++ only)}
2016 @opindex Wctor-dtor-privacy
2017 Warn when a class seems unusable because all the constructors or
2018 destructors in that class are private, and it has neither friends nor
2019 public static member functions.
2021 @item -Wnon-virtual-dtor @r{(C++ only)}
2022 @opindex Wnon-virtual-dtor
2023 Warn when a class has virtual functions and accessible non-virtual
2024 destructor, in which case it would be possible but unsafe to delete
2025 an instance of a derived class through a pointer to the base class.
2026 This warning is also enabled if -Weffc++ is specified.
2028 @item -Wreorder @r{(C++ only)}
2030 @cindex reordering, warning
2031 @cindex warning for reordering of member initializers
2032 Warn when the order of member initializers given in the code does not
2033 match the order in which they must be executed. For instance:
2039 A(): j (0), i (1) @{ @}
2043 The compiler will rearrange the member initializers for @samp{i}
2044 and @samp{j} to match the declaration order of the members, emitting
2045 a warning to that effect. This warning is enabled by @option{-Wall}.
2048 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
2051 @item -Weffc++ @r{(C++ only)}
2053 Warn about violations of the following style guidelines from Scott Meyers'
2054 @cite{Effective C++} book:
2058 Item 11: Define a copy constructor and an assignment operator for classes
2059 with dynamically allocated memory.
2062 Item 12: Prefer initialization to assignment in constructors.
2065 Item 14: Make destructors virtual in base classes.
2068 Item 15: Have @code{operator=} return a reference to @code{*this}.
2071 Item 23: Don't try to return a reference when you must return an object.
2075 Also warn about violations of the following style guidelines from
2076 Scott Meyers' @cite{More Effective C++} book:
2080 Item 6: Distinguish between prefix and postfix forms of increment and
2081 decrement operators.
2084 Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
2088 When selecting this option, be aware that the standard library
2089 headers do not obey all of these guidelines; use @samp{grep -v}
2090 to filter out those warnings.
2092 @item -Wno-deprecated @r{(C++ only)}
2093 @opindex Wno-deprecated
2094 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
2096 @item -Wstrict-null-sentinel @r{(C++ only)}
2097 @opindex Wstrict-null-sentinel
2098 Warn also about the use of an uncasted @code{NULL} as sentinel. When
2099 compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
2100 to @code{__null}. Although it is a null pointer constant not a null pointer,
2101 it is guaranteed to of the same size as a pointer. But this use is
2102 not portable across different compilers.
2104 @item -Wno-non-template-friend @r{(C++ only)}
2105 @opindex Wno-non-template-friend
2106 Disable warnings when non-templatized friend functions are declared
2107 within a template. Since the advent of explicit template specification
2108 support in G++, if the name of the friend is an unqualified-id (i.e.,
2109 @samp{friend foo(int)}), the C++ language specification demands that the
2110 friend declare or define an ordinary, nontemplate function. (Section
2111 14.5.3). Before G++ implemented explicit specification, unqualified-ids
2112 could be interpreted as a particular specialization of a templatized
2113 function. Because this non-conforming behavior is no longer the default
2114 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
2115 check existing code for potential trouble spots and is on by default.
2116 This new compiler behavior can be turned off with
2117 @option{-Wno-non-template-friend} which keeps the conformant compiler code
2118 but disables the helpful warning.
2120 @item -Wold-style-cast @r{(C++ only)}
2121 @opindex Wold-style-cast
2122 Warn if an old-style (C-style) cast to a non-void type is used within
2123 a C++ program. The new-style casts (@samp{dynamic_cast},
2124 @samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
2125 less vulnerable to unintended effects and much easier to search for.
2127 @item -Woverloaded-virtual @r{(C++ only)}
2128 @opindex Woverloaded-virtual
2129 @cindex overloaded virtual fn, warning
2130 @cindex warning for overloaded virtual fn
2131 Warn when a function declaration hides virtual functions from a
2132 base class. For example, in:
2139 struct B: public A @{
2144 the @code{A} class version of @code{f} is hidden in @code{B}, and code
2152 will fail to compile.
2154 @item -Wno-pmf-conversions @r{(C++ only)}
2155 @opindex Wno-pmf-conversions
2156 Disable the diagnostic for converting a bound pointer to member function
2159 @item -Wsign-promo @r{(C++ only)}
2160 @opindex Wsign-promo
2161 Warn when overload resolution chooses a promotion from unsigned or
2162 enumerated type to a signed type, over a conversion to an unsigned type of
2163 the same size. Previous versions of G++ would try to preserve
2164 unsignedness, but the standard mandates the current behavior.
2169 A& operator = (int);
2179 In this example, G++ will synthesize a default @samp{A& operator =
2180 (const A&);}, while cfront will use the user-defined @samp{operator =}.
2183 @node Objective-C and Objective-C++ Dialect Options
2184 @section Options Controlling Objective-C and Objective-C++ Dialects
2186 @cindex compiler options, Objective-C and Objective-C++
2187 @cindex Objective-C and Objective-C++ options, command line
2188 @cindex options, Objective-C and Objective-C++
2189 (NOTE: This manual does not describe the Objective-C and Objective-C++
2190 languages themselves. See @xref{Standards,,Language Standards
2191 Supported by GCC}, for references.)
2193 This section describes the command-line options that are only meaningful
2194 for Objective-C and Objective-C++ programs, but you can also use most of
2195 the language-independent GNU compiler options.
2196 For example, you might compile a file @code{some_class.m} like this:
2199 gcc -g -fgnu-runtime -O -c some_class.m
2203 In this example, @option{-fgnu-runtime} is an option meant only for
2204 Objective-C and Objective-C++ programs; you can use the other options with
2205 any language supported by GCC@.
2207 Note that since Objective-C is an extension of the C language, Objective-C
2208 compilations may also use options specific to the C front-end (e.g.,
2209 @option{-Wtraditional}). Similarly, Objective-C++ compilations may use
2210 C++-specific options (e.g., @option{-Wabi}).
2212 Here is a list of options that are @emph{only} for compiling Objective-C
2213 and Objective-C++ programs:
2216 @item -fconstant-string-class=@var{class-name}
2217 @opindex fconstant-string-class
2218 Use @var{class-name} as the name of the class to instantiate for each
2219 literal string specified with the syntax @code{@@"@dots{}"}. The default
2220 class name is @code{NXConstantString} if the GNU runtime is being used, and
2221 @code{NSConstantString} if the NeXT runtime is being used (see below). The
2222 @option{-fconstant-cfstrings} option, if also present, will override the
2223 @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
2224 to be laid out as constant CoreFoundation strings.
2227 @opindex fgnu-runtime
2228 Generate object code compatible with the standard GNU Objective-C
2229 runtime. This is the default for most types of systems.
2231 @item -fnext-runtime
2232 @opindex fnext-runtime
2233 Generate output compatible with the NeXT runtime. This is the default
2234 for NeXT-based systems, including Darwin and Mac OS X@. The macro
2235 @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
2238 @item -fno-nil-receivers
2239 @opindex fno-nil-receivers
2240 Assume that all Objective-C message dispatches (e.g.,
2241 @code{[receiver message:arg]}) in this translation unit ensure that the receiver
2242 is not @code{nil}. This allows for more efficient entry points in the runtime
2243 to be used. Currently, this option is only available in conjunction with
2244 the NeXT runtime on Mac OS X 10.3 and later.
2246 @item -fobjc-call-cxx-cdtors
2247 @opindex fobjc-call-cxx-cdtors
2248 For each Objective-C class, check if any of its instance variables is a
2249 C++ object with a non-trivial default constructor. If so, synthesize a
2250 special @code{- (id) .cxx_construct} instance method that will run
2251 non-trivial default constructors on any such instance variables, in order,
2252 and then return @code{self}. Similarly, check if any instance variable
2253 is a C++ object with a non-trivial destructor, and if so, synthesize a
2254 special @code{- (void) .cxx_destruct} method that will run
2255 all such default destructors, in reverse order.
2257 The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
2258 thusly generated will only operate on instance variables declared in the
2259 current Objective-C class, and not those inherited from superclasses. It
2260 is the responsibility of the Objective-C runtime to invoke all such methods
2261 in an object's inheritance hierarchy. The @code{- (id) .cxx_construct} methods
2262 will be invoked by the runtime immediately after a new object
2263 instance is allocated; the @code{- (void) .cxx_destruct} methods will
2264 be invoked immediately before the runtime deallocates an object instance.
2266 As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
2267 support for invoking the @code{- (id) .cxx_construct} and
2268 @code{- (void) .cxx_destruct} methods.
2270 @item -fobjc-direct-dispatch
2271 @opindex fobjc-direct-dispatch
2272 Allow fast jumps to the message dispatcher. On Darwin this is
2273 accomplished via the comm page.
2275 @item -fobjc-exceptions
2276 @opindex fobjc-exceptions
2277 Enable syntactic support for structured exception handling in Objective-C,
2278 similar to what is offered by C++ and Java. This option is
2279 unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2288 @@catch (AnObjCClass *exc) @{
2295 @@catch (AnotherClass *exc) @{
2298 @@catch (id allOthers) @{
2308 The @code{@@throw} statement may appear anywhere in an Objective-C or
2309 Objective-C++ program; when used inside of a @code{@@catch} block, the
2310 @code{@@throw} may appear without an argument (as shown above), in which case
2311 the object caught by the @code{@@catch} will be rethrown.
2313 Note that only (pointers to) Objective-C objects may be thrown and
2314 caught using this scheme. When an object is thrown, it will be caught
2315 by the nearest @code{@@catch} clause capable of handling objects of that type,
2316 analogously to how @code{catch} blocks work in C++ and Java. A
2317 @code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2318 any and all Objective-C exceptions not caught by previous @code{@@catch}
2321 The @code{@@finally} clause, if present, will be executed upon exit from the
2322 immediately preceding @code{@@try @dots{} @@catch} section. This will happen
2323 regardless of whether any exceptions are thrown, caught or rethrown
2324 inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2325 of the @code{finally} clause in Java.
2327 There are several caveats to using the new exception mechanism:
2331 Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2332 idioms provided by the @code{NSException} class, the new
2333 exceptions can only be used on Mac OS X 10.3 (Panther) and later
2334 systems, due to additional functionality needed in the (NeXT) Objective-C
2338 As mentioned above, the new exceptions do not support handling
2339 types other than Objective-C objects. Furthermore, when used from
2340 Objective-C++, the Objective-C exception model does not interoperate with C++
2341 exceptions at this time. This means you cannot @code{@@throw} an exception
2342 from Objective-C and @code{catch} it in C++, or vice versa
2343 (i.e., @code{throw @dots{} @@catch}).
2346 The @option{-fobjc-exceptions} switch also enables the use of synchronization
2347 blocks for thread-safe execution:
2350 @@synchronized (ObjCClass *guard) @{
2355 Upon entering the @code{@@synchronized} block, a thread of execution shall
2356 first check whether a lock has been placed on the corresponding @code{guard}
2357 object by another thread. If it has, the current thread shall wait until
2358 the other thread relinquishes its lock. Once @code{guard} becomes available,
2359 the current thread will place its own lock on it, execute the code contained in
2360 the @code{@@synchronized} block, and finally relinquish the lock (thereby
2361 making @code{guard} available to other threads).
2363 Unlike Java, Objective-C does not allow for entire methods to be marked
2364 @code{@@synchronized}. Note that throwing exceptions out of
2365 @code{@@synchronized} blocks is allowed, and will cause the guarding object
2366 to be unlocked properly.
2370 Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2372 @item -freplace-objc-classes
2373 @opindex freplace-objc-classes
2374 Emit a special marker instructing @command{ld(1)} not to statically link in
2375 the resulting object file, and allow @command{dyld(1)} to load it in at
2376 run time instead. This is used in conjunction with the Fix-and-Continue
2377 debugging mode, where the object file in question may be recompiled and
2378 dynamically reloaded in the course of program execution, without the need
2379 to restart the program itself. Currently, Fix-and-Continue functionality
2380 is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2385 When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2386 to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2387 compile time) with static class references that get initialized at load time,
2388 which improves run-time performance. Specifying the @option{-fzero-link} flag
2389 suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2390 to be retained. This is useful in Zero-Link debugging mode, since it allows
2391 for individual class implementations to be modified during program execution.
2395 Dump interface declarations for all classes seen in the source file to a
2396 file named @file{@var{sourcename}.decl}.
2398 @item -Wassign-intercept
2399 @opindex Wassign-intercept
2400 Warn whenever an Objective-C assignment is being intercepted by the
2404 @opindex Wno-protocol
2405 If a class is declared to implement a protocol, a warning is issued for
2406 every method in the protocol that is not implemented by the class. The
2407 default behavior is to issue a warning for every method not explicitly
2408 implemented in the class, even if a method implementation is inherited
2409 from the superclass. If you use the @option{-Wno-protocol} option, then
2410 methods inherited from the superclass are considered to be implemented,
2411 and no warning is issued for them.
2415 Warn if multiple methods of different types for the same selector are
2416 found during compilation. The check is performed on the list of methods
2417 in the final stage of compilation. Additionally, a check is performed
2418 for each selector appearing in a @code{@@selector(@dots{})}
2419 expression, and a corresponding method for that selector has been found
2420 during compilation. Because these checks scan the method table only at
2421 the end of compilation, these warnings are not produced if the final
2422 stage of compilation is not reached, for example because an error is
2423 found during compilation, or because the @option{-fsyntax-only} option is
2426 @item -Wstrict-selector-match
2427 @opindex Wstrict-selector-match
2428 Warn if multiple methods with differing argument and/or return types are
2429 found for a given selector when attempting to send a message using this
2430 selector to a receiver of type @code{id} or @code{Class}. When this flag
2431 is off (which is the default behavior), the compiler will omit such warnings
2432 if any differences found are confined to types which share the same size
2435 @item -Wundeclared-selector
2436 @opindex Wundeclared-selector
2437 Warn if a @code{@@selector(@dots{})} expression referring to an
2438 undeclared selector is found. A selector is considered undeclared if no
2439 method with that name has been declared before the
2440 @code{@@selector(@dots{})} expression, either explicitly in an
2441 @code{@@interface} or @code{@@protocol} declaration, or implicitly in
2442 an @code{@@implementation} section. This option always performs its
2443 checks as soon as a @code{@@selector(@dots{})} expression is found,
2444 while @option{-Wselector} only performs its checks in the final stage of
2445 compilation. This also enforces the coding style convention
2446 that methods and selectors must be declared before being used.
2448 @item -print-objc-runtime-info
2449 @opindex print-objc-runtime-info
2450 Generate C header describing the largest structure that is passed by
2455 @node Language Independent Options
2456 @section Options to Control Diagnostic Messages Formatting
2457 @cindex options to control diagnostics formatting
2458 @cindex diagnostic messages
2459 @cindex message formatting
2461 Traditionally, diagnostic messages have been formatted irrespective of
2462 the output device's aspect (e.g.@: its width, @dots{}). The options described
2463 below can be used to control the diagnostic messages formatting
2464 algorithm, e.g.@: how many characters per line, how often source location
2465 information should be reported. Right now, only the C++ front end can
2466 honor these options. However it is expected, in the near future, that
2467 the remaining front ends would be able to digest them correctly.
2470 @item -fmessage-length=@var{n}
2471 @opindex fmessage-length
2472 Try to format error messages so that they fit on lines of about @var{n}
2473 characters. The default is 72 characters for @command{g++} and 0 for the rest of
2474 the front ends supported by GCC@. If @var{n} is zero, then no
2475 line-wrapping will be done; each error message will appear on a single
2478 @opindex fdiagnostics-show-location
2479 @item -fdiagnostics-show-location=once
2480 Only meaningful in line-wrapping mode. Instructs the diagnostic messages
2481 reporter to emit @emph{once} source location information; that is, in
2482 case the message is too long to fit on a single physical line and has to
2483 be wrapped, the source location won't be emitted (as prefix) again,
2484 over and over, in subsequent continuation lines. This is the default
2487 @item -fdiagnostics-show-location=every-line
2488 Only meaningful in line-wrapping mode. Instructs the diagnostic
2489 messages reporter to emit the same source location information (as
2490 prefix) for physical lines that result from the process of breaking
2491 a message which is too long to fit on a single line.
2493 @item -fdiagnostics-show-option
2494 @opindex fdiagnostics-show-option
2495 This option instructs the diagnostic machinery to add text to each
2496 diagnostic emitted, which indicates which command line option directly
2497 controls that diagnostic, when such an option is known to the
2498 diagnostic machinery.
2500 @item -Wcoverage-mismatch
2501 @opindex Wcoverage-mismatch
2502 Warn if feedback profiles do not match when using the
2503 @option{-fprofile-use} option.
2504 If a source file was changed between @option{-fprofile-gen} and
2505 @option{-fprofile-use}, the files with the profile feedback can fail
2506 to match the source file and GCC can not use the profile feedback
2507 information. By default, GCC emits an error message in this case.
2508 The option @option{-Wcoverage-mismatch} emits a warning instead of an
2509 error. GCC does not use appropriate feedback profiles, so using this
2510 option can result in poorly optimized code. This option is useful
2511 only in the case of very minor changes such as bug fixes to an
2516 @node Warning Options
2517 @section Options to Request or Suppress Warnings
2518 @cindex options to control warnings
2519 @cindex warning messages
2520 @cindex messages, warning
2521 @cindex suppressing warnings
2523 Warnings are diagnostic messages that report constructions which
2524 are not inherently erroneous but which are risky or suggest there
2525 may have been an error.
2527 The following language-independent options do not enable specific
2528 warnings but control the kinds of diagnostics produced by GCC.
2531 @cindex syntax checking
2533 @opindex fsyntax-only
2534 Check the code for syntax errors, but don't do anything beyond that.
2538 Inhibit all warning messages.
2542 Make all warnings into errors.
2546 Make the specified warning into an error. The specifier for a warning
2547 is appended, for example @option{-Werror=switch} turns the warnings
2548 controlled by @option{-Wswitch} into errors. This switch takes a
2549 negative form, to be used to negate @option{-Werror} for specific
2550 warnings, for example @option{-Wno-error=switch} makes
2551 @option{-Wswitch} warnings not be errors, even when @option{-Werror}
2552 is in effect. You can use the @option{-fdiagnostics-show-option}
2553 option to have each controllable warning amended with the option which
2554 controls it, to determine what to use with this option.
2556 Note that specifying @option{-Werror=}@var{foo} automatically implies
2557 @option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
2560 @item -Wfatal-errors
2561 @opindex Wfatal-errors
2562 This option causes the compiler to abort compilation on the first error
2563 occurred rather than trying to keep going and printing further error
2568 You can request many specific warnings with options beginning
2569 @samp{-W}, for example @option{-Wimplicit} to request warnings on
2570 implicit declarations. Each of these specific warning options also
2571 has a negative form beginning @samp{-Wno-} to turn off warnings; for
2572 example, @option{-Wno-implicit}. This manual lists only one of the
2573 two forms, whichever is not the default. For further,
2574 language-specific options also refer to @ref{C++ Dialect Options} and
2575 @ref{Objective-C and Objective-C++ Dialect Options}.
2580 Issue all the warnings demanded by strict ISO C and ISO C++;
2581 reject all programs that use forbidden extensions, and some other
2582 programs that do not follow ISO C and ISO C++. For ISO C, follows the
2583 version of the ISO C standard specified by any @option{-std} option used.
2585 Valid ISO C and ISO C++ programs should compile properly with or without
2586 this option (though a rare few will require @option{-ansi} or a
2587 @option{-std} option specifying the required version of ISO C)@. However,
2588 without this option, certain GNU extensions and traditional C and C++
2589 features are supported as well. With this option, they are rejected.
2591 @option{-pedantic} does not cause warning messages for use of the
2592 alternate keywords whose names begin and end with @samp{__}. Pedantic
2593 warnings are also disabled in the expression that follows
2594 @code{__extension__}. However, only system header files should use
2595 these escape routes; application programs should avoid them.
2596 @xref{Alternate Keywords}.
2598 Some users try to use @option{-pedantic} to check programs for strict ISO
2599 C conformance. They soon find that it does not do quite what they want:
2600 it finds some non-ISO practices, but not all---only those for which
2601 ISO C @emph{requires} a diagnostic, and some others for which
2602 diagnostics have been added.
2604 A feature to report any failure to conform to ISO C might be useful in
2605 some instances, but would require considerable additional work and would
2606 be quite different from @option{-pedantic}. We don't have plans to
2607 support such a feature in the near future.
2609 Where the standard specified with @option{-std} represents a GNU
2610 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2611 corresponding @dfn{base standard}, the version of ISO C on which the GNU
2612 extended dialect is based. Warnings from @option{-pedantic} are given
2613 where they are required by the base standard. (It would not make sense
2614 for such warnings to be given only for features not in the specified GNU
2615 C dialect, since by definition the GNU dialects of C include all
2616 features the compiler supports with the given option, and there would be
2617 nothing to warn about.)
2619 @item -pedantic-errors
2620 @opindex pedantic-errors
2621 Like @option{-pedantic}, except that errors are produced rather than
2626 This enables all the warnings about constructions that some users
2627 consider questionable, and that are easy to avoid (or modify to
2628 prevent the warning), even in conjunction with macros. This also
2629 enables some language-specific warnings described in @ref{C++ Dialect
2630 Options} and @ref{Objective-C and Objective-C++ Dialect Options}.
2632 @option{-Wall} turns on the following warning flags:
2634 @gccoptlist{-Waddress @gol
2635 -Warray-bounds @r{(only with} @option{-O2}@r{)} @gol
2637 -Wchar-subscripts @gol
2639 -Wimplicit-function-declaration @gol
2642 -Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)} @gol
2643 -Wmissing-braces @gol
2649 -Wsequence-point @gol
2650 -Wsign-compare @r{(only in C++)} @gol
2651 -Wstrict-aliasing @gol
2652 -Wstrict-overflow=1 @gol
2655 -Wuninitialized @r{(only with} @option{-O1} @r{and above)} @gol
2656 -Wunknown-pragmas @gol
2657 -Wunused-function @gol
2660 -Wunused-variable @gol
2663 Note that some warning flags are not implied by @option{-Wall}. Some of
2664 them warn about constructions that users generally do not consider
2665 questionable, but which occasionally you might wish to check for;
2666 others warn about constructions that are necessary or hard to avoid in
2667 some cases, and there is no simple way to modify the code to suppress
2668 the warning. Some of them are enabled by @option{-Wextra} but many of
2669 them must be enabled individually.
2674 This enables some extra warning flags that are not enabled by
2675 @option{-Wall}. (This option used to be called @option{-W}. The older
2676 name is still supported, but the newer name is more descriptive.)
2678 @gccoptlist{-Wclobbered @gol
2680 -Wignored-qualifiers @gol
2681 -Wmissing-field-initializers @gol
2682 -Wmissing-parameter-type @r{(C only)} @gol
2683 -Wold-style-declaration @r{(C only)} @gol
2684 -Woverride-init @gol
2687 -Wuninitialized @r{(only with} @option{-O1} @r{and above)} @gol
2688 -Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
2691 The option @option{-Wextra} also prints warning messages for the
2697 A pointer is compared against integer zero with @samp{<}, @samp{<=},
2698 @samp{>}, or @samp{>=}.
2701 (C++ only) An enumerator and a non-enumerator both appear in a
2702 conditional expression.
2705 (C++ only) A non-static reference or non-static @samp{const} member
2706 appears in a class without constructors.
2709 (C++ only) Ambiguous virtual bases.
2712 (C++ only) Subscripting an array which has been declared @samp{register}.
2715 (C++ only) Taking the address of a variable which has been declared
2719 (C++ only) A base class is not initialized in a derived class' copy
2726 Inhibit warning messages about the use of @samp{#import}.
2728 @item -Wchar-subscripts
2729 @opindex Wchar-subscripts
2730 Warn if an array subscript has type @code{char}. This is a common cause
2731 of error, as programmers often forget that this type is signed on some
2733 This warning is enabled by @option{-Wall}.
2737 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2738 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2739 This warning is enabled by @option{-Wall}.
2743 @opindex ffreestanding
2744 @opindex fno-builtin
2745 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2746 the arguments supplied have types appropriate to the format string
2747 specified, and that the conversions specified in the format string make
2748 sense. This includes standard functions, and others specified by format
2749 attributes (@pxref{Function Attributes}), in the @code{printf},
2750 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2751 not in the C standard) families (or other target-specific families).
2752 Which functions are checked without format attributes having been
2753 specified depends on the standard version selected, and such checks of
2754 functions without the attribute specified are disabled by
2755 @option{-ffreestanding} or @option{-fno-builtin}.
2757 The formats are checked against the format features supported by GNU
2758 libc version 2.2. These include all ISO C90 and C99 features, as well
2759 as features from the Single Unix Specification and some BSD and GNU
2760 extensions. Other library implementations may not support all these
2761 features; GCC does not support warning about features that go beyond a
2762 particular library's limitations. However, if @option{-pedantic} is used
2763 with @option{-Wformat}, warnings will be given about format features not
2764 in the selected standard version (but not for @code{strfmon} formats,
2765 since those are not in any version of the C standard). @xref{C Dialect
2766 Options,,Options Controlling C Dialect}.
2768 Since @option{-Wformat} also checks for null format arguments for
2769 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2771 @option{-Wformat} is included in @option{-Wall}. For more control over some
2772 aspects of format checking, the options @option{-Wformat-y2k},
2773 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2774 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2775 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
2778 @opindex Wformat-y2k
2779 If @option{-Wformat} is specified, also warn about @code{strftime}
2780 formats which may yield only a two-digit year.
2782 @item -Wno-format-extra-args
2783 @opindex Wno-format-extra-args
2784 If @option{-Wformat} is specified, do not warn about excess arguments to a
2785 @code{printf} or @code{scanf} format function. The C standard specifies
2786 that such arguments are ignored.
2788 Where the unused arguments lie between used arguments that are
2789 specified with @samp{$} operand number specifications, normally
2790 warnings are still given, since the implementation could not know what
2791 type to pass to @code{va_arg} to skip the unused arguments. However,
2792 in the case of @code{scanf} formats, this option will suppress the
2793 warning if the unused arguments are all pointers, since the Single
2794 Unix Specification says that such unused arguments are allowed.
2796 @item -Wno-format-zero-length
2797 @opindex Wno-format-zero-length
2798 If @option{-Wformat} is specified, do not warn about zero-length formats.
2799 The C standard specifies that zero-length formats are allowed.
2801 @item -Wformat-nonliteral
2802 @opindex Wformat-nonliteral
2803 If @option{-Wformat} is specified, also warn if the format string is not a
2804 string literal and so cannot be checked, unless the format function
2805 takes its format arguments as a @code{va_list}.
2807 @item -Wformat-security
2808 @opindex Wformat-security
2809 If @option{-Wformat} is specified, also warn about uses of format
2810 functions that represent possible security problems. At present, this
2811 warns about calls to @code{printf} and @code{scanf} functions where the
2812 format string is not a string literal and there are no format arguments,
2813 as in @code{printf (foo);}. This may be a security hole if the format
2814 string came from untrusted input and contains @samp{%n}. (This is
2815 currently a subset of what @option{-Wformat-nonliteral} warns about, but
2816 in future warnings may be added to @option{-Wformat-security} that are not
2817 included in @option{-Wformat-nonliteral}.)
2821 Enable @option{-Wformat} plus format checks not included in
2822 @option{-Wformat}. Currently equivalent to @samp{-Wformat
2823 -Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2827 Warn about passing a null pointer for arguments marked as
2828 requiring a non-null value by the @code{nonnull} function attribute.
2830 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2831 can be disabled with the @option{-Wno-nonnull} option.
2833 @item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
2835 Warn about uninitialized variables which are initialized with themselves.
2836 Note this option can only be used with the @option{-Wuninitialized} option,
2837 which in turn only works with @option{-O1} and above.
2839 For example, GCC will warn about @code{i} being uninitialized in the
2840 following snippet only when @option{-Winit-self} has been specified:
2851 @item -Wimplicit-int
2852 @opindex Wimplicit-int
2853 Warn when a declaration does not specify a type.
2854 This warning is enabled by @option{-Wall}.
2856 @item -Wimplicit-function-declaration
2857 @opindex Wimplicit-function-declaration
2858 @opindex Wno-implicit-function-declaration
2859 Give a warning whenever a function is used before being declared. In
2860 C99 mode (@option{-std=c99} or @option{-std=gnu99}), this warning is
2861 enabled by default and it is made into an error by
2862 @option{-pedantic-errors}. This warning is also enabled by
2867 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2868 This warning is enabled by @option{-Wall}.
2870 @item -Wignored-qualifiers
2871 @opindex Wignored-qualifiers
2872 @opindex Wno-ignored-qualifiers
2873 Warn if the return type of a function has a type qualifier
2874 such as @code{const}. For ISO C such a type qualifier has no effect,
2875 since the value returned by a function is not an lvalue.
2876 For C++, the warning is only emitted for scalar types or @code{void}.
2877 ISO C prohibits qualified @code{void} return types on function
2878 definitions, so such return types always receive a warning
2879 even without this option.
2881 This warning is also enabled by @option{-Wextra}.
2885 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2886 function with external linkage, returning int, taking either zero
2887 arguments, two, or three arguments of appropriate types.
2888 This warning is enabled by @option{-Wall}.
2890 @item -Wmissing-braces
2891 @opindex Wmissing-braces
2892 Warn if an aggregate or union initializer is not fully bracketed. In
2893 the following example, the initializer for @samp{a} is not fully
2894 bracketed, but that for @samp{b} is fully bracketed.
2897 int a[2][2] = @{ 0, 1, 2, 3 @};
2898 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2901 This warning is enabled by @option{-Wall}.
2903 @item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
2904 @opindex Wmissing-include-dirs
2905 Warn if a user-supplied include directory does not exist.
2908 @opindex Wparentheses
2909 Warn if parentheses are omitted in certain contexts, such
2910 as when there is an assignment in a context where a truth value
2911 is expected, or when operators are nested whose precedence people
2912 often get confused about.
2914 Also warn if a comparison like @samp{x<=y<=z} appears; this is
2915 equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2916 interpretation from that of ordinary mathematical notation.
2918 Also warn about constructions where there may be confusion to which
2919 @code{if} statement an @code{else} branch belongs. Here is an example of
2934 In C/C++, every @code{else} branch belongs to the innermost possible
2935 @code{if} statement, which in this example is @code{if (b)}. This is
2936 often not what the programmer expected, as illustrated in the above
2937 example by indentation the programmer chose. When there is the
2938 potential for this confusion, GCC will issue a warning when this flag
2939 is specified. To eliminate the warning, add explicit braces around
2940 the innermost @code{if} statement so there is no way the @code{else}
2941 could belong to the enclosing @code{if}. The resulting code would
2958 This warning is enabled by @option{-Wall}.
2960 @item -Wsequence-point
2961 @opindex Wsequence-point
2962 Warn about code that may have undefined semantics because of violations
2963 of sequence point rules in the C and C++ standards.
2965 The C and C++ standards defines the order in which expressions in a C/C++
2966 program are evaluated in terms of @dfn{sequence points}, which represent
2967 a partial ordering between the execution of parts of the program: those
2968 executed before the sequence point, and those executed after it. These
2969 occur after the evaluation of a full expression (one which is not part
2970 of a larger expression), after the evaluation of the first operand of a
2971 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2972 function is called (but after the evaluation of its arguments and the
2973 expression denoting the called function), and in certain other places.
2974 Other than as expressed by the sequence point rules, the order of
2975 evaluation of subexpressions of an expression is not specified. All
2976 these rules describe only a partial order rather than a total order,
2977 since, for example, if two functions are called within one expression
2978 with no sequence point between them, the order in which the functions
2979 are called is not specified. However, the standards committee have
2980 ruled that function calls do not overlap.
2982 It is not specified when between sequence points modifications to the
2983 values of objects take effect. Programs whose behavior depends on this
2984 have undefined behavior; the C and C++ standards specify that ``Between
2985 the previous and next sequence point an object shall have its stored
2986 value modified at most once by the evaluation of an expression.
2987 Furthermore, the prior value shall be read only to determine the value
2988 to be stored.''. If a program breaks these rules, the results on any
2989 particular implementation are entirely unpredictable.
2991 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2992 = b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2993 diagnosed by this option, and it may give an occasional false positive
2994 result, but in general it has been found fairly effective at detecting
2995 this sort of problem in programs.
2997 The standard is worded confusingly, therefore there is some debate
2998 over the precise meaning of the sequence point rules in subtle cases.
2999 Links to discussions of the problem, including proposed formal
3000 definitions, may be found on the GCC readings page, at
3001 @w{@uref{http://gcc.gnu.org/readings.html}}.
3003 This warning is enabled by @option{-Wall} for C and C++.
3006 @opindex Wreturn-type
3007 @opindex Wno-return-type
3008 Warn whenever a function is defined with a return-type that defaults
3009 to @code{int}. Also warn about any @code{return} statement with no
3010 return-value in a function whose return-type is not @code{void}
3011 (falling off the end of the function body is considered returning
3012 without a value), and about a @code{return} statement with a
3013 expression in a function whose return-type is @code{void}.
3015 For C++, a function without return type always produces a diagnostic
3016 message, even when @option{-Wno-return-type} is specified. The only
3017 exceptions are @samp{main} and functions defined in system headers.
3019 This warning is enabled by @option{-Wall}.
3023 Warn whenever a @code{switch} statement has an index of enumerated type
3024 and lacks a @code{case} for one or more of the named codes of that
3025 enumeration. (The presence of a @code{default} label prevents this
3026 warning.) @code{case} labels outside the enumeration range also
3027 provoke warnings when this option is used.
3028 This warning is enabled by @option{-Wall}.
3030 @item -Wswitch-default
3031 @opindex Wswitch-switch
3032 Warn whenever a @code{switch} statement does not have a @code{default}
3036 @opindex Wswitch-enum
3037 Warn whenever a @code{switch} statement has an index of enumerated type
3038 and lacks a @code{case} for one or more of the named codes of that
3039 enumeration. @code{case} labels outside the enumeration range also
3040 provoke warnings when this option is used.
3044 Warn if any trigraphs are encountered that might change the meaning of
3045 the program (trigraphs within comments are not warned about).
3046 This warning is enabled by @option{-Wall}.
3048 @item -Wunused-function
3049 @opindex Wunused-function
3050 Warn whenever a static function is declared but not defined or a
3051 non-inline static function is unused.
3052 This warning is enabled by @option{-Wall}.
3054 @item -Wunused-label
3055 @opindex Wunused-label
3056 Warn whenever a label is declared but not used.
3057 This warning is enabled by @option{-Wall}.
3059 To suppress this warning use the @samp{unused} attribute
3060 (@pxref{Variable Attributes}).
3062 @item -Wunused-parameter
3063 @opindex Wunused-parameter
3064 Warn whenever a function parameter is unused aside from its declaration.
3066 To suppress this warning use the @samp{unused} attribute
3067 (@pxref{Variable Attributes}).
3069 @item -Wunused-variable
3070 @opindex Wunused-variable
3071 Warn whenever a local variable or non-constant static variable is unused
3072 aside from its declaration.
3073 This warning is enabled by @option{-Wall}.
3075 To suppress this warning use the @samp{unused} attribute
3076 (@pxref{Variable Attributes}).
3078 @item -Wunused-value
3079 @opindex Wunused-value
3080 Warn whenever a statement computes a result that is explicitly not
3081 used. To suppress this warning cast the unused expression to
3082 @samp{void}. This includes an expression-statement or the left-hand
3083 side of a comma expression that contains no side effects. For example,
3084 an expression such as @samp{x[i,j]} will cause a warning, while
3085 @samp{x[(void)i,j]} will not.
3087 This warning is enabled by @option{-Wall}.
3091 All the above @option{-Wunused} options combined.
3093 In order to get a warning about an unused function parameter, you must
3094 either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
3095 @samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
3097 @item -Wuninitialized
3098 @opindex Wuninitialized
3099 Warn if an automatic variable is used without first being initialized or
3100 if a variable may be clobbered by a @code{setjmp} call.
3102 These warnings are possible only in optimizing compilation,
3103 because they require data flow information that is computed only
3104 when optimizing. If you do not specify @option{-O}, you will not get
3105 these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
3106 requiring @option{-O}.
3108 If you want to warn about code which uses the uninitialized value of the
3109 variable in its own initializer, use the @option{-Winit-self} option.
3111 These warnings occur for individual uninitialized or clobbered
3112 elements of structure, union or array variables as well as for
3113 variables which are uninitialized or clobbered as a whole. They do
3114 not occur for variables or elements declared @code{volatile}. Because
3115 these warnings depend on optimization, the exact variables or elements
3116 for which there are warnings will depend on the precise optimization
3117 options and version of GCC used.
3119 Note that there may be no warning about a variable that is used only
3120 to compute a value that itself is never used, because such
3121 computations may be deleted by data flow analysis before the warnings
3124 These warnings are made optional because GCC is not smart
3125 enough to see all the reasons why the code might be correct
3126 despite appearing to have an error. Here is one example of how
3147 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
3148 always initialized, but GCC doesn't know this. Here is
3149 another common case:
3154 if (change_y) save_y = y, y = new_y;
3156 if (change_y) y = save_y;
3161 This has no bug because @code{save_y} is used only if it is set.
3163 @cindex @code{longjmp} warnings
3164 This option also warns when a non-volatile automatic variable might be
3165 changed by a call to @code{longjmp}. These warnings as well are possible
3166 only in optimizing compilation.
3168 The compiler sees only the calls to @code{setjmp}. It cannot know
3169 where @code{longjmp} will be called; in fact, a signal handler could
3170 call it at any point in the code. As a result, you may get a warning
3171 even when there is in fact no problem because @code{longjmp} cannot
3172 in fact be called at the place which would cause a problem.
3174 Some spurious warnings can be avoided if you declare all the functions
3175 you use that never return as @code{noreturn}. @xref{Function
3178 This warning is enabled by @option{-Wall} or @option{-Wextra} in
3179 optimizing compilations (@option{-O1} and above).
3181 @item -Wunknown-pragmas
3182 @opindex Wunknown-pragmas
3183 @cindex warning for unknown pragmas
3184 @cindex unknown pragmas, warning
3185 @cindex pragmas, warning of unknown
3186 Warn when a #pragma directive is encountered which is not understood by
3187 GCC@. If this command line option is used, warnings will even be issued
3188 for unknown pragmas in system header files. This is not the case if
3189 the warnings were only enabled by the @option{-Wall} command line option.
3192 @opindex Wno-pragmas
3194 Do not warn about misuses of pragmas, such as incorrect parameters,
3195 invalid syntax, or conflicts between pragmas. See also
3196 @samp{-Wunknown-pragmas}.
3198 @item -Wstrict-aliasing
3199 @opindex Wstrict-aliasing
3200 This option is only active when @option{-fstrict-aliasing} is active.
3201 It warns about code which might break the strict aliasing rules that the
3202 compiler is using for optimization. The warning does not catch all
3203 cases, but does attempt to catch the more common pitfalls. It is
3204 included in @option{-Wall}.
3205 It is equivalent to @option{-Wstrict-aliasing=3}
3207 @item -Wstrict-aliasing=n
3208 @opindex Wstrict-aliasing=n
3209 This option is only active when @option{-fstrict-aliasing} is active.
3210 It warns about code which might break the strict aliasing rules that the
3211 compiler is using for optimization.
3212 Higher levels correspond to higher accuracy (fewer false positives).
3213 Higher levels also correspond to more effort, similar to the way -O works.
3214 @option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
3217 Level 1: Most aggressive, quick, least accurate.
3218 Possibly useful when higher levels
3219 do not warn but -fstrict-aliasing still breaks the code, as it has very few
3220 false negatives. However, it has many false positives.
3221 Warns for all pointer conversions between possibly incompatible types,
3222 even if never dereferenced. Runs in the frontend only.
3224 Level 2: Aggressive, quick, not too precise.
3225 May still have many false positives (not as many as level 1 though),
3226 and few false negatives (but possibly more than level 1).
3227 Unlike level 1, it only warns when an address is taken. Warns about
3228 incomplete types. Runs in the frontend only.
3230 Level 3 (default for @option{-Wstrict-aliasing}):
3231 Should have very few false positives and few false
3232 negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
3233 Takes care of the common punn+dereference pattern in the frontend:
3234 @code{*(int*)&some_float}.
3235 If optimization is enabled, it also runs in the backend, where it deals
3236 with multiple statement cases using flow-sensitive points-to information.
3237 Only warns when the converted pointer is dereferenced.
3238 Does not warn about incomplete types.
3240 @item -Wstrict-overflow
3241 @itemx -Wstrict-overflow=@var{n}
3242 @opindex Wstrict-overflow
3243 This option is only active when @option{-fstrict-overflow} is active.
3244 It warns about cases where the compiler optimizes based on the
3245 assumption that signed overflow does not occur. Note that it does not
3246 warn about all cases where the code might overflow: it only warns
3247 about cases where the compiler implements some optimization. Thus
3248 this warning depends on the optimization level.
3250 An optimization which assumes that signed overflow does not occur is
3251 perfectly safe if the values of the variables involved are such that
3252 overflow never does, in fact, occur. Therefore this warning can
3253 easily give a false positive: a warning about code which is not
3254 actually a problem. To help focus on important issues, several
3255 warning levels are defined. No warnings are issued for the use of
3256 undefined signed overflow when estimating how many iterations a loop
3257 will require, in particular when determining whether a loop will be
3261 @item -Wstrict-overflow=1
3262 Warn about cases which are both questionable and easy to avoid. For
3263 example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
3264 compiler will simplify this to @code{1}. This level of
3265 @option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
3266 are not, and must be explicitly requested.
3268 @item -Wstrict-overflow=2
3269 Also warn about other cases where a comparison is simplified to a
3270 constant. For example: @code{abs (x) >= 0}. This can only be
3271 simplified when @option{-fstrict-overflow} is in effect, because
3272 @code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
3273 zero. @option{-Wstrict-overflow} (with no level) is the same as
3274 @option{-Wstrict-overflow=2}.
3276 @item -Wstrict-overflow=3
3277 Also warn about other cases where a comparison is simplified. For
3278 example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
3280 @item -Wstrict-overflow=4
3281 Also warn about other simplifications not covered by the above cases.
3282 For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
3284 @item -Wstrict-overflow=5
3285 Also warn about cases where the compiler reduces the magnitude of a
3286 constant involved in a comparison. For example: @code{x + 2 > y} will
3287 be simplified to @code{x + 1 >= y}. This is reported only at the
3288 highest warning level because this simplification applies to many
3289 comparisons, so this warning level will give a very large number of
3293 @item -Warray-bounds
3294 @opindex Wno-array-bounds
3295 @opindex Warray-bounds
3296 This option is only active when @option{-ftree-vrp} is active
3297 (default for -O2 and above). It warns about subscripts to arrays
3298 that are always out of bounds. This warning is enabled by @option{-Wall}.
3300 @item -Wno-div-by-zero
3301 @opindex Wno-div-by-zero
3302 @opindex Wdiv-by-zero
3303 Do not warn about compile-time integer division by zero. Floating point
3304 division by zero is not warned about, as it can be a legitimate way of
3305 obtaining infinities and NaNs.
3307 @item -Wsystem-headers
3308 @opindex Wsystem-headers
3309 @cindex warnings from system headers
3310 @cindex system headers, warnings from
3311 Print warning messages for constructs found in system header files.
3312 Warnings from system headers are normally suppressed, on the assumption
3313 that they usually do not indicate real problems and would only make the
3314 compiler output harder to read. Using this command line option tells
3315 GCC to emit warnings from system headers as if they occurred in user
3316 code. However, note that using @option{-Wall} in conjunction with this
3317 option will @emph{not} warn about unknown pragmas in system
3318 headers---for that, @option{-Wunknown-pragmas} must also be used.
3321 @opindex Wfloat-equal
3322 Warn if floating point values are used in equality comparisons.
3324 The idea behind this is that sometimes it is convenient (for the
3325 programmer) to consider floating-point values as approximations to
3326 infinitely precise real numbers. If you are doing this, then you need
3327 to compute (by analyzing the code, or in some other way) the maximum or
3328 likely maximum error that the computation introduces, and allow for it
3329 when performing comparisons (and when producing output, but that's a
3330 different problem). In particular, instead of testing for equality, you
3331 would check to see whether the two values have ranges that overlap; and
3332 this is done with the relational operators, so equality comparisons are
3335 @item -Wtraditional @r{(C only)}
3336 @opindex Wtraditional
3337 Warn about certain constructs that behave differently in traditional and
3338 ISO C@. Also warn about ISO C constructs that have no traditional C
3339 equivalent, and/or problematic constructs which should be avoided.
3343 Macro parameters that appear within string literals in the macro body.
3344 In traditional C macro replacement takes place within string literals,
3345 but does not in ISO C@.
3348 In traditional C, some preprocessor directives did not exist.
3349 Traditional preprocessors would only consider a line to be a directive
3350 if the @samp{#} appeared in column 1 on the line. Therefore
3351 @option{-Wtraditional} warns about directives that traditional C
3352 understands but would ignore because the @samp{#} does not appear as the
3353 first character on the line. It also suggests you hide directives like
3354 @samp{#pragma} not understood by traditional C by indenting them. Some
3355 traditional implementations would not recognize @samp{#elif}, so it
3356 suggests avoiding it altogether.
3359 A function-like macro that appears without arguments.
3362 The unary plus operator.
3365 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
3366 constant suffixes. (Traditional C does support the @samp{L} suffix on integer
3367 constants.) Note, these suffixes appear in macros defined in the system
3368 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
3369 Use of these macros in user code might normally lead to spurious
3370 warnings, however GCC's integrated preprocessor has enough context to
3371 avoid warning in these cases.
3374 A function declared external in one block and then used after the end of
3378 A @code{switch} statement has an operand of type @code{long}.
3381 A non-@code{static} function declaration follows a @code{static} one.
3382 This construct is not accepted by some traditional C compilers.
3385 The ISO type of an integer constant has a different width or
3386 signedness from its traditional type. This warning is only issued if
3387 the base of the constant is ten. I.e.@: hexadecimal or octal values, which
3388 typically represent bit patterns, are not warned about.
3391 Usage of ISO string concatenation is detected.
3394 Initialization of automatic aggregates.
3397 Identifier conflicts with labels. Traditional C lacks a separate
3398 namespace for labels.
3401 Initialization of unions. If the initializer is zero, the warning is
3402 omitted. This is done under the assumption that the zero initializer in
3403 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
3404 initializer warnings and relies on default initialization to zero in the
3408 Conversions by prototypes between fixed/floating point values and vice
3409 versa. The absence of these prototypes when compiling with traditional
3410 C would cause serious problems. This is a subset of the possible
3411 conversion warnings, for the full set use @option{-Wtraditional-conversion}.
3414 Use of ISO C style function definitions. This warning intentionally is
3415 @emph{not} issued for prototype declarations or variadic functions
3416 because these ISO C features will appear in your code when using
3417 libiberty's traditional C compatibility macros, @code{PARAMS} and
3418 @code{VPARAMS}. This warning is also bypassed for nested functions
3419 because that feature is already a GCC extension and thus not relevant to
3420 traditional C compatibility.
3423 @item -Wtraditional-conversion @r{(C only)}
3424 @opindex Wtraditional-conversion
3425 Warn if a prototype causes a type conversion that is different from what
3426 would happen to the same argument in the absence of a prototype. This
3427 includes conversions of fixed point to floating and vice versa, and
3428 conversions changing the width or signedness of a fixed point argument
3429 except when the same as the default promotion.
3431 @item -Wdeclaration-after-statement @r{(C only)}
3432 @opindex Wdeclaration-after-statement
3433 Warn when a declaration is found after a statement in a block. This
3434 construct, known from C++, was introduced with ISO C99 and is by default
3435 allowed in GCC@. It is not supported by ISO C90 and was not supported by
3436 GCC versions before GCC 3.0. @xref{Mixed Declarations}.
3440 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3442 @item -Wno-endif-labels
3443 @opindex Wno-endif-labels
3444 @opindex Wendif-labels
3445 Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3449 Warn whenever a local variable shadows another local variable, parameter or
3450 global variable or whenever a built-in function is shadowed.
3452 @item -Wlarger-than-@var{len}
3453 @opindex Wlarger-than
3454 Warn whenever an object of larger than @var{len} bytes is defined.
3456 @item -Wunsafe-loop-optimizations
3457 @opindex Wunsafe-loop-optimizations
3458 Warn if the loop cannot be optimized because the compiler could not
3459 assume anything on the bounds of the loop indices. With
3460 @option{-funsafe-loop-optimizations} warn if the compiler made
3463 @item -Wpointer-arith
3464 @opindex Wpointer-arith
3465 Warn about anything that depends on the ``size of'' a function type or
3466 of @code{void}. GNU C assigns these types a size of 1, for
3467 convenience in calculations with @code{void *} pointers and pointers
3468 to functions. In C++, warn also when an arithmetic operation involves
3469 @code{NULL}. This warning is also enabled by @option{-pedantic}.
3472 @opindex Wtype-limits
3473 @opindex Wno-type-limits
3474 Warn if a comparison is always true or always false due to the limited
3475 range of the data type, but do not warn for constant expressions. For
3476 example, warn if an unsigned variable is compared against zero with
3477 @samp{<} or @samp{>=}. This warning is also enabled by
3480 @item -Wbad-function-cast @r{(C only)}
3481 @opindex Wbad-function-cast
3482 Warn whenever a function call is cast to a non-matching type.
3483 For example, warn if @code{int malloc()} is cast to @code{anything *}.
3486 Warn about ISO C constructs that are outside of the common subset of
3487 ISO C and ISO C++, e.g.@: request for implicit conversion from
3488 @code{void *} to a pointer to non-@code{void} type.
3490 @item -Wc++0x-compat @r{(C++ and Objective-C++ only)}
3491 Warn about C++ constructs whose meaning differs between ISO C++ 1998 and
3492 ISO C++ 200x, e.g., identifiers in ISO C++ 1998 that will become keywords
3493 in ISO C++ 200x. This warning is enabled by @option{-Wall}.
3497 Warn whenever a pointer is cast so as to remove a type qualifier from
3498 the target type. For example, warn if a @code{const char *} is cast
3499 to an ordinary @code{char *}.
3502 @opindex Wcast-align
3503 Warn whenever a pointer is cast such that the required alignment of the
3504 target is increased. For example, warn if a @code{char *} is cast to
3505 an @code{int *} on machines where integers can only be accessed at
3506 two- or four-byte boundaries.
3508 @item -Wwrite-strings
3509 @opindex Wwrite-strings
3510 When compiling C, give string constants the type @code{const
3511 char[@var{length}]} so that
3512 copying the address of one into a non-@code{const} @code{char *}
3513 pointer will get a warning; when compiling C++, warn about the
3514 deprecated conversion from string literals to @code{char *}. This
3515 warning, by default, is enabled for C++ programs.
3516 These warnings will help you find at
3517 compile time code that can try to write into a string constant, but
3518 only if you have been very careful about using @code{const} in
3519 declarations and prototypes. Otherwise, it will just be a nuisance;
3520 this is why we did not make @option{-Wall} request these warnings.
3524 Warn for variables that might be changed by @samp{longjmp} or
3525 @samp{vfork}. This warning is also enabled by @option{-Wextra}.
3528 @opindex Wconversion
3529 @opindex Wno-conversion
3530 Warn for implicit conversions that may alter a value. This includes
3531 conversions between real and integer, like @code{abs (x)} when
3532 @code{x} is @code{double}; conversions between signed and unsigned,
3533 like @code{unsigned ui = -1}; and conversions to smaller types, like
3534 @code{sqrtf (M_PI)}. Do not warn for explicit casts like @code{abs
3535 ((int) x)} and @code{ui = (unsigned) -1}, or if the value is not
3536 changed by the conversion like in @code{abs (2.0)}. Warnings about
3537 conversions between signed and unsigned integers can be disabled by
3538 using @option{-Wno-sign-conversion}.
3540 For C++, also warn for conversions between @code{NULL} and non-pointer
3541 types; confusing overload resolution for user-defined conversions; and
3542 conversions that will never use a type conversion operator:
3543 conversions to @code{void}, the same type, a base class or a reference
3544 to them. Warnings about conversions between signed and unsigned
3545 integers are disabled by default in C++ unless
3546 @option{-Wsign-conversion} is explicitly enabled.
3549 @opindex Wempty-body
3550 Warn if an empty body occurs in an @samp{if}, @samp{else} or @samp{do
3551 while} statement. Additionally, in C++, warn when an empty body occurs
3552 in a @samp{while} or @samp{for} statement with no whitespacing before
3553 the semicolon. This warning is also enabled by @option{-Wextra}.
3555 @item -Wsign-compare
3556 @opindex Wsign-compare
3557 @cindex warning for comparison of signed and unsigned values
3558 @cindex comparison of signed and unsigned values, warning
3559 @cindex signed and unsigned values, comparison warning
3560 Warn when a comparison between signed and unsigned values could produce
3561 an incorrect result when the signed value is converted to unsigned.
3562 This warning is also enabled by @option{-Wextra}; to get the other warnings
3563 of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
3565 @item -Wsign-conversion
3566 @opindex Wsign-conversion
3567 @opindex Wno-sign-conversion
3568 Warn for implicit conversions that may change the sign of an integer
3569 value, like assigning a signed integer expression to an unsigned
3570 integer variable. An explicit cast silences the warning. In C, this
3571 option is enabled also by @option{-Wconversion}.
3575 @opindex Wno-address
3576 Warn about suspicious uses of memory addresses. These include using
3577 the address of a function in a conditional expression, such as
3578 @code{void func(void); if (func)}, and comparisons against the memory
3579 address of a string literal, such as @code{if (x == "abc")}. Such
3580 uses typically indicate a programmer error: the address of a function
3581 always evaluates to true, so their use in a conditional usually
3582 indicate that the programmer forgot the parentheses in a function
3583 call; and comparisons against string literals result in unspecified
3584 behavior and are not portable in C, so they usually indicate that the
3585 programmer intended to use @code{strcmp}. This warning is enabled by
3589 @opindex Wlogical-op
3590 @opindex Wno-logical-op
3591 Warn about suspicious uses of logical operators in expressions.
3592 This includes using logical operators in contexts where a
3593 bit-wise operator is likely to be expected.
3595 @item -Waggregate-return
3596 @opindex Waggregate-return
3597 Warn if any functions that return structures or unions are defined or
3598 called. (In languages where you can return an array, this also elicits
3601 @item -Wno-attributes
3602 @opindex Wno-attributes
3603 @opindex Wattributes
3604 Do not warn if an unexpected @code{__attribute__} is used, such as
3605 unrecognized attributes, function attributes applied to variables,
3606 etc. This will not stop errors for incorrect use of supported
3609 @item -Wstrict-prototypes @r{(C only)}
3610 @opindex Wstrict-prototypes
3611 Warn if a function is declared or defined without specifying the
3612 argument types. (An old-style function definition is permitted without
3613 a warning if preceded by a declaration which specifies the argument
3616 @item -Wold-style-declaration @r{(C only)}
3617 @opindex Wold-style-declaration
3618 Warn for obsolescent usages, according to the C Standard, in a
3619 declaration. For example, warn if storage-class specifiers like
3620 @code{static} are not the first things in a declaration. This warning
3621 is also enabled by @option{-Wextra}.
3623 @item -Wold-style-definition @r{(C only)}
3624 @opindex Wold-style-definition
3625 Warn if an old-style function definition is used. A warning is given
3626 even if there is a previous prototype.
3628 @item -Wmissing-parameter-type @r{(C only)}
3629 @opindex Wmissing-parameter-type
3630 A function parameter is declared without a type specifier in K&R-style
3637 This warning is also enabled by @option{-Wextra}.
3639 @item -Wmissing-prototypes @r{(C only)}
3640 @opindex Wmissing-prototypes
3641 Warn if a global function is defined without a previous prototype
3642 declaration. This warning is issued even if the definition itself
3643 provides a prototype. The aim is to detect global functions that fail
3644 to be declared in header files.
3646 @item -Wmissing-declarations @r{(C and C++ only)}
3647 @opindex Wmissing-declarations
3648 Warn if a global function is defined without a previous declaration.
3649 Do so even if the definition itself provides a prototype.
3650 Use this option to detect global functions that are not declared in
3651 header files. In C++, no warnings are issued for function templates,
3652 or for inline functions, or for functions in anonymous namespaces.
3654 @item -Wmissing-field-initializers
3655 @opindex Wmissing-field-initializers
3658 Warn if a structure's initializer has some fields missing. For
3659 example, the following code would cause such a warning, because
3660 @code{x.h} is implicitly zero:
3663 struct s @{ int f, g, h; @};
3664 struct s x = @{ 3, 4 @};
3667 This option does not warn about designated initializers, so the following
3668 modification would not trigger a warning:
3671 struct s @{ int f, g, h; @};
3672 struct s x = @{ .f = 3, .g = 4 @};
3675 This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3676 warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3678 @item -Wmissing-noreturn
3679 @opindex Wmissing-noreturn
3680 Warn about functions which might be candidates for attribute @code{noreturn}.
3681 Note these are only possible candidates, not absolute ones. Care should
3682 be taken to manually verify functions actually do not ever return before
3683 adding the @code{noreturn} attribute, otherwise subtle code generation
3684 bugs could be introduced. You will not get a warning for @code{main} in
3685 hosted C environments.
3687 @item -Wmissing-format-attribute
3688 @opindex Wmissing-format-attribute
3690 Warn about function pointers which might be candidates for @code{format}
3691 attributes. Note these are only possible candidates, not absolute ones.
3692 GCC will guess that function pointers with @code{format} attributes that
3693 are used in assignment, initialization, parameter passing or return
3694 statements should have a corresponding @code{format} attribute in the
3695 resulting type. I.e.@: the left-hand side of the assignment or
3696 initialization, the type of the parameter variable, or the return type
3697 of the containing function respectively should also have a @code{format}
3698 attribute to avoid the warning.
3700 GCC will also warn about function definitions which might be
3701 candidates for @code{format} attributes. Again, these are only
3702 possible candidates. GCC will guess that @code{format} attributes
3703 might be appropriate for any function that calls a function like
3704 @code{vprintf} or @code{vscanf}, but this might not always be the
3705 case, and some functions for which @code{format} attributes are
3706 appropriate may not be detected.
3708 @item -Wno-multichar
3709 @opindex Wno-multichar
3711 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3712 Usually they indicate a typo in the user's code, as they have
3713 implementation-defined values, and should not be used in portable code.
3715 @item -Wnormalized=<none|id|nfc|nfkc>
3716 @opindex Wnormalized
3719 @cindex character set, input normalization
3720 In ISO C and ISO C++, two identifiers are different if they are
3721 different sequences of characters. However, sometimes when characters
3722 outside the basic ASCII character set are used, you can have two
3723 different character sequences that look the same. To avoid confusion,
3724 the ISO 10646 standard sets out some @dfn{normalization rules} which
3725 when applied ensure that two sequences that look the same are turned into
3726 the same sequence. GCC can warn you if you are using identifiers which
3727 have not been normalized; this option controls that warning.
3729 There are four levels of warning that GCC supports. The default is
3730 @option{-Wnormalized=nfc}, which warns about any identifier which is
3731 not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3732 recommended form for most uses.
3734 Unfortunately, there are some characters which ISO C and ISO C++ allow
3735 in identifiers that when turned into NFC aren't allowable as
3736 identifiers. That is, there's no way to use these symbols in portable
3737 ISO C or C++ and have all your identifiers in NFC.
3738 @option{-Wnormalized=id} suppresses the warning for these characters.
3739 It is hoped that future versions of the standards involved will correct
3740 this, which is why this option is not the default.
3742 You can switch the warning off for all characters by writing
3743 @option{-Wnormalized=none}. You would only want to do this if you
3744 were using some other normalization scheme (like ``D''), because
3745 otherwise you can easily create bugs that are literally impossible to see.
3747 Some characters in ISO 10646 have distinct meanings but look identical
3748 in some fonts or display methodologies, especially once formatting has
3749 been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3750 LETTER N'', will display just like a regular @code{n} which has been
3751 placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3752 normalization scheme to convert all these into a standard form as
3753 well, and GCC will warn if your code is not in NFKC if you use
3754 @option{-Wnormalized=nfkc}. This warning is comparable to warning
3755 about every identifier that contains the letter O because it might be
3756 confused with the digit 0, and so is not the default, but may be
3757 useful as a local coding convention if the programming environment is
3758 unable to be fixed to display these characters distinctly.
3760 @item -Wno-deprecated-declarations
3761 @opindex Wno-deprecated-declarations
3762 Do not warn about uses of functions (@pxref{Function Attributes}),
3763 variables (@pxref{Variable Attributes}), and types (@pxref{Type
3764 Attributes}) marked as deprecated by using the @code{deprecated}
3768 @opindex Wno-overflow
3769 Do not warn about compile-time overflow in constant expressions.
3771 @item -Woverride-init
3772 @opindex Woverride-init
3775 Warn if an initialized field without side effects is overridden when
3776 using designated initializers (@pxref{Designated Inits, , Designated
3779 This warning is included in @option{-Wextra}. To get other
3780 @option{-Wextra} warnings without this one, use @samp{-Wextra
3781 -Wno-override-init}.
3785 Warn if a structure is given the packed attribute, but the packed
3786 attribute has no effect on the layout or size of the structure.
3787 Such structures may be mis-aligned for little benefit. For
3788 instance, in this code, the variable @code{f.x} in @code{struct bar}
3789 will be misaligned even though @code{struct bar} does not itself
3790 have the packed attribute:
3797 @} __attribute__((packed));
3807 Warn if padding is included in a structure, either to align an element
3808 of the structure or to align the whole structure. Sometimes when this
3809 happens it is possible to rearrange the fields of the structure to
3810 reduce the padding and so make the structure smaller.
3812 @item -Wredundant-decls
3813 @opindex Wredundant-decls
3814 Warn if anything is declared more than once in the same scope, even in
3815 cases where multiple declaration is valid and changes nothing.
3817 @item -Wnested-externs @r{(C only)}
3818 @opindex Wnested-externs
3819 Warn if an @code{extern} declaration is encountered within a function.
3821 @item -Wunreachable-code
3822 @opindex Wunreachable-code
3823 Warn if the compiler detects that code will never be executed.
3825 This option is intended to warn when the compiler detects that at
3826 least a whole line of source code will never be executed, because
3827 some condition is never satisfied or because it is after a
3828 procedure that never returns.
3830 It is possible for this option to produce a warning even though there
3831 are circumstances under which part of the affected line can be executed,
3832 so care should be taken when removing apparently-unreachable code.
3834 For instance, when a function is inlined, a warning may mean that the
3835 line is unreachable in only one inlined copy of the function.
3837 This option is not made part of @option{-Wall} because in a debugging
3838 version of a program there is often substantial code which checks
3839 correct functioning of the program and is, hopefully, unreachable
3840 because the program does work. Another common use of unreachable
3841 code is to provide behavior which is selectable at compile-time.
3845 Warn if a function can not be inlined and it was declared as inline.
3846 Even with this option, the compiler will not warn about failures to
3847 inline functions declared in system headers.
3849 The compiler uses a variety of heuristics to determine whether or not
3850 to inline a function. For example, the compiler takes into account
3851 the size of the function being inlined and the amount of inlining
3852 that has already been done in the current function. Therefore,
3853 seemingly insignificant changes in the source program can cause the
3854 warnings produced by @option{-Winline} to appear or disappear.
3856 @item -Wno-invalid-offsetof @r{(C++ only)}
3857 @opindex Wno-invalid-offsetof
3858 Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3859 type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3860 to a non-POD type is undefined. In existing C++ implementations,
3861 however, @samp{offsetof} typically gives meaningful results even when
3862 applied to certain kinds of non-POD types. (Such as a simple
3863 @samp{struct} that fails to be a POD type only by virtue of having a
3864 constructor.) This flag is for users who are aware that they are
3865 writing nonportable code and who have deliberately chosen to ignore the
3868 The restrictions on @samp{offsetof} may be relaxed in a future version
3869 of the C++ standard.
3871 @item -Wno-int-to-pointer-cast @r{(C only)}
3872 @opindex Wno-int-to-pointer-cast
3873 Suppress warnings from casts to pointer type of an integer of a
3876 @item -Wno-pointer-to-int-cast @r{(C only)}
3877 @opindex Wno-pointer-to-int-cast
3878 Suppress warnings from casts from a pointer to an integer type of a
3882 @opindex Winvalid-pch
3883 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3884 the search path but can't be used.
3888 @opindex Wno-long-long
3889 Warn if @samp{long long} type is used. This is default. To inhibit
3890 the warning messages, use @option{-Wno-long-long}. Flags
3891 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3892 only when @option{-pedantic} flag is used.
3894 @item -Wvariadic-macros
3895 @opindex Wvariadic-macros
3896 @opindex Wno-variadic-macros
3897 Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3898 alternate syntax when in pedantic ISO C99 mode. This is default.
3899 To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3904 Warn if variable length array is used in the code.
3905 @option{-Wno-vla} will prevent the @option{-pedantic} warning of
3906 the variable length array.
3908 @item -Wvolatile-register-var
3909 @opindex Wvolatile-register-var
3910 @opindex Wno-volatile-register-var
3911 Warn if a register variable is declared volatile. The volatile
3912 modifier does not inhibit all optimizations that may eliminate reads
3913 and/or writes to register variables.
3915 @item -Wdisabled-optimization
3916 @opindex Wdisabled-optimization
3917 Warn if a requested optimization pass is disabled. This warning does
3918 not generally indicate that there is anything wrong with your code; it
3919 merely indicates that GCC's optimizers were unable to handle the code
3920 effectively. Often, the problem is that your code is too big or too
3921 complex; GCC will refuse to optimize programs when the optimization
3922 itself is likely to take inordinate amounts of time.
3924 @item -Wpointer-sign
3925 @opindex Wpointer-sign
3926 @opindex Wno-pointer-sign
3927 Warn for pointer argument passing or assignment with different signedness.
3928 This option is only supported for C and Objective-C@. It is implied by
3929 @option{-Wall} and by @option{-pedantic}, which can be disabled with
3930 @option{-Wno-pointer-sign}.
3932 @item -Wstack-protector
3933 @opindex Wstack-protector
3934 This option is only active when @option{-fstack-protector} is active. It
3935 warns about functions that will not be protected against stack smashing.
3937 @item -Woverlength-strings
3938 @opindex Woverlength-strings
3939 Warn about string constants which are longer than the ``minimum
3940 maximum'' length specified in the C standard. Modern compilers
3941 generally allow string constants which are much longer than the
3942 standard's minimum limit, but very portable programs should avoid
3943 using longer strings.
3945 The limit applies @emph{after} string constant concatenation, and does
3946 not count the trailing NUL@. In C89, the limit was 509 characters; in
3947 C99, it was raised to 4095. C++98 does not specify a normative
3948 minimum maximum, so we do not diagnose overlength strings in C++@.
3950 This option is implied by @option{-pedantic}, and can be disabled with
3951 @option{-Wno-overlength-strings}.
3954 @node Debugging Options
3955 @section Options for Debugging Your Program or GCC
3956 @cindex options, debugging
3957 @cindex debugging information options
3959 GCC has various special options that are used for debugging
3960 either your program or GCC:
3965 Produce debugging information in the operating system's native format
3966 (stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3969 On most systems that use stabs format, @option{-g} enables use of extra
3970 debugging information that only GDB can use; this extra information
3971 makes debugging work better in GDB but will probably make other debuggers
3973 refuse to read the program. If you want to control for certain whether
3974 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3975 @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3977 GCC allows you to use @option{-g} with
3978 @option{-O}. The shortcuts taken by optimized code may occasionally
3979 produce surprising results: some variables you declared may not exist
3980 at all; flow of control may briefly move where you did not expect it;
3981 some statements may not be executed because they compute constant
3982 results or their values were already at hand; some statements may
3983 execute in different places because they were moved out of loops.
3985 Nevertheless it proves possible to debug optimized output. This makes
3986 it reasonable to use the optimizer for programs that might have bugs.
3988 The following options are useful when GCC is generated with the
3989 capability for more than one debugging format.
3993 Produce debugging information for use by GDB@. This means to use the
3994 most expressive format available (DWARF 2, stabs, or the native format
3995 if neither of those are supported), including GDB extensions if at all
4000 Produce debugging information in stabs format (if that is supported),
4001 without GDB extensions. This is the format used by DBX on most BSD
4002 systems. On MIPS, Alpha and System V Release 4 systems this option
4003 produces stabs debugging output which is not understood by DBX or SDB@.
4004 On System V Release 4 systems this option requires the GNU assembler.
4006 @item -feliminate-unused-debug-symbols
4007 @opindex feliminate-unused-debug-symbols
4008 Produce debugging information in stabs format (if that is supported),
4009 for only symbols that are actually used.
4011 @item -femit-class-debug-always
4012 Instead of emitting debugging information for a C++ class in only one
4013 object file, emit it in all object files using the class. This option
4014 should be used only with debuggers that are unable to handle the way GCC
4015 normally emits debugging information for classes because using this
4016 option will increase the size of debugging information by as much as a
4021 Produce debugging information in stabs format (if that is supported),
4022 using GNU extensions understood only by the GNU debugger (GDB)@. The
4023 use of these extensions is likely to make other debuggers crash or
4024 refuse to read the program.
4028 Produce debugging information in COFF format (if that is supported).
4029 This is the format used by SDB on most System V systems prior to
4034 Produce debugging information in XCOFF format (if that is supported).
4035 This is the format used by the DBX debugger on IBM RS/6000 systems.
4039 Produce debugging information in XCOFF format (if that is supported),
4040 using GNU extensions understood only by the GNU debugger (GDB)@. The
4041 use of these extensions is likely to make other debuggers crash or
4042 refuse to read the program, and may cause assemblers other than the GNU
4043 assembler (GAS) to fail with an error.
4047 Produce debugging information in DWARF version 2 format (if that is
4048 supported). This is the format used by DBX on IRIX 6. With this
4049 option, GCC uses features of DWARF version 3 when they are useful;
4050 version 3 is upward compatible with version 2, but may still cause
4051 problems for older debuggers.
4055 Produce debugging information in VMS debug format (if that is
4056 supported). This is the format used by DEBUG on VMS systems.
4059 @itemx -ggdb@var{level}
4060 @itemx -gstabs@var{level}
4061 @itemx -gcoff@var{level}
4062 @itemx -gxcoff@var{level}
4063 @itemx -gvms@var{level}
4064 Request debugging information and also use @var{level} to specify how
4065 much information. The default level is 2.
4067 Level 0 produces no debug information at all. Thus, @option{-g0} negates
4070 Level 1 produces minimal information, enough for making backtraces in
4071 parts of the program that you don't plan to debug. This includes
4072 descriptions of functions and external variables, but no information
4073 about local variables and no line numbers.
4075 Level 3 includes extra information, such as all the macro definitions
4076 present in the program. Some debuggers support macro expansion when
4077 you use @option{-g3}.
4079 @option{-gdwarf-2} does not accept a concatenated debug level, because
4080 GCC used to support an option @option{-gdwarf} that meant to generate
4081 debug information in version 1 of the DWARF format (which is very
4082 different from version 2), and it would have been too confusing. That
4083 debug format is long obsolete, but the option cannot be changed now.
4084 Instead use an additional @option{-g@var{level}} option to change the
4085 debug level for DWARF2.
4087 @item -feliminate-dwarf2-dups
4088 @opindex feliminate-dwarf2-dups
4089 Compress DWARF2 debugging information by eliminating duplicated
4090 information about each symbol. This option only makes sense when
4091 generating DWARF2 debugging information with @option{-gdwarf-2}.
4093 @item -femit-struct-debug-baseonly
4094 Emit debug information for struct-like types
4095 only when the base name of the compilation source file
4096 matches the base name of file in which the struct was defined.
4098 This option substantially reduces the size of debugging information,
4099 but at significant potential loss in type information to the debugger.
4100 See @option{-femit-struct-debug-reduced} for a less aggressive option.
4101 See @option{-femit-struct-debug-detailed} for more detailed control.
4103 This option works only with DWARF 2.
4105 @item -femit-struct-debug-reduced
4106 Emit debug information for struct-like types
4107 only when the base name of the compilation source file
4108 matches the base name of file in which the type was defined,
4109 unless the struct is a template or defined in a system header.
4111 This option significantly reduces the size of debugging information,
4112 with some potential loss in type information to the debugger.
4113 See @option{-femit-struct-debug-baseonly} for a more aggressive option.
4114 See @option{-femit-struct-debug-detailed} for more detailed control.
4116 This option works only with DWARF 2.
4118 @item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
4119 Specify the struct-like types
4120 for which the compiler will generate debug information.
4121 The intent is to reduce duplicate struct debug information
4122 between different object files within the same program.
4124 This option is a detailed version of
4125 @option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
4126 which will serve for most needs.
4128 A specification has the syntax
4129 [@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
4131 The optional first word limits the specification to
4132 structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
4133 A struct type is used directly when it is the type of a variable, member.
4134 Indirect uses arise through pointers to structs.
4135 That is, when use of an incomplete struct would be legal, the use is indirect.
4137 @samp{struct one direct; struct two * indirect;}.
4139 The optional second word limits the specification to
4140 ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
4141 Generic structs are a bit complicated to explain.
4142 For C++, these are non-explicit specializations of template classes,
4143 or non-template classes within the above.
4144 Other programming languages have generics,
4145 but @samp{-femit-struct-debug-detailed} does not yet implement them.
4147 The third word specifies the source files for those
4148 structs for which the compiler will emit debug information.
4149 The values @samp{none} and @samp{any} have the normal meaning.
4150 The value @samp{base} means that
4151 the base of name of the file in which the type declaration appears
4152 must match the base of the name of the main compilation file.
4153 In practice, this means that
4154 types declared in @file{foo.c} and @file{foo.h} will have debug information,
4155 but types declared in other header will not.
4156 The value @samp{sys} means those types satisfying @samp{base}
4157 or declared in system or compiler headers.
4159 You may need to experiment to determine the best settings for your application.
4161 The default is @samp{-femit-struct-debug-detailed=all}.
4163 This option works only with DWARF 2.
4165 @item -fno-merge-debug-strings
4166 @opindex fmerge-debug-strings
4167 @opindex fno-merge-debug-strings
4168 Direct the linker to merge together strings which are identical in
4169 different object files. This is not supported by all assemblers or
4170 linker. This decreases the size of the debug information in the
4171 output file at the cost of increasing link processing time. This is
4174 @item -fdebug-prefix-map=@var{old}=@var{new}
4175 @opindex fdebug-prefix-map
4176 When compiling files in directory @file{@var{old}}, record debugging
4177 information describing them as in @file{@var{new}} instead.
4179 @cindex @command{prof}
4182 Generate extra code to write profile information suitable for the
4183 analysis program @command{prof}. You must use this option when compiling
4184 the source files you want data about, and you must also use it when
4187 @cindex @command{gprof}
4190 Generate extra code to write profile information suitable for the
4191 analysis program @command{gprof}. You must use this option when compiling
4192 the source files you want data about, and you must also use it when
4197 Makes the compiler print out each function name as it is compiled, and
4198 print some statistics about each pass when it finishes.
4201 @opindex ftime-report
4202 Makes the compiler print some statistics about the time consumed by each
4203 pass when it finishes.
4206 @opindex fmem-report
4207 Makes the compiler print some statistics about permanent memory
4208 allocation when it finishes.
4210 @item -fpre-ipa-mem-report
4211 @opindex fpre-ipa-mem-report
4212 @item -fpost-ipa-mem-report
4213 @opindex fpost-ipa-mem-report
4214 Makes the compiler print some statistics about permanent memory
4215 allocation before or after interprocedural optimization.
4217 @item -fprofile-arcs
4218 @opindex fprofile-arcs
4219 Add code so that program flow @dfn{arcs} are instrumented. During
4220 execution the program records how many times each branch and call is
4221 executed and how many times it is taken or returns. When the compiled
4222 program exits it saves this data to a file called
4223 @file{@var{auxname}.gcda} for each source file. The data may be used for
4224 profile-directed optimizations (@option{-fbranch-probabilities}), or for
4225 test coverage analysis (@option{-ftest-coverage}). Each object file's
4226 @var{auxname} is generated from the name of the output file, if
4227 explicitly specified and it is not the final executable, otherwise it is
4228 the basename of the source file. In both cases any suffix is removed
4229 (e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
4230 @file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
4231 @xref{Cross-profiling}.
4233 @cindex @command{gcov}
4237 This option is used to compile and link code instrumented for coverage
4238 analysis. The option is a synonym for @option{-fprofile-arcs}
4239 @option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
4240 linking). See the documentation for those options for more details.
4245 Compile the source files with @option{-fprofile-arcs} plus optimization
4246 and code generation options. For test coverage analysis, use the
4247 additional @option{-ftest-coverage} option. You do not need to profile
4248 every source file in a program.
4251 Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
4252 (the latter implies the former).
4255 Run the program on a representative workload to generate the arc profile
4256 information. This may be repeated any number of times. You can run
4257 concurrent instances of your program, and provided that the file system
4258 supports locking, the data files will be correctly updated. Also
4259 @code{fork} calls are detected and correctly handled (double counting
4263 For profile-directed optimizations, compile the source files again with
4264 the same optimization and code generation options plus
4265 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
4266 Control Optimization}).
4269 For test coverage analysis, use @command{gcov} to produce human readable
4270 information from the @file{.gcno} and @file{.gcda} files. Refer to the
4271 @command{gcov} documentation for further information.
4275 With @option{-fprofile-arcs}, for each function of your program GCC
4276 creates a program flow graph, then finds a spanning tree for the graph.
4277 Only arcs that are not on the spanning tree have to be instrumented: the
4278 compiler adds code to count the number of times that these arcs are
4279 executed. When an arc is the only exit or only entrance to a block, the
4280 instrumentation code can be added to the block; otherwise, a new basic
4281 block must be created to hold the instrumentation code.
4284 @item -ftest-coverage
4285 @opindex ftest-coverage
4286 Produce a notes file that the @command{gcov} code-coverage utility
4287 (@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
4288 show program coverage. Each source file's note file is called
4289 @file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
4290 above for a description of @var{auxname} and instructions on how to
4291 generate test coverage data. Coverage data will match the source files
4292 more closely, if you do not optimize.
4294 @item -fdbg-cnt-list
4295 @opindex fdbg-cnt-list
4296 Print the name and the counter upperbound for all debug counters.
4298 @item -fdbg-cnt=@var{counter-value-list}
4300 Set the internal debug counter upperbound. @var{counter-value-list}
4301 is a comma-separated list of @var{name}:@var{value} pairs
4302 which sets the upperbound of each debug counter @var{name} to @var{value}.
4303 All debug counters have the initial upperbound of @var{UINT_MAX},
4304 thus dbg_cnt() returns true always unless the upperbound is set by this option.
4305 e.g. With -fdbg-cnt=dce:10,tail_call:0
4306 dbg_cnt(dce) will return true only for first 10 invocations
4307 and dbg_cnt(tail_call) will return false always.
4309 @item -d@var{letters}
4310 @item -fdump-rtl-@var{pass}
4312 Says to make debugging dumps during compilation at times specified by
4313 @var{letters}. This is used for debugging the RTL-based passes of the
4314 compiler. The file names for most of the dumps are made by appending a
4315 pass number and a word to the @var{dumpname}. @var{dumpname} is generated
4316 from the name of the output file, if explicitly specified and it is not
4317 an executable, otherwise it is the basename of the source file. These
4318 switches may have different effects when @option{-E} is used for
4321 Most debug dumps can be enabled either passing a letter to the @option{-d}
4322 option, or with a long @option{-fdump-rtl} switch; here are the possible
4323 letters for use in @var{letters} and @var{pass}, and their meanings:
4328 Annotate the assembler output with miscellaneous debugging information.
4331 @itemx -fdump-rtl-bbro
4333 @opindex fdump-rtl-bbro
4334 Dump after block reordering, to @file{@var{file}.148r.bbro}.
4337 @itemx -fdump-rtl-combine
4339 @opindex fdump-rtl-combine
4340 Dump after the RTL instruction combination pass, to the file
4341 @file{@var{file}.129r.combine}.
4344 @itemx -fdump-rtl-ce1
4345 @itemx -fdump-rtl-ce2
4347 @opindex fdump-rtl-ce1
4348 @opindex fdump-rtl-ce2
4349 @option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
4350 first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
4351 and @option{-fdump-rtl-ce2} enable dumping after the second if
4352 conversion, to the file @file{@var{file}.130r.ce2}.
4355 @itemx -fdump-rtl-btl
4356 @itemx -fdump-rtl-dbr
4358 @opindex fdump-rtl-btl
4359 @opindex fdump-rtl-dbr
4360 @option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
4361 target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
4362 and @option{-fdump-rtl-dbr} enable dumping after delayed branch
4363 scheduling, to @file{@var{file}.36.dbr}.
4367 Dump all macro definitions, at the end of preprocessing, in addition to
4371 @itemx -fdump-rtl-ce3
4373 @opindex fdump-rtl-ce3
4374 Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
4377 @itemx -fdump-rtl-cfg
4378 @itemx -fdump-rtl-life
4380 @opindex fdump-rtl-cfg
4381 @opindex fdump-rtl-life
4382 @option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
4383 and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
4384 and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
4385 to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
4388 @itemx -fdump-rtl-greg
4390 @opindex fdump-rtl-greg
4391 Dump after global register allocation, to @file{@var{file}.139r.greg}.
4394 @itemx -fdump-rtl-gcse
4395 @itemx -fdump-rtl-bypass
4397 @opindex fdump-rtl-gcse
4398 @opindex fdump-rtl-bypass
4399 @option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
4400 @file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
4401 enable dumping after jump bypassing and control flow optimizations, to
4402 @file{@var{file}.115r.bypass}.
4405 @itemx -fdump-rtl-eh
4407 @opindex fdump-rtl-eh
4408 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
4411 @itemx -fdump-rtl-sibling
4413 @opindex fdump-rtl-sibling
4414 Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
4417 @itemx -fdump-rtl-jump
4419 @opindex fdump-rtl-jump
4420 Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
4423 @itemx -fdump-rtl-stack
4425 @opindex fdump-rtl-stack
4426 Dump after conversion from GCC's "flat register file" registers to the
4427 x87's stack-like registers, to @file{@var{file}.152r.stack}.
4430 @itemx -fdump-rtl-lreg
4432 @opindex fdump-rtl-lreg
4433 Dump after local register allocation, to @file{@var{file}.138r.lreg}.
4436 @itemx -fdump-rtl-loop2
4438 @opindex fdump-rtl-loop2
4439 @option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
4440 loop optimization pass, to @file{@var{file}.119r.loop2},
4441 @file{@var{file}.120r.loop2_init},
4442 @file{@var{file}.121r.loop2_invariant}, and
4443 @file{@var{file}.125r.loop2_done}.
4446 @itemx -fdump-rtl-sms
4448 @opindex fdump-rtl-sms
4449 Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
4452 @itemx -fdump-rtl-mach
4454 @opindex fdump-rtl-mach
4455 Dump after performing the machine dependent reorganization pass, to
4456 @file{@var{file}.155r.mach} if that pass exists.
4459 @itemx -fdump-rtl-rnreg
4461 @opindex fdump-rtl-rnreg
4462 Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
4465 @itemx -fdump-rtl-regmove
4467 @opindex fdump-rtl-regmove
4468 Dump after the register move pass, to @file{@var{file}.132r.regmove}.
4471 @itemx -fdump-rtl-postreload
4473 @opindex fdump-rtl-postreload
4474 Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
4477 @itemx -fdump-rtl-expand
4479 @opindex fdump-rtl-expand
4480 Dump after RTL generation, to @file{@var{file}.104r.expand}.
4483 @itemx -fdump-rtl-sched2
4485 @opindex fdump-rtl-sched2
4486 Dump after the second scheduling pass, to @file{@var{file}.149r.sched2}.
4489 @itemx -fdump-rtl-cse
4491 @opindex fdump-rtl-cse
4492 Dump after CSE (including the jump optimization that sometimes follows
4493 CSE), to @file{@var{file}.113r.cse}.
4496 @itemx -fdump-rtl-sched1
4498 @opindex fdump-rtl-sched1
4499 Dump after the first scheduling pass, to @file{@var{file}.136r.sched1}.
4502 @itemx -fdump-rtl-cse2
4504 @opindex fdump-rtl-cse2
4505 Dump after the second CSE pass (including the jump optimization that
4506 sometimes follows CSE), to @file{@var{file}.127r.cse2}.
4509 @itemx -fdump-rtl-tracer
4511 @opindex fdump-rtl-tracer
4512 Dump after running tracer, to @file{@var{file}.118r.tracer}.
4515 @itemx -fdump-rtl-vpt
4516 @itemx -fdump-rtl-vartrack
4518 @opindex fdump-rtl-vpt
4519 @opindex fdump-rtl-vartrack
4520 @option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
4521 profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
4522 and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
4523 to @file{@var{file}.154r.vartrack}.
4526 @itemx -fdump-rtl-flow2
4528 @opindex fdump-rtl-flow2
4529 Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
4532 @itemx -fdump-rtl-peephole2
4534 @opindex fdump-rtl-peephole2
4535 Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
4538 @itemx -fdump-rtl-web
4540 @opindex fdump-rtl-web
4541 Dump after live range splitting, to @file{@var{file}.126r.web}.
4544 @itemx -fdump-rtl-all
4546 @opindex fdump-rtl-all
4547 Produce all the dumps listed above.
4551 Produce a core dump whenever an error occurs.
4555 Print statistics on memory usage, at the end of the run, to
4560 Annotate the assembler output with a comment indicating which
4561 pattern and alternative was used. The length of each instruction is
4566 Dump the RTL in the assembler output as a comment before each instruction.
4567 Also turns on @option{-dp} annotation.
4571 For each of the other indicated dump files (either with @option{-d} or
4572 @option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
4573 graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
4577 Just generate RTL for a function instead of compiling it. Usually used
4578 with @samp{r} (@option{-fdump-rtl-expand}).
4582 Dump debugging information during parsing, to standard error.
4586 @opindex fdump-noaddr
4587 When doing debugging dumps (see @option{-d} option above), suppress
4588 address output. This makes it more feasible to use diff on debugging
4589 dumps for compiler invocations with different compiler binaries and/or
4590 different text / bss / data / heap / stack / dso start locations.
4592 @item -fdump-unnumbered
4593 @opindex fdump-unnumbered
4594 When doing debugging dumps (see @option{-d} option above), suppress instruction
4595 numbers and address output. This makes it more feasible to
4596 use diff on debugging dumps for compiler invocations with different
4597 options, in particular with and without @option{-g}.
4599 @item -fdump-translation-unit @r{(C++ only)}
4600 @itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
4601 @opindex fdump-translation-unit
4602 Dump a representation of the tree structure for the entire translation
4603 unit to a file. The file name is made by appending @file{.tu} to the
4604 source file name. If the @samp{-@var{options}} form is used, @var{options}
4605 controls the details of the dump as described for the
4606 @option{-fdump-tree} options.
4608 @item -fdump-class-hierarchy @r{(C++ only)}
4609 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
4610 @opindex fdump-class-hierarchy
4611 Dump a representation of each class's hierarchy and virtual function
4612 table layout to a file. The file name is made by appending @file{.class}
4613 to the source file name. If the @samp{-@var{options}} form is used,
4614 @var{options} controls the details of the dump as described for the
4615 @option{-fdump-tree} options.
4617 @item -fdump-ipa-@var{switch}
4619 Control the dumping at various stages of inter-procedural analysis
4620 language tree to a file. The file name is generated by appending a switch
4621 specific suffix to the source file name. The following dumps are possible:
4625 Enables all inter-procedural analysis dumps; currently the only produced
4626 dump is the @samp{cgraph} dump.
4629 Dumps information about call-graph optimization, unused function removal,
4630 and inlining decisions.
4633 @item -fdump-tree-@var{switch}
4634 @itemx -fdump-tree-@var{switch}-@var{options}
4636 Control the dumping at various stages of processing the intermediate
4637 language tree to a file. The file name is generated by appending a switch
4638 specific suffix to the source file name. If the @samp{-@var{options}}
4639 form is used, @var{options} is a list of @samp{-} separated options that
4640 control the details of the dump. Not all options are applicable to all
4641 dumps, those which are not meaningful will be ignored. The following
4642 options are available
4646 Print the address of each node. Usually this is not meaningful as it
4647 changes according to the environment and source file. Its primary use
4648 is for tying up a dump file with a debug environment.
4650 Inhibit dumping of members of a scope or body of a function merely
4651 because that scope has been reached. Only dump such items when they
4652 are directly reachable by some other path. When dumping pretty-printed
4653 trees, this option inhibits dumping the bodies of control structures.
4655 Print a raw representation of the tree. By default, trees are
4656 pretty-printed into a C-like representation.
4658 Enable more detailed dumps (not honored by every dump option).
4660 Enable dumping various statistics about the pass (not honored by every dump
4663 Enable showing basic block boundaries (disabled in raw dumps).
4665 Enable showing virtual operands for every statement.
4667 Enable showing line numbers for statements.
4669 Enable showing the unique ID (@code{DECL_UID}) for each variable.
4671 Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4674 The following tree dumps are possible:
4678 Dump before any tree based optimization, to @file{@var{file}.original}.
4681 Dump after all tree based optimization, to @file{@var{file}.optimized}.
4684 Dump after function inlining, to @file{@var{file}.inlined}.
4687 @opindex fdump-tree-gimple
4688 Dump each function before and after the gimplification pass to a file. The
4689 file name is made by appending @file{.gimple} to the source file name.
4692 @opindex fdump-tree-cfg
4693 Dump the control flow graph of each function to a file. The file name is
4694 made by appending @file{.cfg} to the source file name.
4697 @opindex fdump-tree-vcg
4698 Dump the control flow graph of each function to a file in VCG format. The
4699 file name is made by appending @file{.vcg} to the source file name. Note
4700 that if the file contains more than one function, the generated file cannot
4701 be used directly by VCG@. You will need to cut and paste each function's
4702 graph into its own separate file first.
4705 @opindex fdump-tree-ch
4706 Dump each function after copying loop headers. The file name is made by
4707 appending @file{.ch} to the source file name.
4710 @opindex fdump-tree-ssa
4711 Dump SSA related information to a file. The file name is made by appending
4712 @file{.ssa} to the source file name.
4715 @opindex fdump-tree-salias
4716 Dump structure aliasing variable information to a file. This file name
4717 is made by appending @file{.salias} to the source file name.
4720 @opindex fdump-tree-alias
4721 Dump aliasing information for each function. The file name is made by
4722 appending @file{.alias} to the source file name.
4725 @opindex fdump-tree-ccp
4726 Dump each function after CCP@. The file name is made by appending
4727 @file{.ccp} to the source file name.
4730 @opindex fdump-tree-storeccp
4731 Dump each function after STORE-CCP. The file name is made by appending
4732 @file{.storeccp} to the source file name.
4735 @opindex fdump-tree-pre
4736 Dump trees after partial redundancy elimination. The file name is made
4737 by appending @file{.pre} to the source file name.
4740 @opindex fdump-tree-fre
4741 Dump trees after full redundancy elimination. The file name is made
4742 by appending @file{.fre} to the source file name.
4745 @opindex fdump-tree-copyprop
4746 Dump trees after copy propagation. The file name is made
4747 by appending @file{.copyprop} to the source file name.
4749 @item store_copyprop
4750 @opindex fdump-tree-store_copyprop
4751 Dump trees after store copy-propagation. The file name is made
4752 by appending @file{.store_copyprop} to the source file name.
4755 @opindex fdump-tree-dce
4756 Dump each function after dead code elimination. The file name is made by
4757 appending @file{.dce} to the source file name.
4760 @opindex fdump-tree-mudflap
4761 Dump each function after adding mudflap instrumentation. The file name is
4762 made by appending @file{.mudflap} to the source file name.
4765 @opindex fdump-tree-sra
4766 Dump each function after performing scalar replacement of aggregates. The
4767 file name is made by appending @file{.sra} to the source file name.
4770 @opindex fdump-tree-sink
4771 Dump each function after performing code sinking. The file name is made
4772 by appending @file{.sink} to the source file name.
4775 @opindex fdump-tree-dom
4776 Dump each function after applying dominator tree optimizations. The file
4777 name is made by appending @file{.dom} to the source file name.
4780 @opindex fdump-tree-dse
4781 Dump each function after applying dead store elimination. The file
4782 name is made by appending @file{.dse} to the source file name.
4785 @opindex fdump-tree-phiopt
4786 Dump each function after optimizing PHI nodes into straightline code. The file
4787 name is made by appending @file{.phiopt} to the source file name.
4790 @opindex fdump-tree-forwprop
4791 Dump each function after forward propagating single use variables. The file
4792 name is made by appending @file{.forwprop} to the source file name.
4795 @opindex fdump-tree-copyrename
4796 Dump each function after applying the copy rename optimization. The file
4797 name is made by appending @file{.copyrename} to the source file name.
4800 @opindex fdump-tree-nrv
4801 Dump each function after applying the named return value optimization on
4802 generic trees. The file name is made by appending @file{.nrv} to the source
4806 @opindex fdump-tree-vect
4807 Dump each function after applying vectorization of loops. The file name is
4808 made by appending @file{.vect} to the source file name.
4811 @opindex fdump-tree-vrp
4812 Dump each function after Value Range Propagation (VRP). The file name
4813 is made by appending @file{.vrp} to the source file name.
4816 @opindex fdump-tree-all
4817 Enable all the available tree dumps with the flags provided in this option.
4820 @item -ftree-vectorizer-verbose=@var{n}
4821 @opindex ftree-vectorizer-verbose
4822 This option controls the amount of debugging output the vectorizer prints.
4823 This information is written to standard error, unless
4824 @option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4825 in which case it is output to the usual dump listing file, @file{.vect}.
4826 For @var{n}=0 no diagnostic information is reported.
4827 If @var{n}=1 the vectorizer reports each loop that got vectorized,
4828 and the total number of loops that got vectorized.
4829 If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4830 the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4831 inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4832 level that @option{-fdump-tree-vect-stats} uses.
4833 Higher verbosity levels mean either more information dumped for each
4834 reported loop, or same amount of information reported for more loops:
4835 If @var{n}=3, alignment related information is added to the reports.
4836 If @var{n}=4, data-references related information (e.g. memory dependences,
4837 memory access-patterns) is added to the reports.
4838 If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4839 that did not pass the first analysis phase (i.e. may not be countable, or
4840 may have complicated control-flow).
4841 If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4842 For @var{n}=7, all the information the vectorizer generates during its
4843 analysis and transformation is reported. This is the same verbosity level
4844 that @option{-fdump-tree-vect-details} uses.
4846 @item -frandom-seed=@var{string}
4847 @opindex frandom-string
4848 This option provides a seed that GCC uses when it would otherwise use
4849 random numbers. It is used to generate certain symbol names
4850 that have to be different in every compiled file. It is also used to
4851 place unique stamps in coverage data files and the object files that
4852 produce them. You can use the @option{-frandom-seed} option to produce
4853 reproducibly identical object files.
4855 The @var{string} should be different for every file you compile.
4857 @item -fsched-verbose=@var{n}
4858 @opindex fsched-verbose
4859 On targets that use instruction scheduling, this option controls the
4860 amount of debugging output the scheduler prints. This information is
4861 written to standard error, unless @option{-dS} or @option{-dR} is
4862 specified, in which case it is output to the usual dump
4863 listing file, @file{.sched} or @file{.sched2} respectively. However
4864 for @var{n} greater than nine, the output is always printed to standard
4867 For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4868 same information as @option{-dRS}. For @var{n} greater than one, it
4869 also output basic block probabilities, detailed ready list information
4870 and unit/insn info. For @var{n} greater than two, it includes RTL
4871 at abort point, control-flow and regions info. And for @var{n} over
4872 four, @option{-fsched-verbose} also includes dependence info.
4876 Store the usual ``temporary'' intermediate files permanently; place them
4877 in the current directory and name them based on the source file. Thus,
4878 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4879 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4880 preprocessed @file{foo.i} output file even though the compiler now
4881 normally uses an integrated preprocessor.
4883 When used in combination with the @option{-x} command line option,
4884 @option{-save-temps} is sensible enough to avoid over writing an
4885 input source file with the same extension as an intermediate file.
4886 The corresponding intermediate file may be obtained by renaming the
4887 source file before using @option{-save-temps}.
4891 Report the CPU time taken by each subprocess in the compilation
4892 sequence. For C source files, this is the compiler proper and assembler
4893 (plus the linker if linking is done). The output looks like this:
4900 The first number on each line is the ``user time'', that is time spent
4901 executing the program itself. The second number is ``system time'',
4902 time spent executing operating system routines on behalf of the program.
4903 Both numbers are in seconds.
4905 @item -fvar-tracking
4906 @opindex fvar-tracking
4907 Run variable tracking pass. It computes where variables are stored at each
4908 position in code. Better debugging information is then generated
4909 (if the debugging information format supports this information).
4911 It is enabled by default when compiling with optimization (@option{-Os},
4912 @option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4913 the debug info format supports it.
4915 @item -print-file-name=@var{library}
4916 @opindex print-file-name
4917 Print the full absolute name of the library file @var{library} that
4918 would be used when linking---and don't do anything else. With this
4919 option, GCC does not compile or link anything; it just prints the
4922 @item -print-multi-directory
4923 @opindex print-multi-directory
4924 Print the directory name corresponding to the multilib selected by any
4925 other switches present in the command line. This directory is supposed
4926 to exist in @env{GCC_EXEC_PREFIX}.
4928 @item -print-multi-lib
4929 @opindex print-multi-lib
4930 Print the mapping from multilib directory names to compiler switches
4931 that enable them. The directory name is separated from the switches by
4932 @samp{;}, and each switch starts with an @samp{@@} instead of the
4933 @samp{-}, without spaces between multiple switches. This is supposed to
4934 ease shell-processing.
4936 @item -print-prog-name=@var{program}
4937 @opindex print-prog-name
4938 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4940 @item -print-libgcc-file-name
4941 @opindex print-libgcc-file-name
4942 Same as @option{-print-file-name=libgcc.a}.
4944 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4945 but you do want to link with @file{libgcc.a}. You can do
4948 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4951 @item -print-search-dirs
4952 @opindex print-search-dirs
4953 Print the name of the configured installation directory and a list of
4954 program and library directories @command{gcc} will search---and don't do anything else.
4956 This is useful when @command{gcc} prints the error message
4957 @samp{installation problem, cannot exec cpp0: No such file or directory}.
4958 To resolve this you either need to put @file{cpp0} and the other compiler
4959 components where @command{gcc} expects to find them, or you can set the environment
4960 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4961 Don't forget the trailing @samp{/}.
4962 @xref{Environment Variables}.
4964 @item -print-sysroot-headers-suffix
4965 @opindex print-sysroot-headers-suffix
4966 Print the suffix added to the target sysroot when searching for
4967 headers, or give an error if the compiler is not configured with such
4968 a suffix---and don't do anything else.
4971 @opindex dumpmachine
4972 Print the compiler's target machine (for example,
4973 @samp{i686-pc-linux-gnu})---and don't do anything else.
4976 @opindex dumpversion
4977 Print the compiler version (for example, @samp{3.0})---and don't do
4982 Print the compiler's built-in specs---and don't do anything else. (This
4983 is used when GCC itself is being built.) @xref{Spec Files}.
4985 @item -feliminate-unused-debug-types
4986 @opindex feliminate-unused-debug-types
4987 Normally, when producing DWARF2 output, GCC will emit debugging
4988 information for all types declared in a compilation
4989 unit, regardless of whether or not they are actually used
4990 in that compilation unit. Sometimes this is useful, such as
4991 if, in the debugger, you want to cast a value to a type that is
4992 not actually used in your program (but is declared). More often,
4993 however, this results in a significant amount of wasted space.
4994 With this option, GCC will avoid producing debug symbol output
4995 for types that are nowhere used in the source file being compiled.
4998 @node Optimize Options
4999 @section Options That Control Optimization
5000 @cindex optimize options
5001 @cindex options, optimization
5003 These options control various sorts of optimizations.
5005 Without any optimization option, the compiler's goal is to reduce the
5006 cost of compilation and to make debugging produce the expected
5007 results. Statements are independent: if you stop the program with a
5008 breakpoint between statements, you can then assign a new value to any
5009 variable or change the program counter to any other statement in the
5010 function and get exactly the results you would expect from the source
5013 Turning on optimization flags makes the compiler attempt to improve
5014 the performance and/or code size at the expense of compilation time
5015 and possibly the ability to debug the program.
5017 The compiler performs optimization based on the knowledge it has of
5018 the program. Optimization levels @option{-O} and above, in
5019 particular, enable @emph{unit-at-a-time} mode, which allows the
5020 compiler to consider information gained from later functions in
5021 the file when compiling a function. Compiling multiple files at
5022 once to a single output file in @emph{unit-at-a-time} mode allows
5023 the compiler to use information gained from all of the files when
5024 compiling each of them.
5026 Not all optimizations are controlled directly by a flag. Only
5027 optimizations that have a flag are listed.
5034 Optimize. Optimizing compilation takes somewhat more time, and a lot
5035 more memory for a large function.
5037 With @option{-O}, the compiler tries to reduce code size and execution
5038 time, without performing any optimizations that take a great deal of
5041 @option{-O} turns on the following optimization flags:
5044 -fcprop-registers @gol
5047 -fdelayed-branch @gol
5049 -fguess-branch-probability @gol
5050 -fif-conversion2 @gol
5051 -fif-conversion @gol
5052 -finline-small-functions @gol
5053 -fipa-pure-const @gol
5054 -fipa-reference @gol
5056 -fsplit-wide-types @gol
5059 -ftree-copyrename @gol
5061 -ftree-dominator-opts @gol
5068 @option{-O} also turns on @option{-fomit-frame-pointer} on machines
5069 where doing so does not interfere with debugging.
5073 Optimize even more. GCC performs nearly all supported optimizations
5074 that do not involve a space-speed tradeoff. The compiler does not
5075 perform loop unrolling or function inlining when you specify @option{-O2}.
5076 As compared to @option{-O}, this option increases both compilation time
5077 and the performance of the generated code.
5079 @option{-O2} turns on all optimization flags specified by @option{-O}. It
5080 also turns on the following optimization flags:
5081 @gccoptlist{-fthread-jumps @gol
5082 -falign-functions -falign-jumps @gol
5083 -falign-loops -falign-labels @gol
5086 -fcse-follow-jumps -fcse-skip-blocks @gol
5087 -fdelete-null-pointer-checks @gol
5088 -fexpensive-optimizations @gol
5089 -fgcse -fgcse-lm @gol
5090 -foptimize-sibling-calls @gol
5093 -freorder-blocks -freorder-functions @gol
5094 -frerun-cse-after-loop @gol
5095 -fsched-interblock -fsched-spec @gol
5096 -fschedule-insns -fschedule-insns2 @gol
5097 -fstrict-aliasing -fstrict-overflow @gol
5101 Please note the warning under @option{-fgcse} about
5102 invoking @option{-O2} on programs that use computed gotos.
5106 Optimize yet more. @option{-O3} turns on all optimizations specified by
5107 @option{-O2} and also turns on the @option{-finline-functions},
5108 @option{-funswitch-loops}, @option{-fpredictive-commoning} and
5109 @option{-fgcse-after-reload} options.
5113 Reduce compilation time and make debugging produce the expected
5114 results. This is the default.
5118 Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
5119 do not typically increase code size. It also performs further
5120 optimizations designed to reduce code size.
5122 @option{-Os} disables the following optimization flags:
5123 @gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
5124 -falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
5125 -fprefetch-loop-arrays -ftree-vect-loop-version}
5127 If you use multiple @option{-O} options, with or without level numbers,
5128 the last such option is the one that is effective.
5131 Options of the form @option{-f@var{flag}} specify machine-independent
5132 flags. Most flags have both positive and negative forms; the negative
5133 form of @option{-ffoo} would be @option{-fno-foo}. In the table
5134 below, only one of the forms is listed---the one you typically will
5135 use. You can figure out the other form by either removing @samp{no-}
5138 The following options control specific optimizations. They are either
5139 activated by @option{-O} options or are related to ones that are. You
5140 can use the following flags in the rare cases when ``fine-tuning'' of
5141 optimizations to be performed is desired.
5144 @item -fno-default-inline
5145 @opindex fno-default-inline
5146 Do not make member functions inline by default merely because they are
5147 defined inside the class scope (C++ only). Otherwise, when you specify
5148 @w{@option{-O}}, member functions defined inside class scope are compiled
5149 inline by default; i.e., you don't need to add @samp{inline} in front of
5150 the member function name.
5152 @item -fno-defer-pop
5153 @opindex fno-defer-pop
5154 Always pop the arguments to each function call as soon as that function
5155 returns. For machines which must pop arguments after a function call,
5156 the compiler normally lets arguments accumulate on the stack for several
5157 function calls and pops them all at once.
5159 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5161 @item -fforward-propagate
5162 @opindex fforward-propagate
5163 Perform a forward propagation pass on RTL. The pass tries to combine two
5164 instructions and checks if the result can be simplified. If loop unrolling
5165 is active, two passes are performed and the second is scheduled after
5168 This option is enabled by default at optimization levels @option{-O2},
5169 @option{-O3}, @option{-Os}.
5171 @item -fomit-frame-pointer
5172 @opindex fomit-frame-pointer
5173 Don't keep the frame pointer in a register for functions that
5174 don't need one. This avoids the instructions to save, set up and
5175 restore frame pointers; it also makes an extra register available
5176 in many functions. @strong{It also makes debugging impossible on
5179 On some machines, such as the VAX, this flag has no effect, because
5180 the standard calling sequence automatically handles the frame pointer
5181 and nothing is saved by pretending it doesn't exist. The
5182 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
5183 whether a target machine supports this flag. @xref{Registers,,Register
5184 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
5186 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5188 @item -foptimize-sibling-calls
5189 @opindex foptimize-sibling-calls
5190 Optimize sibling and tail recursive calls.
5192 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5196 Don't pay attention to the @code{inline} keyword. Normally this option
5197 is used to keep the compiler from expanding any functions inline.
5198 Note that if you are not optimizing, no functions can be expanded inline.
5200 @item -finline-small-functions
5201 @opindex finline-small-functions
5202 Integrate functions into their callers when their body is smaller than expected
5203 function call code (so overall size of program gets smaller). The compiler
5204 heuristically decides which functions are simple enough to be worth integrating
5207 Enabled at level @option{-O2}.
5209 @item -finline-functions
5210 @opindex finline-functions
5211 Integrate all simple functions into their callers. The compiler
5212 heuristically decides which functions are simple enough to be worth
5213 integrating in this way.
5215 If all calls to a given function are integrated, and the function is
5216 declared @code{static}, then the function is normally not output as
5217 assembler code in its own right.
5219 Enabled at level @option{-O3}.
5221 @item -finline-functions-called-once
5222 @opindex finline-functions-called-once
5223 Consider all @code{static} functions called once for inlining into their
5224 caller even if they are not marked @code{inline}. If a call to a given
5225 function is integrated, then the function is not output as assembler code
5228 Enabled if @option{-funit-at-a-time} is enabled.
5230 @item -fearly-inlining
5231 @opindex fearly-inlining
5232 Inline functions marked by @code{always_inline} and functions whose body seems
5233 smaller than the function call overhead early before doing
5234 @option{-fprofile-generate} instrumentation and real inlining pass. Doing so
5235 makes profiling significantly cheaper and usually inlining faster on programs
5236 having large chains of nested wrapper functions.
5240 @item -finline-limit=@var{n}
5241 @opindex finline-limit
5242 By default, GCC limits the size of functions that can be inlined. This flag
5243 allows the control of this limit for functions that are explicitly marked as
5244 inline (i.e., marked with the inline keyword or defined within the class
5245 definition in c++). @var{n} is the size of functions that can be inlined in
5246 number of pseudo instructions (not counting parameter handling). The default
5247 value of @var{n} is 600.
5248 Increasing this value can result in more inlined code at
5249 the cost of compilation time and memory consumption. Decreasing usually makes
5250 the compilation faster and less code will be inlined (which presumably
5251 means slower programs). This option is particularly useful for programs that
5252 use inlining heavily such as those based on recursive templates with C++.
5254 Inlining is actually controlled by a number of parameters, which may be
5255 specified individually by using @option{--param @var{name}=@var{value}}.
5256 The @option{-finline-limit=@var{n}} option sets some of these parameters
5260 @item max-inline-insns-single
5261 is set to @var{n}/2.
5262 @item max-inline-insns-auto
5263 is set to @var{n}/2.
5264 @item min-inline-insns
5265 is set to 130 or @var{n}/4, whichever is smaller.
5266 @item max-inline-insns-rtl
5270 See below for a documentation of the individual
5271 parameters controlling inlining.
5273 @emph{Note:} pseudo instruction represents, in this particular context, an
5274 abstract measurement of function's size. In no way does it represent a count
5275 of assembly instructions and as such its exact meaning might change from one
5276 release to an another.
5278 @item -fkeep-inline-functions
5279 @opindex fkeep-inline-functions
5280 In C, emit @code{static} functions that are declared @code{inline}
5281 into the object file, even if the function has been inlined into all
5282 of its callers. This switch does not affect functions using the
5283 @code{extern inline} extension in GNU C89@. In C++, emit any and all
5284 inline functions into the object file.
5286 @item -fkeep-static-consts
5287 @opindex fkeep-static-consts
5288 Emit variables declared @code{static const} when optimization isn't turned
5289 on, even if the variables aren't referenced.
5291 GCC enables this option by default. If you want to force the compiler to
5292 check if the variable was referenced, regardless of whether or not
5293 optimization is turned on, use the @option{-fno-keep-static-consts} option.
5295 @item -fmerge-constants
5296 @opindex fmerge-constants
5297 Attempt to merge identical constants (string constants and floating point
5298 constants) across compilation units.
5300 This option is the default for optimized compilation if the assembler and
5301 linker support it. Use @option{-fno-merge-constants} to inhibit this
5304 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5306 @item -fmerge-all-constants
5307 @opindex fmerge-all-constants
5308 Attempt to merge identical constants and identical variables.
5310 This option implies @option{-fmerge-constants}. In addition to
5311 @option{-fmerge-constants} this considers e.g.@: even constant initialized
5312 arrays or initialized constant variables with integral or floating point
5313 types. Languages like C or C++ require each non-automatic variable to
5314 have distinct location, so using this option will result in non-conforming
5317 @item -fmodulo-sched
5318 @opindex fmodulo-sched
5319 Perform swing modulo scheduling immediately before the first scheduling
5320 pass. This pass looks at innermost loops and reorders their
5321 instructions by overlapping different iterations.
5323 @item -fmodulo-sched-allow-regmoves
5324 @opindex fmodulo-sched-allow-regmoves
5325 Perform more aggressive SMS based modulo scheduling with register moves
5326 allowed. By setting this flag certain anti-dependences edges will be
5327 deleted which will trigger the generation of reg-moves based on the
5328 life-range analysis. This option is effective only with
5329 @option{-fmodulo-sched} enabled.
5331 @item -fno-branch-count-reg
5332 @opindex fno-branch-count-reg
5333 Do not use ``decrement and branch'' instructions on a count register,
5334 but instead generate a sequence of instructions that decrement a
5335 register, compare it against zero, then branch based upon the result.
5336 This option is only meaningful on architectures that support such
5337 instructions, which include x86, PowerPC, IA-64 and S/390.
5339 The default is @option{-fbranch-count-reg}.
5341 @item -fno-function-cse
5342 @opindex fno-function-cse
5343 Do not put function addresses in registers; make each instruction that
5344 calls a constant function contain the function's address explicitly.
5346 This option results in less efficient code, but some strange hacks
5347 that alter the assembler output may be confused by the optimizations
5348 performed when this option is not used.
5350 The default is @option{-ffunction-cse}
5352 @item -fno-zero-initialized-in-bss
5353 @opindex fno-zero-initialized-in-bss
5354 If the target supports a BSS section, GCC by default puts variables that
5355 are initialized to zero into BSS@. This can save space in the resulting
5358 This option turns off this behavior because some programs explicitly
5359 rely on variables going to the data section. E.g., so that the
5360 resulting executable can find the beginning of that section and/or make
5361 assumptions based on that.
5363 The default is @option{-fzero-initialized-in-bss}.
5365 @item -fmudflap -fmudflapth -fmudflapir
5369 @cindex bounds checking
5371 For front-ends that support it (C and C++), instrument all risky
5372 pointer/array dereferencing operations, some standard library
5373 string/heap functions, and some other associated constructs with
5374 range/validity tests. Modules so instrumented should be immune to
5375 buffer overflows, invalid heap use, and some other classes of C/C++
5376 programming errors. The instrumentation relies on a separate runtime
5377 library (@file{libmudflap}), which will be linked into a program if
5378 @option{-fmudflap} is given at link time. Run-time behavior of the
5379 instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
5380 environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
5383 Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
5384 link if your program is multi-threaded. Use @option{-fmudflapir}, in
5385 addition to @option{-fmudflap} or @option{-fmudflapth}, if
5386 instrumentation should ignore pointer reads. This produces less
5387 instrumentation (and therefore faster execution) and still provides
5388 some protection against outright memory corrupting writes, but allows
5389 erroneously read data to propagate within a program.
5391 @item -fthread-jumps
5392 @opindex fthread-jumps
5393 Perform optimizations where we check to see if a jump branches to a
5394 location where another comparison subsumed by the first is found. If
5395 so, the first branch is redirected to either the destination of the
5396 second branch or a point immediately following it, depending on whether
5397 the condition is known to be true or false.
5399 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5401 @item -fsplit-wide-types
5402 @opindex fsplit-wide-types
5403 When using a type that occupies multiple registers, such as @code{long
5404 long} on a 32-bit system, split the registers apart and allocate them
5405 independently. This normally generates better code for those types,
5406 but may make debugging more difficult.
5408 Enabled at levels @option{-O}, @option{-O2}, @option{-O3},
5411 @item -fcse-follow-jumps
5412 @opindex fcse-follow-jumps
5413 In common subexpression elimination (CSE), scan through jump instructions
5414 when the target of the jump is not reached by any other path. For
5415 example, when CSE encounters an @code{if} statement with an
5416 @code{else} clause, CSE will follow the jump when the condition
5419 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5421 @item -fcse-skip-blocks
5422 @opindex fcse-skip-blocks
5423 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
5424 follow jumps which conditionally skip over blocks. When CSE
5425 encounters a simple @code{if} statement with no else clause,
5426 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
5427 body of the @code{if}.
5429 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5431 @item -frerun-cse-after-loop
5432 @opindex frerun-cse-after-loop
5433 Re-run common subexpression elimination after loop optimizations has been
5436 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5440 Perform a global common subexpression elimination pass.
5441 This pass also performs global constant and copy propagation.
5443 @emph{Note:} When compiling a program using computed gotos, a GCC
5444 extension, you may get better runtime performance if you disable
5445 the global common subexpression elimination pass by adding
5446 @option{-fno-gcse} to the command line.
5448 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5452 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
5453 attempt to move loads which are only killed by stores into themselves. This
5454 allows a loop containing a load/store sequence to be changed to a load outside
5455 the loop, and a copy/store within the loop.
5457 Enabled by default when gcse is enabled.
5461 When @option{-fgcse-sm} is enabled, a store motion pass is run after
5462 global common subexpression elimination. This pass will attempt to move
5463 stores out of loops. When used in conjunction with @option{-fgcse-lm},
5464 loops containing a load/store sequence can be changed to a load before
5465 the loop and a store after the loop.
5467 Not enabled at any optimization level.
5471 When @option{-fgcse-las} is enabled, the global common subexpression
5472 elimination pass eliminates redundant loads that come after stores to the
5473 same memory location (both partial and full redundancies).
5475 Not enabled at any optimization level.
5477 @item -fgcse-after-reload
5478 @opindex fgcse-after-reload
5479 When @option{-fgcse-after-reload} is enabled, a redundant load elimination
5480 pass is performed after reload. The purpose of this pass is to cleanup
5483 @item -funsafe-loop-optimizations
5484 @opindex funsafe-loop-optimizations
5485 If given, the loop optimizer will assume that loop indices do not
5486 overflow, and that the loops with nontrivial exit condition are not
5487 infinite. This enables a wider range of loop optimizations even if
5488 the loop optimizer itself cannot prove that these assumptions are valid.
5489 Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
5490 if it finds this kind of loop.
5492 @item -fcrossjumping
5493 @opindex fcrossjumping
5494 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
5495 resulting code may or may not perform better than without cross-jumping.
5497 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5499 @item -fauto-inc-dec
5500 @opindex fauto-inc-dec
5501 Combine increments or decrements of addresses with memory accesses.
5502 This pass is always skipped on architectures that do not have
5503 instructions to support this. Enabled by default at @option{-O} and
5504 higher on architectures that support this.
5508 Perform dead code elimination (DCE) on RTL.
5509 Enabled by default at @option{-O} and higher.
5513 Perform dead store elimination (DSE) on RTL.
5514 Enabled by default at @option{-O} and higher.
5516 @item -fif-conversion
5517 @opindex fif-conversion
5518 Attempt to transform conditional jumps into branch-less equivalents. This
5519 include use of conditional moves, min, max, set flags and abs instructions, and
5520 some tricks doable by standard arithmetics. The use of conditional execution
5521 on chips where it is available is controlled by @code{if-conversion2}.
5523 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5525 @item -fif-conversion2
5526 @opindex fif-conversion2
5527 Use conditional execution (where available) to transform conditional jumps into
5528 branch-less equivalents.
5530 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5532 @item -fdelete-null-pointer-checks
5533 @opindex fdelete-null-pointer-checks
5534 Use global dataflow analysis to identify and eliminate useless checks
5535 for null pointers. The compiler assumes that dereferencing a null
5536 pointer would have halted the program. If a pointer is checked after
5537 it has already been dereferenced, it cannot be null.
5539 In some environments, this assumption is not true, and programs can
5540 safely dereference null pointers. Use
5541 @option{-fno-delete-null-pointer-checks} to disable this optimization
5542 for programs which depend on that behavior.
5544 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5546 @item -fexpensive-optimizations
5547 @opindex fexpensive-optimizations
5548 Perform a number of minor optimizations that are relatively expensive.
5550 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5552 @item -foptimize-register-move
5554 @opindex foptimize-register-move
5556 Attempt to reassign register numbers in move instructions and as
5557 operands of other simple instructions in order to maximize the amount of
5558 register tying. This is especially helpful on machines with two-operand
5561 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
5564 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5566 @item -fdelayed-branch
5567 @opindex fdelayed-branch
5568 If supported for the target machine, attempt to reorder instructions
5569 to exploit instruction slots available after delayed branch
5572 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5574 @item -fschedule-insns
5575 @opindex fschedule-insns
5576 If supported for the target machine, attempt to reorder instructions to
5577 eliminate execution stalls due to required data being unavailable. This
5578 helps machines that have slow floating point or memory load instructions
5579 by allowing other instructions to be issued until the result of the load
5580 or floating point instruction is required.
5582 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5584 @item -fschedule-insns2
5585 @opindex fschedule-insns2
5586 Similar to @option{-fschedule-insns}, but requests an additional pass of
5587 instruction scheduling after register allocation has been done. This is
5588 especially useful on machines with a relatively small number of
5589 registers and where memory load instructions take more than one cycle.
5591 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5593 @item -fno-sched-interblock
5594 @opindex fno-sched-interblock
5595 Don't schedule instructions across basic blocks. This is normally
5596 enabled by default when scheduling before register allocation, i.e.@:
5597 with @option{-fschedule-insns} or at @option{-O2} or higher.
5599 @item -fno-sched-spec
5600 @opindex fno-sched-spec
5601 Don't allow speculative motion of non-load instructions. This is normally
5602 enabled by default when scheduling before register allocation, i.e.@:
5603 with @option{-fschedule-insns} or at @option{-O2} or higher.
5605 @item -fsched-spec-load
5606 @opindex fsched-spec-load
5607 Allow speculative motion of some load instructions. This only makes
5608 sense when scheduling before register allocation, i.e.@: with
5609 @option{-fschedule-insns} or at @option{-O2} or higher.
5611 @item -fsched-spec-load-dangerous
5612 @opindex fsched-spec-load-dangerous
5613 Allow speculative motion of more load instructions. This only makes
5614 sense when scheduling before register allocation, i.e.@: with
5615 @option{-fschedule-insns} or at @option{-O2} or higher.
5617 @item -fsched-stalled-insns
5618 @itemx -fsched-stalled-insns=@var{n}
5619 @opindex fsched-stalled-insns
5620 Define how many insns (if any) can be moved prematurely from the queue
5621 of stalled insns into the ready list, during the second scheduling pass.
5622 @option{-fno-sched-stalled-insns} means that no insns will be moved
5623 prematurely, @option{-fsched-stalled-insns=0} means there is no limit
5624 on how many queued insns can be moved prematurely.
5625 @option{-fsched-stalled-insns} without a value is equivalent to
5626 @option{-fsched-stalled-insns=1}.
5628 @item -fsched-stalled-insns-dep
5629 @itemx -fsched-stalled-insns-dep=@var{n}
5630 @opindex fsched-stalled-insns-dep
5631 Define how many insn groups (cycles) will be examined for a dependency
5632 on a stalled insn that is candidate for premature removal from the queue
5633 of stalled insns. This has an effect only during the second scheduling pass,
5634 and only if @option{-fsched-stalled-insns} is used.
5635 @option{-fno-sched-stalled-insns-dep} is equivalent to
5636 @option{-fsched-stalled-insns-dep=0}.
5637 @option{-fsched-stalled-insns-dep} without a value is equivalent to
5638 @option{-fsched-stalled-insns-dep=1}.
5640 @item -fsched2-use-superblocks
5641 @opindex fsched2-use-superblocks
5642 When scheduling after register allocation, do use superblock scheduling
5643 algorithm. Superblock scheduling allows motion across basic block boundaries
5644 resulting on faster schedules. This option is experimental, as not all machine
5645 descriptions used by GCC model the CPU closely enough to avoid unreliable
5646 results from the algorithm.
5648 This only makes sense when scheduling after register allocation, i.e.@: with
5649 @option{-fschedule-insns2} or at @option{-O2} or higher.
5651 @item -fsched2-use-traces
5652 @opindex fsched2-use-traces
5653 Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
5654 allocation and additionally perform code duplication in order to increase the
5655 size of superblocks using tracer pass. See @option{-ftracer} for details on
5658 This mode should produce faster but significantly longer programs. Also
5659 without @option{-fbranch-probabilities} the traces constructed may not
5660 match the reality and hurt the performance. This only makes
5661 sense when scheduling after register allocation, i.e.@: with
5662 @option{-fschedule-insns2} or at @option{-O2} or higher.
5666 Eliminate redundant sign extension instructions and move the non-redundant
5667 ones to optimal placement using lazy code motion (LCM).
5669 @item -freschedule-modulo-scheduled-loops
5670 @opindex freschedule-modulo-scheduled-loops
5671 The modulo scheduling comes before the traditional scheduling, if a loop
5672 was modulo scheduled we may want to prevent the later scheduling passes
5673 from changing its schedule, we use this option to control that.
5675 @item -fcaller-saves
5676 @opindex fcaller-saves
5677 Enable values to be allocated in registers that will be clobbered by
5678 function calls, by emitting extra instructions to save and restore the
5679 registers around such calls. Such allocation is done only when it
5680 seems to result in better code than would otherwise be produced.
5682 This option is always enabled by default on certain machines, usually
5683 those which have no call-preserved registers to use instead.
5685 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5687 @item -ftree-reassoc
5688 @opindex ftree-reassoc
5689 Perform reassociation on trees. This flag is enabled by default
5690 at @option{-O} and higher.
5694 Perform partial redundancy elimination (PRE) on trees. This flag is
5695 enabled by default at @option{-O2} and @option{-O3}.
5699 Perform full redundancy elimination (FRE) on trees. The difference
5700 between FRE and PRE is that FRE only considers expressions
5701 that are computed on all paths leading to the redundant computation.
5702 This analysis is faster than PRE, though it exposes fewer redundancies.
5703 This flag is enabled by default at @option{-O} and higher.
5705 @item -ftree-copy-prop
5706 @opindex ftree-copy-prop
5707 Perform copy propagation on trees. This pass eliminates unnecessary
5708 copy operations. This flag is enabled by default at @option{-O} and
5712 @opindex ftree-salias
5713 Perform structural alias analysis on trees. This flag
5714 is enabled by default at @option{-O} and higher.
5716 @item -fipa-pure-const
5717 @opindex fipa-pure-const
5718 Discover which functions are pure or constant.
5719 Enabled by default at @option{-O} and higher.
5721 @item -fipa-reference
5722 @opindex fipa-reference
5723 Discover which static variables do not escape cannot escape the
5725 Enabled by default at @option{-O} and higher.
5727 @item -fipa-struct-reorg
5728 @opindex fipa-struct-reorg
5729 Perform structure reorganization optimization, that change C-like structures
5730 layout in order to better utilize spatial locality. This transformation is
5731 affective for programs containing arrays of structures. Available in two
5732 compilation modes: profile-based (enabled with @option{-fprofile-generate})
5733 or static (which uses built-in heuristics). Require @option{-fipa-type-escape}
5734 to provide the safety of this transformation. It works only in whole program
5735 mode, so it requires @option{-fwhole-program} and @option{-combine} to be
5736 enabled. Structures considered @samp{cold} by this transformation are not
5737 affected (see @option{--param struct-reorg-cold-struct-ratio=@var{value}}).
5739 With this flag, the program debug info reflects a new structure layout.
5743 Perform interprocedural pointer analysis.
5747 Perform interprocedural constant propagation.
5748 This optimization analyzes the program to determine when values passed
5749 to functions are constants and then optimizes accordingly.
5750 This optimization can substantially increase performance
5751 if the application has constants passed to functions, but
5752 because this optimization can create multiple copies of functions,
5753 it may significantly increase code size.
5755 @item -fipa-matrix-reorg
5756 @opindex fipa-matrix-reorg
5757 Perform matrix flattening and transposing.
5758 Matrix flattening tries to replace a m-dimensional matrix
5759 with its equivalent n-dimensional matrix, where n < m.
5760 This reduces the level of indirection needed for accessing the elements
5761 of the matrix. The second optimization is matrix transposing that
5762 attemps to change the order of the matrix's dimensions in order to
5763 improve cache locality.
5764 Both optimizations need fwhole-program flag.
5765 Transposing is enabled only if profiling information is avaliable.
5770 Perform forward store motion on trees. This flag is
5771 enabled by default at @option{-O} and higher.
5775 Perform sparse conditional constant propagation (CCP) on trees. This
5776 pass only operates on local scalar variables and is enabled by default
5777 at @option{-O} and higher.
5779 @item -ftree-store-ccp
5780 @opindex ftree-store-ccp
5781 Perform sparse conditional constant propagation (CCP) on trees. This
5782 pass operates on both local scalar variables and memory stores and
5783 loads (global variables, structures, arrays, etc). This flag is
5784 enabled by default at @option{-O2} and higher.
5788 Perform dead code elimination (DCE) on trees. This flag is enabled by
5789 default at @option{-O} and higher.
5791 @item -ftree-dominator-opts
5792 @opindex ftree-dominator-opts
5793 Perform a variety of simple scalar cleanups (constant/copy
5794 propagation, redundancy elimination, range propagation and expression
5795 simplification) based on a dominator tree traversal. This also
5796 performs jump threading (to reduce jumps to jumps). This flag is
5797 enabled by default at @option{-O} and higher.
5801 Perform dead store elimination (DSE) on trees. A dead store is a store into
5802 a memory location which will later be overwritten by another store without
5803 any intervening loads. In this case the earlier store can be deleted. This
5804 flag is enabled by default at @option{-O} and higher.
5808 Perform loop header copying on trees. This is beneficial since it increases
5809 effectiveness of code motion optimizations. It also saves one jump. This flag
5810 is enabled by default at @option{-O} and higher. It is not enabled
5811 for @option{-Os}, since it usually increases code size.
5813 @item -ftree-loop-optimize
5814 @opindex ftree-loop-optimize
5815 Perform loop optimizations on trees. This flag is enabled by default
5816 at @option{-O} and higher.
5818 @item -ftree-loop-linear
5819 @opindex ftree-loop-linear
5820 Perform linear loop transformations on tree. This flag can improve cache
5821 performance and allow further loop optimizations to take place.
5823 @item -fcheck-data-deps
5824 @opindex fcheck-data-deps
5825 Compare the results of several data dependence analyzers. This option
5826 is used for debugging the data dependence analyzers.
5828 @item -ftree-loop-im
5829 @opindex ftree-loop-im
5830 Perform loop invariant motion on trees. This pass moves only invariants that
5831 would be hard to handle at RTL level (function calls, operations that expand to
5832 nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5833 operands of conditions that are invariant out of the loop, so that we can use
5834 just trivial invariantness analysis in loop unswitching. The pass also includes
5837 @item -ftree-loop-ivcanon
5838 @opindex ftree-loop-ivcanon
5839 Create a canonical counter for number of iterations in the loop for that
5840 determining number of iterations requires complicated analysis. Later
5841 optimizations then may determine the number easily. Useful especially
5842 in connection with unrolling.
5846 Perform induction variable optimizations (strength reduction, induction
5847 variable merging and induction variable elimination) on trees.
5849 @item -ftree-parallelize-loops=n
5850 @opindex ftree-parallelize-loops
5851 Parallelize loops, i.e., split their iteration space to run in n threads.
5852 This is only possible for loops whose iterations are independent
5853 and can be arbitrarily reordered. The optimization is only
5854 profitable on multiprocessor machines, for loops that are CPU-intensive,
5855 rather than constrained e.g. by memory bandwidth. This option
5856 implies @option{-pthread}, and thus is only supported on targets
5857 that have support for @option{-pthread}.
5861 Perform scalar replacement of aggregates. This pass replaces structure
5862 references with scalars to prevent committing structures to memory too
5863 early. This flag is enabled by default at @option{-O} and higher.
5865 @item -ftree-copyrename
5866 @opindex ftree-copyrename
5867 Perform copy renaming on trees. This pass attempts to rename compiler
5868 temporaries to other variables at copy locations, usually resulting in
5869 variable names which more closely resemble the original variables. This flag
5870 is enabled by default at @option{-O} and higher.
5874 Perform temporary expression replacement during the SSA->normal phase. Single
5875 use/single def temporaries are replaced at their use location with their
5876 defining expression. This results in non-GIMPLE code, but gives the expanders
5877 much more complex trees to work on resulting in better RTL generation. This is
5878 enabled by default at @option{-O} and higher.
5880 @item -ftree-vectorize
5881 @opindex ftree-vectorize
5882 Perform loop vectorization on trees.
5884 @item -ftree-vect-loop-version
5885 @opindex ftree-vect-loop-version
5886 Perform loop versioning when doing loop vectorization on trees. When a loop
5887 appears to be vectorizable except that data alignment or data dependence cannot
5888 be determined at compile time then vectorized and non-vectorized versions of
5889 the loop are generated along with runtime checks for alignment or dependence
5890 to control which version is executed. This option is enabled by default
5891 except at level @option{-Os} where it is disabled.
5893 @item -fvect-cost-model
5894 @opindex fvect-cost-model
5895 Enable cost model for vectorization.
5899 Perform Value Range Propagation on trees. This is similar to the
5900 constant propagation pass, but instead of values, ranges of values are
5901 propagated. This allows the optimizers to remove unnecessary range
5902 checks like array bound checks and null pointer checks. This is
5903 enabled by default at @option{-O2} and higher. Null pointer check
5904 elimination is only done if @option{-fdelete-null-pointer-checks} is
5909 Perform tail duplication to enlarge superblock size. This transformation
5910 simplifies the control flow of the function allowing other optimizations to do
5913 @item -funroll-loops
5914 @opindex funroll-loops
5915 Unroll loops whose number of iterations can be determined at compile
5916 time or upon entry to the loop. @option{-funroll-loops} implies
5917 @option{-frerun-cse-after-loop}. This option makes code larger,
5918 and may or may not make it run faster.
5920 @item -funroll-all-loops
5921 @opindex funroll-all-loops
5922 Unroll all loops, even if their number of iterations is uncertain when
5923 the loop is entered. This usually makes programs run more slowly.
5924 @option{-funroll-all-loops} implies the same options as
5925 @option{-funroll-loops},
5927 @item -fsplit-ivs-in-unroller
5928 @opindex fsplit-ivs-in-unroller
5929 Enables expressing of values of induction variables in later iterations
5930 of the unrolled loop using the value in the first iteration. This breaks
5931 long dependency chains, thus improving efficiency of the scheduling passes.
5933 Combination of @option{-fweb} and CSE is often sufficient to obtain the
5934 same effect. However in cases the loop body is more complicated than
5935 a single basic block, this is not reliable. It also does not work at all
5936 on some of the architectures due to restrictions in the CSE pass.
5938 This optimization is enabled by default.
5940 @item -fvariable-expansion-in-unroller
5941 @opindex fvariable-expansion-in-unroller
5942 With this option, the compiler will create multiple copies of some
5943 local variables when unrolling a loop which can result in superior code.
5945 @item -fpredictive-commoning
5946 @opindex fpredictive-commoning
5947 Perform predictive commoning optimization, i.e., reusing computations
5948 (especially memory loads and stores) performed in previous
5949 iterations of loops.
5951 This option is enabled at level @option{-O3}.
5953 @item -fprefetch-loop-arrays
5954 @opindex fprefetch-loop-arrays
5955 If supported by the target machine, generate instructions to prefetch
5956 memory to improve the performance of loops that access large arrays.
5958 This option may generate better or worse code; results are highly
5959 dependent on the structure of loops within the source code.
5961 Disabled at level @option{-Os}.
5964 @itemx -fno-peephole2
5965 @opindex fno-peephole
5966 @opindex fno-peephole2
5967 Disable any machine-specific peephole optimizations. The difference
5968 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5969 are implemented in the compiler; some targets use one, some use the
5970 other, a few use both.
5972 @option{-fpeephole} is enabled by default.
5973 @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5975 @item -fno-guess-branch-probability
5976 @opindex fno-guess-branch-probability
5977 Do not guess branch probabilities using heuristics.
5979 GCC will use heuristics to guess branch probabilities if they are
5980 not provided by profiling feedback (@option{-fprofile-arcs}). These
5981 heuristics are based on the control flow graph. If some branch probabilities
5982 are specified by @samp{__builtin_expect}, then the heuristics will be
5983 used to guess branch probabilities for the rest of the control flow graph,
5984 taking the @samp{__builtin_expect} info into account. The interactions
5985 between the heuristics and @samp{__builtin_expect} can be complex, and in
5986 some cases, it may be useful to disable the heuristics so that the effects
5987 of @samp{__builtin_expect} are easier to understand.
5989 The default is @option{-fguess-branch-probability} at levels
5990 @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5992 @item -freorder-blocks
5993 @opindex freorder-blocks
5994 Reorder basic blocks in the compiled function in order to reduce number of
5995 taken branches and improve code locality.
5997 Enabled at levels @option{-O2}, @option{-O3}.
5999 @item -freorder-blocks-and-partition
6000 @opindex freorder-blocks-and-partition
6001 In addition to reordering basic blocks in the compiled function, in order
6002 to reduce number of taken branches, partitions hot and cold basic blocks
6003 into separate sections of the assembly and .o files, to improve
6004 paging and cache locality performance.
6006 This optimization is automatically turned off in the presence of
6007 exception handling, for linkonce sections, for functions with a user-defined
6008 section attribute and on any architecture that does not support named
6011 @item -freorder-functions
6012 @opindex freorder-functions
6013 Reorder functions in the object file in order to
6014 improve code locality. This is implemented by using special
6015 subsections @code{.text.hot} for most frequently executed functions and
6016 @code{.text.unlikely} for unlikely executed functions. Reordering is done by
6017 the linker so object file format must support named sections and linker must
6018 place them in a reasonable way.
6020 Also profile feedback must be available in to make this option effective. See
6021 @option{-fprofile-arcs} for details.
6023 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6025 @item -fstrict-aliasing
6026 @opindex fstrict-aliasing
6027 Allows the compiler to assume the strictest aliasing rules applicable to
6028 the language being compiled. For C (and C++), this activates
6029 optimizations based on the type of expressions. In particular, an
6030 object of one type is assumed never to reside at the same address as an
6031 object of a different type, unless the types are almost the same. For
6032 example, an @code{unsigned int} can alias an @code{int}, but not a
6033 @code{void*} or a @code{double}. A character type may alias any other
6036 Pay special attention to code like this:
6049 The practice of reading from a different union member than the one most
6050 recently written to (called ``type-punning'') is common. Even with
6051 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
6052 is accessed through the union type. So, the code above will work as
6053 expected. However, this code might not:
6064 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6066 @item -fstrict-overflow
6067 @opindex fstrict-overflow
6068 Allow the compiler to assume strict signed overflow rules, depending
6069 on the language being compiled. For C (and C++) this means that
6070 overflow when doing arithmetic with signed numbers is undefined, which
6071 means that the compiler may assume that it will not happen. This
6072 permits various optimizations. For example, the compiler will assume
6073 that an expression like @code{i + 10 > i} will always be true for
6074 signed @code{i}. This assumption is only valid if signed overflow is
6075 undefined, as the expression is false if @code{i + 10} overflows when
6076 using twos complement arithmetic. When this option is in effect any
6077 attempt to determine whether an operation on signed numbers will
6078 overflow must be written carefully to not actually involve overflow.
6080 See also the @option{-fwrapv} option. Using @option{-fwrapv} means
6081 that signed overflow is fully defined: it wraps. When
6082 @option{-fwrapv} is used, there is no difference between
6083 @option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
6084 @option{-fwrapv} certain types of overflow are permitted. For
6085 example, if the compiler gets an overflow when doing arithmetic on
6086 constants, the overflowed value can still be used with
6087 @option{-fwrapv}, but not otherwise.
6089 The @option{-fstrict-overflow} option is enabled at levels
6090 @option{-O2}, @option{-O3}, @option{-Os}.
6092 @item -falign-functions
6093 @itemx -falign-functions=@var{n}
6094 @opindex falign-functions
6095 Align the start of functions to the next power-of-two greater than
6096 @var{n}, skipping up to @var{n} bytes. For instance,
6097 @option{-falign-functions=32} aligns functions to the next 32-byte
6098 boundary, but @option{-falign-functions=24} would align to the next
6099 32-byte boundary only if this can be done by skipping 23 bytes or less.
6101 @option{-fno-align-functions} and @option{-falign-functions=1} are
6102 equivalent and mean that functions will not be aligned.
6104 Some assemblers only support this flag when @var{n} is a power of two;
6105 in that case, it is rounded up.
6107 If @var{n} is not specified or is zero, use a machine-dependent default.
6109 Enabled at levels @option{-O2}, @option{-O3}.
6111 @item -falign-labels
6112 @itemx -falign-labels=@var{n}
6113 @opindex falign-labels
6114 Align all branch targets to a power-of-two boundary, skipping up to
6115 @var{n} bytes like @option{-falign-functions}. This option can easily
6116 make code slower, because it must insert dummy operations for when the
6117 branch target is reached in the usual flow of the code.
6119 @option{-fno-align-labels} and @option{-falign-labels=1} are
6120 equivalent and mean that labels will not be aligned.
6122 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
6123 are greater than this value, then their values are used instead.
6125 If @var{n} is not specified or is zero, use a machine-dependent default
6126 which is very likely to be @samp{1}, meaning no alignment.
6128 Enabled at levels @option{-O2}, @option{-O3}.
6131 @itemx -falign-loops=@var{n}
6132 @opindex falign-loops
6133 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
6134 like @option{-falign-functions}. The hope is that the loop will be
6135 executed many times, which will make up for any execution of the dummy
6138 @option{-fno-align-loops} and @option{-falign-loops=1} are
6139 equivalent and mean that loops will not be aligned.
6141 If @var{n} is not specified or is zero, use a machine-dependent default.
6143 Enabled at levels @option{-O2}, @option{-O3}.
6146 @itemx -falign-jumps=@var{n}
6147 @opindex falign-jumps
6148 Align branch targets to a power-of-two boundary, for branch targets
6149 where the targets can only be reached by jumping, skipping up to @var{n}
6150 bytes like @option{-falign-functions}. In this case, no dummy operations
6153 @option{-fno-align-jumps} and @option{-falign-jumps=1} are
6154 equivalent and mean that loops will not be aligned.
6156 If @var{n} is not specified or is zero, use a machine-dependent default.
6158 Enabled at levels @option{-O2}, @option{-O3}.
6160 @item -funit-at-a-time
6161 @opindex funit-at-a-time
6162 Parse the whole compilation unit before starting to produce code.
6163 This allows some extra optimizations to take place but consumes
6164 more memory (in general). There are some compatibility issues
6165 with @emph{unit-at-a-time} mode:
6168 enabling @emph{unit-at-a-time} mode may change the order
6169 in which functions, variables, and top-level @code{asm} statements
6170 are emitted, and will likely break code relying on some particular
6171 ordering. The majority of such top-level @code{asm} statements,
6172 though, can be replaced by @code{section} attributes. The
6173 @option{fno-toplevel-reorder} option may be used to keep the ordering
6174 used in the input file, at the cost of some optimizations.
6177 @emph{unit-at-a-time} mode removes unreferenced static variables
6178 and functions. This may result in undefined references
6179 when an @code{asm} statement refers directly to variables or functions
6180 that are otherwise unused. In that case either the variable/function
6181 shall be listed as an operand of the @code{asm} statement operand or,
6182 in the case of top-level @code{asm} statements the attribute @code{used}
6183 shall be used on the declaration.
6186 Static functions now can use non-standard passing conventions that
6187 may break @code{asm} statements calling functions directly. Again,
6188 attribute @code{used} will prevent this behavior.
6191 As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
6192 but this scheme may not be supported by future releases of GCC@.
6194 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6196 @item -fno-toplevel-reorder
6197 @opindex fno-toplevel-reorder
6198 Do not reorder top-level functions, variables, and @code{asm}
6199 statements. Output them in the same order that they appear in the
6200 input file. When this option is used, unreferenced static variables
6201 will not be removed. This option is intended to support existing code
6202 which relies on a particular ordering. For new code, it is better to
6207 Constructs webs as commonly used for register allocation purposes and assign
6208 each web individual pseudo register. This allows the register allocation pass
6209 to operate on pseudos directly, but also strengthens several other optimization
6210 passes, such as CSE, loop optimizer and trivial dead code remover. It can,
6211 however, make debugging impossible, since variables will no longer stay in a
6214 Enabled by default with @option{-funroll-loops}.
6216 @item -fwhole-program
6217 @opindex fwhole-program
6218 Assume that the current compilation unit represents whole program being
6219 compiled. All public functions and variables with the exception of @code{main}
6220 and those merged by attribute @code{externally_visible} become static functions
6221 and in a affect gets more aggressively optimized by interprocedural optimizers.
6222 While this option is equivalent to proper use of @code{static} keyword for
6223 programs consisting of single file, in combination with option
6224 @option{--combine} this flag can be used to compile most of smaller scale C
6225 programs since the functions and variables become local for the whole combined
6226 compilation unit, not for the single source file itself.
6228 This option is not supported for Fortran programs.
6230 @item -fcprop-registers
6231 @opindex fcprop-registers
6232 After register allocation and post-register allocation instruction splitting,
6233 we perform a copy-propagation pass to try to reduce scheduling dependencies
6234 and occasionally eliminate the copy.
6236 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6238 @item -fprofile-generate
6239 @opindex fprofile-generate
6241 Enable options usually used for instrumenting application to produce
6242 profile useful for later recompilation with profile feedback based
6243 optimization. You must use @option{-fprofile-generate} both when
6244 compiling and when linking your program.
6246 The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
6249 @opindex fprofile-use
6250 Enable profile feedback directed optimizations, and optimizations
6251 generally profitable only with profile feedback available.
6253 The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
6254 @code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
6256 By default, GCC emits an error message if the feedback profiles do not
6257 match the source code. This error can be turned into a warning by using
6258 @option{-Wcoverage-mismatch}. Note this may result in poorly optimized
6262 The following options control compiler behavior regarding floating
6263 point arithmetic. These options trade off between speed and
6264 correctness. All must be specifically enabled.
6268 @opindex ffloat-store
6269 Do not store floating point variables in registers, and inhibit other
6270 options that might change whether a floating point value is taken from a
6273 @cindex floating point precision
6274 This option prevents undesirable excess precision on machines such as
6275 the 68000 where the floating registers (of the 68881) keep more
6276 precision than a @code{double} is supposed to have. Similarly for the
6277 x86 architecture. For most programs, the excess precision does only
6278 good, but a few programs rely on the precise definition of IEEE floating
6279 point. Use @option{-ffloat-store} for such programs, after modifying
6280 them to store all pertinent intermediate computations into variables.
6284 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations},
6285 @option{-ffinite-math-only}, @option{-fno-rounding-math},
6286 @option{-fno-signaling-nans} and @option{-fcx-limited-range}.
6288 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
6290 This option is not turned on by any @option{-O} option since
6291 it can result in incorrect output for programs which depend on
6292 an exact implementation of IEEE or ISO rules/specifications for
6293 math functions. It may, however, yield faster code for programs
6294 that do not require the guarantees of these specifications.
6296 @item -fno-math-errno
6297 @opindex fno-math-errno
6298 Do not set ERRNO after calling math functions that are executed
6299 with a single instruction, e.g., sqrt. A program that relies on
6300 IEEE exceptions for math error handling may want to use this flag
6301 for speed while maintaining IEEE arithmetic compatibility.
6303 This option is not turned on by any @option{-O} option since
6304 it can result in incorrect output for programs which depend on
6305 an exact implementation of IEEE or ISO rules/specifications for
6306 math functions. It may, however, yield faster code for programs
6307 that do not require the guarantees of these specifications.
6309 The default is @option{-fmath-errno}.
6311 On Darwin systems, the math library never sets @code{errno}. There is
6312 therefore no reason for the compiler to consider the possibility that
6313 it might, and @option{-fno-math-errno} is the default.
6315 @item -funsafe-math-optimizations
6316 @opindex funsafe-math-optimizations
6318 Allow optimizations for floating-point arithmetic that (a) assume
6319 that arguments and results are valid and (b) may violate IEEE or
6320 ANSI standards. When used at link-time, it may include libraries
6321 or startup files that change the default FPU control word or other
6322 similar optimizations.
6324 This option is not turned on by any @option{-O} option since
6325 it can result in incorrect output for programs which depend on
6326 an exact implementation of IEEE or ISO rules/specifications for
6327 math functions. It may, however, yield faster code for programs
6328 that do not require the guarantees of these specifications.
6329 Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math},
6330 @option{-fassociative-math} and @option{-freciprocal-math}.
6332 The default is @option{-fno-unsafe-math-optimizations}.
6334 @item -fassociative-math
6335 @opindex fassociative-math
6337 Allow re-association of operands in series of floating-point operations.
6338 This violates the ISO C and C++ language standard by possibly changing
6339 computation result. NOTE: re-ordering may change the sign of zero as
6340 well as ignore NaNs and inhibit or create underflow or overflow (and
6341 thus cannot be used on a code which relies on rounding behavior like
6342 @code{(x + 2**52) - 2**52)}. May also reorder floating-point comparisons
6343 and thus may not be used when ordered comparisons are required.
6344 This option requires that both @option{-fno-signed-zeros} and
6345 @option{-fno-trapping-math} be in effect. Moreover, it doesn't make
6346 much sense with @option{-frounding-math}.
6348 The default is @option{-fno-associative-math}.
6350 @item -freciprocal-math
6351 @opindex freciprocal-math
6353 Allow the reciprocal of a value to be used instead of dividing by
6354 the value if this enables optimizations. For example @code{x / y}
6355 can be replaced with @code{x * (1/y)} which is useful if @code{(1/y)}
6356 is subject to common subexpression elimination. Note that this loses
6357 precision and increases the number of flops operating on the value.
6359 The default is @option{-fno-reciprocal-math}.
6361 @item -ffinite-math-only
6362 @opindex ffinite-math-only
6363 Allow optimizations for floating-point arithmetic that assume
6364 that arguments and results are not NaNs or +-Infs.
6366 This option is not turned on by any @option{-O} option since
6367 it can result in incorrect output for programs which depend on
6368 an exact implementation of IEEE or ISO rules/specifications for
6369 math functions. It may, however, yield faster code for programs
6370 that do not require the guarantees of these specifications.
6372 The default is @option{-fno-finite-math-only}.
6374 @item -fno-signed-zeros
6375 @opindex fno-signed-zeros
6376 Allow optimizations for floating point arithmetic that ignore the
6377 signedness of zero. IEEE arithmetic specifies the behavior of
6378 distinct +0.0 and @minus{}0.0 values, which then prohibits simplification
6379 of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}).
6380 This option implies that the sign of a zero result isn't significant.
6382 The default is @option{-fsigned-zeros}.
6384 @item -fno-trapping-math
6385 @opindex fno-trapping-math
6386 Compile code assuming that floating-point operations cannot generate
6387 user-visible traps. These traps include division by zero, overflow,
6388 underflow, inexact result and invalid operation. This option requires
6389 that @option{-fno-signaling-nans} be in effect. Setting this option may
6390 allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example.
6392 This option should never be turned on by any @option{-O} option since
6393 it can result in incorrect output for programs which depend on
6394 an exact implementation of IEEE or ISO rules/specifications for
6397 The default is @option{-ftrapping-math}.
6399 @item -frounding-math
6400 @opindex frounding-math
6401 Disable transformations and optimizations that assume default floating
6402 point rounding behavior. This is round-to-zero for all floating point
6403 to integer conversions, and round-to-nearest for all other arithmetic
6404 truncations. This option should be specified for programs that change
6405 the FP rounding mode dynamically, or that may be executed with a
6406 non-default rounding mode. This option disables constant folding of
6407 floating point expressions at compile-time (which may be affected by
6408 rounding mode) and arithmetic transformations that are unsafe in the
6409 presence of sign-dependent rounding modes.
6411 The default is @option{-fno-rounding-math}.
6413 This option is experimental and does not currently guarantee to
6414 disable all GCC optimizations that are affected by rounding mode.
6415 Future versions of GCC may provide finer control of this setting
6416 using C99's @code{FENV_ACCESS} pragma. This command line option
6417 will be used to specify the default state for @code{FENV_ACCESS}.
6419 @item -frtl-abstract-sequences
6420 @opindex frtl-abstract-sequences
6421 It is a size optimization method. This option is to find identical
6422 sequences of code, which can be turned into pseudo-procedures and
6423 then replace all occurrences with calls to the newly created
6424 subroutine. It is kind of an opposite of @option{-finline-functions}.
6425 This optimization runs at RTL level.
6427 @item -fsignaling-nans
6428 @opindex fsignaling-nans
6429 Compile code assuming that IEEE signaling NaNs may generate user-visible
6430 traps during floating-point operations. Setting this option disables
6431 optimizations that may change the number of exceptions visible with
6432 signaling NaNs. This option implies @option{-ftrapping-math}.
6434 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
6437 The default is @option{-fno-signaling-nans}.
6439 This option is experimental and does not currently guarantee to
6440 disable all GCC optimizations that affect signaling NaN behavior.
6442 @item -fsingle-precision-constant
6443 @opindex fsingle-precision-constant
6444 Treat floating point constant as single precision constant instead of
6445 implicitly converting it to double precision constant.
6447 @item -fcx-limited-range
6448 @opindex fcx-limited-range
6449 When enabled, this option states that a range reduction step is not
6450 needed when performing complex division. The default is
6451 @option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
6453 This option controls the default setting of the ISO C99
6454 @code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
6459 The following options control optimizations that may improve
6460 performance, but are not enabled by any @option{-O} options. This
6461 section includes experimental options that may produce broken code.
6464 @item -fbranch-probabilities
6465 @opindex fbranch-probabilities
6466 After running a program compiled with @option{-fprofile-arcs}
6467 (@pxref{Debugging Options,, Options for Debugging Your Program or
6468 @command{gcc}}), you can compile it a second time using
6469 @option{-fbranch-probabilities}, to improve optimizations based on
6470 the number of times each branch was taken. When the program
6471 compiled with @option{-fprofile-arcs} exits it saves arc execution
6472 counts to a file called @file{@var{sourcename}.gcda} for each source
6473 file. The information in this data file is very dependent on the
6474 structure of the generated code, so you must use the same source code
6475 and the same optimization options for both compilations.
6477 With @option{-fbranch-probabilities}, GCC puts a
6478 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
6479 These can be used to improve optimization. Currently, they are only
6480 used in one place: in @file{reorg.c}, instead of guessing which path a
6481 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
6482 exactly determine which path is taken more often.
6484 @item -fprofile-values
6485 @opindex fprofile-values
6486 If combined with @option{-fprofile-arcs}, it adds code so that some
6487 data about values of expressions in the program is gathered.
6489 With @option{-fbranch-probabilities}, it reads back the data gathered
6490 from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
6491 notes to instructions for their later usage in optimizations.
6493 Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
6497 If combined with @option{-fprofile-arcs}, it instructs the compiler to add
6498 a code to gather information about values of expressions.
6500 With @option{-fbranch-probabilities}, it reads back the data gathered
6501 and actually performs the optimizations based on them.
6502 Currently the optimizations include specialization of division operation
6503 using the knowledge about the value of the denominator.
6505 @item -frename-registers
6506 @opindex frename-registers
6507 Attempt to avoid false dependencies in scheduled code by making use
6508 of registers left over after register allocation. This optimization
6509 will most benefit processors with lots of registers. Depending on the
6510 debug information format adopted by the target, however, it can
6511 make debugging impossible, since variables will no longer stay in
6512 a ``home register''.
6514 Enabled by default with @option{-funroll-loops}.
6518 Perform tail duplication to enlarge superblock size. This transformation
6519 simplifies the control flow of the function allowing other optimizations to do
6522 Enabled with @option{-fprofile-use}.
6524 @item -funroll-loops
6525 @opindex funroll-loops
6526 Unroll loops whose number of iterations can be determined at compile time or
6527 upon entry to the loop. @option{-funroll-loops} implies
6528 @option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
6529 It also turns on complete loop peeling (i.e.@: complete removal of loops with
6530 small constant number of iterations). This option makes code larger, and may
6531 or may not make it run faster.
6533 Enabled with @option{-fprofile-use}.
6535 @item -funroll-all-loops
6536 @opindex funroll-all-loops
6537 Unroll all loops, even if their number of iterations is uncertain when
6538 the loop is entered. This usually makes programs run more slowly.
6539 @option{-funroll-all-loops} implies the same options as
6540 @option{-funroll-loops}.
6543 @opindex fpeel-loops
6544 Peels the loops for that there is enough information that they do not
6545 roll much (from profile feedback). It also turns on complete loop peeling
6546 (i.e.@: complete removal of loops with small constant number of iterations).
6548 Enabled with @option{-fprofile-use}.
6550 @item -fmove-loop-invariants
6551 @opindex fmove-loop-invariants
6552 Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
6553 at level @option{-O1}
6555 @item -funswitch-loops
6556 @opindex funswitch-loops
6557 Move branches with loop invariant conditions out of the loop, with duplicates
6558 of the loop on both branches (modified according to result of the condition).
6560 @item -ffunction-sections
6561 @itemx -fdata-sections
6562 @opindex ffunction-sections
6563 @opindex fdata-sections
6564 Place each function or data item into its own section in the output
6565 file if the target supports arbitrary sections. The name of the
6566 function or the name of the data item determines the section's name
6569 Use these options on systems where the linker can perform optimizations
6570 to improve locality of reference in the instruction space. Most systems
6571 using the ELF object format and SPARC processors running Solaris 2 have
6572 linkers with such optimizations. AIX may have these optimizations in
6575 Only use these options when there are significant benefits from doing
6576 so. When you specify these options, the assembler and linker will
6577 create larger object and executable files and will also be slower.
6578 You will not be able to use @code{gprof} on all systems if you
6579 specify this option and you may have problems with debugging if
6580 you specify both this option and @option{-g}.
6582 @item -fbranch-target-load-optimize
6583 @opindex fbranch-target-load-optimize
6584 Perform branch target register load optimization before prologue / epilogue
6586 The use of target registers can typically be exposed only during reload,
6587 thus hoisting loads out of loops and doing inter-block scheduling needs
6588 a separate optimization pass.
6590 @item -fbranch-target-load-optimize2
6591 @opindex fbranch-target-load-optimize2
6592 Perform branch target register load optimization after prologue / epilogue
6595 @item -fbtr-bb-exclusive
6596 @opindex fbtr-bb-exclusive
6597 When performing branch target register load optimization, don't reuse
6598 branch target registers in within any basic block.
6600 @item -fstack-protector
6601 @opindex fstack-protector
6602 Emit extra code to check for buffer overflows, such as stack smashing
6603 attacks. This is done by adding a guard variable to functions with
6604 vulnerable objects. This includes functions that call alloca, and
6605 functions with buffers larger than 8 bytes. The guards are initialized
6606 when a function is entered and then checked when the function exits.
6607 If a guard check fails, an error message is printed and the program exits.
6609 @item -fstack-protector-all
6610 @opindex fstack-protector-all
6611 Like @option{-fstack-protector} except that all functions are protected.
6613 @item -fsection-anchors
6614 @opindex fsection-anchors
6615 Try to reduce the number of symbolic address calculations by using
6616 shared ``anchor'' symbols to address nearby objects. This transformation
6617 can help to reduce the number of GOT entries and GOT accesses on some
6620 For example, the implementation of the following function @code{foo}:
6624 int foo (void) @{ return a + b + c; @}
6627 would usually calculate the addresses of all three variables, but if you
6628 compile it with @option{-fsection-anchors}, it will access the variables
6629 from a common anchor point instead. The effect is similar to the
6630 following pseudocode (which isn't valid C):
6635 register int *xr = &x;
6636 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
6640 Not all targets support this option.
6642 @item --param @var{name}=@var{value}
6644 In some places, GCC uses various constants to control the amount of
6645 optimization that is done. For example, GCC will not inline functions
6646 that contain more that a certain number of instructions. You can
6647 control some of these constants on the command-line using the
6648 @option{--param} option.
6650 The names of specific parameters, and the meaning of the values, are
6651 tied to the internals of the compiler, and are subject to change
6652 without notice in future releases.
6654 In each case, the @var{value} is an integer. The allowable choices for
6655 @var{name} are given in the following table:
6658 @item salias-max-implicit-fields
6659 The maximum number of fields in a variable without direct
6660 structure accesses for which structure aliasing will consider trying
6661 to track each field. The default is 5
6663 @item salias-max-array-elements
6664 The maximum number of elements an array can have and its elements
6665 still be tracked individually by structure aliasing. The default is 4
6667 @item sra-max-structure-size
6668 The maximum structure size, in bytes, at which the scalar replacement
6669 of aggregates (SRA) optimization will perform block copies. The
6670 default value, 0, implies that GCC will select the most appropriate
6673 @item sra-field-structure-ratio
6674 The threshold ratio (as a percentage) between instantiated fields and
6675 the complete structure size. We say that if the ratio of the number
6676 of bytes in instantiated fields to the number of bytes in the complete
6677 structure exceeds this parameter, then block copies are not used. The
6680 @item struct-reorg-cold-struct-ratio
6681 The threshold ratio (as a percentage) between a structure frequency
6682 and the frequency of the hottest structure in the program. This parameter
6683 is used by struct-reorg optimization enabled by @option{-fipa-struct-reorg}.
6684 We say that if the ratio of a structure frequency, calculated by profiling,
6685 to the hottest structure frequency in the program is less than this
6686 parameter, then structure reorganization is not applied to this structure.
6689 @item max-crossjump-edges
6690 The maximum number of incoming edges to consider for crossjumping.
6691 The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
6692 the number of edges incoming to each block. Increasing values mean
6693 more aggressive optimization, making the compile time increase with
6694 probably small improvement in executable size.
6696 @item min-crossjump-insns
6697 The minimum number of instructions which must be matched at the end
6698 of two blocks before crossjumping will be performed on them. This
6699 value is ignored in the case where all instructions in the block being
6700 crossjumped from are matched. The default value is 5.
6702 @item max-grow-copy-bb-insns
6703 The maximum code size expansion factor when copying basic blocks
6704 instead of jumping. The expansion is relative to a jump instruction.
6705 The default value is 8.
6707 @item max-goto-duplication-insns
6708 The maximum number of instructions to duplicate to a block that jumps
6709 to a computed goto. To avoid @math{O(N^2)} behavior in a number of
6710 passes, GCC factors computed gotos early in the compilation process,
6711 and unfactors them as late as possible. Only computed jumps at the
6712 end of a basic blocks with no more than max-goto-duplication-insns are
6713 unfactored. The default value is 8.
6715 @item max-delay-slot-insn-search
6716 The maximum number of instructions to consider when looking for an
6717 instruction to fill a delay slot. If more than this arbitrary number of
6718 instructions is searched, the time savings from filling the delay slot
6719 will be minimal so stop searching. Increasing values mean more
6720 aggressive optimization, making the compile time increase with probably
6721 small improvement in executable run time.
6723 @item max-delay-slot-live-search
6724 When trying to fill delay slots, the maximum number of instructions to
6725 consider when searching for a block with valid live register
6726 information. Increasing this arbitrarily chosen value means more
6727 aggressive optimization, increasing the compile time. This parameter
6728 should be removed when the delay slot code is rewritten to maintain the
6731 @item max-gcse-memory
6732 The approximate maximum amount of memory that will be allocated in
6733 order to perform the global common subexpression elimination
6734 optimization. If more memory than specified is required, the
6735 optimization will not be done.
6737 @item max-gcse-passes
6738 The maximum number of passes of GCSE to run. The default is 1.
6740 @item max-pending-list-length
6741 The maximum number of pending dependencies scheduling will allow
6742 before flushing the current state and starting over. Large functions
6743 with few branches or calls can create excessively large lists which
6744 needlessly consume memory and resources.
6746 @item max-inline-insns-single
6747 Several parameters control the tree inliner used in gcc.
6748 This number sets the maximum number of instructions (counted in GCC's
6749 internal representation) in a single function that the tree inliner
6750 will consider for inlining. This only affects functions declared
6751 inline and methods implemented in a class declaration (C++).
6752 The default value is 450.
6754 @item max-inline-insns-auto
6755 When you use @option{-finline-functions} (included in @option{-O3}),
6756 a lot of functions that would otherwise not be considered for inlining
6757 by the compiler will be investigated. To those functions, a different
6758 (more restrictive) limit compared to functions declared inline can
6760 The default value is 90.
6762 @item large-function-insns
6763 The limit specifying really large functions. For functions larger than this
6764 limit after inlining inlining is constrained by
6765 @option{--param large-function-growth}. This parameter is useful primarily
6766 to avoid extreme compilation time caused by non-linear algorithms used by the
6768 This parameter is ignored when @option{-funit-at-a-time} is not used.
6769 The default value is 2700.
6771 @item large-function-growth
6772 Specifies maximal growth of large function caused by inlining in percents.
6773 This parameter is ignored when @option{-funit-at-a-time} is not used.
6774 The default value is 100 which limits large function growth to 2.0 times
6777 @item large-unit-insns
6778 The limit specifying large translation unit. Growth caused by inlining of
6779 units larger than this limit is limited by @option{--param inline-unit-growth}.
6780 For small units this might be too tight (consider unit consisting of function A
6781 that is inline and B that just calls A three time. If B is small relative to
6782 A, the growth of unit is 300\% and yet such inlining is very sane. For very
6783 large units consisting of small inlininable functions however the overall unit
6784 growth limit is needed to avoid exponential explosion of code size. Thus for
6785 smaller units, the size is increased to @option{--param large-unit-insns}
6786 before applying @option{--param inline-unit-growth}. The default is 10000
6788 @item inline-unit-growth
6789 Specifies maximal overall growth of the compilation unit caused by inlining.
6790 This parameter is ignored when @option{-funit-at-a-time} is not used.
6791 The default value is 30 which limits unit growth to 1.3 times the original
6794 @item large-stack-frame
6795 The limit specifying large stack frames. While inlining the algorithm is trying
6796 to not grow past this limit too much. Default value is 256 bytes.
6798 @item large-stack-frame-growth
6799 Specifies maximal growth of large stack frames caused by inlining in percents.
6800 The default value is 1000 which limits large stack frame growth to 11 times
6803 @item max-inline-insns-recursive
6804 @itemx max-inline-insns-recursive-auto
6805 Specifies maximum number of instructions out-of-line copy of self recursive inline
6806 function can grow into by performing recursive inlining.
6808 For functions declared inline @option{--param max-inline-insns-recursive} is
6809 taken into account. For function not declared inline, recursive inlining
6810 happens only when @option{-finline-functions} (included in @option{-O3}) is
6811 enabled and @option{--param max-inline-insns-recursive-auto} is used. The
6812 default value is 450.
6814 @item max-inline-recursive-depth
6815 @itemx max-inline-recursive-depth-auto
6816 Specifies maximum recursion depth used by the recursive inlining.
6818 For functions declared inline @option{--param max-inline-recursive-depth} is
6819 taken into account. For function not declared inline, recursive inlining
6820 happens only when @option{-finline-functions} (included in @option{-O3}) is
6821 enabled and @option{--param max-inline-recursive-depth-auto} is used. The
6824 @item min-inline-recursive-probability
6825 Recursive inlining is profitable only for function having deep recursion
6826 in average and can hurt for function having little recursion depth by
6827 increasing the prologue size or complexity of function body to other
6830 When profile feedback is available (see @option{-fprofile-generate}) the actual
6831 recursion depth can be guessed from probability that function will recurse via
6832 given call expression. This parameter limits inlining only to call expression
6833 whose probability exceeds given threshold (in percents). The default value is
6836 @item inline-call-cost
6837 Specify cost of call instruction relative to simple arithmetics operations
6838 (having cost of 1). Increasing this cost disqualifies inlining of non-leaf
6839 functions and at the same time increases size of leaf function that is believed to
6840 reduce function size by being inlined. In effect it increases amount of
6841 inlining for code having large abstraction penalty (many functions that just
6842 pass the arguments to other functions) and decrease inlining for code with low
6843 abstraction penalty. The default value is 12.
6845 @item min-vect-loop-bound
6846 The minimum number of iterations under which a loop will not get vectorized
6847 when @option{-ftree-vectorize} is used. The number of iterations after
6848 vectorization needs to be greater than the value specified by this option
6849 to allow vectorization. The default value is 0.
6851 @item max-unrolled-insns
6852 The maximum number of instructions that a loop should have if that loop
6853 is unrolled, and if the loop is unrolled, it determines how many times
6854 the loop code is unrolled.
6856 @item max-average-unrolled-insns
6857 The maximum number of instructions biased by probabilities of their execution
6858 that a loop should have if that loop is unrolled, and if the loop is unrolled,
6859 it determines how many times the loop code is unrolled.
6861 @item max-unroll-times
6862 The maximum number of unrollings of a single loop.
6864 @item max-peeled-insns
6865 The maximum number of instructions that a loop should have if that loop
6866 is peeled, and if the loop is peeled, it determines how many times
6867 the loop code is peeled.
6869 @item max-peel-times
6870 The maximum number of peelings of a single loop.
6872 @item max-completely-peeled-insns
6873 The maximum number of insns of a completely peeled loop.
6875 @item max-completely-peel-times
6876 The maximum number of iterations of a loop to be suitable for complete peeling.
6878 @item max-unswitch-insns
6879 The maximum number of insns of an unswitched loop.
6881 @item max-unswitch-level
6882 The maximum number of branches unswitched in a single loop.
6885 The minimum cost of an expensive expression in the loop invariant motion.
6887 @item iv-consider-all-candidates-bound
6888 Bound on number of candidates for induction variables below that
6889 all candidates are considered for each use in induction variable
6890 optimizations. Only the most relevant candidates are considered
6891 if there are more candidates, to avoid quadratic time complexity.
6893 @item iv-max-considered-uses
6894 The induction variable optimizations give up on loops that contain more
6895 induction variable uses.
6897 @item iv-always-prune-cand-set-bound
6898 If number of candidates in the set is smaller than this value,
6899 we always try to remove unnecessary ivs from the set during its
6900 optimization when a new iv is added to the set.
6902 @item scev-max-expr-size
6903 Bound on size of expressions used in the scalar evolutions analyzer.
6904 Large expressions slow the analyzer.
6906 @item omega-max-vars
6907 The maximum number of variables in an Omega constraint system.
6908 The default value is 128.
6910 @item omega-max-geqs
6911 The maximum number of inequalities in an Omega constraint system.
6912 The default value is 256.
6915 The maximum number of equalities in an Omega constraint system.
6916 The default value is 128.
6918 @item omega-max-wild-cards
6919 The maximum number of wildcard variables that the Omega solver will
6920 be able to insert. The default value is 18.
6922 @item omega-hash-table-size
6923 The size of the hash table in the Omega solver. The default value is
6926 @item omega-max-keys
6927 The maximal number of keys used by the Omega solver. The default
6930 @item omega-eliminate-redundant-constraints
6931 When set to 1, use expensive methods to eliminate all redundant
6932 constraints. The default value is 0.
6934 @item vect-max-version-for-alignment-checks
6935 The maximum number of runtime checks that can be performed when
6936 doing loop versioning for alignment in the vectorizer. See option
6937 ftree-vect-loop-version for more information.
6939 @item vect-max-version-for-alias-checks
6940 The maximum number of runtime checks that can be performed when
6941 doing loop versioning for alias in the vectorizer. See option
6942 ftree-vect-loop-version for more information.
6944 @item max-iterations-to-track
6946 The maximum number of iterations of a loop the brute force algorithm
6947 for analysis of # of iterations of the loop tries to evaluate.
6949 @item hot-bb-count-fraction
6950 Select fraction of the maximal count of repetitions of basic block in program
6951 given basic block needs to have to be considered hot.
6953 @item hot-bb-frequency-fraction
6954 Select fraction of the maximal frequency of executions of basic block in
6955 function given basic block needs to have to be considered hot
6957 @item max-predicted-iterations
6958 The maximum number of loop iterations we predict statically. This is useful
6959 in cases where function contain single loop with known bound and other loop
6960 with unknown. We predict the known number of iterations correctly, while
6961 the unknown number of iterations average to roughly 10. This means that the
6962 loop without bounds would appear artificially cold relative to the other one.
6964 @item align-threshold
6966 Select fraction of the maximal frequency of executions of basic block in
6967 function given basic block will get aligned.
6969 @item align-loop-iterations
6971 A loop expected to iterate at lest the selected number of iterations will get
6974 @item tracer-dynamic-coverage
6975 @itemx tracer-dynamic-coverage-feedback
6977 This value is used to limit superblock formation once the given percentage of
6978 executed instructions is covered. This limits unnecessary code size
6981 The @option{tracer-dynamic-coverage-feedback} is used only when profile
6982 feedback is available. The real profiles (as opposed to statically estimated
6983 ones) are much less balanced allowing the threshold to be larger value.
6985 @item tracer-max-code-growth
6986 Stop tail duplication once code growth has reached given percentage. This is
6987 rather hokey argument, as most of the duplicates will be eliminated later in
6988 cross jumping, so it may be set to much higher values than is the desired code
6991 @item tracer-min-branch-ratio
6993 Stop reverse growth when the reverse probability of best edge is less than this
6994 threshold (in percent).
6996 @item tracer-min-branch-ratio
6997 @itemx tracer-min-branch-ratio-feedback
6999 Stop forward growth if the best edge do have probability lower than this
7002 Similarly to @option{tracer-dynamic-coverage} two values are present, one for
7003 compilation for profile feedback and one for compilation without. The value
7004 for compilation with profile feedback needs to be more conservative (higher) in
7005 order to make tracer effective.
7007 @item max-cse-path-length
7009 Maximum number of basic blocks on path that cse considers. The default is 10.
7012 The maximum instructions CSE process before flushing. The default is 1000.
7014 @item max-aliased-vops
7016 Maximum number of virtual operands per function allowed to represent
7017 aliases before triggering the alias partitioning heuristic. Alias
7018 partitioning reduces compile times and memory consumption needed for
7019 aliasing at the expense of precision loss in alias information. The
7020 default value for this parameter is 100 for -O1, 500 for -O2 and 1000
7023 Notice that if a function contains more memory statements than the
7024 value of this parameter, it is not really possible to achieve this
7025 reduction. In this case, the compiler will use the number of memory
7026 statements as the value for @option{max-aliased-vops}.
7028 @item avg-aliased-vops
7030 Average number of virtual operands per statement allowed to represent
7031 aliases before triggering the alias partitioning heuristic. This
7032 works in conjunction with @option{max-aliased-vops}. If a function
7033 contains more than @option{max-aliased-vops} virtual operators, then
7034 memory symbols will be grouped into memory partitions until either the
7035 total number of virtual operators is below @option{max-aliased-vops}
7036 or the average number of virtual operators per memory statement is
7037 below @option{avg-aliased-vops}. The default value for this parameter
7038 is 1 for -O1 and -O2, and 3 for -O3.
7040 @item ggc-min-expand
7042 GCC uses a garbage collector to manage its own memory allocation. This
7043 parameter specifies the minimum percentage by which the garbage
7044 collector's heap should be allowed to expand between collections.
7045 Tuning this may improve compilation speed; it has no effect on code
7048 The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
7049 RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
7050 the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
7051 GCC is not able to calculate RAM on a particular platform, the lower
7052 bound of 30% is used. Setting this parameter and
7053 @option{ggc-min-heapsize} to zero causes a full collection to occur at
7054 every opportunity. This is extremely slow, but can be useful for
7057 @item ggc-min-heapsize
7059 Minimum size of the garbage collector's heap before it begins bothering
7060 to collect garbage. The first collection occurs after the heap expands
7061 by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
7062 tuning this may improve compilation speed, and has no effect on code
7065 The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
7066 tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
7067 with a lower bound of 4096 (four megabytes) and an upper bound of
7068 131072 (128 megabytes). If GCC is not able to calculate RAM on a
7069 particular platform, the lower bound is used. Setting this parameter
7070 very large effectively disables garbage collection. Setting this
7071 parameter and @option{ggc-min-expand} to zero causes a full collection
7072 to occur at every opportunity.
7074 @item max-reload-search-insns
7075 The maximum number of instruction reload should look backward for equivalent
7076 register. Increasing values mean more aggressive optimization, making the
7077 compile time increase with probably slightly better performance. The default
7080 @item max-cselib-memory-locations
7081 The maximum number of memory locations cselib should take into account.
7082 Increasing values mean more aggressive optimization, making the compile time
7083 increase with probably slightly better performance. The default value is 500.
7085 @item max-flow-memory-locations
7086 Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
7087 The default value is 100.
7089 @item reorder-blocks-duplicate
7090 @itemx reorder-blocks-duplicate-feedback
7092 Used by basic block reordering pass to decide whether to use unconditional
7093 branch or duplicate the code on its destination. Code is duplicated when its
7094 estimated size is smaller than this value multiplied by the estimated size of
7095 unconditional jump in the hot spots of the program.
7097 The @option{reorder-block-duplicate-feedback} is used only when profile
7098 feedback is available and may be set to higher values than
7099 @option{reorder-block-duplicate} since information about the hot spots is more
7102 @item max-sched-ready-insns
7103 The maximum number of instructions ready to be issued the scheduler should
7104 consider at any given time during the first scheduling pass. Increasing
7105 values mean more thorough searches, making the compilation time increase
7106 with probably little benefit. The default value is 100.
7108 @item max-sched-region-blocks
7109 The maximum number of blocks in a region to be considered for
7110 interblock scheduling. The default value is 10.
7112 @item max-sched-region-insns
7113 The maximum number of insns in a region to be considered for
7114 interblock scheduling. The default value is 100.
7117 The minimum probability (in percents) of reaching a source block
7118 for interblock speculative scheduling. The default value is 40.
7120 @item max-sched-extend-regions-iters
7121 The maximum number of iterations through CFG to extend regions.
7122 0 - disable region extension,
7123 N - do at most N iterations.
7124 The default value is 0.
7126 @item max-sched-insn-conflict-delay
7127 The maximum conflict delay for an insn to be considered for speculative motion.
7128 The default value is 3.
7130 @item sched-spec-prob-cutoff
7131 The minimal probability of speculation success (in percents), so that
7132 speculative insn will be scheduled.
7133 The default value is 40.
7135 @item max-last-value-rtl
7137 The maximum size measured as number of RTLs that can be recorded in an expression
7138 in combiner for a pseudo register as last known value of that register. The default
7141 @item integer-share-limit
7142 Small integer constants can use a shared data structure, reducing the
7143 compiler's memory usage and increasing its speed. This sets the maximum
7144 value of a shared integer constant's. The default value is 256.
7146 @item min-virtual-mappings
7147 Specifies the minimum number of virtual mappings in the incremental
7148 SSA updater that should be registered to trigger the virtual mappings
7149 heuristic defined by virtual-mappings-ratio. The default value is
7152 @item virtual-mappings-ratio
7153 If the number of virtual mappings is virtual-mappings-ratio bigger
7154 than the number of virtual symbols to be updated, then the incremental
7155 SSA updater switches to a full update for those symbols. The default
7158 @item ssp-buffer-size
7159 The minimum size of buffers (i.e. arrays) that will receive stack smashing
7160 protection when @option{-fstack-protection} is used.
7162 @item max-jump-thread-duplication-stmts
7163 Maximum number of statements allowed in a block that needs to be
7164 duplicated when threading jumps.
7166 @item max-fields-for-field-sensitive
7167 Maximum number of fields in a structure we will treat in
7168 a field sensitive manner during pointer analysis.
7170 @item prefetch-latency
7171 Estimate on average number of instructions that are executed before
7172 prefetch finishes. The distance we prefetch ahead is proportional
7173 to this constant. Increasing this number may also lead to less
7174 streams being prefetched (see @option{simultaneous-prefetches}).
7176 @item simultaneous-prefetches
7177 Maximum number of prefetches that can run at the same time.
7179 @item l1-cache-line-size
7180 The size of cache line in L1 cache, in bytes.
7183 The size of L1 cache, in kilobytes.
7186 The size of L2 cache, in kilobytes.
7188 @item use-canonical-types
7189 Whether the compiler should use the ``canonical'' type system. By
7190 default, this should always be 1, which uses a more efficient internal
7191 mechanism for comparing types in C++ and Objective-C++. However, if
7192 bugs in the canonical type system are causing compilation failures,
7193 set this value to 0 to disable canonical types.
7195 @item max-partial-antic-length
7196 Maximum length of the partial antic set computed during the tree
7197 partial redundancy elimination optimization (@option{-ftree-pre}) when
7198 optimizing at @option{-O3} and above. For some sorts of source code
7199 the enhanced partial redundancy elimination optimization can run away,
7200 consuming all of the memory available on the host machine. This
7201 parameter sets a limit on the length of the sets that are computed,
7202 which prevents the runaway behaviour. Setting a value of 0 for
7203 this paramter will allow an unlimited set length.
7205 @item sccvn-max-scc-size
7206 Maximum size of a strongly connected component (SCC) during SCCVN
7207 processing. If this limit is hit, SCCVN processing for the whole
7208 function will not be done and optimizations depending on it will
7209 be disabled. The default maximum SCC size is 10000.
7214 @node Preprocessor Options
7215 @section Options Controlling the Preprocessor
7216 @cindex preprocessor options
7217 @cindex options, preprocessor
7219 These options control the C preprocessor, which is run on each C source
7220 file before actual compilation.
7222 If you use the @option{-E} option, nothing is done except preprocessing.
7223 Some of these options make sense only together with @option{-E} because
7224 they cause the preprocessor output to be unsuitable for actual
7229 You can use @option{-Wp,@var{option}} to bypass the compiler driver
7230 and pass @var{option} directly through to the preprocessor. If
7231 @var{option} contains commas, it is split into multiple options at the
7232 commas. However, many options are modified, translated or interpreted
7233 by the compiler driver before being passed to the preprocessor, and
7234 @option{-Wp} forcibly bypasses this phase. The preprocessor's direct
7235 interface is undocumented and subject to change, so whenever possible
7236 you should avoid using @option{-Wp} and let the driver handle the
7239 @item -Xpreprocessor @var{option}
7240 @opindex preprocessor
7241 Pass @var{option} as an option to the preprocessor. You can use this to
7242 supply system-specific preprocessor options which GCC does not know how to
7245 If you want to pass an option that takes an argument, you must use
7246 @option{-Xpreprocessor} twice, once for the option and once for the argument.
7249 @include cppopts.texi
7251 @node Assembler Options
7252 @section Passing Options to the Assembler
7254 @c prevent bad page break with this line
7255 You can pass options to the assembler.
7258 @item -Wa,@var{option}
7260 Pass @var{option} as an option to the assembler. If @var{option}
7261 contains commas, it is split into multiple options at the commas.
7263 @item -Xassembler @var{option}
7265 Pass @var{option} as an option to the assembler. You can use this to
7266 supply system-specific assembler options which GCC does not know how to
7269 If you want to pass an option that takes an argument, you must use
7270 @option{-Xassembler} twice, once for the option and once for the argument.
7275 @section Options for Linking
7276 @cindex link options
7277 @cindex options, linking
7279 These options come into play when the compiler links object files into
7280 an executable output file. They are meaningless if the compiler is
7281 not doing a link step.
7285 @item @var{object-file-name}
7286 A file name that does not end in a special recognized suffix is
7287 considered to name an object file or library. (Object files are
7288 distinguished from libraries by the linker according to the file
7289 contents.) If linking is done, these object files are used as input
7298 If any of these options is used, then the linker is not run, and
7299 object file names should not be used as arguments. @xref{Overall
7303 @item -l@var{library}
7304 @itemx -l @var{library}
7306 Search the library named @var{library} when linking. (The second
7307 alternative with the library as a separate argument is only for
7308 POSIX compliance and is not recommended.)
7310 It makes a difference where in the command you write this option; the
7311 linker searches and processes libraries and object files in the order they
7312 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
7313 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
7314 to functions in @samp{z}, those functions may not be loaded.
7316 The linker searches a standard list of directories for the library,
7317 which is actually a file named @file{lib@var{library}.a}. The linker
7318 then uses this file as if it had been specified precisely by name.
7320 The directories searched include several standard system directories
7321 plus any that you specify with @option{-L}.
7323 Normally the files found this way are library files---archive files
7324 whose members are object files. The linker handles an archive file by
7325 scanning through it for members which define symbols that have so far
7326 been referenced but not defined. But if the file that is found is an
7327 ordinary object file, it is linked in the usual fashion. The only
7328 difference between using an @option{-l} option and specifying a file name
7329 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
7330 and searches several directories.
7334 You need this special case of the @option{-l} option in order to
7335 link an Objective-C or Objective-C++ program.
7338 @opindex nostartfiles
7339 Do not use the standard system startup files when linking.
7340 The standard system libraries are used normally, unless @option{-nostdlib}
7341 or @option{-nodefaultlibs} is used.
7343 @item -nodefaultlibs
7344 @opindex nodefaultlibs
7345 Do not use the standard system libraries when linking.
7346 Only the libraries you specify will be passed to the linker.
7347 The standard startup files are used normally, unless @option{-nostartfiles}
7348 is used. The compiler may generate calls to @code{memcmp},
7349 @code{memset}, @code{memcpy} and @code{memmove}.
7350 These entries are usually resolved by entries in
7351 libc. These entry points should be supplied through some other
7352 mechanism when this option is specified.
7356 Do not use the standard system startup files or libraries when linking.
7357 No startup files and only the libraries you specify will be passed to
7358 the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
7359 @code{memcpy} and @code{memmove}.
7360 These entries are usually resolved by entries in
7361 libc. These entry points should be supplied through some other
7362 mechanism when this option is specified.
7364 @cindex @option{-lgcc}, use with @option{-nostdlib}
7365 @cindex @option{-nostdlib} and unresolved references
7366 @cindex unresolved references and @option{-nostdlib}
7367 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
7368 @cindex @option{-nodefaultlibs} and unresolved references
7369 @cindex unresolved references and @option{-nodefaultlibs}
7370 One of the standard libraries bypassed by @option{-nostdlib} and
7371 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
7372 that GCC uses to overcome shortcomings of particular machines, or special
7373 needs for some languages.
7374 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
7375 Collection (GCC) Internals},
7376 for more discussion of @file{libgcc.a}.)
7377 In most cases, you need @file{libgcc.a} even when you want to avoid
7378 other standard libraries. In other words, when you specify @option{-nostdlib}
7379 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
7380 This ensures that you have no unresolved references to internal GCC
7381 library subroutines. (For example, @samp{__main}, used to ensure C++
7382 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
7383 GNU Compiler Collection (GCC) Internals}.)
7387 Produce a position independent executable on targets which support it.
7388 For predictable results, you must also specify the same set of options
7389 that were used to generate code (@option{-fpie}, @option{-fPIE},
7390 or model suboptions) when you specify this option.
7394 Pass the flag @option{-export-dynamic} to the ELF linker, on targets
7395 that support it. This instructs the linker to add all symbols, not
7396 only used ones, to the dynamic symbol table. This option is needed
7397 for some uses of @code{dlopen} or to allow obtaining backtraces
7398 from within a program.
7402 Remove all symbol table and relocation information from the executable.
7406 On systems that support dynamic linking, this prevents linking with the shared
7407 libraries. On other systems, this option has no effect.
7411 Produce a shared object which can then be linked with other objects to
7412 form an executable. Not all systems support this option. For predictable
7413 results, you must also specify the same set of options that were used to
7414 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
7415 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
7416 needs to build supplementary stub code for constructors to work. On
7417 multi-libbed systems, @samp{gcc -shared} must select the correct support
7418 libraries to link against. Failing to supply the correct flags may lead
7419 to subtle defects. Supplying them in cases where they are not necessary
7422 @item -shared-libgcc
7423 @itemx -static-libgcc
7424 @opindex shared-libgcc
7425 @opindex static-libgcc
7426 On systems that provide @file{libgcc} as a shared library, these options
7427 force the use of either the shared or static version respectively.
7428 If no shared version of @file{libgcc} was built when the compiler was
7429 configured, these options have no effect.
7431 There are several situations in which an application should use the
7432 shared @file{libgcc} instead of the static version. The most common
7433 of these is when the application wishes to throw and catch exceptions
7434 across different shared libraries. In that case, each of the libraries
7435 as well as the application itself should use the shared @file{libgcc}.
7437 Therefore, the G++ and GCJ drivers automatically add
7438 @option{-shared-libgcc} whenever you build a shared library or a main
7439 executable, because C++ and Java programs typically use exceptions, so
7440 this is the right thing to do.
7442 If, instead, you use the GCC driver to create shared libraries, you may
7443 find that they will not always be linked with the shared @file{libgcc}.
7444 If GCC finds, at its configuration time, that you have a non-GNU linker
7445 or a GNU linker that does not support option @option{--eh-frame-hdr},
7446 it will link the shared version of @file{libgcc} into shared libraries
7447 by default. Otherwise, it will take advantage of the linker and optimize
7448 away the linking with the shared version of @file{libgcc}, linking with
7449 the static version of libgcc by default. This allows exceptions to
7450 propagate through such shared libraries, without incurring relocation
7451 costs at library load time.
7453 However, if a library or main executable is supposed to throw or catch
7454 exceptions, you must link it using the G++ or GCJ driver, as appropriate
7455 for the languages used in the program, or using the option
7456 @option{-shared-libgcc}, such that it is linked with the shared
7461 Bind references to global symbols when building a shared object. Warn
7462 about any unresolved references (unless overridden by the link editor
7463 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
7466 @item -Xlinker @var{option}
7468 Pass @var{option} as an option to the linker. You can use this to
7469 supply system-specific linker options which GCC does not know how to
7472 If you want to pass an option that takes an argument, you must use
7473 @option{-Xlinker} twice, once for the option and once for the argument.
7474 For example, to pass @option{-assert definitions}, you must write
7475 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
7476 @option{-Xlinker "-assert definitions"}, because this passes the entire
7477 string as a single argument, which is not what the linker expects.
7479 @item -Wl,@var{option}
7481 Pass @var{option} as an option to the linker. If @var{option} contains
7482 commas, it is split into multiple options at the commas.
7484 @item -u @var{symbol}
7486 Pretend the symbol @var{symbol} is undefined, to force linking of
7487 library modules to define it. You can use @option{-u} multiple times with
7488 different symbols to force loading of additional library modules.
7491 @node Directory Options
7492 @section Options for Directory Search
7493 @cindex directory options
7494 @cindex options, directory search
7497 These options specify directories to search for header files, for
7498 libraries and for parts of the compiler:
7503 Add the directory @var{dir} to the head of the list of directories to be
7504 searched for header files. This can be used to override a system header
7505 file, substituting your own version, since these directories are
7506 searched before the system header file directories. However, you should
7507 not use this option to add directories that contain vendor-supplied
7508 system header files (use @option{-isystem} for that). If you use more than
7509 one @option{-I} option, the directories are scanned in left-to-right
7510 order; the standard system directories come after.
7512 If a standard system include directory, or a directory specified with
7513 @option{-isystem}, is also specified with @option{-I}, the @option{-I}
7514 option will be ignored. The directory will still be searched but as a
7515 system directory at its normal position in the system include chain.
7516 This is to ensure that GCC's procedure to fix buggy system headers and
7517 the ordering for the include_next directive are not inadvertently changed.
7518 If you really need to change the search order for system directories,
7519 use the @option{-nostdinc} and/or @option{-isystem} options.
7521 @item -iquote@var{dir}
7523 Add the directory @var{dir} to the head of the list of directories to
7524 be searched for header files only for the case of @samp{#include
7525 "@var{file}"}; they are not searched for @samp{#include <@var{file}>},
7526 otherwise just like @option{-I}.
7530 Add directory @var{dir} to the list of directories to be searched
7533 @item -B@var{prefix}
7535 This option specifies where to find the executables, libraries,
7536 include files, and data files of the compiler itself.
7538 The compiler driver program runs one or more of the subprograms
7539 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
7540 @var{prefix} as a prefix for each program it tries to run, both with and
7541 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
7543 For each subprogram to be run, the compiler driver first tries the
7544 @option{-B} prefix, if any. If that name is not found, or if @option{-B}
7545 was not specified, the driver tries two standard prefixes, which are
7546 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
7547 those results in a file name that is found, the unmodified program
7548 name is searched for using the directories specified in your
7549 @env{PATH} environment variable.
7551 The compiler will check to see if the path provided by the @option{-B}
7552 refers to a directory, and if necessary it will add a directory
7553 separator character at the end of the path.
7555 @option{-B} prefixes that effectively specify directory names also apply
7556 to libraries in the linker, because the compiler translates these
7557 options into @option{-L} options for the linker. They also apply to
7558 includes files in the preprocessor, because the compiler translates these
7559 options into @option{-isystem} options for the preprocessor. In this case,
7560 the compiler appends @samp{include} to the prefix.
7562 The run-time support file @file{libgcc.a} can also be searched for using
7563 the @option{-B} prefix, if needed. If it is not found there, the two
7564 standard prefixes above are tried, and that is all. The file is left
7565 out of the link if it is not found by those means.
7567 Another way to specify a prefix much like the @option{-B} prefix is to use
7568 the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
7571 As a special kludge, if the path provided by @option{-B} is
7572 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
7573 9, then it will be replaced by @file{[dir/]include}. This is to help
7574 with boot-strapping the compiler.
7576 @item -specs=@var{file}
7578 Process @var{file} after the compiler reads in the standard @file{specs}
7579 file, in order to override the defaults that the @file{gcc} driver
7580 program uses when determining what switches to pass to @file{cc1},
7581 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
7582 @option{-specs=@var{file}} can be specified on the command line, and they
7583 are processed in order, from left to right.
7585 @item --sysroot=@var{dir}
7587 Use @var{dir} as the logical root directory for headers and libraries.
7588 For example, if the compiler would normally search for headers in
7589 @file{/usr/include} and libraries in @file{/usr/lib}, it will instead
7590 search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
7592 If you use both this option and the @option{-isysroot} option, then
7593 the @option{--sysroot} option will apply to libraries, but the
7594 @option{-isysroot} option will apply to header files.
7596 The GNU linker (beginning with version 2.16) has the necessary support
7597 for this option. If your linker does not support this option, the
7598 header file aspect of @option{--sysroot} will still work, but the
7599 library aspect will not.
7603 This option has been deprecated. Please use @option{-iquote} instead for
7604 @option{-I} directories before the @option{-I-} and remove the @option{-I-}.
7605 Any directories you specify with @option{-I} options before the @option{-I-}
7606 option are searched only for the case of @samp{#include "@var{file}"};
7607 they are not searched for @samp{#include <@var{file}>}.
7609 If additional directories are specified with @option{-I} options after
7610 the @option{-I-}, these directories are searched for all @samp{#include}
7611 directives. (Ordinarily @emph{all} @option{-I} directories are used
7614 In addition, the @option{-I-} option inhibits the use of the current
7615 directory (where the current input file came from) as the first search
7616 directory for @samp{#include "@var{file}"}. There is no way to
7617 override this effect of @option{-I-}. With @option{-I.} you can specify
7618 searching the directory which was current when the compiler was
7619 invoked. That is not exactly the same as what the preprocessor does
7620 by default, but it is often satisfactory.
7622 @option{-I-} does not inhibit the use of the standard system directories
7623 for header files. Thus, @option{-I-} and @option{-nostdinc} are
7630 @section Specifying subprocesses and the switches to pass to them
7633 @command{gcc} is a driver program. It performs its job by invoking a
7634 sequence of other programs to do the work of compiling, assembling and
7635 linking. GCC interprets its command-line parameters and uses these to
7636 deduce which programs it should invoke, and which command-line options
7637 it ought to place on their command lines. This behavior is controlled
7638 by @dfn{spec strings}. In most cases there is one spec string for each
7639 program that GCC can invoke, but a few programs have multiple spec
7640 strings to control their behavior. The spec strings built into GCC can
7641 be overridden by using the @option{-specs=} command-line switch to specify
7644 @dfn{Spec files} are plaintext files that are used to construct spec
7645 strings. They consist of a sequence of directives separated by blank
7646 lines. The type of directive is determined by the first non-whitespace
7647 character on the line and it can be one of the following:
7650 @item %@var{command}
7651 Issues a @var{command} to the spec file processor. The commands that can
7655 @item %include <@var{file}>
7657 Search for @var{file} and insert its text at the current point in the
7660 @item %include_noerr <@var{file}>
7661 @cindex %include_noerr
7662 Just like @samp{%include}, but do not generate an error message if the include
7663 file cannot be found.
7665 @item %rename @var{old_name} @var{new_name}
7667 Rename the spec string @var{old_name} to @var{new_name}.
7671 @item *[@var{spec_name}]:
7672 This tells the compiler to create, override or delete the named spec
7673 string. All lines after this directive up to the next directive or
7674 blank line are considered to be the text for the spec string. If this
7675 results in an empty string then the spec will be deleted. (Or, if the
7676 spec did not exist, then nothing will happened.) Otherwise, if the spec
7677 does not currently exist a new spec will be created. If the spec does
7678 exist then its contents will be overridden by the text of this
7679 directive, unless the first character of that text is the @samp{+}
7680 character, in which case the text will be appended to the spec.
7682 @item [@var{suffix}]:
7683 Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
7684 and up to the next directive or blank line are considered to make up the
7685 spec string for the indicated suffix. When the compiler encounters an
7686 input file with the named suffix, it will processes the spec string in
7687 order to work out how to compile that file. For example:
7694 This says that any input file whose name ends in @samp{.ZZ} should be
7695 passed to the program @samp{z-compile}, which should be invoked with the
7696 command-line switch @option{-input} and with the result of performing the
7697 @samp{%i} substitution. (See below.)
7699 As an alternative to providing a spec string, the text that follows a
7700 suffix directive can be one of the following:
7703 @item @@@var{language}
7704 This says that the suffix is an alias for a known @var{language}. This is
7705 similar to using the @option{-x} command-line switch to GCC to specify a
7706 language explicitly. For example:
7713 Says that .ZZ files are, in fact, C++ source files.
7716 This causes an error messages saying:
7719 @var{name} compiler not installed on this system.
7723 GCC already has an extensive list of suffixes built into it.
7724 This directive will add an entry to the end of the list of suffixes, but
7725 since the list is searched from the end backwards, it is effectively
7726 possible to override earlier entries using this technique.
7730 GCC has the following spec strings built into it. Spec files can
7731 override these strings or create their own. Note that individual
7732 targets can also add their own spec strings to this list.
7735 asm Options to pass to the assembler
7736 asm_final Options to pass to the assembler post-processor
7737 cpp Options to pass to the C preprocessor
7738 cc1 Options to pass to the C compiler
7739 cc1plus Options to pass to the C++ compiler
7740 endfile Object files to include at the end of the link
7741 link Options to pass to the linker
7742 lib Libraries to include on the command line to the linker
7743 libgcc Decides which GCC support library to pass to the linker
7744 linker Sets the name of the linker
7745 predefines Defines to be passed to the C preprocessor
7746 signed_char Defines to pass to CPP to say whether @code{char} is signed
7748 startfile Object files to include at the start of the link
7751 Here is a small example of a spec file:
7757 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
7760 This example renames the spec called @samp{lib} to @samp{old_lib} and
7761 then overrides the previous definition of @samp{lib} with a new one.
7762 The new definition adds in some extra command-line options before
7763 including the text of the old definition.
7765 @dfn{Spec strings} are a list of command-line options to be passed to their
7766 corresponding program. In addition, the spec strings can contain
7767 @samp{%}-prefixed sequences to substitute variable text or to
7768 conditionally insert text into the command line. Using these constructs
7769 it is possible to generate quite complex command lines.
7771 Here is a table of all defined @samp{%}-sequences for spec
7772 strings. Note that spaces are not generated automatically around the
7773 results of expanding these sequences. Therefore you can concatenate them
7774 together or combine them with constant text in a single argument.
7778 Substitute one @samp{%} into the program name or argument.
7781 Substitute the name of the input file being processed.
7784 Substitute the basename of the input file being processed.
7785 This is the substring up to (and not including) the last period
7786 and not including the directory.
7789 This is the same as @samp{%b}, but include the file suffix (text after
7793 Marks the argument containing or following the @samp{%d} as a
7794 temporary file name, so that that file will be deleted if GCC exits
7795 successfully. Unlike @samp{%g}, this contributes no text to the
7798 @item %g@var{suffix}
7799 Substitute a file name that has suffix @var{suffix} and is chosen
7800 once per compilation, and mark the argument in the same way as
7801 @samp{%d}. To reduce exposure to denial-of-service attacks, the file
7802 name is now chosen in a way that is hard to predict even when previously
7803 chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
7804 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
7805 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
7806 treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
7807 was simply substituted with a file name chosen once per compilation,
7808 without regard to any appended suffix (which was therefore treated
7809 just like ordinary text), making such attacks more likely to succeed.
7811 @item %u@var{suffix}
7812 Like @samp{%g}, but generates a new temporary file name even if
7813 @samp{%u@var{suffix}} was already seen.
7815 @item %U@var{suffix}
7816 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
7817 new one if there is no such last file name. In the absence of any
7818 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
7819 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
7820 would involve the generation of two distinct file names, one
7821 for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
7822 simply substituted with a file name chosen for the previous @samp{%u},
7823 without regard to any appended suffix.
7825 @item %j@var{suffix}
7826 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
7827 writable, and if save-temps is off; otherwise, substitute the name
7828 of a temporary file, just like @samp{%u}. This temporary file is not
7829 meant for communication between processes, but rather as a junk
7832 @item %|@var{suffix}
7833 @itemx %m@var{suffix}
7834 Like @samp{%g}, except if @option{-pipe} is in effect. In that case
7835 @samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
7836 all. These are the two most common ways to instruct a program that it
7837 should read from standard input or write to standard output. If you
7838 need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
7839 construct: see for example @file{f/lang-specs.h}.
7841 @item %.@var{SUFFIX}
7842 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
7843 when it is subsequently output with @samp{%*}. @var{SUFFIX} is
7844 terminated by the next space or %.
7847 Marks the argument containing or following the @samp{%w} as the
7848 designated output file of this compilation. This puts the argument
7849 into the sequence of arguments that @samp{%o} will substitute later.
7852 Substitutes the names of all the output files, with spaces
7853 automatically placed around them. You should write spaces
7854 around the @samp{%o} as well or the results are undefined.
7855 @samp{%o} is for use in the specs for running the linker.
7856 Input files whose names have no recognized suffix are not compiled
7857 at all, but they are included among the output files, so they will
7861 Substitutes the suffix for object files. Note that this is
7862 handled specially when it immediately follows @samp{%g, %u, or %U},
7863 because of the need for those to form complete file names. The
7864 handling is such that @samp{%O} is treated exactly as if it had already
7865 been substituted, except that @samp{%g, %u, and %U} do not currently
7866 support additional @var{suffix} characters following @samp{%O} as they would
7867 following, for example, @samp{.o}.
7870 Substitutes the standard macro predefinitions for the
7871 current target machine. Use this when running @code{cpp}.
7874 Like @samp{%p}, but puts @samp{__} before and after the name of each
7875 predefined macro, except for macros that start with @samp{__} or with
7876 @samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
7880 Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
7881 @option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
7882 @option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
7883 and @option{-imultilib} as necessary.
7886 Current argument is the name of a library or startup file of some sort.
7887 Search for that file in a standard list of directories and substitute
7888 the full name found.
7891 Print @var{str} as an error message. @var{str} is terminated by a newline.
7892 Use this when inconsistent options are detected.
7895 Substitute the contents of spec string @var{name} at this point.
7898 Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
7900 @item %x@{@var{option}@}
7901 Accumulate an option for @samp{%X}.
7904 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
7908 Output the accumulated assembler options specified by @option{-Wa}.
7911 Output the accumulated preprocessor options specified by @option{-Wp}.
7914 Process the @code{asm} spec. This is used to compute the
7915 switches to be passed to the assembler.
7918 Process the @code{asm_final} spec. This is a spec string for
7919 passing switches to an assembler post-processor, if such a program is
7923 Process the @code{link} spec. This is the spec for computing the
7924 command line passed to the linker. Typically it will make use of the
7925 @samp{%L %G %S %D and %E} sequences.
7928 Dump out a @option{-L} option for each directory that GCC believes might
7929 contain startup files. If the target supports multilibs then the
7930 current multilib directory will be prepended to each of these paths.
7933 Process the @code{lib} spec. This is a spec string for deciding which
7934 libraries should be included on the command line to the linker.
7937 Process the @code{libgcc} spec. This is a spec string for deciding
7938 which GCC support library should be included on the command line to the linker.
7941 Process the @code{startfile} spec. This is a spec for deciding which
7942 object files should be the first ones passed to the linker. Typically
7943 this might be a file named @file{crt0.o}.
7946 Process the @code{endfile} spec. This is a spec string that specifies
7947 the last object files that will be passed to the linker.
7950 Process the @code{cpp} spec. This is used to construct the arguments
7951 to be passed to the C preprocessor.
7954 Process the @code{cc1} spec. This is used to construct the options to be
7955 passed to the actual C compiler (@samp{cc1}).
7958 Process the @code{cc1plus} spec. This is used to construct the options to be
7959 passed to the actual C++ compiler (@samp{cc1plus}).
7962 Substitute the variable part of a matched option. See below.
7963 Note that each comma in the substituted string is replaced by
7967 Remove all occurrences of @code{-S} from the command line. Note---this
7968 command is position dependent. @samp{%} commands in the spec string
7969 before this one will see @code{-S}, @samp{%} commands in the spec string
7970 after this one will not.
7972 @item %:@var{function}(@var{args})
7973 Call the named function @var{function}, passing it @var{args}.
7974 @var{args} is first processed as a nested spec string, then split
7975 into an argument vector in the usual fashion. The function returns
7976 a string which is processed as if it had appeared literally as part
7977 of the current spec.
7979 The following built-in spec functions are provided:
7983 The @code{getenv} spec function takes two arguments: an environment
7984 variable name and a string. If the environment variable is not
7985 defined, a fatal error is issued. Otherwise, the return value is the
7986 value of the environment variable concatenated with the string. For
7987 example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
7990 %:getenv(TOPDIR /include)
7993 expands to @file{/path/to/top/include}.
7995 @item @code{if-exists}
7996 The @code{if-exists} spec function takes one argument, an absolute
7997 pathname to a file. If the file exists, @code{if-exists} returns the
7998 pathname. Here is a small example of its usage:
8002 crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
8005 @item @code{if-exists-else}
8006 The @code{if-exists-else} spec function is similar to the @code{if-exists}
8007 spec function, except that it takes two arguments. The first argument is
8008 an absolute pathname to a file. If the file exists, @code{if-exists-else}
8009 returns the pathname. If it does not exist, it returns the second argument.
8010 This way, @code{if-exists-else} can be used to select one file or another,
8011 based on the existence of the first. Here is a small example of its usage:
8015 crt0%O%s %:if-exists(crti%O%s) \
8016 %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
8019 @item @code{replace-outfile}
8020 The @code{replace-outfile} spec function takes two arguments. It looks for the
8021 first argument in the outfiles array and replaces it with the second argument. Here
8022 is a small example of its usage:
8025 %@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
8028 @item @code{print-asm-header}
8029 The @code{print-asm-header} function takes no arguments and simply
8030 prints a banner like:
8036 Use "-Wa,OPTION" to pass "OPTION" to the assembler.
8039 It is used to separate compiler options from assembler options
8040 in the @option{--target-help} output.
8044 Substitutes the @code{-S} switch, if that switch was given to GCC@.
8045 If that switch was not specified, this substitutes nothing. Note that
8046 the leading dash is omitted when specifying this option, and it is
8047 automatically inserted if the substitution is performed. Thus the spec
8048 string @samp{%@{foo@}} would match the command-line option @option{-foo}
8049 and would output the command line option @option{-foo}.
8051 @item %W@{@code{S}@}
8052 Like %@{@code{S}@} but mark last argument supplied within as a file to be
8055 @item %@{@code{S}*@}
8056 Substitutes all the switches specified to GCC whose names start
8057 with @code{-S}, but which also take an argument. This is used for
8058 switches like @option{-o}, @option{-D}, @option{-I}, etc.
8059 GCC considers @option{-o foo} as being
8060 one switch whose names starts with @samp{o}. %@{o*@} would substitute this
8061 text, including the space. Thus two arguments would be generated.
8063 @item %@{@code{S}*&@code{T}*@}
8064 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
8065 (the order of @code{S} and @code{T} in the spec is not significant).
8066 There can be any number of ampersand-separated variables; for each the
8067 wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
8069 @item %@{@code{S}:@code{X}@}
8070 Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
8072 @item %@{!@code{S}:@code{X}@}
8073 Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
8075 @item %@{@code{S}*:@code{X}@}
8076 Substitutes @code{X} if one or more switches whose names start with
8077 @code{-S} are specified to GCC@. Normally @code{X} is substituted only
8078 once, no matter how many such switches appeared. However, if @code{%*}
8079 appears somewhere in @code{X}, then @code{X} will be substituted once
8080 for each matching switch, with the @code{%*} replaced by the part of
8081 that switch that matched the @code{*}.
8083 @item %@{.@code{S}:@code{X}@}
8084 Substitutes @code{X}, if processing a file with suffix @code{S}.
8086 @item %@{!.@code{S}:@code{X}@}
8087 Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
8089 @item %@{,@code{S}:@code{X}@}
8090 Substitutes @code{X}, if processing a file for language @code{S}.
8092 @item %@{!,@code{S}:@code{X}@}
8093 Substitutes @code{X}, if not processing a file for language @code{S}.
8095 @item %@{@code{S}|@code{P}:@code{X}@}
8096 Substitutes @code{X} if either @code{-S} or @code{-P} was given to
8097 GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and
8098 @code{*} sequences as well, although they have a stronger binding than
8099 the @samp{|}. If @code{%*} appears in @code{X}, all of the
8100 alternatives must be starred, and only the first matching alternative
8103 For example, a spec string like this:
8106 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
8109 will output the following command-line options from the following input
8110 command-line options:
8115 -d fred.c -foo -baz -boggle
8116 -d jim.d -bar -baz -boggle
8119 @item %@{S:X; T:Y; :D@}
8121 If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
8122 given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
8123 be as many clauses as you need. This may be combined with @code{.},
8124 @code{,}, @code{!}, @code{|}, and @code{*} as needed.
8129 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
8130 construct may contain other nested @samp{%} constructs or spaces, or
8131 even newlines. They are processed as usual, as described above.
8132 Trailing white space in @code{X} is ignored. White space may also
8133 appear anywhere on the left side of the colon in these constructs,
8134 except between @code{.} or @code{*} and the corresponding word.
8136 The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
8137 handled specifically in these constructs. If another value of
8138 @option{-O} or the negated form of a @option{-f}, @option{-m}, or
8139 @option{-W} switch is found later in the command line, the earlier
8140 switch value is ignored, except with @{@code{S}*@} where @code{S} is
8141 just one letter, which passes all matching options.
8143 The character @samp{|} at the beginning of the predicate text is used to
8144 indicate that a command should be piped to the following command, but
8145 only if @option{-pipe} is specified.
8147 It is built into GCC which switches take arguments and which do not.
8148 (You might think it would be useful to generalize this to allow each
8149 compiler's spec to say which switches take arguments. But this cannot
8150 be done in a consistent fashion. GCC cannot even decide which input
8151 files have been specified without knowing which switches take arguments,
8152 and it must know which input files to compile in order to tell which
8155 GCC also knows implicitly that arguments starting in @option{-l} are to be
8156 treated as compiler output files, and passed to the linker in their
8157 proper position among the other output files.
8159 @c man begin OPTIONS
8161 @node Target Options
8162 @section Specifying Target Machine and Compiler Version
8163 @cindex target options
8164 @cindex cross compiling
8165 @cindex specifying machine version
8166 @cindex specifying compiler version and target machine
8167 @cindex compiler version, specifying
8168 @cindex target machine, specifying
8170 The usual way to run GCC is to run the executable called @file{gcc}, or
8171 @file{<machine>-gcc} when cross-compiling, or
8172 @file{<machine>-gcc-<version>} to run a version other than the one that
8173 was installed last. Sometimes this is inconvenient, so GCC provides
8174 options that will switch to another cross-compiler or version.
8177 @item -b @var{machine}
8179 The argument @var{machine} specifies the target machine for compilation.
8181 The value to use for @var{machine} is the same as was specified as the
8182 machine type when configuring GCC as a cross-compiler. For
8183 example, if a cross-compiler was configured with @samp{configure
8184 arm-elf}, meaning to compile for an arm processor with elf binaries,
8185 then you would specify @option{-b arm-elf} to run that cross compiler.
8186 Because there are other options beginning with @option{-b}, the
8187 configuration must contain a hyphen.
8189 @item -V @var{version}
8191 The argument @var{version} specifies which version of GCC to run.
8192 This is useful when multiple versions are installed. For example,
8193 @var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
8196 The @option{-V} and @option{-b} options work by running the
8197 @file{<machine>-gcc-<version>} executable, so there's no real reason to
8198 use them if you can just run that directly.
8200 @node Submodel Options
8201 @section Hardware Models and Configurations
8202 @cindex submodel options
8203 @cindex specifying hardware config
8204 @cindex hardware models and configurations, specifying
8205 @cindex machine dependent options
8207 Earlier we discussed the standard option @option{-b} which chooses among
8208 different installed compilers for completely different target
8209 machines, such as VAX vs.@: 68000 vs.@: 80386.
8211 In addition, each of these target machine types can have its own
8212 special options, starting with @samp{-m}, to choose among various
8213 hardware models or configurations---for example, 68010 vs 68020,
8214 floating coprocessor or none. A single installed version of the
8215 compiler can compile for any model or configuration, according to the
8218 Some configurations of the compiler also support additional special
8219 options, usually for compatibility with other compilers on the same
8222 @c This list is ordered alphanumerically by subsection name.
8223 @c It should be the same order and spelling as these options are listed
8224 @c in Machine Dependent Options
8230 * Blackfin Options::
8234 * DEC Alpha Options::
8235 * DEC Alpha/VMS Options::
8237 * GNU/Linux Options::
8240 * i386 and x86-64 Options::
8253 * RS/6000 and PowerPC Options::
8254 * S/390 and zSeries Options::
8259 * System V Options::
8260 * TMS320C3x/C4x Options::
8265 * Xstormy16 Options::
8271 @subsection ARC Options
8274 These options are defined for ARC implementations:
8279 Compile code for little endian mode. This is the default.
8283 Compile code for big endian mode.
8286 @opindex mmangle-cpu
8287 Prepend the name of the cpu to all public symbol names.
8288 In multiple-processor systems, there are many ARC variants with different
8289 instruction and register set characteristics. This flag prevents code
8290 compiled for one cpu to be linked with code compiled for another.
8291 No facility exists for handling variants that are ``almost identical''.
8292 This is an all or nothing option.
8294 @item -mcpu=@var{cpu}
8296 Compile code for ARC variant @var{cpu}.
8297 Which variants are supported depend on the configuration.
8298 All variants support @option{-mcpu=base}, this is the default.
8300 @item -mtext=@var{text-section}
8301 @itemx -mdata=@var{data-section}
8302 @itemx -mrodata=@var{readonly-data-section}
8306 Put functions, data, and readonly data in @var{text-section},
8307 @var{data-section}, and @var{readonly-data-section} respectively
8308 by default. This can be overridden with the @code{section} attribute.
8309 @xref{Variable Attributes}.
8314 @subsection ARM Options
8317 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
8321 @item -mabi=@var{name}
8323 Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
8324 @samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
8327 @opindex mapcs-frame
8328 Generate a stack frame that is compliant with the ARM Procedure Call
8329 Standard for all functions, even if this is not strictly necessary for
8330 correct execution of the code. Specifying @option{-fomit-frame-pointer}
8331 with this option will cause the stack frames not to be generated for
8332 leaf functions. The default is @option{-mno-apcs-frame}.
8336 This is a synonym for @option{-mapcs-frame}.
8339 @c not currently implemented
8340 @item -mapcs-stack-check
8341 @opindex mapcs-stack-check
8342 Generate code to check the amount of stack space available upon entry to
8343 every function (that actually uses some stack space). If there is
8344 insufficient space available then either the function
8345 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
8346 called, depending upon the amount of stack space required. The run time
8347 system is required to provide these functions. The default is
8348 @option{-mno-apcs-stack-check}, since this produces smaller code.
8350 @c not currently implemented
8352 @opindex mapcs-float
8353 Pass floating point arguments using the float point registers. This is
8354 one of the variants of the APCS@. This option is recommended if the
8355 target hardware has a floating point unit or if a lot of floating point
8356 arithmetic is going to be performed by the code. The default is
8357 @option{-mno-apcs-float}, since integer only code is slightly increased in
8358 size if @option{-mapcs-float} is used.
8360 @c not currently implemented
8361 @item -mapcs-reentrant
8362 @opindex mapcs-reentrant
8363 Generate reentrant, position independent code. The default is
8364 @option{-mno-apcs-reentrant}.
8367 @item -mthumb-interwork
8368 @opindex mthumb-interwork
8369 Generate code which supports calling between the ARM and Thumb
8370 instruction sets. Without this option the two instruction sets cannot
8371 be reliably used inside one program. The default is
8372 @option{-mno-thumb-interwork}, since slightly larger code is generated
8373 when @option{-mthumb-interwork} is specified.
8375 @item -mno-sched-prolog
8376 @opindex mno-sched-prolog
8377 Prevent the reordering of instructions in the function prolog, or the
8378 merging of those instruction with the instructions in the function's
8379 body. This means that all functions will start with a recognizable set
8380 of instructions (or in fact one of a choice from a small set of
8381 different function prologues), and this information can be used to
8382 locate the start if functions inside an executable piece of code. The
8383 default is @option{-msched-prolog}.
8386 @opindex mhard-float
8387 Generate output containing floating point instructions. This is the
8391 @opindex msoft-float
8392 Generate output containing library calls for floating point.
8393 @strong{Warning:} the requisite libraries are not available for all ARM
8394 targets. Normally the facilities of the machine's usual C compiler are
8395 used, but this cannot be done directly in cross-compilation. You must make
8396 your own arrangements to provide suitable library functions for
8399 @option{-msoft-float} changes the calling convention in the output file;
8400 therefore, it is only useful if you compile @emph{all} of a program with
8401 this option. In particular, you need to compile @file{libgcc.a}, the
8402 library that comes with GCC, with @option{-msoft-float} in order for
8405 @item -mfloat-abi=@var{name}
8407 Specifies which ABI to use for floating point values. Permissible values
8408 are: @samp{soft}, @samp{softfp} and @samp{hard}.
8410 @samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
8411 and @option{-mhard-float} respectively. @samp{softfp} allows the generation
8412 of floating point instructions, but still uses the soft-float calling
8415 @item -mlittle-endian
8416 @opindex mlittle-endian
8417 Generate code for a processor running in little-endian mode. This is
8418 the default for all standard configurations.
8421 @opindex mbig-endian
8422 Generate code for a processor running in big-endian mode; the default is
8423 to compile code for a little-endian processor.
8425 @item -mwords-little-endian
8426 @opindex mwords-little-endian
8427 This option only applies when generating code for big-endian processors.
8428 Generate code for a little-endian word order but a big-endian byte
8429 order. That is, a byte order of the form @samp{32107654}. Note: this
8430 option should only be used if you require compatibility with code for
8431 big-endian ARM processors generated by versions of the compiler prior to
8434 @item -mcpu=@var{name}
8436 This specifies the name of the target ARM processor. GCC uses this name
8437 to determine what kind of instructions it can emit when generating
8438 assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
8439 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
8440 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
8441 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
8442 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
8443 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
8444 @samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
8445 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
8446 @samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
8447 @samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
8448 @samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
8449 @samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
8450 @samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
8451 @samp{arm1156t2-s}, @samp{arm1176jz-s}, @samp{arm1176jzf-s},
8452 @samp{cortex-a8}, @samp{cortex-r4}, @samp{cortex-m3},
8453 @samp{xscale}, @samp{iwmmxt}, @samp{ep9312}.
8455 @itemx -mtune=@var{name}
8457 This option is very similar to the @option{-mcpu=} option, except that
8458 instead of specifying the actual target processor type, and hence
8459 restricting which instructions can be used, it specifies that GCC should
8460 tune the performance of the code as if the target were of the type
8461 specified in this option, but still choosing the instructions that it
8462 will generate based on the cpu specified by a @option{-mcpu=} option.
8463 For some ARM implementations better performance can be obtained by using
8466 @item -march=@var{name}
8468 This specifies the name of the target ARM architecture. GCC uses this
8469 name to determine what kind of instructions it can emit when generating
8470 assembly code. This option can be used in conjunction with or instead
8471 of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
8472 @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
8473 @samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
8474 @samp{armv6t2}, @samp{armv6z}, @samp{armv6zk}, @samp{armv7}, @samp{armv7-a},
8475 @samp{armv7-r}, @samp{armv7-m}, @samp{iwmmxt}, @samp{ep9312}.
8477 @item -mfpu=@var{name}
8478 @itemx -mfpe=@var{number}
8479 @itemx -mfp=@var{number}
8483 This specifies what floating point hardware (or hardware emulation) is
8484 available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
8485 @samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
8486 are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
8487 with older versions of GCC@.
8489 If @option{-msoft-float} is specified this specifies the format of
8490 floating point values.
8492 @item -mstructure-size-boundary=@var{n}
8493 @opindex mstructure-size-boundary
8494 The size of all structures and unions will be rounded up to a multiple
8495 of the number of bits set by this option. Permissible values are 8, 32
8496 and 64. The default value varies for different toolchains. For the COFF
8497 targeted toolchain the default value is 8. A value of 64 is only allowed
8498 if the underlying ABI supports it.
8500 Specifying the larger number can produce faster, more efficient code, but
8501 can also increase the size of the program. Different values are potentially
8502 incompatible. Code compiled with one value cannot necessarily expect to
8503 work with code or libraries compiled with another value, if they exchange
8504 information using structures or unions.
8506 @item -mabort-on-noreturn
8507 @opindex mabort-on-noreturn
8508 Generate a call to the function @code{abort} at the end of a
8509 @code{noreturn} function. It will be executed if the function tries to
8513 @itemx -mno-long-calls
8514 @opindex mlong-calls
8515 @opindex mno-long-calls
8516 Tells the compiler to perform function calls by first loading the
8517 address of the function into a register and then performing a subroutine
8518 call on this register. This switch is needed if the target function
8519 will lie outside of the 64 megabyte addressing range of the offset based
8520 version of subroutine call instruction.
8522 Even if this switch is enabled, not all function calls will be turned
8523 into long calls. The heuristic is that static functions, functions
8524 which have the @samp{short-call} attribute, functions that are inside
8525 the scope of a @samp{#pragma no_long_calls} directive and functions whose
8526 definitions have already been compiled within the current compilation
8527 unit, will not be turned into long calls. The exception to this rule is
8528 that weak function definitions, functions with the @samp{long-call}
8529 attribute or the @samp{section} attribute, and functions that are within
8530 the scope of a @samp{#pragma long_calls} directive, will always be
8531 turned into long calls.
8533 This feature is not enabled by default. Specifying
8534 @option{-mno-long-calls} will restore the default behavior, as will
8535 placing the function calls within the scope of a @samp{#pragma
8536 long_calls_off} directive. Note these switches have no effect on how
8537 the compiler generates code to handle function calls via function
8540 @item -mnop-fun-dllimport
8541 @opindex mnop-fun-dllimport
8542 Disable support for the @code{dllimport} attribute.
8544 @item -msingle-pic-base
8545 @opindex msingle-pic-base
8546 Treat the register used for PIC addressing as read-only, rather than
8547 loading it in the prologue for each function. The run-time system is
8548 responsible for initializing this register with an appropriate value
8549 before execution begins.
8551 @item -mpic-register=@var{reg}
8552 @opindex mpic-register
8553 Specify the register to be used for PIC addressing. The default is R10
8554 unless stack-checking is enabled, when R9 is used.
8556 @item -mcirrus-fix-invalid-insns
8557 @opindex mcirrus-fix-invalid-insns
8558 @opindex mno-cirrus-fix-invalid-insns
8559 Insert NOPs into the instruction stream to in order to work around
8560 problems with invalid Maverick instruction combinations. This option
8561 is only valid if the @option{-mcpu=ep9312} option has been used to
8562 enable generation of instructions for the Cirrus Maverick floating
8563 point co-processor. This option is not enabled by default, since the
8564 problem is only present in older Maverick implementations. The default
8565 can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
8568 @item -mpoke-function-name
8569 @opindex mpoke-function-name
8570 Write the name of each function into the text section, directly
8571 preceding the function prologue. The generated code is similar to this:
8575 .ascii "arm_poke_function_name", 0
8578 .word 0xff000000 + (t1 - t0)
8579 arm_poke_function_name
8581 stmfd sp!, @{fp, ip, lr, pc@}
8585 When performing a stack backtrace, code can inspect the value of
8586 @code{pc} stored at @code{fp + 0}. If the trace function then looks at
8587 location @code{pc - 12} and the top 8 bits are set, then we know that
8588 there is a function name embedded immediately preceding this location
8589 and has length @code{((pc[-3]) & 0xff000000)}.
8593 Generate code for the Thumb instruction set. The default is to
8594 use the 32-bit ARM instruction set.
8595 This option automatically enables either 16-bit Thumb-1 or
8596 mixed 16/32-bit Thumb-2 instructions based on the @option{-mcpu=@var{name}}
8597 and @option{-march=@var{name}} options.
8600 @opindex mtpcs-frame
8601 Generate a stack frame that is compliant with the Thumb Procedure Call
8602 Standard for all non-leaf functions. (A leaf function is one that does
8603 not call any other functions.) The default is @option{-mno-tpcs-frame}.
8605 @item -mtpcs-leaf-frame
8606 @opindex mtpcs-leaf-frame
8607 Generate a stack frame that is compliant with the Thumb Procedure Call
8608 Standard for all leaf functions. (A leaf function is one that does
8609 not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
8611 @item -mcallee-super-interworking
8612 @opindex mcallee-super-interworking
8613 Gives all externally visible functions in the file being compiled an ARM
8614 instruction set header which switches to Thumb mode before executing the
8615 rest of the function. This allows these functions to be called from
8616 non-interworking code.
8618 @item -mcaller-super-interworking
8619 @opindex mcaller-super-interworking
8620 Allows calls via function pointers (including virtual functions) to
8621 execute correctly regardless of whether the target code has been
8622 compiled for interworking or not. There is a small overhead in the cost
8623 of executing a function pointer if this option is enabled.
8625 @item -mtp=@var{name}
8627 Specify the access model for the thread local storage pointer. The valid
8628 models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
8629 @option{cp15}, which fetches the thread pointer from @code{cp15} directly
8630 (supported in the arm6k architecture), and @option{auto}, which uses the
8631 best available method for the selected processor. The default setting is
8637 @subsection AVR Options
8640 These options are defined for AVR implementations:
8643 @item -mmcu=@var{mcu}
8645 Specify ATMEL AVR instruction set or MCU type.
8647 Instruction set avr1 is for the minimal AVR core, not supported by the C
8648 compiler, only for assembler programs (MCU types: at90s1200, attiny10,
8649 attiny11, attiny12, attiny15, attiny28).
8651 Instruction set avr2 (default) is for the classic AVR core with up to
8652 8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
8653 at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
8654 at90c8534, at90s8535).
8656 Instruction set avr3 is for the classic AVR core with up to 128K program
8657 memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
8659 Instruction set avr4 is for the enhanced AVR core with up to 8K program
8660 memory space (MCU types: atmega8, atmega83, atmega85).
8662 Instruction set avr5 is for the enhanced AVR core with up to 128K program
8663 memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
8664 atmega64, atmega128, at43usb355, at94k).
8668 Output instruction sizes to the asm file.
8670 @item -minit-stack=@var{N}
8671 @opindex minit-stack
8672 Specify the initial stack address, which may be a symbol or numeric value,
8673 @samp{__stack} is the default.
8675 @item -mno-interrupts
8676 @opindex mno-interrupts
8677 Generated code is not compatible with hardware interrupts.
8678 Code size will be smaller.
8680 @item -mcall-prologues
8681 @opindex mcall-prologues
8682 Functions prologues/epilogues expanded as call to appropriate
8683 subroutines. Code size will be smaller.
8685 @item -mno-tablejump
8686 @opindex mno-tablejump
8687 Do not generate tablejump insns which sometimes increase code size.
8690 @opindex mtiny-stack
8691 Change only the low 8 bits of the stack pointer.
8695 Assume int to be 8 bit integer. This affects the sizes of all types: A
8696 char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
8697 and long long will be 4 bytes. Please note that this option does not
8698 comply to the C standards, but it will provide you with smaller code
8702 @node Blackfin Options
8703 @subsection Blackfin Options
8704 @cindex Blackfin Options
8707 @item -mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]}
8709 Specifies the name of the target Blackfin processor. Currently, @var{cpu}
8710 can be one of @samp{bf522}, @samp{bf525}, @samp{bf527},
8711 @samp{bf531}, @samp{bf532}, @samp{bf533}, @samp{bf534},
8712 @samp{bf536}, @samp{bf537}, @samp{bf538}, @samp{bf539},
8713 @samp{bf542}, @samp{bf544}, @samp{bf548}, @samp{bf549},
8715 The optional @var{sirevision} specifies the silicon revision of the target
8716 Blackfin processor. Any workarounds available for the targeted silicon revision
8717 will be enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled.
8718 If @var{sirevision} is @samp{any}, all workarounds for the targeted processor
8719 will be enabled. The @code{__SILICON_REVISION__} macro is defined to two
8720 hexadecimal digits representing the major and minor numbers in the silicon
8721 revision. If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__}
8722 is not defined. If @var{sirevision} is @samp{any}, the
8723 @code{__SILICON_REVISION__} is defined to be @code{0xffff}.
8724 If this optional @var{sirevision} is not used, GCC assumes the latest known
8725 silicon revision of the targeted Blackfin processor.
8727 Support for @samp{bf561} is incomplete. For @samp{bf561},
8728 Only the processor macro is defined.
8729 Without this option, @samp{bf532} is used as the processor by default.
8730 The corresponding predefined processor macros for @var{cpu} is to
8731 be defined. And for @samp{bfin-elf} toolchain, this causes the hardware BSP
8732 provided by libgloss to be linked in if @option{-msim} is not given.
8736 Specifies that the program will be run on the simulator. This causes
8737 the simulator BSP provided by libgloss to be linked in. This option
8738 has effect only for @samp{bfin-elf} toolchain.
8739 Certain other options, such as @option{-mid-shared-library} and
8740 @option{-mfdpic}, imply @option{-msim}.
8742 @item -momit-leaf-frame-pointer
8743 @opindex momit-leaf-frame-pointer
8744 Don't keep the frame pointer in a register for leaf functions. This
8745 avoids the instructions to save, set up and restore frame pointers and
8746 makes an extra register available in leaf functions. The option
8747 @option{-fomit-frame-pointer} removes the frame pointer for all functions
8748 which might make debugging harder.
8750 @item -mspecld-anomaly
8751 @opindex mspecld-anomaly
8752 When enabled, the compiler will ensure that the generated code does not
8753 contain speculative loads after jump instructions. If this option is used,
8754 @code{__WORKAROUND_SPECULATIVE_LOADS} is defined.
8756 @item -mno-specld-anomaly
8757 @opindex mno-specld-anomaly
8758 Don't generate extra code to prevent speculative loads from occurring.
8760 @item -mcsync-anomaly
8761 @opindex mcsync-anomaly
8762 When enabled, the compiler will ensure that the generated code does not
8763 contain CSYNC or SSYNC instructions too soon after conditional branches.
8764 If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined.
8766 @item -mno-csync-anomaly
8767 @opindex mno-csync-anomaly
8768 Don't generate extra code to prevent CSYNC or SSYNC instructions from
8769 occurring too soon after a conditional branch.
8773 When enabled, the compiler is free to take advantage of the knowledge that
8774 the entire program fits into the low 64k of memory.
8777 @opindex mno-low-64k
8778 Assume that the program is arbitrarily large. This is the default.
8780 @item -mstack-check-l1
8781 @opindex mstack-check-l1
8782 Do stack checking using information placed into L1 scratchpad memory by the
8785 @item -mid-shared-library
8786 @opindex mid-shared-library
8787 Generate code that supports shared libraries via the library ID method.
8788 This allows for execute in place and shared libraries in an environment
8789 without virtual memory management. This option implies @option{-fPIC}.
8790 With a @samp{bfin-elf} target, this option implies @option{-msim}.
8792 @item -mno-id-shared-library
8793 @opindex mno-id-shared-library
8794 Generate code that doesn't assume ID based shared libraries are being used.
8795 This is the default.
8797 @item -mleaf-id-shared-library
8798 @opindex mleaf-id-shared-library
8799 Generate code that supports shared libraries via the library ID method,
8800 but assumes that this library or executable won't link against any other
8801 ID shared libraries. That allows the compiler to use faster code for jumps
8804 @item -mno-leaf-id-shared-library
8805 @opindex mno-leaf-id-shared-library
8806 Do not assume that the code being compiled won't link against any ID shared
8807 libraries. Slower code will be generated for jump and call insns.
8809 @item -mshared-library-id=n
8810 @opindex mshared-library-id
8811 Specified the identification number of the ID based shared library being
8812 compiled. Specifying a value of 0 will generate more compact code, specifying
8813 other values will force the allocation of that number to the current
8814 library but is no more space or time efficient than omitting this option.
8818 Generate code that allows the data segment to be located in a different
8819 area of memory from the text segment. This allows for execute in place in
8820 an environment without virtual memory management by eliminating relocations
8821 against the text section.
8824 @opindex mno-sep-data
8825 Generate code that assumes that the data segment follows the text segment.
8826 This is the default.
8829 @itemx -mno-long-calls
8830 @opindex mlong-calls
8831 @opindex mno-long-calls
8832 Tells the compiler to perform function calls by first loading the
8833 address of the function into a register and then performing a subroutine
8834 call on this register. This switch is needed if the target function
8835 will lie outside of the 24 bit addressing range of the offset based
8836 version of subroutine call instruction.
8838 This feature is not enabled by default. Specifying
8839 @option{-mno-long-calls} will restore the default behavior. Note these
8840 switches have no effect on how the compiler generates code to handle
8841 function calls via function pointers.
8845 Link with the fast floating-point library. This library relaxes some of
8846 the IEEE floating-point standard's rules for checking inputs against
8847 Not-a-Number (NAN), in the interest of performance.
8850 @opindex minline-plt
8851 Enable inlining of PLT entries in function calls to functions that are
8852 not known to bind locally. It has no effect without @option{-mfdpic}.
8856 @subsection CRIS Options
8857 @cindex CRIS Options
8859 These options are defined specifically for the CRIS ports.
8862 @item -march=@var{architecture-type}
8863 @itemx -mcpu=@var{architecture-type}
8866 Generate code for the specified architecture. The choices for
8867 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
8868 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
8869 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
8872 @item -mtune=@var{architecture-type}
8874 Tune to @var{architecture-type} everything applicable about the generated
8875 code, except for the ABI and the set of available instructions. The
8876 choices for @var{architecture-type} are the same as for
8877 @option{-march=@var{architecture-type}}.
8879 @item -mmax-stack-frame=@var{n}
8880 @opindex mmax-stack-frame
8881 Warn when the stack frame of a function exceeds @var{n} bytes.
8883 @item -melinux-stacksize=@var{n}
8884 @opindex melinux-stacksize
8885 Only available with the @samp{cris-axis-aout} target. Arranges for
8886 indications in the program to the kernel loader that the stack of the
8887 program should be set to @var{n} bytes.
8893 The options @option{-metrax4} and @option{-metrax100} are synonyms for
8894 @option{-march=v3} and @option{-march=v8} respectively.
8896 @item -mmul-bug-workaround
8897 @itemx -mno-mul-bug-workaround
8898 @opindex mmul-bug-workaround
8899 @opindex mno-mul-bug-workaround
8900 Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
8901 models where it applies. This option is active by default.
8905 Enable CRIS-specific verbose debug-related information in the assembly
8906 code. This option also has the effect to turn off the @samp{#NO_APP}
8907 formatted-code indicator to the assembler at the beginning of the
8912 Do not use condition-code results from previous instruction; always emit
8913 compare and test instructions before use of condition codes.
8915 @item -mno-side-effects
8916 @opindex mno-side-effects
8917 Do not emit instructions with side-effects in addressing modes other than
8921 @itemx -mno-stack-align
8923 @itemx -mno-data-align
8924 @itemx -mconst-align
8925 @itemx -mno-const-align
8926 @opindex mstack-align
8927 @opindex mno-stack-align
8928 @opindex mdata-align
8929 @opindex mno-data-align
8930 @opindex mconst-align
8931 @opindex mno-const-align
8932 These options (no-options) arranges (eliminate arrangements) for the
8933 stack-frame, individual data and constants to be aligned for the maximum
8934 single data access size for the chosen CPU model. The default is to
8935 arrange for 32-bit alignment. ABI details such as structure layout are
8936 not affected by these options.
8944 Similar to the stack- data- and const-align options above, these options
8945 arrange for stack-frame, writable data and constants to all be 32-bit,
8946 16-bit or 8-bit aligned. The default is 32-bit alignment.
8948 @item -mno-prologue-epilogue
8949 @itemx -mprologue-epilogue
8950 @opindex mno-prologue-epilogue
8951 @opindex mprologue-epilogue
8952 With @option{-mno-prologue-epilogue}, the normal function prologue and
8953 epilogue that sets up the stack-frame are omitted and no return
8954 instructions or return sequences are generated in the code. Use this
8955 option only together with visual inspection of the compiled code: no
8956 warnings or errors are generated when call-saved registers must be saved,
8957 or storage for local variable needs to be allocated.
8963 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
8964 instruction sequences that load addresses for functions from the PLT part
8965 of the GOT rather than (traditional on other architectures) calls to the
8966 PLT@. The default is @option{-mgotplt}.
8970 Legacy no-op option only recognized with the cris-axis-aout target.
8974 Legacy no-op option only recognized with the cris-axis-elf and
8975 cris-axis-linux-gnu targets.
8979 Only recognized with the cris-axis-aout target, where it selects a
8980 GNU/linux-like multilib, include files and instruction set for
8985 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
8989 This option, recognized for the cris-axis-aout and cris-axis-elf arranges
8990 to link with input-output functions from a simulator library. Code,
8991 initialized data and zero-initialized data are allocated consecutively.
8995 Like @option{-sim}, but pass linker options to locate initialized data at
8996 0x40000000 and zero-initialized data at 0x80000000.
9000 @subsection CRX Options
9003 These options are defined specifically for the CRX ports.
9009 Enable the use of multiply-accumulate instructions. Disabled by default.
9013 Push instructions will be used to pass outgoing arguments when functions
9014 are called. Enabled by default.
9017 @node Darwin Options
9018 @subsection Darwin Options
9019 @cindex Darwin options
9021 These options are defined for all architectures running the Darwin operating
9024 FSF GCC on Darwin does not create ``fat'' object files; it will create
9025 an object file for the single architecture that it was built to
9026 target. Apple's GCC on Darwin does create ``fat'' files if multiple
9027 @option{-arch} options are used; it does so by running the compiler or
9028 linker multiple times and joining the results together with
9031 The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
9032 @samp{i686}) is determined by the flags that specify the ISA
9033 that GCC is targetting, like @option{-mcpu} or @option{-march}. The
9034 @option{-force_cpusubtype_ALL} option can be used to override this.
9036 The Darwin tools vary in their behavior when presented with an ISA
9037 mismatch. The assembler, @file{as}, will only permit instructions to
9038 be used that are valid for the subtype of the file it is generating,
9039 so you cannot put 64-bit instructions in an @samp{ppc750} object file.
9040 The linker for shared libraries, @file{/usr/bin/libtool}, will fail
9041 and print an error if asked to create a shared library with a less
9042 restrictive subtype than its input files (for instance, trying to put
9043 a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
9044 for executables, @file{ld}, will quietly give the executable the most
9045 restrictive subtype of any of its input files.
9050 Add the framework directory @var{dir} to the head of the list of
9051 directories to be searched for header files. These directories are
9052 interleaved with those specified by @option{-I} options and are
9053 scanned in a left-to-right order.
9055 A framework directory is a directory with frameworks in it. A
9056 framework is a directory with a @samp{"Headers"} and/or
9057 @samp{"PrivateHeaders"} directory contained directly in it that ends
9058 in @samp{".framework"}. The name of a framework is the name of this
9059 directory excluding the @samp{".framework"}. Headers associated with
9060 the framework are found in one of those two directories, with
9061 @samp{"Headers"} being searched first. A subframework is a framework
9062 directory that is in a framework's @samp{"Frameworks"} directory.
9063 Includes of subframework headers can only appear in a header of a
9064 framework that contains the subframework, or in a sibling subframework
9065 header. Two subframeworks are siblings if they occur in the same
9066 framework. A subframework should not have the same name as a
9067 framework, a warning will be issued if this is violated. Currently a
9068 subframework cannot have subframeworks, in the future, the mechanism
9069 may be extended to support this. The standard frameworks can be found
9070 in @samp{"/System/Library/Frameworks"} and
9071 @samp{"/Library/Frameworks"}. An example include looks like
9072 @code{#include <Framework/header.h>}, where @samp{Framework} denotes
9073 the name of the framework and header.h is found in the
9074 @samp{"PrivateHeaders"} or @samp{"Headers"} directory.
9076 @item -iframework@var{dir}
9078 Like @option{-F} except the directory is a treated as a system
9079 directory. The main difference between this @option{-iframework} and
9080 @option{-F} is that with @option{-iframework} the compiler does not
9081 warn about constructs contained within header files found via
9082 @var{dir}. This option is valid only for the C family of languages.
9086 Emit debugging information for symbols that are used. For STABS
9087 debugging format, this enables @option{-feliminate-unused-debug-symbols}.
9088 This is by default ON@.
9092 Emit debugging information for all symbols and types.
9094 @item -mmacosx-version-min=@var{version}
9095 The earliest version of MacOS X that this executable will run on
9096 is @var{version}. Typical values of @var{version} include @code{10.1},
9097 @code{10.2}, and @code{10.3.9}.
9099 If the compiler was built to use the system's headers by default,
9100 then the default for this option is the system version on which the
9101 compiler is running, otherwise the default is to make choices which
9102 are compatible with as many systems and code bases as possible.
9106 Enable kernel development mode. The @option{-mkernel} option sets
9107 @option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
9108 @option{-fno-exceptions}, @option{-fno-non-call-exceptions},
9109 @option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
9110 applicable. This mode also sets @option{-mno-altivec},
9111 @option{-msoft-float}, @option{-fno-builtin} and
9112 @option{-mlong-branch} for PowerPC targets.
9114 @item -mone-byte-bool
9115 @opindex mone-byte-bool
9116 Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
9117 By default @samp{sizeof(bool)} is @samp{4} when compiling for
9118 Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
9119 option has no effect on x86.
9121 @strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
9122 to generate code that is not binary compatible with code generated
9123 without that switch. Using this switch may require recompiling all
9124 other modules in a program, including system libraries. Use this
9125 switch to conform to a non-default data model.
9127 @item -mfix-and-continue
9128 @itemx -ffix-and-continue
9129 @itemx -findirect-data
9130 @opindex mfix-and-continue
9131 @opindex ffix-and-continue
9132 @opindex findirect-data
9133 Generate code suitable for fast turn around development. Needed to
9134 enable gdb to dynamically load @code{.o} files into already running
9135 programs. @option{-findirect-data} and @option{-ffix-and-continue}
9136 are provided for backwards compatibility.
9140 Loads all members of static archive libraries.
9141 See man ld(1) for more information.
9143 @item -arch_errors_fatal
9144 @opindex arch_errors_fatal
9145 Cause the errors having to do with files that have the wrong architecture
9149 @opindex bind_at_load
9150 Causes the output file to be marked such that the dynamic linker will
9151 bind all undefined references when the file is loaded or launched.
9155 Produce a Mach-o bundle format file.
9156 See man ld(1) for more information.
9158 @item -bundle_loader @var{executable}
9159 @opindex bundle_loader
9160 This option specifies the @var{executable} that will be loading the build
9161 output file being linked. See man ld(1) for more information.
9165 When passed this option, GCC will produce a dynamic library instead of
9166 an executable when linking, using the Darwin @file{libtool} command.
9168 @item -force_cpusubtype_ALL
9169 @opindex force_cpusubtype_ALL
9170 This causes GCC's output file to have the @var{ALL} subtype, instead of
9171 one controlled by the @option{-mcpu} or @option{-march} option.
9173 @item -allowable_client @var{client_name}
9175 @itemx -compatibility_version
9176 @itemx -current_version
9178 @itemx -dependency-file
9180 @itemx -dylinker_install_name
9182 @itemx -exported_symbols_list
9184 @itemx -flat_namespace
9185 @itemx -force_flat_namespace
9186 @itemx -headerpad_max_install_names
9189 @itemx -install_name
9190 @itemx -keep_private_externs
9191 @itemx -multi_module
9192 @itemx -multiply_defined
9193 @itemx -multiply_defined_unused
9195 @itemx -no_dead_strip_inits_and_terms
9196 @itemx -nofixprebinding
9199 @itemx -noseglinkedit
9200 @itemx -pagezero_size
9202 @itemx -prebind_all_twolevel_modules
9203 @itemx -private_bundle
9204 @itemx -read_only_relocs
9206 @itemx -sectobjectsymbols
9210 @itemx -sectobjectsymbols
9213 @itemx -segs_read_only_addr
9214 @itemx -segs_read_write_addr
9215 @itemx -seg_addr_table
9216 @itemx -seg_addr_table_filename
9219 @itemx -segs_read_only_addr
9220 @itemx -segs_read_write_addr
9221 @itemx -single_module
9224 @itemx -sub_umbrella
9225 @itemx -twolevel_namespace
9228 @itemx -unexported_symbols_list
9229 @itemx -weak_reference_mismatches
9232 @opindex allowable_client
9233 @opindex client_name
9234 @opindex compatibility_version
9235 @opindex current_version
9237 @opindex dependency-file
9239 @opindex dylinker_install_name
9241 @opindex exported_symbols_list
9243 @opindex flat_namespace
9244 @opindex force_flat_namespace
9245 @opindex headerpad_max_install_names
9248 @opindex install_name
9249 @opindex keep_private_externs
9250 @opindex multi_module
9251 @opindex multiply_defined
9252 @opindex multiply_defined_unused
9254 @opindex no_dead_strip_inits_and_terms
9255 @opindex nofixprebinding
9256 @opindex nomultidefs
9258 @opindex noseglinkedit
9259 @opindex pagezero_size
9261 @opindex prebind_all_twolevel_modules
9262 @opindex private_bundle
9263 @opindex read_only_relocs
9265 @opindex sectobjectsymbols
9269 @opindex sectobjectsymbols
9272 @opindex segs_read_only_addr
9273 @opindex segs_read_write_addr
9274 @opindex seg_addr_table
9275 @opindex seg_addr_table_filename
9276 @opindex seglinkedit
9278 @opindex segs_read_only_addr
9279 @opindex segs_read_write_addr
9280 @opindex single_module
9282 @opindex sub_library
9283 @opindex sub_umbrella
9284 @opindex twolevel_namespace
9287 @opindex unexported_symbols_list
9288 @opindex weak_reference_mismatches
9289 @opindex whatsloaded
9291 These options are passed to the Darwin linker. The Darwin linker man page
9292 describes them in detail.
9295 @node DEC Alpha Options
9296 @subsection DEC Alpha Options
9298 These @samp{-m} options are defined for the DEC Alpha implementations:
9301 @item -mno-soft-float
9303 @opindex mno-soft-float
9304 @opindex msoft-float
9305 Use (do not use) the hardware floating-point instructions for
9306 floating-point operations. When @option{-msoft-float} is specified,
9307 functions in @file{libgcc.a} will be used to perform floating-point
9308 operations. Unless they are replaced by routines that emulate the
9309 floating-point operations, or compiled in such a way as to call such
9310 emulations routines, these routines will issue floating-point
9311 operations. If you are compiling for an Alpha without floating-point
9312 operations, you must ensure that the library is built so as not to call
9315 Note that Alpha implementations without floating-point operations are
9316 required to have floating-point registers.
9321 @opindex mno-fp-regs
9322 Generate code that uses (does not use) the floating-point register set.
9323 @option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
9324 register set is not used, floating point operands are passed in integer
9325 registers as if they were integers and floating-point results are passed
9326 in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
9327 so any function with a floating-point argument or return value called by code
9328 compiled with @option{-mno-fp-regs} must also be compiled with that
9331 A typical use of this option is building a kernel that does not use,
9332 and hence need not save and restore, any floating-point registers.
9336 The Alpha architecture implements floating-point hardware optimized for
9337 maximum performance. It is mostly compliant with the IEEE floating
9338 point standard. However, for full compliance, software assistance is
9339 required. This option generates code fully IEEE compliant code
9340 @emph{except} that the @var{inexact-flag} is not maintained (see below).
9341 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
9342 defined during compilation. The resulting code is less efficient but is
9343 able to correctly support denormalized numbers and exceptional IEEE
9344 values such as not-a-number and plus/minus infinity. Other Alpha
9345 compilers call this option @option{-ieee_with_no_inexact}.
9347 @item -mieee-with-inexact
9348 @opindex mieee-with-inexact
9349 This is like @option{-mieee} except the generated code also maintains
9350 the IEEE @var{inexact-flag}. Turning on this option causes the
9351 generated code to implement fully-compliant IEEE math. In addition to
9352 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
9353 macro. On some Alpha implementations the resulting code may execute
9354 significantly slower than the code generated by default. Since there is
9355 very little code that depends on the @var{inexact-flag}, you should
9356 normally not specify this option. Other Alpha compilers call this
9357 option @option{-ieee_with_inexact}.
9359 @item -mfp-trap-mode=@var{trap-mode}
9360 @opindex mfp-trap-mode
9361 This option controls what floating-point related traps are enabled.
9362 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
9363 The trap mode can be set to one of four values:
9367 This is the default (normal) setting. The only traps that are enabled
9368 are the ones that cannot be disabled in software (e.g., division by zero
9372 In addition to the traps enabled by @samp{n}, underflow traps are enabled
9376 Like @samp{u}, but the instructions are marked to be safe for software
9377 completion (see Alpha architecture manual for details).
9380 Like @samp{su}, but inexact traps are enabled as well.
9383 @item -mfp-rounding-mode=@var{rounding-mode}
9384 @opindex mfp-rounding-mode
9385 Selects the IEEE rounding mode. Other Alpha compilers call this option
9386 @option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
9391 Normal IEEE rounding mode. Floating point numbers are rounded towards
9392 the nearest machine number or towards the even machine number in case
9396 Round towards minus infinity.
9399 Chopped rounding mode. Floating point numbers are rounded towards zero.
9402 Dynamic rounding mode. A field in the floating point control register
9403 (@var{fpcr}, see Alpha architecture reference manual) controls the
9404 rounding mode in effect. The C library initializes this register for
9405 rounding towards plus infinity. Thus, unless your program modifies the
9406 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
9409 @item -mtrap-precision=@var{trap-precision}
9410 @opindex mtrap-precision
9411 In the Alpha architecture, floating point traps are imprecise. This
9412 means without software assistance it is impossible to recover from a
9413 floating trap and program execution normally needs to be terminated.
9414 GCC can generate code that can assist operating system trap handlers
9415 in determining the exact location that caused a floating point trap.
9416 Depending on the requirements of an application, different levels of
9417 precisions can be selected:
9421 Program precision. This option is the default and means a trap handler
9422 can only identify which program caused a floating point exception.
9425 Function precision. The trap handler can determine the function that
9426 caused a floating point exception.
9429 Instruction precision. The trap handler can determine the exact
9430 instruction that caused a floating point exception.
9433 Other Alpha compilers provide the equivalent options called
9434 @option{-scope_safe} and @option{-resumption_safe}.
9436 @item -mieee-conformant
9437 @opindex mieee-conformant
9438 This option marks the generated code as IEEE conformant. You must not
9439 use this option unless you also specify @option{-mtrap-precision=i} and either
9440 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
9441 is to emit the line @samp{.eflag 48} in the function prologue of the
9442 generated assembly file. Under DEC Unix, this has the effect that
9443 IEEE-conformant math library routines will be linked in.
9445 @item -mbuild-constants
9446 @opindex mbuild-constants
9447 Normally GCC examines a 32- or 64-bit integer constant to
9448 see if it can construct it from smaller constants in two or three
9449 instructions. If it cannot, it will output the constant as a literal and
9450 generate code to load it from the data segment at runtime.
9452 Use this option to require GCC to construct @emph{all} integer constants
9453 using code, even if it takes more instructions (the maximum is six).
9455 You would typically use this option to build a shared library dynamic
9456 loader. Itself a shared library, it must relocate itself in memory
9457 before it can find the variables and constants in its own data segment.
9463 Select whether to generate code to be assembled by the vendor-supplied
9464 assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
9482 Indicate whether GCC should generate code to use the optional BWX,
9483 CIX, FIX and MAX instruction sets. The default is to use the instruction
9484 sets supported by the CPU type specified via @option{-mcpu=} option or that
9485 of the CPU on which GCC was built if none was specified.
9490 @opindex mfloat-ieee
9491 Generate code that uses (does not use) VAX F and G floating point
9492 arithmetic instead of IEEE single and double precision.
9494 @item -mexplicit-relocs
9495 @itemx -mno-explicit-relocs
9496 @opindex mexplicit-relocs
9497 @opindex mno-explicit-relocs
9498 Older Alpha assemblers provided no way to generate symbol relocations
9499 except via assembler macros. Use of these macros does not allow
9500 optimal instruction scheduling. GNU binutils as of version 2.12
9501 supports a new syntax that allows the compiler to explicitly mark
9502 which relocations should apply to which instructions. This option
9503 is mostly useful for debugging, as GCC detects the capabilities of
9504 the assembler when it is built and sets the default accordingly.
9508 @opindex msmall-data
9509 @opindex mlarge-data
9510 When @option{-mexplicit-relocs} is in effect, static data is
9511 accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
9512 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
9513 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
9514 16-bit relocations off of the @code{$gp} register. This limits the
9515 size of the small data area to 64KB, but allows the variables to be
9516 directly accessed via a single instruction.
9518 The default is @option{-mlarge-data}. With this option the data area
9519 is limited to just below 2GB@. Programs that require more than 2GB of
9520 data must use @code{malloc} or @code{mmap} to allocate the data in the
9521 heap instead of in the program's data segment.
9523 When generating code for shared libraries, @option{-fpic} implies
9524 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
9528 @opindex msmall-text
9529 @opindex mlarge-text
9530 When @option{-msmall-text} is used, the compiler assumes that the
9531 code of the entire program (or shared library) fits in 4MB, and is
9532 thus reachable with a branch instruction. When @option{-msmall-data}
9533 is used, the compiler can assume that all local symbols share the
9534 same @code{$gp} value, and thus reduce the number of instructions
9535 required for a function call from 4 to 1.
9537 The default is @option{-mlarge-text}.
9539 @item -mcpu=@var{cpu_type}
9541 Set the instruction set and instruction scheduling parameters for
9542 machine type @var{cpu_type}. You can specify either the @samp{EV}
9543 style name or the corresponding chip number. GCC supports scheduling
9544 parameters for the EV4, EV5 and EV6 family of processors and will
9545 choose the default values for the instruction set from the processor
9546 you specify. If you do not specify a processor type, GCC will default
9547 to the processor on which the compiler was built.
9549 Supported values for @var{cpu_type} are
9555 Schedules as an EV4 and has no instruction set extensions.
9559 Schedules as an EV5 and has no instruction set extensions.
9563 Schedules as an EV5 and supports the BWX extension.
9568 Schedules as an EV5 and supports the BWX and MAX extensions.
9572 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
9576 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
9579 @item -mtune=@var{cpu_type}
9581 Set only the instruction scheduling parameters for machine type
9582 @var{cpu_type}. The instruction set is not changed.
9584 @item -mmemory-latency=@var{time}
9585 @opindex mmemory-latency
9586 Sets the latency the scheduler should assume for typical memory
9587 references as seen by the application. This number is highly
9588 dependent on the memory access patterns used by the application
9589 and the size of the external cache on the machine.
9591 Valid options for @var{time} are
9595 A decimal number representing clock cycles.
9601 The compiler contains estimates of the number of clock cycles for
9602 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
9603 (also called Dcache, Scache, and Bcache), as well as to main memory.
9604 Note that L3 is only valid for EV5.
9609 @node DEC Alpha/VMS Options
9610 @subsection DEC Alpha/VMS Options
9612 These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
9615 @item -mvms-return-codes
9616 @opindex mvms-return-codes
9617 Return VMS condition codes from main. The default is to return POSIX
9618 style condition (e.g.@: error) codes.
9622 @subsection FRV Options
9629 Only use the first 32 general purpose registers.
9634 Use all 64 general purpose registers.
9639 Use only the first 32 floating point registers.
9644 Use all 64 floating point registers
9647 @opindex mhard-float
9649 Use hardware instructions for floating point operations.
9652 @opindex msoft-float
9654 Use library routines for floating point operations.
9659 Dynamically allocate condition code registers.
9664 Do not try to dynamically allocate condition code registers, only
9665 use @code{icc0} and @code{fcc0}.
9670 Change ABI to use double word insns.
9675 Do not use double word instructions.
9680 Use floating point double instructions.
9685 Do not use floating point double instructions.
9690 Use media instructions.
9695 Do not use media instructions.
9700 Use multiply and add/subtract instructions.
9705 Do not use multiply and add/subtract instructions.
9710 Select the FDPIC ABI, that uses function descriptors to represent
9711 pointers to functions. Without any PIC/PIE-related options, it
9712 implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
9713 assumes GOT entries and small data are within a 12-bit range from the
9714 GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
9715 are computed with 32 bits.
9716 With a @samp{bfin-elf} target, this option implies @option{-msim}.
9719 @opindex minline-plt
9721 Enable inlining of PLT entries in function calls to functions that are
9722 not known to bind locally. It has no effect without @option{-mfdpic}.
9723 It's enabled by default if optimizing for speed and compiling for
9724 shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
9725 optimization option such as @option{-O3} or above is present in the
9731 Assume a large TLS segment when generating thread-local code.
9736 Do not assume a large TLS segment when generating thread-local code.
9741 Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
9742 that is known to be in read-only sections. It's enabled by default,
9743 except for @option{-fpic} or @option{-fpie}: even though it may help
9744 make the global offset table smaller, it trades 1 instruction for 4.
9745 With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
9746 one of which may be shared by multiple symbols, and it avoids the need
9747 for a GOT entry for the referenced symbol, so it's more likely to be a
9748 win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
9750 @item -multilib-library-pic
9751 @opindex multilib-library-pic
9753 Link with the (library, not FD) pic libraries. It's implied by
9754 @option{-mlibrary-pic}, as well as by @option{-fPIC} and
9755 @option{-fpic} without @option{-mfdpic}. You should never have to use
9761 Follow the EABI requirement of always creating a frame pointer whenever
9762 a stack frame is allocated. This option is enabled by default and can
9763 be disabled with @option{-mno-linked-fp}.
9766 @opindex mlong-calls
9768 Use indirect addressing to call functions outside the current
9769 compilation unit. This allows the functions to be placed anywhere
9770 within the 32-bit address space.
9772 @item -malign-labels
9773 @opindex malign-labels
9775 Try to align labels to an 8-byte boundary by inserting nops into the
9776 previous packet. This option only has an effect when VLIW packing
9777 is enabled. It doesn't create new packets; it merely adds nops to
9781 @opindex mlibrary-pic
9783 Generate position-independent EABI code.
9788 Use only the first four media accumulator registers.
9793 Use all eight media accumulator registers.
9798 Pack VLIW instructions.
9803 Do not pack VLIW instructions.
9808 Do not mark ABI switches in e_flags.
9813 Enable the use of conditional-move instructions (default).
9815 This switch is mainly for debugging the compiler and will likely be removed
9816 in a future version.
9818 @item -mno-cond-move
9819 @opindex mno-cond-move
9821 Disable the use of conditional-move instructions.
9823 This switch is mainly for debugging the compiler and will likely be removed
9824 in a future version.
9829 Enable the use of conditional set instructions (default).
9831 This switch is mainly for debugging the compiler and will likely be removed
9832 in a future version.
9837 Disable the use of conditional set instructions.
9839 This switch is mainly for debugging the compiler and will likely be removed
9840 in a future version.
9845 Enable the use of conditional execution (default).
9847 This switch is mainly for debugging the compiler and will likely be removed
9848 in a future version.
9850 @item -mno-cond-exec
9851 @opindex mno-cond-exec
9853 Disable the use of conditional execution.
9855 This switch is mainly for debugging the compiler and will likely be removed
9856 in a future version.
9859 @opindex mvliw-branch
9861 Run a pass to pack branches into VLIW instructions (default).
9863 This switch is mainly for debugging the compiler and will likely be removed
9864 in a future version.
9866 @item -mno-vliw-branch
9867 @opindex mno-vliw-branch
9869 Do not run a pass to pack branches into VLIW instructions.
9871 This switch is mainly for debugging the compiler and will likely be removed
9872 in a future version.
9874 @item -mmulti-cond-exec
9875 @opindex mmulti-cond-exec
9877 Enable optimization of @code{&&} and @code{||} in conditional execution
9880 This switch is mainly for debugging the compiler and will likely be removed
9881 in a future version.
9883 @item -mno-multi-cond-exec
9884 @opindex mno-multi-cond-exec
9886 Disable optimization of @code{&&} and @code{||} in conditional execution.
9888 This switch is mainly for debugging the compiler and will likely be removed
9889 in a future version.
9891 @item -mnested-cond-exec
9892 @opindex mnested-cond-exec
9894 Enable nested conditional execution optimizations (default).
9896 This switch is mainly for debugging the compiler and will likely be removed
9897 in a future version.
9899 @item -mno-nested-cond-exec
9900 @opindex mno-nested-cond-exec
9902 Disable nested conditional execution optimizations.
9904 This switch is mainly for debugging the compiler and will likely be removed
9905 in a future version.
9907 @item -moptimize-membar
9908 @opindex moptimize-membar
9910 This switch removes redundant @code{membar} instructions from the
9911 compiler generated code. It is enabled by default.
9913 @item -mno-optimize-membar
9914 @opindex mno-optimize-membar
9916 This switch disables the automatic removal of redundant @code{membar}
9917 instructions from the generated code.
9919 @item -mtomcat-stats
9920 @opindex mtomcat-stats
9922 Cause gas to print out tomcat statistics.
9924 @item -mcpu=@var{cpu}
9927 Select the processor type for which to generate code. Possible values are
9928 @samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
9929 @samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
9933 @node GNU/Linux Options
9934 @subsection GNU/Linux Options
9936 These @samp{-m} options are defined for GNU/Linux targets:
9941 Use the GNU C library instead of uClibc. This is the default except
9942 on @samp{*-*-linux-*uclibc*} targets.
9946 Use uClibc instead of the GNU C library. This is the default on
9947 @samp{*-*-linux-*uclibc*} targets.
9950 @node H8/300 Options
9951 @subsection H8/300 Options
9953 These @samp{-m} options are defined for the H8/300 implementations:
9958 Shorten some address references at link time, when possible; uses the
9959 linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
9960 ld, Using ld}, for a fuller description.
9964 Generate code for the H8/300H@.
9968 Generate code for the H8S@.
9972 Generate code for the H8S and H8/300H in the normal mode. This switch
9973 must be used either with @option{-mh} or @option{-ms}.
9977 Generate code for the H8S/2600. This switch must be used with @option{-ms}.
9981 Make @code{int} data 32 bits by default.
9985 On the H8/300H and H8S, use the same alignment rules as for the H8/300.
9986 The default for the H8/300H and H8S is to align longs and floats on 4
9988 @option{-malign-300} causes them to be aligned on 2 byte boundaries.
9989 This option has no effect on the H8/300.
9993 @subsection HPPA Options
9994 @cindex HPPA Options
9996 These @samp{-m} options are defined for the HPPA family of computers:
9999 @item -march=@var{architecture-type}
10001 Generate code for the specified architecture. The choices for
10002 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
10003 1.1, and @samp{2.0} for PA 2.0 processors. Refer to
10004 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
10005 architecture option for your machine. Code compiled for lower numbered
10006 architectures will run on higher numbered architectures, but not the
10009 @item -mpa-risc-1-0
10010 @itemx -mpa-risc-1-1
10011 @itemx -mpa-risc-2-0
10012 @opindex mpa-risc-1-0
10013 @opindex mpa-risc-1-1
10014 @opindex mpa-risc-2-0
10015 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
10018 @opindex mbig-switch
10019 Generate code suitable for big switch tables. Use this option only if
10020 the assembler/linker complain about out of range branches within a switch
10023 @item -mjump-in-delay
10024 @opindex mjump-in-delay
10025 Fill delay slots of function calls with unconditional jump instructions
10026 by modifying the return pointer for the function call to be the target
10027 of the conditional jump.
10029 @item -mdisable-fpregs
10030 @opindex mdisable-fpregs
10031 Prevent floating point registers from being used in any manner. This is
10032 necessary for compiling kernels which perform lazy context switching of
10033 floating point registers. If you use this option and attempt to perform
10034 floating point operations, the compiler will abort.
10036 @item -mdisable-indexing
10037 @opindex mdisable-indexing
10038 Prevent the compiler from using indexing address modes. This avoids some
10039 rather obscure problems when compiling MIG generated code under MACH@.
10041 @item -mno-space-regs
10042 @opindex mno-space-regs
10043 Generate code that assumes the target has no space registers. This allows
10044 GCC to generate faster indirect calls and use unscaled index address modes.
10046 Such code is suitable for level 0 PA systems and kernels.
10048 @item -mfast-indirect-calls
10049 @opindex mfast-indirect-calls
10050 Generate code that assumes calls never cross space boundaries. This
10051 allows GCC to emit code which performs faster indirect calls.
10053 This option will not work in the presence of shared libraries or nested
10056 @item -mfixed-range=@var{register-range}
10057 @opindex mfixed-range
10058 Generate code treating the given register range as fixed registers.
10059 A fixed register is one that the register allocator can not use. This is
10060 useful when compiling kernel code. A register range is specified as
10061 two registers separated by a dash. Multiple register ranges can be
10062 specified separated by a comma.
10064 @item -mlong-load-store
10065 @opindex mlong-load-store
10066 Generate 3-instruction load and store sequences as sometimes required by
10067 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
10070 @item -mportable-runtime
10071 @opindex mportable-runtime
10072 Use the portable calling conventions proposed by HP for ELF systems.
10076 Enable the use of assembler directives only GAS understands.
10078 @item -mschedule=@var{cpu-type}
10080 Schedule code according to the constraints for the machine type
10081 @var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
10082 @samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
10083 to @file{/usr/lib/sched.models} on an HP-UX system to determine the
10084 proper scheduling option for your machine. The default scheduling is
10088 @opindex mlinker-opt
10089 Enable the optimization pass in the HP-UX linker. Note this makes symbolic
10090 debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
10091 linkers in which they give bogus error messages when linking some programs.
10094 @opindex msoft-float
10095 Generate output containing library calls for floating point.
10096 @strong{Warning:} the requisite libraries are not available for all HPPA
10097 targets. Normally the facilities of the machine's usual C compiler are
10098 used, but this cannot be done directly in cross-compilation. You must make
10099 your own arrangements to provide suitable library functions for
10100 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
10101 does provide software floating point support.
10103 @option{-msoft-float} changes the calling convention in the output file;
10104 therefore, it is only useful if you compile @emph{all} of a program with
10105 this option. In particular, you need to compile @file{libgcc.a}, the
10106 library that comes with GCC, with @option{-msoft-float} in order for
10111 Generate the predefine, @code{_SIO}, for server IO@. The default is
10112 @option{-mwsio}. This generates the predefines, @code{__hp9000s700},
10113 @code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
10114 options are available under HP-UX and HI-UX@.
10118 Use GNU ld specific options. This passes @option{-shared} to ld when
10119 building a shared library. It is the default when GCC is configured,
10120 explicitly or implicitly, with the GNU linker. This option does not
10121 have any affect on which ld is called, it only changes what parameters
10122 are passed to that ld. The ld that is called is determined by the
10123 @option{--with-ld} configure option, GCC's program search path, and
10124 finally by the user's @env{PATH}. The linker used by GCC can be printed
10125 using @samp{which `gcc -print-prog-name=ld`}. This option is only available
10126 on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
10130 Use HP ld specific options. This passes @option{-b} to ld when building
10131 a shared library and passes @option{+Accept TypeMismatch} to ld on all
10132 links. It is the default when GCC is configured, explicitly or
10133 implicitly, with the HP linker. This option does not have any affect on
10134 which ld is called, it only changes what parameters are passed to that
10135 ld. The ld that is called is determined by the @option{--with-ld}
10136 configure option, GCC's program search path, and finally by the user's
10137 @env{PATH}. The linker used by GCC can be printed using @samp{which
10138 `gcc -print-prog-name=ld`}. This option is only available on the 64 bit
10139 HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
10142 @opindex mno-long-calls
10143 Generate code that uses long call sequences. This ensures that a call
10144 is always able to reach linker generated stubs. The default is to generate
10145 long calls only when the distance from the call site to the beginning
10146 of the function or translation unit, as the case may be, exceeds a
10147 predefined limit set by the branch type being used. The limits for
10148 normal calls are 7,600,000 and 240,000 bytes, respectively for the
10149 PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
10152 Distances are measured from the beginning of functions when using the
10153 @option{-ffunction-sections} option, or when using the @option{-mgas}
10154 and @option{-mno-portable-runtime} options together under HP-UX with
10157 It is normally not desirable to use this option as it will degrade
10158 performance. However, it may be useful in large applications,
10159 particularly when partial linking is used to build the application.
10161 The types of long calls used depends on the capabilities of the
10162 assembler and linker, and the type of code being generated. The
10163 impact on systems that support long absolute calls, and long pic
10164 symbol-difference or pc-relative calls should be relatively small.
10165 However, an indirect call is used on 32-bit ELF systems in pic code
10166 and it is quite long.
10168 @item -munix=@var{unix-std}
10170 Generate compiler predefines and select a startfile for the specified
10171 UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
10172 and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
10173 is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
10174 11.11 and later. The default values are @samp{93} for HP-UX 10.00,
10175 @samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
10178 @option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
10179 @option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
10180 and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
10181 @option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
10182 @code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
10183 @code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
10185 It is @emph{important} to note that this option changes the interfaces
10186 for various library routines. It also affects the operational behavior
10187 of the C library. Thus, @emph{extreme} care is needed in using this
10190 Library code that is intended to operate with more than one UNIX
10191 standard must test, set and restore the variable @var{__xpg4_extended_mask}
10192 as appropriate. Most GNU software doesn't provide this capability.
10196 Suppress the generation of link options to search libdld.sl when the
10197 @option{-static} option is specified on HP-UX 10 and later.
10201 The HP-UX implementation of setlocale in libc has a dependency on
10202 libdld.sl. There isn't an archive version of libdld.sl. Thus,
10203 when the @option{-static} option is specified, special link options
10204 are needed to resolve this dependency.
10206 On HP-UX 10 and later, the GCC driver adds the necessary options to
10207 link with libdld.sl when the @option{-static} option is specified.
10208 This causes the resulting binary to be dynamic. On the 64-bit port,
10209 the linkers generate dynamic binaries by default in any case. The
10210 @option{-nolibdld} option can be used to prevent the GCC driver from
10211 adding these link options.
10215 Add support for multithreading with the @dfn{dce thread} library
10216 under HP-UX@. This option sets flags for both the preprocessor and
10220 @node i386 and x86-64 Options
10221 @subsection Intel 386 and AMD x86-64 Options
10222 @cindex i386 Options
10223 @cindex x86-64 Options
10224 @cindex Intel 386 Options
10225 @cindex AMD x86-64 Options
10227 These @samp{-m} options are defined for the i386 and x86-64 family of
10231 @item -mtune=@var{cpu-type}
10233 Tune to @var{cpu-type} everything applicable about the generated code, except
10234 for the ABI and the set of available instructions. The choices for
10235 @var{cpu-type} are:
10238 Produce code optimized for the most common IA32/AMD64/EM64T processors.
10239 If you know the CPU on which your code will run, then you should use
10240 the corresponding @option{-mtune} option instead of
10241 @option{-mtune=generic}. But, if you do not know exactly what CPU users
10242 of your application will have, then you should use this option.
10244 As new processors are deployed in the marketplace, the behavior of this
10245 option will change. Therefore, if you upgrade to a newer version of
10246 GCC, the code generated option will change to reflect the processors
10247 that were most common when that version of GCC was released.
10249 There is no @option{-march=generic} option because @option{-march}
10250 indicates the instruction set the compiler can use, and there is no
10251 generic instruction set applicable to all processors. In contrast,
10252 @option{-mtune} indicates the processor (or, in this case, collection of
10253 processors) for which the code is optimized.
10255 This selects the CPU to tune for at compilation time by determining
10256 the processor type of the compiling machine. Using @option{-mtune=native}
10257 will produce code optimized for the local machine under the constraints
10258 of the selected instruction set. Using @option{-march=native} will
10259 enable all instruction subsets supported by the local machine (hence
10260 the result might not run on different machines).
10262 Original Intel's i386 CPU@.
10264 Intel's i486 CPU@. (No scheduling is implemented for this chip.)
10265 @item i586, pentium
10266 Intel Pentium CPU with no MMX support.
10268 Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
10270 Intel PentiumPro CPU@.
10272 Same as @code{generic}, but when used as @code{march} option, PentiumPro
10273 instruction set will be used, so the code will run on all i686 family chips.
10275 Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
10276 @item pentium3, pentium3m
10277 Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
10280 Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
10281 support. Used by Centrino notebooks.
10282 @item pentium4, pentium4m
10283 Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
10285 Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
10288 Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
10289 SSE2 and SSE3 instruction set support.
10291 Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
10292 instruction set support.
10294 AMD K6 CPU with MMX instruction set support.
10296 Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
10297 @item athlon, athlon-tbird
10298 AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
10300 @item athlon-4, athlon-xp, athlon-mp
10301 Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
10302 instruction set support.
10303 @item k8, opteron, athlon64, athlon-fx
10304 AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
10305 MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
10306 @item k8-sse3, opteron-sse3, athlon64-sse3
10307 Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
10308 @item amdfam10, barcelona
10309 AMD Family 10h core based CPUs with x86-64 instruction set support. (This
10310 supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
10311 instruction set extensions.)
10313 IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
10316 IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
10317 instruction set support.
10319 Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
10320 implemented for this chip.)
10322 Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
10323 implemented for this chip.)
10325 Embedded AMD CPU with MMX and 3dNOW! instruction set support.
10328 While picking a specific @var{cpu-type} will schedule things appropriately
10329 for that particular chip, the compiler will not generate any code that
10330 does not run on the i386 without the @option{-march=@var{cpu-type}} option
10333 @item -march=@var{cpu-type}
10335 Generate instructions for the machine type @var{cpu-type}. The choices
10336 for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
10337 specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
10339 @item -mcpu=@var{cpu-type}
10341 A deprecated synonym for @option{-mtune}.
10343 @item -mfpmath=@var{unit}
10345 Generate floating point arithmetics for selected unit @var{unit}. The choices
10346 for @var{unit} are:
10350 Use the standard 387 floating point coprocessor present majority of chips and
10351 emulated otherwise. Code compiled with this option will run almost everywhere.
10352 The temporary results are computed in 80bit precision instead of precision
10353 specified by the type resulting in slightly different results compared to most
10354 of other chips. See @option{-ffloat-store} for more detailed description.
10356 This is the default choice for i386 compiler.
10359 Use scalar floating point instructions present in the SSE instruction set.
10360 This instruction set is supported by Pentium3 and newer chips, in the AMD line
10361 by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
10362 instruction set supports only single precision arithmetics, thus the double and
10363 extended precision arithmetics is still done using 387. Later version, present
10364 only in Pentium4 and the future AMD x86-64 chips supports double precision
10367 For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
10368 or @option{-msse2} switches to enable SSE extensions and make this option
10369 effective. For the x86-64 compiler, these extensions are enabled by default.
10371 The resulting code should be considerably faster in the majority of cases and avoid
10372 the numerical instability problems of 387 code, but may break some existing
10373 code that expects temporaries to be 80bit.
10375 This is the default choice for the x86-64 compiler.
10378 Attempt to utilize both instruction sets at once. This effectively double the
10379 amount of available registers and on chips with separate execution units for
10380 387 and SSE the execution resources too. Use this option with care, as it is
10381 still experimental, because the GCC register allocator does not model separate
10382 functional units well resulting in instable performance.
10385 @item -masm=@var{dialect}
10386 @opindex masm=@var{dialect}
10387 Output asm instructions using selected @var{dialect}. Supported
10388 choices are @samp{intel} or @samp{att} (the default one). Darwin does
10389 not support @samp{intel}.
10392 @itemx -mno-ieee-fp
10394 @opindex mno-ieee-fp
10395 Control whether or not the compiler uses IEEE floating point
10396 comparisons. These handle correctly the case where the result of a
10397 comparison is unordered.
10400 @opindex msoft-float
10401 Generate output containing library calls for floating point.
10402 @strong{Warning:} the requisite libraries are not part of GCC@.
10403 Normally the facilities of the machine's usual C compiler are used, but
10404 this can't be done directly in cross-compilation. You must make your
10405 own arrangements to provide suitable library functions for
10408 On machines where a function returns floating point results in the 80387
10409 register stack, some floating point opcodes may be emitted even if
10410 @option{-msoft-float} is used.
10412 @item -mno-fp-ret-in-387
10413 @opindex mno-fp-ret-in-387
10414 Do not use the FPU registers for return values of functions.
10416 The usual calling convention has functions return values of types
10417 @code{float} and @code{double} in an FPU register, even if there
10418 is no FPU@. The idea is that the operating system should emulate
10421 The option @option{-mno-fp-ret-in-387} causes such values to be returned
10422 in ordinary CPU registers instead.
10424 @item -mno-fancy-math-387
10425 @opindex mno-fancy-math-387
10426 Some 387 emulators do not support the @code{sin}, @code{cos} and
10427 @code{sqrt} instructions for the 387. Specify this option to avoid
10428 generating those instructions. This option is the default on FreeBSD,
10429 OpenBSD and NetBSD@. This option is overridden when @option{-march}
10430 indicates that the target cpu will always have an FPU and so the
10431 instruction will not need emulation. As of revision 2.6.1, these
10432 instructions are not generated unless you also use the
10433 @option{-funsafe-math-optimizations} switch.
10435 @item -malign-double
10436 @itemx -mno-align-double
10437 @opindex malign-double
10438 @opindex mno-align-double
10439 Control whether GCC aligns @code{double}, @code{long double}, and
10440 @code{long long} variables on a two word boundary or a one word
10441 boundary. Aligning @code{double} variables on a two word boundary will
10442 produce code that runs somewhat faster on a @samp{Pentium} at the
10443 expense of more memory.
10445 On x86-64, @option{-malign-double} is enabled by default.
10447 @strong{Warning:} if you use the @option{-malign-double} switch,
10448 structures containing the above types will be aligned differently than
10449 the published application binary interface specifications for the 386
10450 and will not be binary compatible with structures in code compiled
10451 without that switch.
10453 @item -m96bit-long-double
10454 @itemx -m128bit-long-double
10455 @opindex m96bit-long-double
10456 @opindex m128bit-long-double
10457 These switches control the size of @code{long double} type. The i386
10458 application binary interface specifies the size to be 96 bits,
10459 so @option{-m96bit-long-double} is the default in 32 bit mode.
10461 Modern architectures (Pentium and newer) would prefer @code{long double}
10462 to be aligned to an 8 or 16 byte boundary. In arrays or structures
10463 conforming to the ABI, this would not be possible. So specifying a
10464 @option{-m128bit-long-double} will align @code{long double}
10465 to a 16 byte boundary by padding the @code{long double} with an additional
10468 In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
10469 its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
10471 Notice that neither of these options enable any extra precision over the x87
10472 standard of 80 bits for a @code{long double}.
10474 @strong{Warning:} if you override the default value for your target ABI, the
10475 structures and arrays containing @code{long double} variables will change
10476 their size as well as function calling convention for function taking
10477 @code{long double} will be modified. Hence they will not be binary
10478 compatible with arrays or structures in code compiled without that switch.
10480 @item -mmlarge-data-threshold=@var{number}
10481 @opindex mlarge-data-threshold=@var{number}
10482 When @option{-mcmodel=medium} is specified, the data greater than
10483 @var{threshold} are placed in large data section. This value must be the
10484 same across all object linked into the binary and defaults to 65535.
10488 Use a different function-calling convention, in which functions that
10489 take a fixed number of arguments return with the @code{ret} @var{num}
10490 instruction, which pops their arguments while returning. This saves one
10491 instruction in the caller since there is no need to pop the arguments
10494 You can specify that an individual function is called with this calling
10495 sequence with the function attribute @samp{stdcall}. You can also
10496 override the @option{-mrtd} option by using the function attribute
10497 @samp{cdecl}. @xref{Function Attributes}.
10499 @strong{Warning:} this calling convention is incompatible with the one
10500 normally used on Unix, so you cannot use it if you need to call
10501 libraries compiled with the Unix compiler.
10503 Also, you must provide function prototypes for all functions that
10504 take variable numbers of arguments (including @code{printf});
10505 otherwise incorrect code will be generated for calls to those
10508 In addition, seriously incorrect code will result if you call a
10509 function with too many arguments. (Normally, extra arguments are
10510 harmlessly ignored.)
10512 @item -mregparm=@var{num}
10514 Control how many registers are used to pass integer arguments. By
10515 default, no registers are used to pass arguments, and at most 3
10516 registers can be used. You can control this behavior for a specific
10517 function by using the function attribute @samp{regparm}.
10518 @xref{Function Attributes}.
10520 @strong{Warning:} if you use this switch, and
10521 @var{num} is nonzero, then you must build all modules with the same
10522 value, including any libraries. This includes the system libraries and
10526 @opindex msseregparm
10527 Use SSE register passing conventions for float and double arguments
10528 and return values. You can control this behavior for a specific
10529 function by using the function attribute @samp{sseregparm}.
10530 @xref{Function Attributes}.
10532 @strong{Warning:} if you use this switch then you must build all
10533 modules with the same value, including any libraries. This includes
10534 the system libraries and startup modules.
10543 Set 80387 floating-point precision to 32, 64 or 80 bits. When @option{-mpc32}
10544 is specified, the significands of results of floating-point operations are
10545 rounded to 24 bits (single precision); @option{-mpc64} rounds the the
10546 significands of results of floating-point operations to 53 bits (double
10547 precision) and @option{-mpc80} rounds the significands of results of
10548 floating-point operations to 64 bits (extended double precision), which is
10549 the default. When this option is used, floating-point operations in higher
10550 precisions are not available to the programmer without setting the FPU
10551 control word explicitly.
10553 Setting the rounding of floating-point operations to less than the default
10554 80 bits can speed some programs by 2% or more. Note that some mathematical
10555 libraries assume that extended precision (80 bit) floating-point operations
10556 are enabled by default; routines in such libraries could suffer significant
10557 loss of accuracy, typically through so-called "catastrophic cancellation",
10558 when this option is used to set the precision to less than extended precision.
10560 @item -mstackrealign
10561 @opindex mstackrealign
10562 Realign the stack at entry. On the Intel x86, the
10563 @option{-mstackrealign} option will generate an alternate prologue and
10564 epilogue that realigns the runtime stack. This supports mixing legacy
10565 codes that keep a 4-byte aligned stack with modern codes that keep a
10566 16-byte stack for SSE compatibility. The alternate prologue and
10567 epilogue are slower and bigger than the regular ones, and the
10568 alternate prologue requires an extra scratch register; this lowers the
10569 number of registers available if used in conjunction with the
10570 @code{regparm} attribute. The @option{-mstackrealign} option is
10571 incompatible with the nested function prologue; this is considered a
10572 hard error. See also the attribute @code{force_align_arg_pointer},
10573 applicable to individual functions.
10575 @item -mpreferred-stack-boundary=@var{num}
10576 @opindex mpreferred-stack-boundary
10577 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
10578 byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
10579 the default is 4 (16 bytes or 128 bits).
10581 On Pentium and PentiumPro, @code{double} and @code{long double} values
10582 should be aligned to an 8 byte boundary (see @option{-malign-double}) or
10583 suffer significant run time performance penalties. On Pentium III, the
10584 Streaming SIMD Extension (SSE) data type @code{__m128} may not work
10585 properly if it is not 16 byte aligned.
10587 To ensure proper alignment of this values on the stack, the stack boundary
10588 must be as aligned as that required by any value stored on the stack.
10589 Further, every function must be generated such that it keeps the stack
10590 aligned. Thus calling a function compiled with a higher preferred
10591 stack boundary from a function compiled with a lower preferred stack
10592 boundary will most likely misalign the stack. It is recommended that
10593 libraries that use callbacks always use the default setting.
10595 This extra alignment does consume extra stack space, and generally
10596 increases code size. Code that is sensitive to stack space usage, such
10597 as embedded systems and operating system kernels, may want to reduce the
10598 preferred alignment to @option{-mpreferred-stack-boundary=2}.
10632 These switches enable or disable the use of instructions in the MMX,
10633 SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4A, SSE5, ABM or 3DNow! extended
10635 These extensions are also available as built-in functions: see
10636 @ref{X86 Built-in Functions}, for details of the functions enabled and
10637 disabled by these switches.
10639 To have SSE/SSE2 instructions generated automatically from floating-point
10640 code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
10642 These options will enable GCC to use these extended instructions in
10643 generated code, even without @option{-mfpmath=sse}. Applications which
10644 perform runtime CPU detection must compile separate files for each
10645 supported architecture, using the appropriate flags. In particular,
10646 the file containing the CPU detection code should be compiled without
10651 This option will enable GCC to use CMPXCHG16B instruction in generated code.
10652 CMPXCHG16B allows for atomic operations on 128-bit double quadword (or oword)
10653 data types. This is useful for high resolution counters that could be updated
10654 by multiple processors (or cores). This instruction is generated as part of
10655 atomic built-in functions: see @ref{Atomic Builtins} for details.
10659 This option will enable GCC to use SAHF instruction in generated 64-bit code.
10660 Early Intel CPUs with Intel 64 lacked LAHF and SAHF instructions supported
10661 by AMD64 until introduction of Pentium 4 G1 step in December 2005. LAHF and
10662 SAHF are load and store instructions, respectively, for certain status flags.
10663 In 64-bit mode, SAHF instruction is used to optimize @code{fmod}, @code{drem}
10664 or @code{remainder} built-in functions: see @ref{Other Builtins} for details.
10668 This option will enable GCC to use RCPSS and RSQRTSS instructions (and their
10669 vectorized variants RCPPS and RSQRTPS) with an additional Newton-Rhapson step
10670 to increase precision instead of DIVSS and SQRTSS (and their vectorized
10671 variants) for single precision floating point arguments. These instructions
10672 are generated only when @option{-funsafe-math-optimizations} is enabled
10673 together with @option{-finite-math-only} and @option{-fno-trapping-math}.
10674 Note that while the throughput of the sequence is higher than the throughput
10675 of the non-reciprocal instruction, the precision of the sequence can be
10676 decreased by up to 2 ulp (i.e. the inverse of 1.0 equals 0.99999994).
10678 @item -mveclibabi=@var{type}
10679 @opindex mveclibabi
10680 Specifies the ABI type to use for vectorizing intrinsics using an
10681 external library. Supported types are @code{acml} for the AMD
10682 math core library style of interfacing. GCC will currently emit
10683 calls to @code{__vrd2_sin}, @code{__vrd2_cos}, @code{__vrd2_exp},
10684 @code{__vrd2_log}, @code{__vrd2_log2}, @code{__vrd2_log10},
10685 @code{__vrs4_sinf}, @code{__vrs4_cosf}, @code{__vrs4_expf},
10686 @code{__vrs4_logf}, @code{__vrs4_log2f}, @code{__vrs4_log10f}
10687 and @code{__vrs4_powf} when using this type and @option{-ftree-vectorize}
10688 is enabled. A ACML ABI compatible library will have to be specified
10692 @itemx -mno-push-args
10693 @opindex mpush-args
10694 @opindex mno-push-args
10695 Use PUSH operations to store outgoing parameters. This method is shorter
10696 and usually equally fast as method using SUB/MOV operations and is enabled
10697 by default. In some cases disabling it may improve performance because of
10698 improved scheduling and reduced dependencies.
10700 @item -maccumulate-outgoing-args
10701 @opindex maccumulate-outgoing-args
10702 If enabled, the maximum amount of space required for outgoing arguments will be
10703 computed in the function prologue. This is faster on most modern CPUs
10704 because of reduced dependencies, improved scheduling and reduced stack usage
10705 when preferred stack boundary is not equal to 2. The drawback is a notable
10706 increase in code size. This switch implies @option{-mno-push-args}.
10710 Support thread-safe exception handling on @samp{Mingw32}. Code that relies
10711 on thread-safe exception handling must compile and link all code with the
10712 @option{-mthreads} option. When compiling, @option{-mthreads} defines
10713 @option{-D_MT}; when linking, it links in a special thread helper library
10714 @option{-lmingwthrd} which cleans up per thread exception handling data.
10716 @item -mno-align-stringops
10717 @opindex mno-align-stringops
10718 Do not align destination of inlined string operations. This switch reduces
10719 code size and improves performance in case the destination is already aligned,
10720 but GCC doesn't know about it.
10722 @item -minline-all-stringops
10723 @opindex minline-all-stringops
10724 By default GCC inlines string operations only when destination is known to be
10725 aligned at least to 4 byte boundary. This enables more inlining, increase code
10726 size, but may improve performance of code that depends on fast memcpy, strlen
10727 and memset for short lengths.
10729 @item -minline-stringops-dynamically
10730 @opindex minline-stringops-dynamically
10731 For string operation of unknown size, inline runtime checks so for small
10732 blocks inline code is used, while for large blocks library call is used.
10734 @item -mstringop-strategy=@var{alg}
10735 @opindex mstringop-strategy=@var{alg}
10736 Overwrite internal decision heuristic about particular algorithm to inline
10737 string operation with. The allowed values are @code{rep_byte},
10738 @code{rep_4byte}, @code{rep_8byte} for expanding using i386 @code{rep} prefix
10739 of specified size, @code{byte_loop}, @code{loop}, @code{unrolled_loop} for
10740 expanding inline loop, @code{libcall} for always expanding library call.
10742 @item -momit-leaf-frame-pointer
10743 @opindex momit-leaf-frame-pointer
10744 Don't keep the frame pointer in a register for leaf functions. This
10745 avoids the instructions to save, set up and restore frame pointers and
10746 makes an extra register available in leaf functions. The option
10747 @option{-fomit-frame-pointer} removes the frame pointer for all functions
10748 which might make debugging harder.
10750 @item -mtls-direct-seg-refs
10751 @itemx -mno-tls-direct-seg-refs
10752 @opindex mtls-direct-seg-refs
10753 Controls whether TLS variables may be accessed with offsets from the
10754 TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
10755 or whether the thread base pointer must be added. Whether or not this
10756 is legal depends on the operating system, and whether it maps the
10757 segment to cover the entire TLS area.
10759 For systems that use GNU libc, the default is on.
10762 @itemx -mno-fused-madd
10763 @opindex mfused-madd
10764 Enable automatic generation of fused floating point multiply-add instructions
10765 if the ISA supports such instructions. The -mfused-madd option is on by
10766 default. The fused multiply-add instructions have a different
10767 rounding behavior compared to executing a multiply followed by an add.
10770 These @samp{-m} switches are supported in addition to the above
10771 on AMD x86-64 processors in 64-bit environments.
10778 Generate code for a 32-bit or 64-bit environment.
10779 The 32-bit environment sets int, long and pointer to 32 bits and
10780 generates code that runs on any i386 system.
10781 The 64-bit environment sets int to 32 bits and long and pointer
10782 to 64 bits and generates code for AMD's x86-64 architecture. For
10783 darwin only the -m64 option turns off the @option{-fno-pic} and
10784 @option{-mdynamic-no-pic} options.
10786 @item -mno-red-zone
10787 @opindex no-red-zone
10788 Do not use a so called red zone for x86-64 code. The red zone is mandated
10789 by the x86-64 ABI, it is a 128-byte area beyond the location of the
10790 stack pointer that will not be modified by signal or interrupt handlers
10791 and therefore can be used for temporary data without adjusting the stack
10792 pointer. The flag @option{-mno-red-zone} disables this red zone.
10794 @item -mcmodel=small
10795 @opindex mcmodel=small
10796 Generate code for the small code model: the program and its symbols must
10797 be linked in the lower 2 GB of the address space. Pointers are 64 bits.
10798 Programs can be statically or dynamically linked. This is the default
10801 @item -mcmodel=kernel
10802 @opindex mcmodel=kernel
10803 Generate code for the kernel code model. The kernel runs in the
10804 negative 2 GB of the address space.
10805 This model has to be used for Linux kernel code.
10807 @item -mcmodel=medium
10808 @opindex mcmodel=medium
10809 Generate code for the medium model: The program is linked in the lower 2
10810 GB of the address space but symbols can be located anywhere in the
10811 address space. Programs can be statically or dynamically linked, but
10812 building of shared libraries are not supported with the medium model.
10814 @item -mcmodel=large
10815 @opindex mcmodel=large
10816 Generate code for the large model: This model makes no assumptions
10817 about addresses and sizes of sections.
10820 @node IA-64 Options
10821 @subsection IA-64 Options
10822 @cindex IA-64 Options
10824 These are the @samp{-m} options defined for the Intel IA-64 architecture.
10828 @opindex mbig-endian
10829 Generate code for a big endian target. This is the default for HP-UX@.
10831 @item -mlittle-endian
10832 @opindex mlittle-endian
10833 Generate code for a little endian target. This is the default for AIX5
10839 @opindex mno-gnu-as
10840 Generate (or don't) code for the GNU assembler. This is the default.
10841 @c Also, this is the default if the configure option @option{--with-gnu-as}
10847 @opindex mno-gnu-ld
10848 Generate (or don't) code for the GNU linker. This is the default.
10849 @c Also, this is the default if the configure option @option{--with-gnu-ld}
10854 Generate code that does not use a global pointer register. The result
10855 is not position independent code, and violates the IA-64 ABI@.
10857 @item -mvolatile-asm-stop
10858 @itemx -mno-volatile-asm-stop
10859 @opindex mvolatile-asm-stop
10860 @opindex mno-volatile-asm-stop
10861 Generate (or don't) a stop bit immediately before and after volatile asm
10864 @item -mregister-names
10865 @itemx -mno-register-names
10866 @opindex mregister-names
10867 @opindex mno-register-names
10868 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
10869 the stacked registers. This may make assembler output more readable.
10875 Disable (or enable) optimizations that use the small data section. This may
10876 be useful for working around optimizer bugs.
10878 @item -mconstant-gp
10879 @opindex mconstant-gp
10880 Generate code that uses a single constant global pointer value. This is
10881 useful when compiling kernel code.
10885 Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
10886 This is useful when compiling firmware code.
10888 @item -minline-float-divide-min-latency
10889 @opindex minline-float-divide-min-latency
10890 Generate code for inline divides of floating point values
10891 using the minimum latency algorithm.
10893 @item -minline-float-divide-max-throughput
10894 @opindex minline-float-divide-max-throughput
10895 Generate code for inline divides of floating point values
10896 using the maximum throughput algorithm.
10898 @item -minline-int-divide-min-latency
10899 @opindex minline-int-divide-min-latency
10900 Generate code for inline divides of integer values
10901 using the minimum latency algorithm.
10903 @item -minline-int-divide-max-throughput
10904 @opindex minline-int-divide-max-throughput
10905 Generate code for inline divides of integer values
10906 using the maximum throughput algorithm.
10908 @item -minline-sqrt-min-latency
10909 @opindex minline-sqrt-min-latency
10910 Generate code for inline square roots
10911 using the minimum latency algorithm.
10913 @item -minline-sqrt-max-throughput
10914 @opindex minline-sqrt-max-throughput
10915 Generate code for inline square roots
10916 using the maximum throughput algorithm.
10918 @item -mno-dwarf2-asm
10919 @itemx -mdwarf2-asm
10920 @opindex mno-dwarf2-asm
10921 @opindex mdwarf2-asm
10922 Don't (or do) generate assembler code for the DWARF2 line number debugging
10923 info. This may be useful when not using the GNU assembler.
10925 @item -mearly-stop-bits
10926 @itemx -mno-early-stop-bits
10927 @opindex mearly-stop-bits
10928 @opindex mno-early-stop-bits
10929 Allow stop bits to be placed earlier than immediately preceding the
10930 instruction that triggered the stop bit. This can improve instruction
10931 scheduling, but does not always do so.
10933 @item -mfixed-range=@var{register-range}
10934 @opindex mfixed-range
10935 Generate code treating the given register range as fixed registers.
10936 A fixed register is one that the register allocator can not use. This is
10937 useful when compiling kernel code. A register range is specified as
10938 two registers separated by a dash. Multiple register ranges can be
10939 specified separated by a comma.
10941 @item -mtls-size=@var{tls-size}
10943 Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
10946 @item -mtune=@var{cpu-type}
10948 Tune the instruction scheduling for a particular CPU, Valid values are
10949 itanium, itanium1, merced, itanium2, and mckinley.
10955 Add support for multithreading using the POSIX threads library. This
10956 option sets flags for both the preprocessor and linker. It does
10957 not affect the thread safety of object code produced by the compiler or
10958 that of libraries supplied with it. These are HP-UX specific flags.
10964 Generate code for a 32-bit or 64-bit environment.
10965 The 32-bit environment sets int, long and pointer to 32 bits.
10966 The 64-bit environment sets int to 32 bits and long and pointer
10967 to 64 bits. These are HP-UX specific flags.
10969 @item -mno-sched-br-data-spec
10970 @itemx -msched-br-data-spec
10971 @opindex mno-sched-br-data-spec
10972 @opindex msched-br-data-spec
10973 (Dis/En)able data speculative scheduling before reload.
10974 This will result in generation of the ld.a instructions and
10975 the corresponding check instructions (ld.c / chk.a).
10976 The default is 'disable'.
10978 @item -msched-ar-data-spec
10979 @itemx -mno-sched-ar-data-spec
10980 @opindex msched-ar-data-spec
10981 @opindex mno-sched-ar-data-spec
10982 (En/Dis)able data speculative scheduling after reload.
10983 This will result in generation of the ld.a instructions and
10984 the corresponding check instructions (ld.c / chk.a).
10985 The default is 'enable'.
10987 @item -mno-sched-control-spec
10988 @itemx -msched-control-spec
10989 @opindex mno-sched-control-spec
10990 @opindex msched-control-spec
10991 (Dis/En)able control speculative scheduling. This feature is
10992 available only during region scheduling (i.e. before reload).
10993 This will result in generation of the ld.s instructions and
10994 the corresponding check instructions chk.s .
10995 The default is 'disable'.
10997 @item -msched-br-in-data-spec
10998 @itemx -mno-sched-br-in-data-spec
10999 @opindex msched-br-in-data-spec
11000 @opindex mno-sched-br-in-data-spec
11001 (En/Dis)able speculative scheduling of the instructions that
11002 are dependent on the data speculative loads before reload.
11003 This is effective only with @option{-msched-br-data-spec} enabled.
11004 The default is 'enable'.
11006 @item -msched-ar-in-data-spec
11007 @itemx -mno-sched-ar-in-data-spec
11008 @opindex msched-ar-in-data-spec
11009 @opindex mno-sched-ar-in-data-spec
11010 (En/Dis)able speculative scheduling of the instructions that
11011 are dependent on the data speculative loads after reload.
11012 This is effective only with @option{-msched-ar-data-spec} enabled.
11013 The default is 'enable'.
11015 @item -msched-in-control-spec
11016 @itemx -mno-sched-in-control-spec
11017 @opindex msched-in-control-spec
11018 @opindex mno-sched-in-control-spec
11019 (En/Dis)able speculative scheduling of the instructions that
11020 are dependent on the control speculative loads.
11021 This is effective only with @option{-msched-control-spec} enabled.
11022 The default is 'enable'.
11025 @itemx -mno-sched-ldc
11026 @opindex msched-ldc
11027 @opindex mno-sched-ldc
11028 (En/Dis)able use of simple data speculation checks ld.c .
11029 If disabled, only chk.a instructions will be emitted to check
11030 data speculative loads.
11031 The default is 'enable'.
11033 @item -mno-sched-control-ldc
11034 @itemx -msched-control-ldc
11035 @opindex mno-sched-control-ldc
11036 @opindex msched-control-ldc
11037 (Dis/En)able use of ld.c instructions to check control speculative loads.
11038 If enabled, in case of control speculative load with no speculatively
11039 scheduled dependent instructions this load will be emitted as ld.sa and
11040 ld.c will be used to check it.
11041 The default is 'disable'.
11043 @item -mno-sched-spec-verbose
11044 @itemx -msched-spec-verbose
11045 @opindex mno-sched-spec-verbose
11046 @opindex msched-spec-verbose
11047 (Dis/En)able printing of the information about speculative motions.
11049 @item -mno-sched-prefer-non-data-spec-insns
11050 @itemx -msched-prefer-non-data-spec-insns
11051 @opindex mno-sched-prefer-non-data-spec-insns
11052 @opindex msched-prefer-non-data-spec-insns
11053 If enabled, data speculative instructions will be chosen for schedule
11054 only if there are no other choices at the moment. This will make
11055 the use of the data speculation much more conservative.
11056 The default is 'disable'.
11058 @item -mno-sched-prefer-non-control-spec-insns
11059 @itemx -msched-prefer-non-control-spec-insns
11060 @opindex mno-sched-prefer-non-control-spec-insns
11061 @opindex msched-prefer-non-control-spec-insns
11062 If enabled, control speculative instructions will be chosen for schedule
11063 only if there are no other choices at the moment. This will make
11064 the use of the control speculation much more conservative.
11065 The default is 'disable'.
11067 @item -mno-sched-count-spec-in-critical-path
11068 @itemx -msched-count-spec-in-critical-path
11069 @opindex mno-sched-count-spec-in-critical-path
11070 @opindex msched-count-spec-in-critical-path
11071 If enabled, speculative dependencies will be considered during
11072 computation of the instructions priorities. This will make the use of the
11073 speculation a bit more conservative.
11074 The default is 'disable'.
11079 @subsection M32C Options
11080 @cindex M32C options
11083 @item -mcpu=@var{name}
11085 Select the CPU for which code is generated. @var{name} may be one of
11086 @samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
11087 /60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
11088 the M32C/80 series.
11092 Specifies that the program will be run on the simulator. This causes
11093 an alternate runtime library to be linked in which supports, for
11094 example, file I/O. You must not use this option when generating
11095 programs that will run on real hardware; you must provide your own
11096 runtime library for whatever I/O functions are needed.
11098 @item -memregs=@var{number}
11100 Specifies the number of memory-based pseudo-registers GCC will use
11101 during code generation. These pseudo-registers will be used like real
11102 registers, so there is a tradeoff between GCC's ability to fit the
11103 code into available registers, and the performance penalty of using
11104 memory instead of registers. Note that all modules in a program must
11105 be compiled with the same value for this option. Because of that, you
11106 must not use this option with the default runtime libraries gcc
11111 @node M32R/D Options
11112 @subsection M32R/D Options
11113 @cindex M32R/D options
11115 These @option{-m} options are defined for Renesas M32R/D architectures:
11120 Generate code for the M32R/2@.
11124 Generate code for the M32R/X@.
11128 Generate code for the M32R@. This is the default.
11130 @item -mmodel=small
11131 @opindex mmodel=small
11132 Assume all objects live in the lower 16MB of memory (so that their addresses
11133 can be loaded with the @code{ld24} instruction), and assume all subroutines
11134 are reachable with the @code{bl} instruction.
11135 This is the default.
11137 The addressability of a particular object can be set with the
11138 @code{model} attribute.
11140 @item -mmodel=medium
11141 @opindex mmodel=medium
11142 Assume objects may be anywhere in the 32-bit address space (the compiler
11143 will generate @code{seth/add3} instructions to load their addresses), and
11144 assume all subroutines are reachable with the @code{bl} instruction.
11146 @item -mmodel=large
11147 @opindex mmodel=large
11148 Assume objects may be anywhere in the 32-bit address space (the compiler
11149 will generate @code{seth/add3} instructions to load their addresses), and
11150 assume subroutines may not be reachable with the @code{bl} instruction
11151 (the compiler will generate the much slower @code{seth/add3/jl}
11152 instruction sequence).
11155 @opindex msdata=none
11156 Disable use of the small data area. Variables will be put into
11157 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
11158 @code{section} attribute has been specified).
11159 This is the default.
11161 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
11162 Objects may be explicitly put in the small data area with the
11163 @code{section} attribute using one of these sections.
11165 @item -msdata=sdata
11166 @opindex msdata=sdata
11167 Put small global and static data in the small data area, but do not
11168 generate special code to reference them.
11171 @opindex msdata=use
11172 Put small global and static data in the small data area, and generate
11173 special instructions to reference them.
11177 @cindex smaller data references
11178 Put global and static objects less than or equal to @var{num} bytes
11179 into the small data or bss sections instead of the normal data or bss
11180 sections. The default value of @var{num} is 8.
11181 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
11182 for this option to have any effect.
11184 All modules should be compiled with the same @option{-G @var{num}} value.
11185 Compiling with different values of @var{num} may or may not work; if it
11186 doesn't the linker will give an error message---incorrect code will not be
11191 Makes the M32R specific code in the compiler display some statistics
11192 that might help in debugging programs.
11194 @item -malign-loops
11195 @opindex malign-loops
11196 Align all loops to a 32-byte boundary.
11198 @item -mno-align-loops
11199 @opindex mno-align-loops
11200 Do not enforce a 32-byte alignment for loops. This is the default.
11202 @item -missue-rate=@var{number}
11203 @opindex missue-rate=@var{number}
11204 Issue @var{number} instructions per cycle. @var{number} can only be 1
11207 @item -mbranch-cost=@var{number}
11208 @opindex mbranch-cost=@var{number}
11209 @var{number} can only be 1 or 2. If it is 1 then branches will be
11210 preferred over conditional code, if it is 2, then the opposite will
11213 @item -mflush-trap=@var{number}
11214 @opindex mflush-trap=@var{number}
11215 Specifies the trap number to use to flush the cache. The default is
11216 12. Valid numbers are between 0 and 15 inclusive.
11218 @item -mno-flush-trap
11219 @opindex mno-flush-trap
11220 Specifies that the cache cannot be flushed by using a trap.
11222 @item -mflush-func=@var{name}
11223 @opindex mflush-func=@var{name}
11224 Specifies the name of the operating system function to call to flush
11225 the cache. The default is @emph{_flush_cache}, but a function call
11226 will only be used if a trap is not available.
11228 @item -mno-flush-func
11229 @opindex mno-flush-func
11230 Indicates that there is no OS function for flushing the cache.
11234 @node M680x0 Options
11235 @subsection M680x0 Options
11236 @cindex M680x0 options
11238 These are the @samp{-m} options defined for M680x0 and ColdFire processors.
11239 The default settings depend on which architecture was selected when
11240 the compiler was configured; the defaults for the most common choices
11244 @item -march=@var{arch}
11246 Generate code for a specific M680x0 or ColdFire instruction set
11247 architecture. Permissible values of @var{arch} for M680x0
11248 architectures are: @samp{68000}, @samp{68010}, @samp{68020},
11249 @samp{68030}, @samp{68040}, @samp{68060} and @samp{cpu32}. ColdFire
11250 architectures are selected according to Freescale's ISA classification
11251 and the permissible values are: @samp{isaa}, @samp{isaaplus},
11252 @samp{isab} and @samp{isac}.
11254 gcc defines a macro @samp{__mcf@var{arch}__} whenever it is generating
11255 code for a ColdFire target. The @var{arch} in this macro is one of the
11256 @option{-march} arguments given above.
11258 When used together, @option{-march} and @option{-mtune} select code
11259 that runs on a family of similar processors but that is optimized
11260 for a particular microarchitecture.
11262 @item -mcpu=@var{cpu}
11264 Generate code for a specific M680x0 or ColdFire processor.
11265 The M680x0 @var{cpu}s are: @samp{68000}, @samp{68010}, @samp{68020},
11266 @samp{68030}, @samp{68040}, @samp{68060}, @samp{68302}, @samp{68332}
11267 and @samp{cpu32}. The ColdFire @var{cpu}s are given by the table
11268 below, which also classifies the CPUs into families:
11270 @multitable @columnfractions 0.20 0.80
11271 @item @strong{Family} @tab @strong{@samp{-mcpu} arguments}
11272 @item @samp{51qe} @tab @samp{51qe}
11273 @item @samp{5206} @tab @samp{5202} @samp{5204} @samp{5206}
11274 @item @samp{5206e} @tab @samp{5206e}
11275 @item @samp{5208} @tab @samp{5207} @samp{5208}
11276 @item @samp{5211a} @tab @samp{5210a} @samp{5211a}
11277 @item @samp{5213} @tab @samp{5211} @samp{5212} @samp{5213}
11278 @item @samp{5216} @tab @samp{5214} @samp{5216}
11279 @item @samp{52235} @tab @samp{52230} @samp{52231} @samp{52232} @samp{52233} @samp{52234} @samp{52235}
11280 @item @samp{5225} @tab @samp{5224} @samp{5225}
11281 @item @samp{5235} @tab @samp{5232} @samp{5233} @samp{5234} @samp{5235} @samp{523x}
11282 @item @samp{5249} @tab @samp{5249}
11283 @item @samp{5250} @tab @samp{5250}
11284 @item @samp{5271} @tab @samp{5270} @samp{5271}
11285 @item @samp{5272} @tab @samp{5272}
11286 @item @samp{5275} @tab @samp{5274} @samp{5275}
11287 @item @samp{5282} @tab @samp{5280} @samp{5281} @samp{5282} @samp{528x}
11288 @item @samp{5307} @tab @samp{5307}
11289 @item @samp{5329} @tab @samp{5327} @samp{5328} @samp{5329} @samp{532x}
11290 @item @samp{5373} @tab @samp{5372} @samp{5373} @samp{537x}
11291 @item @samp{5407} @tab @samp{5407}
11292 @item @samp{5475} @tab @samp{5470} @samp{5471} @samp{5472} @samp{5473} @samp{5474} @samp{5475} @samp{547x} @samp{5480} @samp{5481} @samp{5482} @samp{5483} @samp{5484} @samp{5485}
11295 @option{-mcpu=@var{cpu}} overrides @option{-march=@var{arch}} if
11296 @var{arch} is compatible with @var{cpu}. Other combinations of
11297 @option{-mcpu} and @option{-march} are rejected.
11299 gcc defines the macro @samp{__mcf_cpu_@var{cpu}} when ColdFire target
11300 @var{cpu} is selected. It also defines @samp{__mcf_family_@var{family}},
11301 where the value of @var{family} is given by the table above.
11303 @item -mtune=@var{tune}
11305 Tune the code for a particular microarchitecture, within the
11306 constraints set by @option{-march} and @option{-mcpu}.
11307 The M680x0 microarchitectures are: @samp{68000}, @samp{68010},
11308 @samp{68020}, @samp{68030}, @samp{68040}, @samp{68060}
11309 and @samp{cpu32}. The ColdFire microarchitectures
11310 are: @samp{cfv1}, @samp{cfv2}, @samp{cfv3}, @samp{cfv4} and @samp{cfv4e}.
11312 You can also use @option{-mtune=68020-40} for code that needs
11313 to run relatively well on 68020, 68030 and 68040 targets.
11314 @option{-mtune=68020-60} is similar but includes 68060 targets
11315 as well. These two options select the same tuning decisions as
11316 @option{-m68020-40} and @option{-m68020-60} respectively.
11318 gcc defines the macros @samp{__mc@var{arch}} and @samp{__mc@var{arch}__}
11319 when tuning for 680x0 architecture @var{arch}. It also defines
11320 @samp{mc@var{arch}} unless either @option{-ansi} or a non-GNU @option{-std}
11321 option is used. If gcc is tuning for a range of architectures,
11322 as selected by @option{-mtune=68020-40} or @option{-mtune=68020-60},
11323 it defines the macros for every architecture in the range.
11325 gcc also defines the macro @samp{__m@var{uarch}__} when tuning for
11326 ColdFire microarchitecture @var{uarch}, where @var{uarch} is one
11327 of the arguments given above.
11333 Generate output for a 68000. This is the default
11334 when the compiler is configured for 68000-based systems.
11335 It is equivalent to @option{-march=68000}.
11337 Use this option for microcontrollers with a 68000 or EC000 core,
11338 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
11342 Generate output for a 68010. This is the default
11343 when the compiler is configured for 68010-based systems.
11344 It is equivalent to @option{-march=68010}.
11350 Generate output for a 68020. This is the default
11351 when the compiler is configured for 68020-based systems.
11352 It is equivalent to @option{-march=68020}.
11356 Generate output for a 68030. This is the default when the compiler is
11357 configured for 68030-based systems. It is equivalent to
11358 @option{-march=68030}.
11362 Generate output for a 68040. This is the default when the compiler is
11363 configured for 68040-based systems. It is equivalent to
11364 @option{-march=68040}.
11366 This option inhibits the use of 68881/68882 instructions that have to be
11367 emulated by software on the 68040. Use this option if your 68040 does not
11368 have code to emulate those instructions.
11372 Generate output for a 68060. This is the default when the compiler is
11373 configured for 68060-based systems. It is equivalent to
11374 @option{-march=68060}.
11376 This option inhibits the use of 68020 and 68881/68882 instructions that
11377 have to be emulated by software on the 68060. Use this option if your 68060
11378 does not have code to emulate those instructions.
11382 Generate output for a CPU32. This is the default
11383 when the compiler is configured for CPU32-based systems.
11384 It is equivalent to @option{-march=cpu32}.
11386 Use this option for microcontrollers with a
11387 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
11388 68336, 68340, 68341, 68349 and 68360.
11392 Generate output for a 520X ColdFire CPU. This is the default
11393 when the compiler is configured for 520X-based systems.
11394 It is equivalent to @option{-mcpu=5206}, and is now deprecated
11395 in favor of that option.
11397 Use this option for microcontroller with a 5200 core, including
11398 the MCF5202, MCF5203, MCF5204 and MCF5206.
11402 Generate output for a 5206e ColdFire CPU. The option is now
11403 deprecated in favor of the equivalent @option{-mcpu=5206e}.
11407 Generate output for a member of the ColdFire 528X family.
11408 The option is now deprecated in favor of the equivalent
11409 @option{-mcpu=528x}.
11413 Generate output for a ColdFire 5307 CPU. The option is now deprecated
11414 in favor of the equivalent @option{-mcpu=5307}.
11418 Generate output for a ColdFire 5407 CPU. The option is now deprecated
11419 in favor of the equivalent @option{-mcpu=5407}.
11423 Generate output for a ColdFire V4e family CPU (e.g.@: 547x/548x).
11424 This includes use of hardware floating point instructions.
11425 The option is equivalent to @option{-mcpu=547x}, and is now
11426 deprecated in favor of that option.
11430 Generate output for a 68040, without using any of the new instructions.
11431 This results in code which can run relatively efficiently on either a
11432 68020/68881 or a 68030 or a 68040. The generated code does use the
11433 68881 instructions that are emulated on the 68040.
11435 The option is equivalent to @option{-march=68020} @option{-mtune=68020-40}.
11439 Generate output for a 68060, without using any of the new instructions.
11440 This results in code which can run relatively efficiently on either a
11441 68020/68881 or a 68030 or a 68040. The generated code does use the
11442 68881 instructions that are emulated on the 68060.
11444 The option is equivalent to @option{-march=68020} @option{-mtune=68020-60}.
11448 @opindex mhard-float
11450 Generate floating-point instructions. This is the default for 68020
11451 and above, and for ColdFire devices that have an FPU. It defines the
11452 macro @samp{__HAVE_68881__} on M680x0 targets and @samp{__mcffpu__}
11453 on ColdFire targets.
11456 @opindex msoft-float
11457 Do not generate floating-point instructions; use library calls instead.
11458 This is the default for 68000, 68010, and 68832 targets. It is also
11459 the default for ColdFire devices that have no FPU.
11465 Generate (do not generate) ColdFire hardware divide and remainder
11466 instructions. If @option{-march} is used without @option{-mcpu},
11467 the default is ``on'' for ColdFire architectures and ``off'' for M680x0
11468 architectures. Otherwise, the default is taken from the target CPU
11469 (either the default CPU, or the one specified by @option{-mcpu}). For
11470 example, the default is ``off'' for @option{-mcpu=5206} and ``on'' for
11471 @option{-mcpu=5206e}.
11473 gcc defines the macro @samp{__mcfhwdiv__} when this option is enabled.
11477 Consider type @code{int} to be 16 bits wide, like @code{short int}.
11478 Additionally, parameters passed on the stack are also aligned to a
11479 16-bit boundary even on targets whose API mandates promotion to 32-bit.
11483 Do not consider type @code{int} to be 16 bits wide. This is the default.
11486 @itemx -mno-bitfield
11487 @opindex mnobitfield
11488 @opindex mno-bitfield
11489 Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
11490 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
11494 Do use the bit-field instructions. The @option{-m68020} option implies
11495 @option{-mbitfield}. This is the default if you use a configuration
11496 designed for a 68020.
11500 Use a different function-calling convention, in which functions
11501 that take a fixed number of arguments return with the @code{rtd}
11502 instruction, which pops their arguments while returning. This
11503 saves one instruction in the caller since there is no need to pop
11504 the arguments there.
11506 This calling convention is incompatible with the one normally
11507 used on Unix, so you cannot use it if you need to call libraries
11508 compiled with the Unix compiler.
11510 Also, you must provide function prototypes for all functions that
11511 take variable numbers of arguments (including @code{printf});
11512 otherwise incorrect code will be generated for calls to those
11515 In addition, seriously incorrect code will result if you call a
11516 function with too many arguments. (Normally, extra arguments are
11517 harmlessly ignored.)
11519 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
11520 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
11524 Do not use the calling conventions selected by @option{-mrtd}.
11525 This is the default.
11528 @itemx -mno-align-int
11529 @opindex malign-int
11530 @opindex mno-align-int
11531 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
11532 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
11533 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
11534 Aligning variables on 32-bit boundaries produces code that runs somewhat
11535 faster on processors with 32-bit busses at the expense of more memory.
11537 @strong{Warning:} if you use the @option{-malign-int} switch, GCC will
11538 align structures containing the above types differently than
11539 most published application binary interface specifications for the m68k.
11543 Use the pc-relative addressing mode of the 68000 directly, instead of
11544 using a global offset table. At present, this option implies @option{-fpic},
11545 allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
11546 not presently supported with @option{-mpcrel}, though this could be supported for
11547 68020 and higher processors.
11549 @item -mno-strict-align
11550 @itemx -mstrict-align
11551 @opindex mno-strict-align
11552 @opindex mstrict-align
11553 Do not (do) assume that unaligned memory references will be handled by
11557 Generate code that allows the data segment to be located in a different
11558 area of memory from the text segment. This allows for execute in place in
11559 an environment without virtual memory management. This option implies
11562 @item -mno-sep-data
11563 Generate code that assumes that the data segment follows the text segment.
11564 This is the default.
11566 @item -mid-shared-library
11567 Generate code that supports shared libraries via the library ID method.
11568 This allows for execute in place and shared libraries in an environment
11569 without virtual memory management. This option implies @option{-fPIC}.
11571 @item -mno-id-shared-library
11572 Generate code that doesn't assume ID based shared libraries are being used.
11573 This is the default.
11575 @item -mshared-library-id=n
11576 Specified the identification number of the ID based shared library being
11577 compiled. Specifying a value of 0 will generate more compact code, specifying
11578 other values will force the allocation of that number to the current
11579 library but is no more space or time efficient than omitting this option.
11583 @node M68hc1x Options
11584 @subsection M68hc1x Options
11585 @cindex M68hc1x options
11587 These are the @samp{-m} options defined for the 68hc11 and 68hc12
11588 microcontrollers. The default values for these options depends on
11589 which style of microcontroller was selected when the compiler was configured;
11590 the defaults for the most common choices are given below.
11597 Generate output for a 68HC11. This is the default
11598 when the compiler is configured for 68HC11-based systems.
11604 Generate output for a 68HC12. This is the default
11605 when the compiler is configured for 68HC12-based systems.
11611 Generate output for a 68HCS12.
11613 @item -mauto-incdec
11614 @opindex mauto-incdec
11615 Enable the use of 68HC12 pre and post auto-increment and auto-decrement
11622 Enable the use of 68HC12 min and max instructions.
11625 @itemx -mno-long-calls
11626 @opindex mlong-calls
11627 @opindex mno-long-calls
11628 Treat all calls as being far away (near). If calls are assumed to be
11629 far away, the compiler will use the @code{call} instruction to
11630 call a function and the @code{rtc} instruction for returning.
11634 Consider type @code{int} to be 16 bits wide, like @code{short int}.
11636 @item -msoft-reg-count=@var{count}
11637 @opindex msoft-reg-count
11638 Specify the number of pseudo-soft registers which are used for the
11639 code generation. The maximum number is 32. Using more pseudo-soft
11640 register may or may not result in better code depending on the program.
11641 The default is 4 for 68HC11 and 2 for 68HC12.
11645 @node MCore Options
11646 @subsection MCore Options
11647 @cindex MCore options
11649 These are the @samp{-m} options defined for the Motorola M*Core
11655 @itemx -mno-hardlit
11657 @opindex mno-hardlit
11658 Inline constants into the code stream if it can be done in two
11659 instructions or less.
11665 Use the divide instruction. (Enabled by default).
11667 @item -mrelax-immediate
11668 @itemx -mno-relax-immediate
11669 @opindex mrelax-immediate
11670 @opindex mno-relax-immediate
11671 Allow arbitrary sized immediates in bit operations.
11673 @item -mwide-bitfields
11674 @itemx -mno-wide-bitfields
11675 @opindex mwide-bitfields
11676 @opindex mno-wide-bitfields
11677 Always treat bit-fields as int-sized.
11679 @item -m4byte-functions
11680 @itemx -mno-4byte-functions
11681 @opindex m4byte-functions
11682 @opindex mno-4byte-functions
11683 Force all functions to be aligned to a four byte boundary.
11685 @item -mcallgraph-data
11686 @itemx -mno-callgraph-data
11687 @opindex mcallgraph-data
11688 @opindex mno-callgraph-data
11689 Emit callgraph information.
11692 @itemx -mno-slow-bytes
11693 @opindex mslow-bytes
11694 @opindex mno-slow-bytes
11695 Prefer word access when reading byte quantities.
11697 @item -mlittle-endian
11698 @itemx -mbig-endian
11699 @opindex mlittle-endian
11700 @opindex mbig-endian
11701 Generate code for a little endian target.
11707 Generate code for the 210 processor.
11711 @subsection MIPS Options
11712 @cindex MIPS options
11718 Generate big-endian code.
11722 Generate little-endian code. This is the default for @samp{mips*el-*-*}
11725 @item -march=@var{arch}
11727 Generate code that will run on @var{arch}, which can be the name of a
11728 generic MIPS ISA, or the name of a particular processor.
11730 @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
11731 @samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
11732 The processor names are:
11733 @samp{4kc}, @samp{4km}, @samp{4kp}, @samp{4ksc},
11734 @samp{4kec}, @samp{4kem}, @samp{4kep}, @samp{4ksd},
11735 @samp{5kc}, @samp{5kf},
11737 @samp{24kc}, @samp{24kf2_1}, @samp{24kf1_1},
11738 @samp{24kec}, @samp{24kef2_1}, @samp{24kef1_1},
11739 @samp{34kc}, @samp{34kf2_1}, @samp{34kf1_1},
11740 @samp{74kc}, @samp{74kf2_1}, @samp{74kf1_1}, @samp{74kf3_2},
11743 @samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
11744 @samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
11745 @samp{rm7000}, @samp{rm9000},
11748 @samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
11749 @samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
11750 The special value @samp{from-abi} selects the
11751 most compatible architecture for the selected ABI (that is,
11752 @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
11754 In processor names, a final @samp{000} can be abbreviated as @samp{k}
11755 (for example, @samp{-march=r2k}). Prefixes are optional, and
11756 @samp{vr} may be written @samp{r}.
11758 Names of the form @samp{@var{n}f2_1} refer to processors with
11759 FPUs clocked at half the rate of the core, names of the form
11760 @samp{@var{n}f1_1} refer to processors with FPUs clocked at the same
11761 rate as the core, and names of the form @samp{@var{n}f3_2} refer to
11762 processors with FPUs clocked a ratio of 3:2 with respect to the core.
11763 For compatibility reasons, @samp{@var{n}f} is accepted as a synonym
11764 for @samp{@var{n}f2_1} while @samp{@var{n}x} and @samp{@var{b}fx} are
11765 accepted as synonyms for @samp{@var{n}f1_1}.
11767 GCC defines two macros based on the value of this option. The first
11768 is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
11769 a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
11770 where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
11771 For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
11772 to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
11774 Note that the @samp{_MIPS_ARCH} macro uses the processor names given
11775 above. In other words, it will have the full prefix and will not
11776 abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
11777 the macro names the resolved architecture (either @samp{"mips1"} or
11778 @samp{"mips3"}). It names the default architecture when no
11779 @option{-march} option is given.
11781 @item -mtune=@var{arch}
11783 Optimize for @var{arch}. Among other things, this option controls
11784 the way instructions are scheduled, and the perceived cost of arithmetic
11785 operations. The list of @var{arch} values is the same as for
11788 When this option is not used, GCC will optimize for the processor
11789 specified by @option{-march}. By using @option{-march} and
11790 @option{-mtune} together, it is possible to generate code that will
11791 run on a family of processors, but optimize the code for one
11792 particular member of that family.
11794 @samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
11795 @samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
11796 @samp{-march} ones described above.
11800 Equivalent to @samp{-march=mips1}.
11804 Equivalent to @samp{-march=mips2}.
11808 Equivalent to @samp{-march=mips3}.
11812 Equivalent to @samp{-march=mips4}.
11816 Equivalent to @samp{-march=mips32}.
11820 Equivalent to @samp{-march=mips32r2}.
11824 Equivalent to @samp{-march=mips64}.
11829 @opindex mno-mips16
11830 Generate (do not generate) MIPS16 code. If GCC is targetting a
11831 MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
11833 MIPS16 code generation can also be controlled on a per-function basis
11834 by means of @code{mips16} and @code{nomips16} attributes.
11835 @xref{Function Attributes}, for more information.
11837 @item -mflip-mips16
11838 @opindex mflip-mips16
11839 Generate MIPS16 code on alternating functions. This option is provided
11840 for regression testing of mixed MIPS16/non-MIPS16 code generation, and is
11841 not intended for ordinary use in compiling user code.
11843 @item -minterlink-mips16
11844 @itemx -mno-interlink-mips16
11845 @opindex minterlink-mips16
11846 @opindex mno-interlink-mips16
11847 Require (do not require) that non-MIPS16 code be link-compatible with
11850 For example, non-MIPS16 code cannot jump directly to MIPS16 code;
11851 it must either use a call or an indirect jump. @option{-minterlink-mips16}
11852 therefore disables direct jumps unless GCC knows that the target of the
11853 jump is not MIPS16.
11865 Generate code for the given ABI@.
11867 Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
11868 generates 64-bit code when you select a 64-bit architecture, but you
11869 can use @option{-mgp32} to get 32-bit code instead.
11871 For information about the O64 ABI, see
11872 @w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
11874 GCC supports a variant of the o32 ABI in which floating-point registers
11875 are 64 rather than 32 bits wide. You can select this combination with
11876 @option{-mabi=32} @option{-mfp64}. This ABI relies on the @samp{mthc1}
11877 and @samp{mfhc1} instructions and is therefore only supported for
11878 MIPS32R2 processors.
11880 The register assignments for arguments and return values remain the
11881 same, but each scalar value is passed in a single 64-bit register
11882 rather than a pair of 32-bit registers. For example, scalar
11883 floating-point values are returned in @samp{$f0} only, not a
11884 @samp{$f0}/@samp{$f1} pair. The set of call-saved registers also
11885 remains the same, but all 64 bits are saved.
11888 @itemx -mno-abicalls
11890 @opindex mno-abicalls
11891 Generate (do not generate) code that is suitable for SVR4-style
11892 dynamic objects. @option{-mabicalls} is the default for SVR4-based
11897 Generate (do not generate) code that is fully position-independent,
11898 and that can therefore be linked into shared libraries. This option
11899 only affects @option{-mabicalls}.
11901 All @option{-mabicalls} code has traditionally been position-independent,
11902 regardless of options like @option{-fPIC} and @option{-fpic}. However,
11903 as an extension, the GNU toolchain allows executables to use absolute
11904 accesses for locally-binding symbols. It can also use shorter GP
11905 initialization sequences and generate direct calls to locally-defined
11906 functions. This mode is selected by @option{-mno-shared}.
11908 @option{-mno-shared} depends on binutils 2.16 or higher and generates
11909 objects that can only be linked by the GNU linker. However, the option
11910 does not affect the ABI of the final executable; it only affects the ABI
11911 of relocatable objects. Using @option{-mno-shared} will generally make
11912 executables both smaller and quicker.
11914 @option{-mshared} is the default.
11920 Lift (do not lift) the usual restrictions on the size of the global
11923 GCC normally uses a single instruction to load values from the GOT@.
11924 While this is relatively efficient, it will only work if the GOT
11925 is smaller than about 64k. Anything larger will cause the linker
11926 to report an error such as:
11928 @cindex relocation truncated to fit (MIPS)
11930 relocation truncated to fit: R_MIPS_GOT16 foobar
11933 If this happens, you should recompile your code with @option{-mxgot}.
11934 It should then work with very large GOTs, although it will also be
11935 less efficient, since it will take three instructions to fetch the
11936 value of a global symbol.
11938 Note that some linkers can create multiple GOTs. If you have such a
11939 linker, you should only need to use @option{-mxgot} when a single object
11940 file accesses more than 64k's worth of GOT entries. Very few do.
11942 These options have no effect unless GCC is generating position
11947 Assume that general-purpose registers are 32 bits wide.
11951 Assume that general-purpose registers are 64 bits wide.
11955 Assume that floating-point registers are 32 bits wide.
11959 Assume that floating-point registers are 64 bits wide.
11962 @opindex mhard-float
11963 Use floating-point coprocessor instructions.
11966 @opindex msoft-float
11967 Do not use floating-point coprocessor instructions. Implement
11968 floating-point calculations using library calls instead.
11970 @item -msingle-float
11971 @opindex msingle-float
11972 Assume that the floating-point coprocessor only supports single-precision
11975 @item -mdouble-float
11976 @opindex mdouble-float
11977 Assume that the floating-point coprocessor supports double-precision
11978 operations. This is the default.
11984 Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to
11985 implement atomic memory built-in functions. When neither option is
11986 specified, GCC will use the instructions if the target architecture
11989 @option{-mllsc} is useful if the runtime environment can emulate the
11990 instructions and @option{-mno-llsc} can be useful when compiling for
11991 nonstandard ISAs. You can make either option the default by
11992 configuring GCC with @option{--with-llsc} and @option{--without-llsc}
11993 respectively. @option{--with-llsc} is the default for some
11994 configurations; see the installation documentation for details.
12000 Use (do not use) revision 1 of the MIPS DSP ASE.
12001 @xref{MIPS DSP Built-in Functions}. This option defines the
12002 preprocessor macro @samp{__mips_dsp}. It also defines
12003 @samp{__mips_dsp_rev} to 1.
12009 Use (do not use) revision 2 of the MIPS DSP ASE.
12010 @xref{MIPS DSP Built-in Functions}. This option defines the
12011 preprocessor macros @samp{__mips_dsp} and @samp{__mips_dspr2}.
12012 It also defines @samp{__mips_dsp_rev} to 2.
12015 @itemx -mno-smartmips
12016 @opindex msmartmips
12017 @opindex mno-smartmips
12018 Use (do not use) the MIPS SmartMIPS ASE.
12020 @item -mpaired-single
12021 @itemx -mno-paired-single
12022 @opindex mpaired-single
12023 @opindex mno-paired-single
12024 Use (do not use) paired-single floating-point instructions.
12025 @xref{MIPS Paired-Single Support}. This option requires
12026 hardware floating-point support to be enabled.
12032 Use (do not use) MIPS Digital Media Extension instructions.
12033 This option can only be used when generating 64-bit code and requires
12034 hardware floating-point support to be enabled.
12039 @opindex mno-mips3d
12040 Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
12041 The option @option{-mips3d} implies @option{-mpaired-single}.
12047 Use (do not use) MT Multithreading instructions.
12051 Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
12052 an explanation of the default and the way that the pointer size is
12057 Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
12059 The default size of @code{int}s, @code{long}s and pointers depends on
12060 the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
12061 uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
12062 32-bit @code{long}s. Pointers are the same size as @code{long}s,
12063 or the same size as integer registers, whichever is smaller.
12069 Assume (do not assume) that all symbols have 32-bit values, regardless
12070 of the selected ABI@. This option is useful in combination with
12071 @option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
12072 to generate shorter and faster references to symbolic addresses.
12076 Put definitions of externally-visible data in a small data section
12077 if that data is no bigger than @var{num} bytes. GCC can then access
12078 the data more efficiently; see @option{-mgpopt} for details.
12080 The default @option{-G} option depends on the configuration.
12082 @item -mlocal-sdata
12083 @itemx -mno-local-sdata
12084 @opindex mlocal-sdata
12085 @opindex mno-local-sdata
12086 Extend (do not extend) the @option{-G} behavior to local data too,
12087 such as to static variables in C. @option{-mlocal-sdata} is the
12088 default for all configurations.
12090 If the linker complains that an application is using too much small data,
12091 you might want to try rebuilding the less performance-critical parts with
12092 @option{-mno-local-sdata}. You might also want to build large
12093 libraries with @option{-mno-local-sdata}, so that the libraries leave
12094 more room for the main program.
12096 @item -mextern-sdata
12097 @itemx -mno-extern-sdata
12098 @opindex mextern-sdata
12099 @opindex mno-extern-sdata
12100 Assume (do not assume) that externally-defined data will be in
12101 a small data section if that data is within the @option{-G} limit.
12102 @option{-mextern-sdata} is the default for all configurations.
12104 If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G
12105 @var{num}} @option{-mgpopt}, and @var{Mod} references a variable @var{Var}
12106 that is no bigger than @var{num} bytes, you must make sure that @var{Var}
12107 is placed in a small data section. If @var{Var} is defined by another
12108 module, you must either compile that module with a high-enough
12109 @option{-G} setting or attach a @code{section} attribute to @var{Var}'s
12110 definition. If @var{Var} is common, you must link the application
12111 with a high-enough @option{-G} setting.
12113 The easiest way of satisfying these restrictions is to compile
12114 and link every module with the same @option{-G} option. However,
12115 you may wish to build a library that supports several different
12116 small data limits. You can do this by compiling the library with
12117 the highest supported @option{-G} setting and additionally using
12118 @option{-mno-extern-sdata} to stop the library from making assumptions
12119 about externally-defined data.
12125 Use (do not use) GP-relative accesses for symbols that are known to be
12126 in a small data section; see @option{-G}, @option{-mlocal-sdata} and
12127 @option{-mextern-sdata}. @option{-mgpopt} is the default for all
12130 @option{-mno-gpopt} is useful for cases where the @code{$gp} register
12131 might not hold the value of @code{_gp}. For example, if the code is
12132 part of a library that might be used in a boot monitor, programs that
12133 call boot monitor routines will pass an unknown value in @code{$gp}.
12134 (In such situations, the boot monitor itself would usually be compiled
12135 with @option{-G0}.)
12137 @option{-mno-gpopt} implies @option{-mno-local-sdata} and
12138 @option{-mno-extern-sdata}.
12140 @item -membedded-data
12141 @itemx -mno-embedded-data
12142 @opindex membedded-data
12143 @opindex mno-embedded-data
12144 Allocate variables to the read-only data section first if possible, then
12145 next in the small data section if possible, otherwise in data. This gives
12146 slightly slower code than the default, but reduces the amount of RAM required
12147 when executing, and thus may be preferred for some embedded systems.
12149 @item -muninit-const-in-rodata
12150 @itemx -mno-uninit-const-in-rodata
12151 @opindex muninit-const-in-rodata
12152 @opindex mno-uninit-const-in-rodata
12153 Put uninitialized @code{const} variables in the read-only data section.
12154 This option is only meaningful in conjunction with @option{-membedded-data}.
12156 @item -mcode-readable=@var{setting}
12157 @opindex mcode-readable
12158 Specify whether GCC may generate code that reads from executable sections.
12159 There are three possible settings:
12162 @item -mcode-readable=yes
12163 Instructions may freely access executable sections. This is the
12166 @item -mcode-readable=pcrel
12167 MIPS16 PC-relative load instructions can access executable sections,
12168 but other instructions must not do so. This option is useful on 4KSc
12169 and 4KSd processors when the code TLBs have the Read Inhibit bit set.
12170 It is also useful on processors that can be configured to have a dual
12171 instruction/data SRAM interface and that, like the M4K, automatically
12172 redirect PC-relative loads to the instruction RAM.
12174 @item -mcode-readable=no
12175 Instructions must not access executable sections. This option can be
12176 useful on targets that are configured to have a dual instruction/data
12177 SRAM interface but that (unlike the M4K) do not automatically redirect
12178 PC-relative loads to the instruction RAM.
12181 @item -msplit-addresses
12182 @itemx -mno-split-addresses
12183 @opindex msplit-addresses
12184 @opindex mno-split-addresses
12185 Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
12186 relocation operators. This option has been superseded by
12187 @option{-mexplicit-relocs} but is retained for backwards compatibility.
12189 @item -mexplicit-relocs
12190 @itemx -mno-explicit-relocs
12191 @opindex mexplicit-relocs
12192 @opindex mno-explicit-relocs
12193 Use (do not use) assembler relocation operators when dealing with symbolic
12194 addresses. The alternative, selected by @option{-mno-explicit-relocs},
12195 is to use assembler macros instead.
12197 @option{-mexplicit-relocs} is the default if GCC was configured
12198 to use an assembler that supports relocation operators.
12200 @item -mcheck-zero-division
12201 @itemx -mno-check-zero-division
12202 @opindex mcheck-zero-division
12203 @opindex mno-check-zero-division
12204 Trap (do not trap) on integer division by zero.
12206 The default is @option{-mcheck-zero-division}.
12208 @item -mdivide-traps
12209 @itemx -mdivide-breaks
12210 @opindex mdivide-traps
12211 @opindex mdivide-breaks
12212 MIPS systems check for division by zero by generating either a
12213 conditional trap or a break instruction. Using traps results in
12214 smaller code, but is only supported on MIPS II and later. Also, some
12215 versions of the Linux kernel have a bug that prevents trap from
12216 generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
12217 allow conditional traps on architectures that support them and
12218 @option{-mdivide-breaks} to force the use of breaks.
12220 The default is usually @option{-mdivide-traps}, but this can be
12221 overridden at configure time using @option{--with-divide=breaks}.
12222 Divide-by-zero checks can be completely disabled using
12223 @option{-mno-check-zero-division}.
12228 @opindex mno-memcpy
12229 Force (do not force) the use of @code{memcpy()} for non-trivial block
12230 moves. The default is @option{-mno-memcpy}, which allows GCC to inline
12231 most constant-sized copies.
12234 @itemx -mno-long-calls
12235 @opindex mlong-calls
12236 @opindex mno-long-calls
12237 Disable (do not disable) use of the @code{jal} instruction. Calling
12238 functions using @code{jal} is more efficient but requires the caller
12239 and callee to be in the same 256 megabyte segment.
12241 This option has no effect on abicalls code. The default is
12242 @option{-mno-long-calls}.
12248 Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
12249 instructions, as provided by the R4650 ISA@.
12252 @itemx -mno-fused-madd
12253 @opindex mfused-madd
12254 @opindex mno-fused-madd
12255 Enable (disable) use of the floating point multiply-accumulate
12256 instructions, when they are available. The default is
12257 @option{-mfused-madd}.
12259 When multiply-accumulate instructions are used, the intermediate
12260 product is calculated to infinite precision and is not subject to
12261 the FCSR Flush to Zero bit. This may be undesirable in some
12266 Tell the MIPS assembler to not run its preprocessor over user
12267 assembler files (with a @samp{.s} suffix) when assembling them.
12270 @itemx -mno-fix-r4000
12271 @opindex mfix-r4000
12272 @opindex mno-fix-r4000
12273 Work around certain R4000 CPU errata:
12276 A double-word or a variable shift may give an incorrect result if executed
12277 immediately after starting an integer division.
12279 A double-word or a variable shift may give an incorrect result if executed
12280 while an integer multiplication is in progress.
12282 An integer division may give an incorrect result if started in a delay slot
12283 of a taken branch or a jump.
12287 @itemx -mno-fix-r4400
12288 @opindex mfix-r4400
12289 @opindex mno-fix-r4400
12290 Work around certain R4400 CPU errata:
12293 A double-word or a variable shift may give an incorrect result if executed
12294 immediately after starting an integer division.
12298 @itemx -mno-fix-vr4120
12299 @opindex mfix-vr4120
12300 Work around certain VR4120 errata:
12303 @code{dmultu} does not always produce the correct result.
12305 @code{div} and @code{ddiv} do not always produce the correct result if one
12306 of the operands is negative.
12308 The workarounds for the division errata rely on special functions in
12309 @file{libgcc.a}. At present, these functions are only provided by
12310 the @code{mips64vr*-elf} configurations.
12312 Other VR4120 errata require a nop to be inserted between certain pairs of
12313 instructions. These errata are handled by the assembler, not by GCC itself.
12316 @opindex mfix-vr4130
12317 Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
12318 workarounds are implemented by the assembler rather than by GCC,
12319 although GCC will avoid using @code{mflo} and @code{mfhi} if the
12320 VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
12321 instructions are available instead.
12324 @itemx -mno-fix-sb1
12326 Work around certain SB-1 CPU core errata.
12327 (This flag currently works around the SB-1 revision 2
12328 ``F1'' and ``F2'' floating point errata.)
12330 @item -mflush-func=@var{func}
12331 @itemx -mno-flush-func
12332 @opindex mflush-func
12333 Specifies the function to call to flush the I and D caches, or to not
12334 call any such function. If called, the function must take the same
12335 arguments as the common @code{_flush_func()}, that is, the address of the
12336 memory range for which the cache is being flushed, the size of the
12337 memory range, and the number 3 (to flush both caches). The default
12338 depends on the target GCC was configured for, but commonly is either
12339 @samp{_flush_func} or @samp{__cpu_flush}.
12341 @item mbranch-cost=@var{num}
12342 @opindex mbranch-cost
12343 Set the cost of branches to roughly @var{num} ``simple'' instructions.
12344 This cost is only a heuristic and is not guaranteed to produce
12345 consistent results across releases. A zero cost redundantly selects
12346 the default, which is based on the @option{-mtune} setting.
12348 @item -mbranch-likely
12349 @itemx -mno-branch-likely
12350 @opindex mbranch-likely
12351 @opindex mno-branch-likely
12352 Enable or disable use of Branch Likely instructions, regardless of the
12353 default for the selected architecture. By default, Branch Likely
12354 instructions may be generated if they are supported by the selected
12355 architecture. An exception is for the MIPS32 and MIPS64 architectures
12356 and processors which implement those architectures; for those, Branch
12357 Likely instructions will not be generated by default because the MIPS32
12358 and MIPS64 architectures specifically deprecate their use.
12360 @item -mfp-exceptions
12361 @itemx -mno-fp-exceptions
12362 @opindex mfp-exceptions
12363 Specifies whether FP exceptions are enabled. This affects how we schedule
12364 FP instructions for some processors. The default is that FP exceptions are
12367 For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
12368 64-bit code, then we can use both FP pipes. Otherwise, we can only use one
12371 @item -mvr4130-align
12372 @itemx -mno-vr4130-align
12373 @opindex mvr4130-align
12374 The VR4130 pipeline is two-way superscalar, but can only issue two
12375 instructions together if the first one is 8-byte aligned. When this
12376 option is enabled, GCC will align pairs of instructions that it
12377 thinks should execute in parallel.
12379 This option only has an effect when optimizing for the VR4130.
12380 It normally makes code faster, but at the expense of making it bigger.
12381 It is enabled by default at optimization level @option{-O3}.
12385 @subsection MMIX Options
12386 @cindex MMIX Options
12388 These options are defined for the MMIX:
12392 @itemx -mno-libfuncs
12394 @opindex mno-libfuncs
12395 Specify that intrinsic library functions are being compiled, passing all
12396 values in registers, no matter the size.
12399 @itemx -mno-epsilon
12401 @opindex mno-epsilon
12402 Generate floating-point comparison instructions that compare with respect
12403 to the @code{rE} epsilon register.
12405 @item -mabi=mmixware
12407 @opindex mabi-mmixware
12409 Generate code that passes function parameters and return values that (in
12410 the called function) are seen as registers @code{$0} and up, as opposed to
12411 the GNU ABI which uses global registers @code{$231} and up.
12413 @item -mzero-extend
12414 @itemx -mno-zero-extend
12415 @opindex mzero-extend
12416 @opindex mno-zero-extend
12417 When reading data from memory in sizes shorter than 64 bits, use (do not
12418 use) zero-extending load instructions by default, rather than
12419 sign-extending ones.
12422 @itemx -mno-knuthdiv
12424 @opindex mno-knuthdiv
12425 Make the result of a division yielding a remainder have the same sign as
12426 the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
12427 remainder follows the sign of the dividend. Both methods are
12428 arithmetically valid, the latter being almost exclusively used.
12430 @item -mtoplevel-symbols
12431 @itemx -mno-toplevel-symbols
12432 @opindex mtoplevel-symbols
12433 @opindex mno-toplevel-symbols
12434 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
12435 code can be used with the @code{PREFIX} assembly directive.
12439 Generate an executable in the ELF format, rather than the default
12440 @samp{mmo} format used by the @command{mmix} simulator.
12442 @item -mbranch-predict
12443 @itemx -mno-branch-predict
12444 @opindex mbranch-predict
12445 @opindex mno-branch-predict
12446 Use (do not use) the probable-branch instructions, when static branch
12447 prediction indicates a probable branch.
12449 @item -mbase-addresses
12450 @itemx -mno-base-addresses
12451 @opindex mbase-addresses
12452 @opindex mno-base-addresses
12453 Generate (do not generate) code that uses @emph{base addresses}. Using a
12454 base address automatically generates a request (handled by the assembler
12455 and the linker) for a constant to be set up in a global register. The
12456 register is used for one or more base address requests within the range 0
12457 to 255 from the value held in the register. The generally leads to short
12458 and fast code, but the number of different data items that can be
12459 addressed is limited. This means that a program that uses lots of static
12460 data may require @option{-mno-base-addresses}.
12462 @item -msingle-exit
12463 @itemx -mno-single-exit
12464 @opindex msingle-exit
12465 @opindex mno-single-exit
12466 Force (do not force) generated code to have a single exit point in each
12470 @node MN10300 Options
12471 @subsection MN10300 Options
12472 @cindex MN10300 options
12474 These @option{-m} options are defined for Matsushita MN10300 architectures:
12479 Generate code to avoid bugs in the multiply instructions for the MN10300
12480 processors. This is the default.
12482 @item -mno-mult-bug
12483 @opindex mno-mult-bug
12484 Do not generate code to avoid bugs in the multiply instructions for the
12485 MN10300 processors.
12489 Generate code which uses features specific to the AM33 processor.
12493 Do not generate code which uses features specific to the AM33 processor. This
12496 @item -mreturn-pointer-on-d0
12497 @opindex mreturn-pointer-on-d0
12498 When generating a function which returns a pointer, return the pointer
12499 in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
12500 only in a0, and attempts to call such functions without a prototype
12501 would result in errors. Note that this option is on by default; use
12502 @option{-mno-return-pointer-on-d0} to disable it.
12506 Do not link in the C run-time initialization object file.
12510 Indicate to the linker that it should perform a relaxation optimization pass
12511 to shorten branches, calls and absolute memory addresses. This option only
12512 has an effect when used on the command line for the final link step.
12514 This option makes symbolic debugging impossible.
12518 @subsection MT Options
12521 These @option{-m} options are defined for Morpho MT architectures:
12525 @item -march=@var{cpu-type}
12527 Generate code that will run on @var{cpu-type}, which is the name of a system
12528 representing a certain processor type. Possible values for
12529 @var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
12530 @samp{ms1-16-003} and @samp{ms2}.
12532 When this option is not used, the default is @option{-march=ms1-16-002}.
12536 Use byte loads and stores when generating code.
12540 Do not use byte loads and stores when generating code.
12544 Use simulator runtime
12548 Do not link in the C run-time initialization object file
12549 @file{crti.o}. Other run-time initialization and termination files
12550 such as @file{startup.o} and @file{exit.o} are still included on the
12551 linker command line.
12555 @node PDP-11 Options
12556 @subsection PDP-11 Options
12557 @cindex PDP-11 Options
12559 These options are defined for the PDP-11:
12564 Use hardware FPP floating point. This is the default. (FIS floating
12565 point on the PDP-11/40 is not supported.)
12568 @opindex msoft-float
12569 Do not use hardware floating point.
12573 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
12577 Return floating-point results in memory. This is the default.
12581 Generate code for a PDP-11/40.
12585 Generate code for a PDP-11/45. This is the default.
12589 Generate code for a PDP-11/10.
12591 @item -mbcopy-builtin
12592 @opindex bcopy-builtin
12593 Use inline @code{movmemhi} patterns for copying memory. This is the
12598 Do not use inline @code{movmemhi} patterns for copying memory.
12604 Use 16-bit @code{int}. This is the default.
12610 Use 32-bit @code{int}.
12613 @itemx -mno-float32
12615 @opindex mno-float32
12616 Use 64-bit @code{float}. This is the default.
12619 @itemx -mno-float64
12621 @opindex mno-float64
12622 Use 32-bit @code{float}.
12626 Use @code{abshi2} pattern. This is the default.
12630 Do not use @code{abshi2} pattern.
12632 @item -mbranch-expensive
12633 @opindex mbranch-expensive
12634 Pretend that branches are expensive. This is for experimenting with
12635 code generation only.
12637 @item -mbranch-cheap
12638 @opindex mbranch-cheap
12639 Do not pretend that branches are expensive. This is the default.
12643 Generate code for a system with split I&D@.
12647 Generate code for a system without split I&D@. This is the default.
12651 Use Unix assembler syntax. This is the default when configured for
12652 @samp{pdp11-*-bsd}.
12656 Use DEC assembler syntax. This is the default when configured for any
12657 PDP-11 target other than @samp{pdp11-*-bsd}.
12660 @node PowerPC Options
12661 @subsection PowerPC Options
12662 @cindex PowerPC options
12664 These are listed under @xref{RS/6000 and PowerPC Options}.
12666 @node RS/6000 and PowerPC Options
12667 @subsection IBM RS/6000 and PowerPC Options
12668 @cindex RS/6000 and PowerPC Options
12669 @cindex IBM RS/6000 and PowerPC Options
12671 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
12678 @itemx -mno-powerpc
12679 @itemx -mpowerpc-gpopt
12680 @itemx -mno-powerpc-gpopt
12681 @itemx -mpowerpc-gfxopt
12682 @itemx -mno-powerpc-gfxopt
12684 @itemx -mno-powerpc64
12688 @itemx -mno-popcntb
12696 @itemx -mno-hard-dfp
12700 @opindex mno-power2
12702 @opindex mno-powerpc
12703 @opindex mpowerpc-gpopt
12704 @opindex mno-powerpc-gpopt
12705 @opindex mpowerpc-gfxopt
12706 @opindex mno-powerpc-gfxopt
12707 @opindex mpowerpc64
12708 @opindex mno-powerpc64
12712 @opindex mno-popcntb
12718 @opindex mno-mfpgpr
12720 @opindex mno-hard-dfp
12721 GCC supports two related instruction set architectures for the
12722 RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
12723 instructions supported by the @samp{rios} chip set used in the original
12724 RS/6000 systems and the @dfn{PowerPC} instruction set is the
12725 architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
12726 the IBM 4xx, 6xx, and follow-on microprocessors.
12728 Neither architecture is a subset of the other. However there is a
12729 large common subset of instructions supported by both. An MQ
12730 register is included in processors supporting the POWER architecture.
12732 You use these options to specify which instructions are available on the
12733 processor you are using. The default value of these options is
12734 determined when configuring GCC@. Specifying the
12735 @option{-mcpu=@var{cpu_type}} overrides the specification of these
12736 options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
12737 rather than the options listed above.
12739 The @option{-mpower} option allows GCC to generate instructions that
12740 are found only in the POWER architecture and to use the MQ register.
12741 Specifying @option{-mpower2} implies @option{-power} and also allows GCC
12742 to generate instructions that are present in the POWER2 architecture but
12743 not the original POWER architecture.
12745 The @option{-mpowerpc} option allows GCC to generate instructions that
12746 are found only in the 32-bit subset of the PowerPC architecture.
12747 Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
12748 GCC to use the optional PowerPC architecture instructions in the
12749 General Purpose group, including floating-point square root. Specifying
12750 @option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
12751 use the optional PowerPC architecture instructions in the Graphics
12752 group, including floating-point select.
12754 The @option{-mmfcrf} option allows GCC to generate the move from
12755 condition register field instruction implemented on the POWER4
12756 processor and other processors that support the PowerPC V2.01
12758 The @option{-mpopcntb} option allows GCC to generate the popcount and
12759 double precision FP reciprocal estimate instruction implemented on the
12760 POWER5 processor and other processors that support the PowerPC V2.02
12762 The @option{-mfprnd} option allows GCC to generate the FP round to
12763 integer instructions implemented on the POWER5+ processor and other
12764 processors that support the PowerPC V2.03 architecture.
12765 The @option{-mcmpb} option allows GCC to generate the compare bytes
12766 instruction implemented on the POWER6 processor and other processors
12767 that support the PowerPC V2.05 architecture.
12768 The @option{-mmfpgpr} option allows GCC to generate the FP move to/from
12769 general purpose register instructions implemented on the POWER6X
12770 processor and other processors that support the extended PowerPC V2.05
12772 The @option{-mhard-dfp} option allows GCC to generate the decimal floating
12773 point instructions implemented on some POWER processors.
12775 The @option{-mpowerpc64} option allows GCC to generate the additional
12776 64-bit instructions that are found in the full PowerPC64 architecture
12777 and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
12778 @option{-mno-powerpc64}.
12780 If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
12781 will use only the instructions in the common subset of both
12782 architectures plus some special AIX common-mode calls, and will not use
12783 the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
12784 permits GCC to use any instruction from either architecture and to
12785 allow use of the MQ register; specify this for the Motorola MPC601.
12787 @item -mnew-mnemonics
12788 @itemx -mold-mnemonics
12789 @opindex mnew-mnemonics
12790 @opindex mold-mnemonics
12791 Select which mnemonics to use in the generated assembler code. With
12792 @option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
12793 the PowerPC architecture. With @option{-mold-mnemonics} it uses the
12794 assembler mnemonics defined for the POWER architecture. Instructions
12795 defined in only one architecture have only one mnemonic; GCC uses that
12796 mnemonic irrespective of which of these options is specified.
12798 GCC defaults to the mnemonics appropriate for the architecture in
12799 use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
12800 value of these option. Unless you are building a cross-compiler, you
12801 should normally not specify either @option{-mnew-mnemonics} or
12802 @option{-mold-mnemonics}, but should instead accept the default.
12804 @item -mcpu=@var{cpu_type}
12806 Set architecture type, register usage, choice of mnemonics, and
12807 instruction scheduling parameters for machine type @var{cpu_type}.
12808 Supported values for @var{cpu_type} are @samp{401}, @samp{403},
12809 @samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
12810 @samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
12811 @samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
12812 @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
12813 @samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
12814 @samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
12815 @samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
12816 @samp{power6x}, @samp{common}, @samp{powerpc}, @samp{powerpc64},
12817 @samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
12819 @option{-mcpu=common} selects a completely generic processor. Code
12820 generated under this option will run on any POWER or PowerPC processor.
12821 GCC will use only the instructions in the common subset of both
12822 architectures, and will not use the MQ register. GCC assumes a generic
12823 processor model for scheduling purposes.
12825 @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
12826 @option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
12827 PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
12828 types, with an appropriate, generic processor model assumed for
12829 scheduling purposes.
12831 The other options specify a specific processor. Code generated under
12832 those options will run best on that processor, and may not run at all on
12835 The @option{-mcpu} options automatically enable or disable the
12838 @gccoptlist{-maltivec -mfprnd -mhard-float -mmfcrf -mmultiple @gol
12839 -mnew-mnemonics -mpopcntb -mpower -mpower2 -mpowerpc64 @gol
12840 -mpowerpc-gpopt -mpowerpc-gfxopt -mstring -mmulhw -mdlmzb -mmfpgpr}
12842 The particular options set for any particular CPU will vary between
12843 compiler versions, depending on what setting seems to produce optimal
12844 code for that CPU; it doesn't necessarily reflect the actual hardware's
12845 capabilities. If you wish to set an individual option to a particular
12846 value, you may specify it after the @option{-mcpu} option, like
12847 @samp{-mcpu=970 -mno-altivec}.
12849 On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
12850 not enabled or disabled by the @option{-mcpu} option at present because
12851 AIX does not have full support for these options. You may still
12852 enable or disable them individually if you're sure it'll work in your
12855 @item -mtune=@var{cpu_type}
12857 Set the instruction scheduling parameters for machine type
12858 @var{cpu_type}, but do not set the architecture type, register usage, or
12859 choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
12860 values for @var{cpu_type} are used for @option{-mtune} as for
12861 @option{-mcpu}. If both are specified, the code generated will use the
12862 architecture, registers, and mnemonics set by @option{-mcpu}, but the
12863 scheduling parameters set by @option{-mtune}.
12869 Generate code to compute division as reciprocal estimate and iterative
12870 refinement, creating opportunities for increased throughput. This
12871 feature requires: optional PowerPC Graphics instruction set for single
12872 precision and FRE instruction for double precision, assuming divides
12873 cannot generate user-visible traps, and the domain values not include
12874 Infinities, denormals or zero denominator.
12877 @itemx -mno-altivec
12879 @opindex mno-altivec
12880 Generate code that uses (does not use) AltiVec instructions, and also
12881 enable the use of built-in functions that allow more direct access to
12882 the AltiVec instruction set. You may also need to set
12883 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
12889 @opindex mno-vrsave
12890 Generate VRSAVE instructions when generating AltiVec code.
12893 @opindex msecure-plt
12894 Generate code that allows ld and ld.so to build executables and shared
12895 libraries with non-exec .plt and .got sections. This is a PowerPC
12896 32-bit SYSV ABI option.
12900 Generate code that uses a BSS .plt section that ld.so fills in, and
12901 requires .plt and .got sections that are both writable and executable.
12902 This is a PowerPC 32-bit SYSV ABI option.
12908 This switch enables or disables the generation of ISEL instructions.
12910 @item -misel=@var{yes/no}
12911 This switch has been deprecated. Use @option{-misel} and
12912 @option{-mno-isel} instead.
12918 This switch enables or disables the generation of SPE simd
12924 @opindex mno-paired
12925 This switch enables or disables the generation of PAIRED simd
12928 @item -mspe=@var{yes/no}
12929 This option has been deprecated. Use @option{-mspe} and
12930 @option{-mno-spe} instead.
12932 @item -mfloat-gprs=@var{yes/single/double/no}
12933 @itemx -mfloat-gprs
12934 @opindex mfloat-gprs
12935 This switch enables or disables the generation of floating point
12936 operations on the general purpose registers for architectures that
12939 The argument @var{yes} or @var{single} enables the use of
12940 single-precision floating point operations.
12942 The argument @var{double} enables the use of single and
12943 double-precision floating point operations.
12945 The argument @var{no} disables floating point operations on the
12946 general purpose registers.
12948 This option is currently only available on the MPC854x.
12954 Generate code for 32-bit or 64-bit environments of Darwin and SVR4
12955 targets (including GNU/Linux). The 32-bit environment sets int, long
12956 and pointer to 32 bits and generates code that runs on any PowerPC
12957 variant. The 64-bit environment sets int to 32 bits and long and
12958 pointer to 64 bits, and generates code for PowerPC64, as for
12959 @option{-mpowerpc64}.
12962 @itemx -mno-fp-in-toc
12963 @itemx -mno-sum-in-toc
12964 @itemx -mminimal-toc
12966 @opindex mno-fp-in-toc
12967 @opindex mno-sum-in-toc
12968 @opindex mminimal-toc
12969 Modify generation of the TOC (Table Of Contents), which is created for
12970 every executable file. The @option{-mfull-toc} option is selected by
12971 default. In that case, GCC will allocate at least one TOC entry for
12972 each unique non-automatic variable reference in your program. GCC
12973 will also place floating-point constants in the TOC@. However, only
12974 16,384 entries are available in the TOC@.
12976 If you receive a linker error message that saying you have overflowed
12977 the available TOC space, you can reduce the amount of TOC space used
12978 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
12979 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
12980 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
12981 generate code to calculate the sum of an address and a constant at
12982 run-time instead of putting that sum into the TOC@. You may specify one
12983 or both of these options. Each causes GCC to produce very slightly
12984 slower and larger code at the expense of conserving TOC space.
12986 If you still run out of space in the TOC even when you specify both of
12987 these options, specify @option{-mminimal-toc} instead. This option causes
12988 GCC to make only one TOC entry for every file. When you specify this
12989 option, GCC will produce code that is slower and larger but which
12990 uses extremely little TOC space. You may wish to use this option
12991 only on files that contain less frequently executed code.
12997 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
12998 @code{long} type, and the infrastructure needed to support them.
12999 Specifying @option{-maix64} implies @option{-mpowerpc64} and
13000 @option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
13001 implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
13004 @itemx -mno-xl-compat
13005 @opindex mxl-compat
13006 @opindex mno-xl-compat
13007 Produce code that conforms more closely to IBM XL compiler semantics
13008 when using AIX-compatible ABI. Pass floating-point arguments to
13009 prototyped functions beyond the register save area (RSA) on the stack
13010 in addition to argument FPRs. Do not assume that most significant
13011 double in 128-bit long double value is properly rounded when comparing
13012 values and converting to double. Use XL symbol names for long double
13015 The AIX calling convention was extended but not initially documented to
13016 handle an obscure K&R C case of calling a function that takes the
13017 address of its arguments with fewer arguments than declared. IBM XL
13018 compilers access floating point arguments which do not fit in the
13019 RSA from the stack when a subroutine is compiled without
13020 optimization. Because always storing floating-point arguments on the
13021 stack is inefficient and rarely needed, this option is not enabled by
13022 default and only is necessary when calling subroutines compiled by IBM
13023 XL compilers without optimization.
13027 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
13028 application written to use message passing with special startup code to
13029 enable the application to run. The system must have PE installed in the
13030 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
13031 must be overridden with the @option{-specs=} option to specify the
13032 appropriate directory location. The Parallel Environment does not
13033 support threads, so the @option{-mpe} option and the @option{-pthread}
13034 option are incompatible.
13036 @item -malign-natural
13037 @itemx -malign-power
13038 @opindex malign-natural
13039 @opindex malign-power
13040 On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
13041 @option{-malign-natural} overrides the ABI-defined alignment of larger
13042 types, such as floating-point doubles, on their natural size-based boundary.
13043 The option @option{-malign-power} instructs GCC to follow the ABI-specified
13044 alignment rules. GCC defaults to the standard alignment defined in the ABI@.
13046 On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
13050 @itemx -mhard-float
13051 @opindex msoft-float
13052 @opindex mhard-float
13053 Generate code that does not use (uses) the floating-point register set.
13054 Software floating point emulation is provided if you use the
13055 @option{-msoft-float} option, and pass the option to GCC when linking.
13058 @itemx -mno-multiple
13060 @opindex mno-multiple
13061 Generate code that uses (does not use) the load multiple word
13062 instructions and the store multiple word instructions. These
13063 instructions are generated by default on POWER systems, and not
13064 generated on PowerPC systems. Do not use @option{-mmultiple} on little
13065 endian PowerPC systems, since those instructions do not work when the
13066 processor is in little endian mode. The exceptions are PPC740 and
13067 PPC750 which permit the instructions usage in little endian mode.
13072 @opindex mno-string
13073 Generate code that uses (does not use) the load string instructions
13074 and the store string word instructions to save multiple registers and
13075 do small block moves. These instructions are generated by default on
13076 POWER systems, and not generated on PowerPC systems. Do not use
13077 @option{-mstring} on little endian PowerPC systems, since those
13078 instructions do not work when the processor is in little endian mode.
13079 The exceptions are PPC740 and PPC750 which permit the instructions
13080 usage in little endian mode.
13085 @opindex mno-update
13086 Generate code that uses (does not use) the load or store instructions
13087 that update the base register to the address of the calculated memory
13088 location. These instructions are generated by default. If you use
13089 @option{-mno-update}, there is a small window between the time that the
13090 stack pointer is updated and the address of the previous frame is
13091 stored, which means code that walks the stack frame across interrupts or
13092 signals may get corrupted data.
13095 @itemx -mno-fused-madd
13096 @opindex mfused-madd
13097 @opindex mno-fused-madd
13098 Generate code that uses (does not use) the floating point multiply and
13099 accumulate instructions. These instructions are generated by default if
13100 hardware floating is used.
13106 Generate code that uses (does not use) the half-word multiply and
13107 multiply-accumulate instructions on the IBM 405 and 440 processors.
13108 These instructions are generated by default when targetting those
13115 Generate code that uses (does not use) the string-search @samp{dlmzb}
13116 instruction on the IBM 405 and 440 processors. This instruction is
13117 generated by default when targetting those processors.
13119 @item -mno-bit-align
13121 @opindex mno-bit-align
13122 @opindex mbit-align
13123 On System V.4 and embedded PowerPC systems do not (do) force structures
13124 and unions that contain bit-fields to be aligned to the base type of the
13127 For example, by default a structure containing nothing but 8
13128 @code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
13129 boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
13130 the structure would be aligned to a 1 byte boundary and be one byte in
13133 @item -mno-strict-align
13134 @itemx -mstrict-align
13135 @opindex mno-strict-align
13136 @opindex mstrict-align
13137 On System V.4 and embedded PowerPC systems do not (do) assume that
13138 unaligned memory references will be handled by the system.
13140 @item -mrelocatable
13141 @itemx -mno-relocatable
13142 @opindex mrelocatable
13143 @opindex mno-relocatable
13144 On embedded PowerPC systems generate code that allows (does not allow)
13145 the program to be relocated to a different address at runtime. If you
13146 use @option{-mrelocatable} on any module, all objects linked together must
13147 be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
13149 @item -mrelocatable-lib
13150 @itemx -mno-relocatable-lib
13151 @opindex mrelocatable-lib
13152 @opindex mno-relocatable-lib
13153 On embedded PowerPC systems generate code that allows (does not allow)
13154 the program to be relocated to a different address at runtime. Modules
13155 compiled with @option{-mrelocatable-lib} can be linked with either modules
13156 compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
13157 with modules compiled with the @option{-mrelocatable} options.
13163 On System V.4 and embedded PowerPC systems do not (do) assume that
13164 register 2 contains a pointer to a global area pointing to the addresses
13165 used in the program.
13168 @itemx -mlittle-endian
13170 @opindex mlittle-endian
13171 On System V.4 and embedded PowerPC systems compile code for the
13172 processor in little endian mode. The @option{-mlittle-endian} option is
13173 the same as @option{-mlittle}.
13176 @itemx -mbig-endian
13178 @opindex mbig-endian
13179 On System V.4 and embedded PowerPC systems compile code for the
13180 processor in big endian mode. The @option{-mbig-endian} option is
13181 the same as @option{-mbig}.
13183 @item -mdynamic-no-pic
13184 @opindex mdynamic-no-pic
13185 On Darwin and Mac OS X systems, compile code so that it is not
13186 relocatable, but that its external references are relocatable. The
13187 resulting code is suitable for applications, but not shared
13190 @item -mprioritize-restricted-insns=@var{priority}
13191 @opindex mprioritize-restricted-insns
13192 This option controls the priority that is assigned to
13193 dispatch-slot restricted instructions during the second scheduling
13194 pass. The argument @var{priority} takes the value @var{0/1/2} to assign
13195 @var{no/highest/second-highest} priority to dispatch slot restricted
13198 @item -msched-costly-dep=@var{dependence_type}
13199 @opindex msched-costly-dep
13200 This option controls which dependences are considered costly
13201 by the target during instruction scheduling. The argument
13202 @var{dependence_type} takes one of the following values:
13203 @var{no}: no dependence is costly,
13204 @var{all}: all dependences are costly,
13205 @var{true_store_to_load}: a true dependence from store to load is costly,
13206 @var{store_to_load}: any dependence from store to load is costly,
13207 @var{number}: any dependence which latency >= @var{number} is costly.
13209 @item -minsert-sched-nops=@var{scheme}
13210 @opindex minsert-sched-nops
13211 This option controls which nop insertion scheme will be used during
13212 the second scheduling pass. The argument @var{scheme} takes one of the
13214 @var{no}: Don't insert nops.
13215 @var{pad}: Pad with nops any dispatch group which has vacant issue slots,
13216 according to the scheduler's grouping.
13217 @var{regroup_exact}: Insert nops to force costly dependent insns into
13218 separate groups. Insert exactly as many nops as needed to force an insn
13219 to a new group, according to the estimated processor grouping.
13220 @var{number}: Insert nops to force costly dependent insns into
13221 separate groups. Insert @var{number} nops to force an insn to a new group.
13224 @opindex mcall-sysv
13225 On System V.4 and embedded PowerPC systems compile code using calling
13226 conventions that adheres to the March 1995 draft of the System V
13227 Application Binary Interface, PowerPC processor supplement. This is the
13228 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
13230 @item -mcall-sysv-eabi
13231 @opindex mcall-sysv-eabi
13232 Specify both @option{-mcall-sysv} and @option{-meabi} options.
13234 @item -mcall-sysv-noeabi
13235 @opindex mcall-sysv-noeabi
13236 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
13238 @item -mcall-solaris
13239 @opindex mcall-solaris
13240 On System V.4 and embedded PowerPC systems compile code for the Solaris
13244 @opindex mcall-linux
13245 On System V.4 and embedded PowerPC systems compile code for the
13246 Linux-based GNU system.
13250 On System V.4 and embedded PowerPC systems compile code for the
13251 Hurd-based GNU system.
13253 @item -mcall-netbsd
13254 @opindex mcall-netbsd
13255 On System V.4 and embedded PowerPC systems compile code for the
13256 NetBSD operating system.
13258 @item -maix-struct-return
13259 @opindex maix-struct-return
13260 Return all structures in memory (as specified by the AIX ABI)@.
13262 @item -msvr4-struct-return
13263 @opindex msvr4-struct-return
13264 Return structures smaller than 8 bytes in registers (as specified by the
13267 @item -mabi=@var{abi-type}
13269 Extend the current ABI with a particular extension, or remove such extension.
13270 Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
13271 @var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
13275 Extend the current ABI with SPE ABI extensions. This does not change
13276 the default ABI, instead it adds the SPE ABI extensions to the current
13280 @opindex mabi=no-spe
13281 Disable Booke SPE ABI extensions for the current ABI@.
13283 @item -mabi=ibmlongdouble
13284 @opindex mabi=ibmlongdouble
13285 Change the current ABI to use IBM extended precision long double.
13286 This is a PowerPC 32-bit SYSV ABI option.
13288 @item -mabi=ieeelongdouble
13289 @opindex mabi=ieeelongdouble
13290 Change the current ABI to use IEEE extended precision long double.
13291 This is a PowerPC 32-bit Linux ABI option.
13294 @itemx -mno-prototype
13295 @opindex mprototype
13296 @opindex mno-prototype
13297 On System V.4 and embedded PowerPC systems assume that all calls to
13298 variable argument functions are properly prototyped. Otherwise, the
13299 compiler must insert an instruction before every non prototyped call to
13300 set or clear bit 6 of the condition code register (@var{CR}) to
13301 indicate whether floating point values were passed in the floating point
13302 registers in case the function takes a variable arguments. With
13303 @option{-mprototype}, only calls to prototyped variable argument functions
13304 will set or clear the bit.
13308 On embedded PowerPC systems, assume that the startup module is called
13309 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
13310 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
13315 On embedded PowerPC systems, assume that the startup module is called
13316 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
13321 On embedded PowerPC systems, assume that the startup module is called
13322 @file{crt0.o} and the standard C libraries are @file{libads.a} and
13325 @item -myellowknife
13326 @opindex myellowknife
13327 On embedded PowerPC systems, assume that the startup module is called
13328 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
13333 On System V.4 and embedded PowerPC systems, specify that you are
13334 compiling for a VxWorks system.
13338 Specify that you are compiling for the WindISS simulation environment.
13342 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
13343 header to indicate that @samp{eabi} extended relocations are used.
13349 On System V.4 and embedded PowerPC systems do (do not) adhere to the
13350 Embedded Applications Binary Interface (eabi) which is a set of
13351 modifications to the System V.4 specifications. Selecting @option{-meabi}
13352 means that the stack is aligned to an 8 byte boundary, a function
13353 @code{__eabi} is called to from @code{main} to set up the eabi
13354 environment, and the @option{-msdata} option can use both @code{r2} and
13355 @code{r13} to point to two separate small data areas. Selecting
13356 @option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
13357 do not call an initialization function from @code{main}, and the
13358 @option{-msdata} option will only use @code{r13} to point to a single
13359 small data area. The @option{-meabi} option is on by default if you
13360 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
13363 @opindex msdata=eabi
13364 On System V.4 and embedded PowerPC systems, put small initialized
13365 @code{const} global and static data in the @samp{.sdata2} section, which
13366 is pointed to by register @code{r2}. Put small initialized
13367 non-@code{const} global and static data in the @samp{.sdata} section,
13368 which is pointed to by register @code{r13}. Put small uninitialized
13369 global and static data in the @samp{.sbss} section, which is adjacent to
13370 the @samp{.sdata} section. The @option{-msdata=eabi} option is
13371 incompatible with the @option{-mrelocatable} option. The
13372 @option{-msdata=eabi} option also sets the @option{-memb} option.
13375 @opindex msdata=sysv
13376 On System V.4 and embedded PowerPC systems, put small global and static
13377 data in the @samp{.sdata} section, which is pointed to by register
13378 @code{r13}. Put small uninitialized global and static data in the
13379 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
13380 The @option{-msdata=sysv} option is incompatible with the
13381 @option{-mrelocatable} option.
13383 @item -msdata=default
13385 @opindex msdata=default
13387 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
13388 compile code the same as @option{-msdata=eabi}, otherwise compile code the
13389 same as @option{-msdata=sysv}.
13392 @opindex msdata-data
13393 On System V.4 and embedded PowerPC systems, put small global
13394 data in the @samp{.sdata} section. Put small uninitialized global
13395 data in the @samp{.sbss} section. Do not use register @code{r13}
13396 to address small data however. This is the default behavior unless
13397 other @option{-msdata} options are used.
13401 @opindex msdata=none
13403 On embedded PowerPC systems, put all initialized global and static data
13404 in the @samp{.data} section, and all uninitialized data in the
13405 @samp{.bss} section.
13409 @cindex smaller data references (PowerPC)
13410 @cindex .sdata/.sdata2 references (PowerPC)
13411 On embedded PowerPC systems, put global and static items less than or
13412 equal to @var{num} bytes into the small data or bss sections instead of
13413 the normal data or bss section. By default, @var{num} is 8. The
13414 @option{-G @var{num}} switch is also passed to the linker.
13415 All modules should be compiled with the same @option{-G @var{num}} value.
13418 @itemx -mno-regnames
13420 @opindex mno-regnames
13421 On System V.4 and embedded PowerPC systems do (do not) emit register
13422 names in the assembly language output using symbolic forms.
13425 @itemx -mno-longcall
13427 @opindex mno-longcall
13428 By default assume that all calls are far away so that a longer more
13429 expensive calling sequence is required. This is required for calls
13430 further than 32 megabytes (33,554,432 bytes) from the current location.
13431 A short call will be generated if the compiler knows
13432 the call cannot be that far away. This setting can be overridden by
13433 the @code{shortcall} function attribute, or by @code{#pragma
13436 Some linkers are capable of detecting out-of-range calls and generating
13437 glue code on the fly. On these systems, long calls are unnecessary and
13438 generate slower code. As of this writing, the AIX linker can do this,
13439 as can the GNU linker for PowerPC/64. It is planned to add this feature
13440 to the GNU linker for 32-bit PowerPC systems as well.
13442 On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
13443 callee, L42'', plus a ``branch island'' (glue code). The two target
13444 addresses represent the callee and the ``branch island''. The
13445 Darwin/PPC linker will prefer the first address and generate a ``bl
13446 callee'' if the PPC ``bl'' instruction will reach the callee directly;
13447 otherwise, the linker will generate ``bl L42'' to call the ``branch
13448 island''. The ``branch island'' is appended to the body of the
13449 calling function; it computes the full 32-bit address of the callee
13452 On Mach-O (Darwin) systems, this option directs the compiler emit to
13453 the glue for every direct call, and the Darwin linker decides whether
13454 to use or discard it.
13456 In the future, we may cause GCC to ignore all longcall specifications
13457 when the linker is known to generate glue.
13461 Adds support for multithreading with the @dfn{pthreads} library.
13462 This option sets flags for both the preprocessor and linker.
13466 @node S/390 and zSeries Options
13467 @subsection S/390 and zSeries Options
13468 @cindex S/390 and zSeries Options
13470 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
13474 @itemx -msoft-float
13475 @opindex mhard-float
13476 @opindex msoft-float
13477 Use (do not use) the hardware floating-point instructions and registers
13478 for floating-point operations. When @option{-msoft-float} is specified,
13479 functions in @file{libgcc.a} will be used to perform floating-point
13480 operations. When @option{-mhard-float} is specified, the compiler
13481 generates IEEE floating-point instructions. This is the default.
13483 @item -mlong-double-64
13484 @itemx -mlong-double-128
13485 @opindex mlong-double-64
13486 @opindex mlong-double-128
13487 These switches control the size of @code{long double} type. A size
13488 of 64bit makes the @code{long double} type equivalent to the @code{double}
13489 type. This is the default.
13492 @itemx -mno-backchain
13493 @opindex mbackchain
13494 @opindex mno-backchain
13495 Store (do not store) the address of the caller's frame as backchain pointer
13496 into the callee's stack frame.
13497 A backchain may be needed to allow debugging using tools that do not understand
13498 DWARF-2 call frame information.
13499 When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
13500 at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
13501 the backchain is placed into the topmost word of the 96/160 byte register
13504 In general, code compiled with @option{-mbackchain} is call-compatible with
13505 code compiled with @option{-mmo-backchain}; however, use of the backchain
13506 for debugging purposes usually requires that the whole binary is built with
13507 @option{-mbackchain}. Note that the combination of @option{-mbackchain},
13508 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
13509 to build a linux kernel use @option{-msoft-float}.
13511 The default is to not maintain the backchain.
13513 @item -mpacked-stack
13514 @item -mno-packed-stack
13515 @opindex mpacked-stack
13516 @opindex mno-packed-stack
13517 Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
13518 specified, the compiler uses the all fields of the 96/160 byte register save
13519 area only for their default purpose; unused fields still take up stack space.
13520 When @option{-mpacked-stack} is specified, register save slots are densely
13521 packed at the top of the register save area; unused space is reused for other
13522 purposes, allowing for more efficient use of the available stack space.
13523 However, when @option{-mbackchain} is also in effect, the topmost word of
13524 the save area is always used to store the backchain, and the return address
13525 register is always saved two words below the backchain.
13527 As long as the stack frame backchain is not used, code generated with
13528 @option{-mpacked-stack} is call-compatible with code generated with
13529 @option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
13530 S/390 or zSeries generated code that uses the stack frame backchain at run
13531 time, not just for debugging purposes. Such code is not call-compatible
13532 with code compiled with @option{-mpacked-stack}. Also, note that the
13533 combination of @option{-mbackchain},
13534 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
13535 to build a linux kernel use @option{-msoft-float}.
13537 The default is to not use the packed stack layout.
13540 @itemx -mno-small-exec
13541 @opindex msmall-exec
13542 @opindex mno-small-exec
13543 Generate (or do not generate) code using the @code{bras} instruction
13544 to do subroutine calls.
13545 This only works reliably if the total executable size does not
13546 exceed 64k. The default is to use the @code{basr} instruction instead,
13547 which does not have this limitation.
13553 When @option{-m31} is specified, generate code compliant to the
13554 GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
13555 code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
13556 particular to generate 64-bit instructions. For the @samp{s390}
13557 targets, the default is @option{-m31}, while the @samp{s390x}
13558 targets default to @option{-m64}.
13564 When @option{-mzarch} is specified, generate code using the
13565 instructions available on z/Architecture.
13566 When @option{-mesa} is specified, generate code using the
13567 instructions available on ESA/390. Note that @option{-mesa} is
13568 not possible with @option{-m64}.
13569 When generating code compliant to the GNU/Linux for S/390 ABI,
13570 the default is @option{-mesa}. When generating code compliant
13571 to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
13577 Generate (or do not generate) code using the @code{mvcle} instruction
13578 to perform block moves. When @option{-mno-mvcle} is specified,
13579 use a @code{mvc} loop instead. This is the default unless optimizing for
13586 Print (or do not print) additional debug information when compiling.
13587 The default is to not print debug information.
13589 @item -march=@var{cpu-type}
13591 Generate code that will run on @var{cpu-type}, which is the name of a system
13592 representing a certain processor type. Possible values for
13593 @var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
13594 When generating code using the instructions available on z/Architecture,
13595 the default is @option{-march=z900}. Otherwise, the default is
13596 @option{-march=g5}.
13598 @item -mtune=@var{cpu-type}
13600 Tune to @var{cpu-type} everything applicable about the generated code,
13601 except for the ABI and the set of available instructions.
13602 The list of @var{cpu-type} values is the same as for @option{-march}.
13603 The default is the value used for @option{-march}.
13606 @itemx -mno-tpf-trace
13607 @opindex mtpf-trace
13608 @opindex mno-tpf-trace
13609 Generate code that adds (does not add) in TPF OS specific branches to trace
13610 routines in the operating system. This option is off by default, even
13611 when compiling for the TPF OS@.
13614 @itemx -mno-fused-madd
13615 @opindex mfused-madd
13616 @opindex mno-fused-madd
13617 Generate code that uses (does not use) the floating point multiply and
13618 accumulate instructions. These instructions are generated by default if
13619 hardware floating point is used.
13621 @item -mwarn-framesize=@var{framesize}
13622 @opindex mwarn-framesize
13623 Emit a warning if the current function exceeds the given frame size. Because
13624 this is a compile time check it doesn't need to be a real problem when the program
13625 runs. It is intended to identify functions which most probably cause
13626 a stack overflow. It is useful to be used in an environment with limited stack
13627 size e.g.@: the linux kernel.
13629 @item -mwarn-dynamicstack
13630 @opindex mwarn-dynamicstack
13631 Emit a warning if the function calls alloca or uses dynamically
13632 sized arrays. This is generally a bad idea with a limited stack size.
13634 @item -mstack-guard=@var{stack-guard}
13635 @item -mstack-size=@var{stack-size}
13636 @opindex mstack-guard
13637 @opindex mstack-size
13638 If these options are provided the s390 back end emits additional instructions in
13639 the function prologue which trigger a trap if the stack size is @var{stack-guard}
13640 bytes above the @var{stack-size} (remember that the stack on s390 grows downward).
13641 If the @var{stack-guard} option is omitted the smallest power of 2 larger than
13642 the frame size of the compiled function is chosen.
13643 These options are intended to be used to help debugging stack overflow problems.
13644 The additionally emitted code causes only little overhead and hence can also be
13645 used in production like systems without greater performance degradation. The given
13646 values have to be exact powers of 2 and @var{stack-size} has to be greater than
13647 @var{stack-guard} without exceeding 64k.
13648 In order to be efficient the extra code makes the assumption that the stack starts
13649 at an address aligned to the value given by @var{stack-size}.
13650 The @var{stack-guard} option can only be used in conjunction with @var{stack-size}.
13653 @node Score Options
13654 @subsection Score Options
13655 @cindex Score Options
13657 These options are defined for Score implementations:
13662 Compile code for big endian mode. This is the default.
13666 Compile code for little endian mode.
13670 Disable generate bcnz instruction.
13674 Enable generate unaligned load and store instruction.
13678 Enable the use of multiply-accumulate instructions. Disabled by default.
13682 Specify the SCORE5 as the target architecture.
13686 Specify the SCORE5U of the target architecture.
13690 Specify the SCORE7 as the target architecture. This is the default.
13694 Specify the SCORE7D as the target architecture.
13698 @subsection SH Options
13700 These @samp{-m} options are defined for the SH implementations:
13705 Generate code for the SH1.
13709 Generate code for the SH2.
13712 Generate code for the SH2e.
13716 Generate code for the SH3.
13720 Generate code for the SH3e.
13724 Generate code for the SH4 without a floating-point unit.
13726 @item -m4-single-only
13727 @opindex m4-single-only
13728 Generate code for the SH4 with a floating-point unit that only
13729 supports single-precision arithmetic.
13733 Generate code for the SH4 assuming the floating-point unit is in
13734 single-precision mode by default.
13738 Generate code for the SH4.
13742 Generate code for the SH4al-dsp, or for a SH4a in such a way that the
13743 floating-point unit is not used.
13745 @item -m4a-single-only
13746 @opindex m4a-single-only
13747 Generate code for the SH4a, in such a way that no double-precision
13748 floating point operations are used.
13751 @opindex m4a-single
13752 Generate code for the SH4a assuming the floating-point unit is in
13753 single-precision mode by default.
13757 Generate code for the SH4a.
13761 Same as @option{-m4a-nofpu}, except that it implicitly passes
13762 @option{-dsp} to the assembler. GCC doesn't generate any DSP
13763 instructions at the moment.
13767 Compile code for the processor in big endian mode.
13771 Compile code for the processor in little endian mode.
13775 Align doubles at 64-bit boundaries. Note that this changes the calling
13776 conventions, and thus some functions from the standard C library will
13777 not work unless you recompile it first with @option{-mdalign}.
13781 Shorten some address references at link time, when possible; uses the
13782 linker option @option{-relax}.
13786 Use 32-bit offsets in @code{switch} tables. The default is to use
13791 Enable the use of the instruction @code{fmovd}.
13795 Comply with the calling conventions defined by Renesas.
13799 Comply with the calling conventions defined by Renesas.
13803 Comply with the calling conventions defined for GCC before the Renesas
13804 conventions were available. This option is the default for all
13805 targets of the SH toolchain except for @samp{sh-symbianelf}.
13808 @opindex mnomacsave
13809 Mark the @code{MAC} register as call-clobbered, even if
13810 @option{-mhitachi} is given.
13814 Increase IEEE-compliance of floating-point code.
13815 At the moment, this is equivalent to @option{-fno-finite-math-only}.
13816 When generating 16 bit SH opcodes, getting IEEE-conforming results for
13817 comparisons of NANs / infinities incurs extra overhead in every
13818 floating point comparison, therefore the default is set to
13819 @option{-ffinite-math-only}.
13821 @item -minline-ic_invalidate
13822 @opindex minline-ic_invalidate
13823 Inline code to invalidate instruction cache entries after setting up
13824 nested function trampolines.
13825 This option has no effect if -musermode is in effect and the selected
13826 code generation option (e.g. -m4) does not allow the use of the icbi
13828 If the selected code generation option does not allow the use of the icbi
13829 instruction, and -musermode is not in effect, the inlined code will
13830 manipulate the instruction cache address array directly with an associative
13831 write. This not only requires privileged mode, but it will also
13832 fail if the cache line had been mapped via the TLB and has become unmapped.
13836 Dump instruction size and location in the assembly code.
13839 @opindex mpadstruct
13840 This option is deprecated. It pads structures to multiple of 4 bytes,
13841 which is incompatible with the SH ABI@.
13845 Optimize for space instead of speed. Implied by @option{-Os}.
13848 @opindex mprefergot
13849 When generating position-independent code, emit function calls using
13850 the Global Offset Table instead of the Procedure Linkage Table.
13854 Don't generate privileged mode only code; implies -mno-inline-ic_invalidate
13855 if the inlined code would not work in user mode.
13856 This is the default when the target is @code{sh-*-linux*}.
13858 @item -multcost=@var{number}
13859 @opindex multcost=@var{number}
13860 Set the cost to assume for a multiply insn.
13862 @item -mdiv=@var{strategy}
13863 @opindex mdiv=@var{strategy}
13864 Set the division strategy to use for SHmedia code. @var{strategy} must be
13865 one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
13866 inv:call2, inv:fp .
13867 "fp" performs the operation in floating point. This has a very high latency,
13868 but needs only a few instructions, so it might be a good choice if
13869 your code has enough easily exploitable ILP to allow the compiler to
13870 schedule the floating point instructions together with other instructions.
13871 Division by zero causes a floating point exception.
13872 "inv" uses integer operations to calculate the inverse of the divisor,
13873 and then multiplies the dividend with the inverse. This strategy allows
13874 cse and hoisting of the inverse calculation. Division by zero calculates
13875 an unspecified result, but does not trap.
13876 "inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
13877 have been found, or if the entire operation has been hoisted to the same
13878 place, the last stages of the inverse calculation are intertwined with the
13879 final multiply to reduce the overall latency, at the expense of using a few
13880 more instructions, and thus offering fewer scheduling opportunities with
13882 "call" calls a library function that usually implements the inv:minlat
13884 This gives high code density for m5-*media-nofpu compilations.
13885 "call2" uses a different entry point of the same library function, where it
13886 assumes that a pointer to a lookup table has already been set up, which
13887 exposes the pointer load to cse / code hoisting optimizations.
13888 "inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
13889 code generation, but if the code stays unoptimized, revert to the "call",
13890 "call2", or "fp" strategies, respectively. Note that the
13891 potentially-trapping side effect of division by zero is carried by a
13892 separate instruction, so it is possible that all the integer instructions
13893 are hoisted out, but the marker for the side effect stays where it is.
13894 A recombination to fp operations or a call is not possible in that case.
13895 "inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
13896 that the inverse calculation was nor separated from the multiply, they speed
13897 up division where the dividend fits into 20 bits (plus sign where applicable),
13898 by inserting a test to skip a number of operations in this case; this test
13899 slows down the case of larger dividends. inv20u assumes the case of a such
13900 a small dividend to be unlikely, and inv20l assumes it to be likely.
13902 @item -mdivsi3_libfunc=@var{name}
13903 @opindex mdivsi3_libfunc=@var{name}
13904 Set the name of the library function used for 32 bit signed division to
13905 @var{name}. This only affect the name used in the call and inv:call
13906 division strategies, and the compiler will still expect the same
13907 sets of input/output/clobbered registers as if this option was not present.
13909 @item -madjust-unroll
13910 @opindex madjust-unroll
13911 Throttle unrolling to avoid thrashing target registers.
13912 This option only has an effect if the gcc code base supports the
13913 TARGET_ADJUST_UNROLL_MAX target hook.
13915 @item -mindexed-addressing
13916 @opindex mindexed-addressing
13917 Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
13918 This is only safe if the hardware and/or OS implement 32 bit wrap-around
13919 semantics for the indexed addressing mode. The architecture allows the
13920 implementation of processors with 64 bit MMU, which the OS could use to
13921 get 32 bit addressing, but since no current hardware implementation supports
13922 this or any other way to make the indexed addressing mode safe to use in
13923 the 32 bit ABI, the default is -mno-indexed-addressing.
13925 @item -mgettrcost=@var{number}
13926 @opindex mgettrcost=@var{number}
13927 Set the cost assumed for the gettr instruction to @var{number}.
13928 The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
13932 Assume pt* instructions won't trap. This will generally generate better
13933 scheduled code, but is unsafe on current hardware. The current architecture
13934 definition says that ptabs and ptrel trap when the target anded with 3 is 3.
13935 This has the unintentional effect of making it unsafe to schedule ptabs /
13936 ptrel before a branch, or hoist it out of a loop. For example,
13937 __do_global_ctors, a part of libgcc that runs constructors at program
13938 startup, calls functions in a list which is delimited by @minus{}1. With the
13939 -mpt-fixed option, the ptabs will be done before testing against @minus{}1.
13940 That means that all the constructors will be run a bit quicker, but when
13941 the loop comes to the end of the list, the program crashes because ptabs
13942 loads @minus{}1 into a target register. Since this option is unsafe for any
13943 hardware implementing the current architecture specification, the default
13944 is -mno-pt-fixed. Unless the user specifies a specific cost with
13945 @option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
13946 this deters register allocation using target registers for storing
13949 @item -minvalid-symbols
13950 @opindex minvalid-symbols
13951 Assume symbols might be invalid. Ordinary function symbols generated by
13952 the compiler will always be valid to load with movi/shori/ptabs or
13953 movi/shori/ptrel, but with assembler and/or linker tricks it is possible
13954 to generate symbols that will cause ptabs / ptrel to trap.
13955 This option is only meaningful when @option{-mno-pt-fixed} is in effect.
13956 It will then prevent cross-basic-block cse, hoisting and most scheduling
13957 of symbol loads. The default is @option{-mno-invalid-symbols}.
13960 @node SPARC Options
13961 @subsection SPARC Options
13962 @cindex SPARC options
13964 These @samp{-m} options are supported on the SPARC:
13967 @item -mno-app-regs
13969 @opindex mno-app-regs
13971 Specify @option{-mapp-regs} to generate output using the global registers
13972 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
13975 To be fully SVR4 ABI compliant at the cost of some performance loss,
13976 specify @option{-mno-app-regs}. You should compile libraries and system
13977 software with this option.
13980 @itemx -mhard-float
13982 @opindex mhard-float
13983 Generate output containing floating point instructions. This is the
13987 @itemx -msoft-float
13989 @opindex msoft-float
13990 Generate output containing library calls for floating point.
13991 @strong{Warning:} the requisite libraries are not available for all SPARC
13992 targets. Normally the facilities of the machine's usual C compiler are
13993 used, but this cannot be done directly in cross-compilation. You must make
13994 your own arrangements to provide suitable library functions for
13995 cross-compilation. The embedded targets @samp{sparc-*-aout} and
13996 @samp{sparclite-*-*} do provide software floating point support.
13998 @option{-msoft-float} changes the calling convention in the output file;
13999 therefore, it is only useful if you compile @emph{all} of a program with
14000 this option. In particular, you need to compile @file{libgcc.a}, the
14001 library that comes with GCC, with @option{-msoft-float} in order for
14004 @item -mhard-quad-float
14005 @opindex mhard-quad-float
14006 Generate output containing quad-word (long double) floating point
14009 @item -msoft-quad-float
14010 @opindex msoft-quad-float
14011 Generate output containing library calls for quad-word (long double)
14012 floating point instructions. The functions called are those specified
14013 in the SPARC ABI@. This is the default.
14015 As of this writing, there are no SPARC implementations that have hardware
14016 support for the quad-word floating point instructions. They all invoke
14017 a trap handler for one of these instructions, and then the trap handler
14018 emulates the effect of the instruction. Because of the trap handler overhead,
14019 this is much slower than calling the ABI library routines. Thus the
14020 @option{-msoft-quad-float} option is the default.
14022 @item -mno-unaligned-doubles
14023 @itemx -munaligned-doubles
14024 @opindex mno-unaligned-doubles
14025 @opindex munaligned-doubles
14026 Assume that doubles have 8 byte alignment. This is the default.
14028 With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
14029 alignment only if they are contained in another type, or if they have an
14030 absolute address. Otherwise, it assumes they have 4 byte alignment.
14031 Specifying this option avoids some rare compatibility problems with code
14032 generated by other compilers. It is not the default because it results
14033 in a performance loss, especially for floating point code.
14035 @item -mno-faster-structs
14036 @itemx -mfaster-structs
14037 @opindex mno-faster-structs
14038 @opindex mfaster-structs
14039 With @option{-mfaster-structs}, the compiler assumes that structures
14040 should have 8 byte alignment. This enables the use of pairs of
14041 @code{ldd} and @code{std} instructions for copies in structure
14042 assignment, in place of twice as many @code{ld} and @code{st} pairs.
14043 However, the use of this changed alignment directly violates the SPARC
14044 ABI@. Thus, it's intended only for use on targets where the developer
14045 acknowledges that their resulting code will not be directly in line with
14046 the rules of the ABI@.
14048 @item -mimpure-text
14049 @opindex mimpure-text
14050 @option{-mimpure-text}, used in addition to @option{-shared}, tells
14051 the compiler to not pass @option{-z text} to the linker when linking a
14052 shared object. Using this option, you can link position-dependent
14053 code into a shared object.
14055 @option{-mimpure-text} suppresses the ``relocations remain against
14056 allocatable but non-writable sections'' linker error message.
14057 However, the necessary relocations will trigger copy-on-write, and the
14058 shared object is not actually shared across processes. Instead of
14059 using @option{-mimpure-text}, you should compile all source code with
14060 @option{-fpic} or @option{-fPIC}.
14062 This option is only available on SunOS and Solaris.
14064 @item -mcpu=@var{cpu_type}
14066 Set the instruction set, register set, and instruction scheduling parameters
14067 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
14068 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
14069 @samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
14070 @samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
14071 @samp{ultrasparc3}, @samp{niagara} and @samp{niagara2}.
14073 Default instruction scheduling parameters are used for values that select
14074 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
14075 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
14077 Here is a list of each supported architecture and their supported
14082 v8: supersparc, hypersparc
14083 sparclite: f930, f934, sparclite86x
14085 v9: ultrasparc, ultrasparc3, niagara, niagara2
14088 By default (unless configured otherwise), GCC generates code for the V7
14089 variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
14090 additionally optimizes it for the Cypress CY7C602 chip, as used in the
14091 SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
14092 SPARCStation 1, 2, IPX etc.
14094 With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
14095 architecture. The only difference from V7 code is that the compiler emits
14096 the integer multiply and integer divide instructions which exist in SPARC-V8
14097 but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
14098 optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
14101 With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
14102 the SPARC architecture. This adds the integer multiply, integer divide step
14103 and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
14104 With @option{-mcpu=f930}, the compiler additionally optimizes it for the
14105 Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
14106 @option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
14107 MB86934 chip, which is the more recent SPARClite with FPU@.
14109 With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
14110 the SPARC architecture. This adds the integer multiply, multiply/accumulate,
14111 integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
14112 but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
14113 optimizes it for the TEMIC SPARClet chip.
14115 With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
14116 architecture. This adds 64-bit integer and floating-point move instructions,
14117 3 additional floating-point condition code registers and conditional move
14118 instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
14119 optimizes it for the Sun UltraSPARC I/II/IIi chips. With
14120 @option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
14121 Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
14122 @option{-mcpu=niagara}, the compiler additionally optimizes it for
14123 Sun UltraSPARC T1 chips. With @option{-mcpu=niagara2}, the compiler
14124 additionally optimizes it for Sun UltraSPARC T2 chips.
14126 @item -mtune=@var{cpu_type}
14128 Set the instruction scheduling parameters for machine type
14129 @var{cpu_type}, but do not set the instruction set or register set that the
14130 option @option{-mcpu=@var{cpu_type}} would.
14132 The same values for @option{-mcpu=@var{cpu_type}} can be used for
14133 @option{-mtune=@var{cpu_type}}, but the only useful values are those
14134 that select a particular cpu implementation. Those are @samp{cypress},
14135 @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
14136 @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
14137 @samp{ultrasparc3}, @samp{niagara}, and @samp{niagara2}.
14142 @opindex mno-v8plus
14143 With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
14144 difference from the V8 ABI is that the global and out registers are
14145 considered 64-bit wide. This is enabled by default on Solaris in 32-bit
14146 mode for all SPARC-V9 processors.
14152 With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
14153 Visual Instruction Set extensions. The default is @option{-mno-vis}.
14156 These @samp{-m} options are supported in addition to the above
14157 on SPARC-V9 processors in 64-bit environments:
14160 @item -mlittle-endian
14161 @opindex mlittle-endian
14162 Generate code for a processor running in little-endian mode. It is only
14163 available for a few configurations and most notably not on Solaris and Linux.
14169 Generate code for a 32-bit or 64-bit environment.
14170 The 32-bit environment sets int, long and pointer to 32 bits.
14171 The 64-bit environment sets int to 32 bits and long and pointer
14174 @item -mcmodel=medlow
14175 @opindex mcmodel=medlow
14176 Generate code for the Medium/Low code model: 64-bit addresses, programs
14177 must be linked in the low 32 bits of memory. Programs can be statically
14178 or dynamically linked.
14180 @item -mcmodel=medmid
14181 @opindex mcmodel=medmid
14182 Generate code for the Medium/Middle code model: 64-bit addresses, programs
14183 must be linked in the low 44 bits of memory, the text and data segments must
14184 be less than 2GB in size and the data segment must be located within 2GB of
14187 @item -mcmodel=medany
14188 @opindex mcmodel=medany
14189 Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
14190 may be linked anywhere in memory, the text and data segments must be less
14191 than 2GB in size and the data segment must be located within 2GB of the
14194 @item -mcmodel=embmedany
14195 @opindex mcmodel=embmedany
14196 Generate code for the Medium/Anywhere code model for embedded systems:
14197 64-bit addresses, the text and data segments must be less than 2GB in
14198 size, both starting anywhere in memory (determined at link time). The
14199 global register %g4 points to the base of the data segment. Programs
14200 are statically linked and PIC is not supported.
14203 @itemx -mno-stack-bias
14204 @opindex mstack-bias
14205 @opindex mno-stack-bias
14206 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
14207 frame pointer if present, are offset by @minus{}2047 which must be added back
14208 when making stack frame references. This is the default in 64-bit mode.
14209 Otherwise, assume no such offset is present.
14212 These switches are supported in addition to the above on Solaris:
14217 Add support for multithreading using the Solaris threads library. This
14218 option sets flags for both the preprocessor and linker. This option does
14219 not affect the thread safety of object code produced by the compiler or
14220 that of libraries supplied with it.
14224 Add support for multithreading using the POSIX threads library. This
14225 option sets flags for both the preprocessor and linker. This option does
14226 not affect the thread safety of object code produced by the compiler or
14227 that of libraries supplied with it.
14231 This is a synonym for @option{-pthreads}.
14235 @subsection SPU Options
14236 @cindex SPU options
14238 These @samp{-m} options are supported on the SPU:
14242 @itemx -merror-reloc
14243 @opindex mwarn-reloc
14244 @opindex merror-reloc
14246 The loader for SPU does not handle dynamic relocations. By default, GCC
14247 will give an error when it generates code that requires a dynamic
14248 relocation. @option{-mno-error-reloc} disables the error,
14249 @option{-mwarn-reloc} will generate a warning instead.
14252 @itemx -munsafe-dma
14254 @opindex munsafe-dma
14256 Instructions which initiate or test completion of DMA must not be
14257 reordered with respect to loads and stores of the memory which is being
14258 accessed. Users typically address this problem using the volatile
14259 keyword, but that can lead to inefficient code in places where the
14260 memory is known to not change. Rather than mark the memory as volatile
14261 we treat the DMA instructions as potentially effecting all memory. With
14262 @option{-munsafe-dma} users must use the volatile keyword to protect
14265 @item -mbranch-hints
14266 @opindex mbranch-hints
14268 By default, GCC will generate a branch hint instruction to avoid
14269 pipeline stalls for always taken or probably taken branches. A hint
14270 will not be generated closer than 8 instructions away from its branch.
14271 There is little reason to disable them, except for debugging purposes,
14272 or to make an object a little bit smaller.
14276 @opindex msmall-mem
14277 @opindex mlarge-mem
14279 By default, GCC generates code assuming that addresses are never larger
14280 than 18 bits. With @option{-mlarge-mem} code is generated that assumes
14281 a full 32 bit address.
14286 By default, GCC links against startup code that assumes the SPU-style
14287 main function interface (which has an unconventional parameter list).
14288 With @option{-mstdmain}, GCC will link your program against startup
14289 code that assumes a C99-style interface to @code{main}, including a
14290 local copy of @code{argv} strings.
14292 @item -mfixed-range=@var{register-range}
14293 @opindex mfixed-range
14294 Generate code treating the given register range as fixed registers.
14295 A fixed register is one that the register allocator can not use. This is
14296 useful when compiling kernel code. A register range is specified as
14297 two registers separated by a dash. Multiple register ranges can be
14298 specified separated by a comma.
14302 @node System V Options
14303 @subsection Options for System V
14305 These additional options are available on System V Release 4 for
14306 compatibility with other compilers on those systems:
14311 Create a shared object.
14312 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
14316 Identify the versions of each tool used by the compiler, in a
14317 @code{.ident} assembler directive in the output.
14321 Refrain from adding @code{.ident} directives to the output file (this is
14324 @item -YP,@var{dirs}
14326 Search the directories @var{dirs}, and no others, for libraries
14327 specified with @option{-l}.
14329 @item -Ym,@var{dir}
14331 Look in the directory @var{dir} to find the M4 preprocessor.
14332 The assembler uses this option.
14333 @c This is supposed to go with a -Yd for predefined M4 macro files, but
14334 @c the generic assembler that comes with Solaris takes just -Ym.
14337 @node TMS320C3x/C4x Options
14338 @subsection TMS320C3x/C4x Options
14339 @cindex TMS320C3x/C4x Options
14341 These @samp{-m} options are defined for TMS320C3x/C4x implementations:
14345 @item -mcpu=@var{cpu_type}
14347 Set the instruction set, register set, and instruction scheduling
14348 parameters for machine type @var{cpu_type}. Supported values for
14349 @var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
14350 @samp{c44}. The default is @samp{c40} to generate code for the
14355 @itemx -msmall-memory
14357 @opindex mbig-memory
14359 @opindex msmall-memory
14361 Generates code for the big or small memory model. The small memory
14362 model assumed that all data fits into one 64K word page. At run-time
14363 the data page (DP) register must be set to point to the 64K page
14364 containing the .bss and .data program sections. The big memory model is
14365 the default and requires reloading of the DP register for every direct
14372 Allow (disallow) allocation of general integer operands into the block
14373 count register BK@.
14379 Enable (disable) generation of code using decrement and branch,
14380 DBcond(D), instructions. This is enabled by default for the C4x. To be
14381 on the safe side, this is disabled for the C3x, since the maximum
14382 iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
14383 @math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
14384 that it can utilize the decrement and branch instruction, but will give
14385 up if there is more than one memory reference in the loop. Thus a loop
14386 where the loop counter is decremented can generate slightly more
14387 efficient code, in cases where the RPTB instruction cannot be utilized.
14389 @item -mdp-isr-reload
14391 @opindex mdp-isr-reload
14393 Force the DP register to be saved on entry to an interrupt service
14394 routine (ISR), reloaded to point to the data section, and restored on
14395 exit from the ISR@. This should not be required unless someone has
14396 violated the small memory model by modifying the DP register, say within
14403 For the C3x use the 24-bit MPYI instruction for integer multiplies
14404 instead of a library call to guarantee 32-bit results. Note that if one
14405 of the operands is a constant, then the multiplication will be performed
14406 using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
14407 then squaring operations are performed inline instead of a library call.
14410 @itemx -mno-fast-fix
14412 @opindex mno-fast-fix
14413 The C3x/C4x FIX instruction to convert a floating point value to an
14414 integer value chooses the nearest integer less than or equal to the
14415 floating point value rather than to the nearest integer. Thus if the
14416 floating point number is negative, the result will be incorrectly
14417 truncated an additional code is necessary to detect and correct this
14418 case. This option can be used to disable generation of the additional
14419 code required to correct the result.
14425 Enable (disable) generation of repeat block sequences using the RPTB
14426 instruction for zero overhead looping. The RPTB construct is only used
14427 for innermost loops that do not call functions or jump across the loop
14428 boundaries. There is no advantage having nested RPTB loops due to the
14429 overhead required to save and restore the RC, RS, and RE registers.
14430 This is enabled by default with @option{-O2}.
14432 @item -mrpts=@var{count}
14436 Enable (disable) the use of the single instruction repeat instruction
14437 RPTS@. If a repeat block contains a single instruction, and the loop
14438 count can be guaranteed to be less than the value @var{count}, GCC will
14439 emit a RPTS instruction instead of a RPTB@. If no value is specified,
14440 then a RPTS will be emitted even if the loop count cannot be determined
14441 at compile time. Note that the repeated instruction following RPTS does
14442 not have to be reloaded from memory each iteration, thus freeing up the
14443 CPU buses for operands. However, since interrupts are blocked by this
14444 instruction, it is disabled by default.
14446 @item -mloop-unsigned
14447 @itemx -mno-loop-unsigned
14448 @opindex mloop-unsigned
14449 @opindex mno-loop-unsigned
14450 The maximum iteration count when using RPTS and RPTB (and DB on the C40)
14451 is @math{2^{31} + 1} since these instructions test if the iteration count is
14452 negative to terminate the loop. If the iteration count is unsigned
14453 there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
14454 exceeded. This switch allows an unsigned iteration count.
14458 Try to emit an assembler syntax that the TI assembler (asm30) is happy
14459 with. This also enforces compatibility with the API employed by the TI
14460 C3x C compiler. For example, long doubles are passed as structures
14461 rather than in floating point registers.
14467 Generate code that uses registers (stack) for passing arguments to functions.
14468 By default, arguments are passed in registers where possible rather
14469 than by pushing arguments on to the stack.
14471 @item -mparallel-insns
14472 @itemx -mno-parallel-insns
14473 @opindex mparallel-insns
14474 @opindex mno-parallel-insns
14475 Allow the generation of parallel instructions. This is enabled by
14476 default with @option{-O2}.
14478 @item -mparallel-mpy
14479 @itemx -mno-parallel-mpy
14480 @opindex mparallel-mpy
14481 @opindex mno-parallel-mpy
14482 Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
14483 provided @option{-mparallel-insns} is also specified. These instructions have
14484 tight register constraints which can pessimize the code generation
14485 of large functions.
14490 @subsection V850 Options
14491 @cindex V850 Options
14493 These @samp{-m} options are defined for V850 implementations:
14497 @itemx -mno-long-calls
14498 @opindex mlong-calls
14499 @opindex mno-long-calls
14500 Treat all calls as being far away (near). If calls are assumed to be
14501 far away, the compiler will always load the functions address up into a
14502 register, and call indirect through the pointer.
14508 Do not optimize (do optimize) basic blocks that use the same index
14509 pointer 4 or more times to copy pointer into the @code{ep} register, and
14510 use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
14511 option is on by default if you optimize.
14513 @item -mno-prolog-function
14514 @itemx -mprolog-function
14515 @opindex mno-prolog-function
14516 @opindex mprolog-function
14517 Do not use (do use) external functions to save and restore registers
14518 at the prologue and epilogue of a function. The external functions
14519 are slower, but use less code space if more than one function saves
14520 the same number of registers. The @option{-mprolog-function} option
14521 is on by default if you optimize.
14525 Try to make the code as small as possible. At present, this just turns
14526 on the @option{-mep} and @option{-mprolog-function} options.
14528 @item -mtda=@var{n}
14530 Put static or global variables whose size is @var{n} bytes or less into
14531 the tiny data area that register @code{ep} points to. The tiny data
14532 area can hold up to 256 bytes in total (128 bytes for byte references).
14534 @item -msda=@var{n}
14536 Put static or global variables whose size is @var{n} bytes or less into
14537 the small data area that register @code{gp} points to. The small data
14538 area can hold up to 64 kilobytes.
14540 @item -mzda=@var{n}
14542 Put static or global variables whose size is @var{n} bytes or less into
14543 the first 32 kilobytes of memory.
14547 Specify that the target processor is the V850.
14550 @opindex mbig-switch
14551 Generate code suitable for big switch tables. Use this option only if
14552 the assembler/linker complain about out of range branches within a switch
14557 This option will cause r2 and r5 to be used in the code generated by
14558 the compiler. This setting is the default.
14560 @item -mno-app-regs
14561 @opindex mno-app-regs
14562 This option will cause r2 and r5 to be treated as fixed registers.
14566 Specify that the target processor is the V850E1. The preprocessor
14567 constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
14568 this option is used.
14572 Specify that the target processor is the V850E@. The preprocessor
14573 constant @samp{__v850e__} will be defined if this option is used.
14575 If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
14576 are defined then a default target processor will be chosen and the
14577 relevant @samp{__v850*__} preprocessor constant will be defined.
14579 The preprocessor constants @samp{__v850} and @samp{__v851__} are always
14580 defined, regardless of which processor variant is the target.
14582 @item -mdisable-callt
14583 @opindex mdisable-callt
14584 This option will suppress generation of the CALLT instruction for the
14585 v850e and v850e1 flavors of the v850 architecture. The default is
14586 @option{-mno-disable-callt} which allows the CALLT instruction to be used.
14591 @subsection VAX Options
14592 @cindex VAX options
14594 These @samp{-m} options are defined for the VAX:
14599 Do not output certain jump instructions (@code{aobleq} and so on)
14600 that the Unix assembler for the VAX cannot handle across long
14605 Do output those jump instructions, on the assumption that you
14606 will assemble with the GNU assembler.
14610 Output code for g-format floating point numbers instead of d-format.
14613 @node VxWorks Options
14614 @subsection VxWorks Options
14615 @cindex VxWorks Options
14617 The options in this section are defined for all VxWorks targets.
14618 Options specific to the target hardware are listed with the other
14619 options for that target.
14624 GCC can generate code for both VxWorks kernels and real time processes
14625 (RTPs). This option switches from the former to the latter. It also
14626 defines the preprocessor macro @code{__RTP__}.
14629 @opindex non-static
14630 Link an RTP executable against shared libraries rather than static
14631 libraries. The options @option{-static} and @option{-shared} can
14632 also be used for RTPs (@pxref{Link Options}); @option{-static}
14639 These options are passed down to the linker. They are defined for
14640 compatibility with Diab.
14643 @opindex Xbind-lazy
14644 Enable lazy binding of function calls. This option is equivalent to
14645 @option{-Wl,-z,now} and is defined for compatibility with Diab.
14649 Disable lazy binding of function calls. This option is the default and
14650 is defined for compatibility with Diab.
14653 @node x86-64 Options
14654 @subsection x86-64 Options
14655 @cindex x86-64 options
14657 These are listed under @xref{i386 and x86-64 Options}.
14659 @node Xstormy16 Options
14660 @subsection Xstormy16 Options
14661 @cindex Xstormy16 Options
14663 These options are defined for Xstormy16:
14668 Choose startup files and linker script suitable for the simulator.
14671 @node Xtensa Options
14672 @subsection Xtensa Options
14673 @cindex Xtensa Options
14675 These options are supported for Xtensa targets:
14679 @itemx -mno-const16
14681 @opindex mno-const16
14682 Enable or disable use of @code{CONST16} instructions for loading
14683 constant values. The @code{CONST16} instruction is currently not a
14684 standard option from Tensilica. When enabled, @code{CONST16}
14685 instructions are always used in place of the standard @code{L32R}
14686 instructions. The use of @code{CONST16} is enabled by default only if
14687 the @code{L32R} instruction is not available.
14690 @itemx -mno-fused-madd
14691 @opindex mfused-madd
14692 @opindex mno-fused-madd
14693 Enable or disable use of fused multiply/add and multiply/subtract
14694 instructions in the floating-point option. This has no effect if the
14695 floating-point option is not also enabled. Disabling fused multiply/add
14696 and multiply/subtract instructions forces the compiler to use separate
14697 instructions for the multiply and add/subtract operations. This may be
14698 desirable in some cases where strict IEEE 754-compliant results are
14699 required: the fused multiply add/subtract instructions do not round the
14700 intermediate result, thereby producing results with @emph{more} bits of
14701 precision than specified by the IEEE standard. Disabling fused multiply
14702 add/subtract instructions also ensures that the program output is not
14703 sensitive to the compiler's ability to combine multiply and add/subtract
14706 @item -mtext-section-literals
14707 @itemx -mno-text-section-literals
14708 @opindex mtext-section-literals
14709 @opindex mno-text-section-literals
14710 Control the treatment of literal pools. The default is
14711 @option{-mno-text-section-literals}, which places literals in a separate
14712 section in the output file. This allows the literal pool to be placed
14713 in a data RAM/ROM, and it also allows the linker to combine literal
14714 pools from separate object files to remove redundant literals and
14715 improve code size. With @option{-mtext-section-literals}, the literals
14716 are interspersed in the text section in order to keep them as close as
14717 possible to their references. This may be necessary for large assembly
14720 @item -mtarget-align
14721 @itemx -mno-target-align
14722 @opindex mtarget-align
14723 @opindex mno-target-align
14724 When this option is enabled, GCC instructs the assembler to
14725 automatically align instructions to reduce branch penalties at the
14726 expense of some code density. The assembler attempts to widen density
14727 instructions to align branch targets and the instructions following call
14728 instructions. If there are not enough preceding safe density
14729 instructions to align a target, no widening will be performed. The
14730 default is @option{-mtarget-align}. These options do not affect the
14731 treatment of auto-aligned instructions like @code{LOOP}, which the
14732 assembler will always align, either by widening density instructions or
14733 by inserting no-op instructions.
14736 @itemx -mno-longcalls
14737 @opindex mlongcalls
14738 @opindex mno-longcalls
14739 When this option is enabled, GCC instructs the assembler to translate
14740 direct calls to indirect calls unless it can determine that the target
14741 of a direct call is in the range allowed by the call instruction. This
14742 translation typically occurs for calls to functions in other source
14743 files. Specifically, the assembler translates a direct @code{CALL}
14744 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
14745 The default is @option{-mno-longcalls}. This option should be used in
14746 programs where the call target can potentially be out of range. This
14747 option is implemented in the assembler, not the compiler, so the
14748 assembly code generated by GCC will still show direct call
14749 instructions---look at the disassembled object code to see the actual
14750 instructions. Note that the assembler will use an indirect call for
14751 every cross-file call, not just those that really will be out of range.
14754 @node zSeries Options
14755 @subsection zSeries Options
14756 @cindex zSeries options
14758 These are listed under @xref{S/390 and zSeries Options}.
14760 @node Code Gen Options
14761 @section Options for Code Generation Conventions
14762 @cindex code generation conventions
14763 @cindex options, code generation
14764 @cindex run-time options
14766 These machine-independent options control the interface conventions
14767 used in code generation.
14769 Most of them have both positive and negative forms; the negative form
14770 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
14771 one of the forms is listed---the one which is not the default. You
14772 can figure out the other form by either removing @samp{no-} or adding
14776 @item -fbounds-check
14777 @opindex fbounds-check
14778 For front-ends that support it, generate additional code to check that
14779 indices used to access arrays are within the declared range. This is
14780 currently only supported by the Java and Fortran front-ends, where
14781 this option defaults to true and false respectively.
14785 This option generates traps for signed overflow on addition, subtraction,
14786 multiplication operations.
14790 This option instructs the compiler to assume that signed arithmetic
14791 overflow of addition, subtraction and multiplication wraps around
14792 using twos-complement representation. This flag enables some optimizations
14793 and disables others. This option is enabled by default for the Java
14794 front-end, as required by the Java language specification.
14797 @opindex fexceptions
14798 Enable exception handling. Generates extra code needed to propagate
14799 exceptions. For some targets, this implies GCC will generate frame
14800 unwind information for all functions, which can produce significant data
14801 size overhead, although it does not affect execution. If you do not
14802 specify this option, GCC will enable it by default for languages like
14803 C++ which normally require exception handling, and disable it for
14804 languages like C that do not normally require it. However, you may need
14805 to enable this option when compiling C code that needs to interoperate
14806 properly with exception handlers written in C++. You may also wish to
14807 disable this option if you are compiling older C++ programs that don't
14808 use exception handling.
14810 @item -fnon-call-exceptions
14811 @opindex fnon-call-exceptions
14812 Generate code that allows trapping instructions to throw exceptions.
14813 Note that this requires platform-specific runtime support that does
14814 not exist everywhere. Moreover, it only allows @emph{trapping}
14815 instructions to throw exceptions, i.e.@: memory references or floating
14816 point instructions. It does not allow exceptions to be thrown from
14817 arbitrary signal handlers such as @code{SIGALRM}.
14819 @item -funwind-tables
14820 @opindex funwind-tables
14821 Similar to @option{-fexceptions}, except that it will just generate any needed
14822 static data, but will not affect the generated code in any other way.
14823 You will normally not enable this option; instead, a language processor
14824 that needs this handling would enable it on your behalf.
14826 @item -fasynchronous-unwind-tables
14827 @opindex fasynchronous-unwind-tables
14828 Generate unwind table in dwarf2 format, if supported by target machine. The
14829 table is exact at each instruction boundary, so it can be used for stack
14830 unwinding from asynchronous events (such as debugger or garbage collector).
14832 @item -fpcc-struct-return
14833 @opindex fpcc-struct-return
14834 Return ``short'' @code{struct} and @code{union} values in memory like
14835 longer ones, rather than in registers. This convention is less
14836 efficient, but it has the advantage of allowing intercallability between
14837 GCC-compiled files and files compiled with other compilers, particularly
14838 the Portable C Compiler (pcc).
14840 The precise convention for returning structures in memory depends
14841 on the target configuration macros.
14843 Short structures and unions are those whose size and alignment match
14844 that of some integer type.
14846 @strong{Warning:} code compiled with the @option{-fpcc-struct-return}
14847 switch is not binary compatible with code compiled with the
14848 @option{-freg-struct-return} switch.
14849 Use it to conform to a non-default application binary interface.
14851 @item -freg-struct-return
14852 @opindex freg-struct-return
14853 Return @code{struct} and @code{union} values in registers when possible.
14854 This is more efficient for small structures than
14855 @option{-fpcc-struct-return}.
14857 If you specify neither @option{-fpcc-struct-return} nor
14858 @option{-freg-struct-return}, GCC defaults to whichever convention is
14859 standard for the target. If there is no standard convention, GCC
14860 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
14861 the principal compiler. In those cases, we can choose the standard, and
14862 we chose the more efficient register return alternative.
14864 @strong{Warning:} code compiled with the @option{-freg-struct-return}
14865 switch is not binary compatible with code compiled with the
14866 @option{-fpcc-struct-return} switch.
14867 Use it to conform to a non-default application binary interface.
14869 @item -fshort-enums
14870 @opindex fshort-enums
14871 Allocate to an @code{enum} type only as many bytes as it needs for the
14872 declared range of possible values. Specifically, the @code{enum} type
14873 will be equivalent to the smallest integer type which has enough room.
14875 @strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
14876 code that is not binary compatible with code generated without that switch.
14877 Use it to conform to a non-default application binary interface.
14879 @item -fshort-double
14880 @opindex fshort-double
14881 Use the same size for @code{double} as for @code{float}.
14883 @strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
14884 code that is not binary compatible with code generated without that switch.
14885 Use it to conform to a non-default application binary interface.
14887 @item -fshort-wchar
14888 @opindex fshort-wchar
14889 Override the underlying type for @samp{wchar_t} to be @samp{short
14890 unsigned int} instead of the default for the target. This option is
14891 useful for building programs to run under WINE@.
14893 @strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
14894 code that is not binary compatible with code generated without that switch.
14895 Use it to conform to a non-default application binary interface.
14898 @opindex fno-common
14899 In C, allocate even uninitialized global variables in the data section of the
14900 object file, rather than generating them as common blocks. This has the
14901 effect that if the same variable is declared (without @code{extern}) in
14902 two different compilations, you will get an error when you link them.
14903 The only reason this might be useful is if you wish to verify that the
14904 program will work on other systems which always work this way.
14908 Ignore the @samp{#ident} directive.
14910 @item -finhibit-size-directive
14911 @opindex finhibit-size-directive
14912 Don't output a @code{.size} assembler directive, or anything else that
14913 would cause trouble if the function is split in the middle, and the
14914 two halves are placed at locations far apart in memory. This option is
14915 used when compiling @file{crtstuff.c}; you should not need to use it
14918 @item -fverbose-asm
14919 @opindex fverbose-asm
14920 Put extra commentary information in the generated assembly code to
14921 make it more readable. This option is generally only of use to those
14922 who actually need to read the generated assembly code (perhaps while
14923 debugging the compiler itself).
14925 @option{-fno-verbose-asm}, the default, causes the
14926 extra information to be omitted and is useful when comparing two assembler
14929 @item -frecord-gcc-switches
14930 @opindex frecord-gcc-switches
14931 This switch causes the command line that was used to invoke the
14932 compiler to be recorded into the object file that is being created.
14933 This switch is only implemented on some targets and the exact format
14934 of the recording is target and binary file format dependent, but it
14935 usually takes the form of a section containing ASCII text. This
14936 switch is related to the @option{-fverbose-asm} switch, but that
14937 switch only records information in the assembler output file as
14938 comments, so it never reaches the object file.
14942 @cindex global offset table
14944 Generate position-independent code (PIC) suitable for use in a shared
14945 library, if supported for the target machine. Such code accesses all
14946 constant addresses through a global offset table (GOT)@. The dynamic
14947 loader resolves the GOT entries when the program starts (the dynamic
14948 loader is not part of GCC; it is part of the operating system). If
14949 the GOT size for the linked executable exceeds a machine-specific
14950 maximum size, you get an error message from the linker indicating that
14951 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
14952 instead. (These maximums are 8k on the SPARC and 32k
14953 on the m68k and RS/6000. The 386 has no such limit.)
14955 Position-independent code requires special support, and therefore works
14956 only on certain machines. For the 386, GCC supports PIC for System V
14957 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
14958 position-independent.
14960 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
14965 If supported for the target machine, emit position-independent code,
14966 suitable for dynamic linking and avoiding any limit on the size of the
14967 global offset table. This option makes a difference on the m68k,
14968 PowerPC and SPARC@.
14970 Position-independent code requires special support, and therefore works
14971 only on certain machines.
14973 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
14980 These options are similar to @option{-fpic} and @option{-fPIC}, but
14981 generated position independent code can be only linked into executables.
14982 Usually these options are used when @option{-pie} GCC option will be
14983 used during linking.
14985 @option{-fpie} and @option{-fPIE} both define the macros
14986 @code{__pie__} and @code{__PIE__}. The macros have the value 1
14987 for @option{-fpie} and 2 for @option{-fPIE}.
14989 @item -fno-jump-tables
14990 @opindex fno-jump-tables
14991 Do not use jump tables for switch statements even where it would be
14992 more efficient than other code generation strategies. This option is
14993 of use in conjunction with @option{-fpic} or @option{-fPIC} for
14994 building code which forms part of a dynamic linker and cannot
14995 reference the address of a jump table. On some targets, jump tables
14996 do not require a GOT and this option is not needed.
14998 @item -ffixed-@var{reg}
15000 Treat the register named @var{reg} as a fixed register; generated code
15001 should never refer to it (except perhaps as a stack pointer, frame
15002 pointer or in some other fixed role).
15004 @var{reg} must be the name of a register. The register names accepted
15005 are machine-specific and are defined in the @code{REGISTER_NAMES}
15006 macro in the machine description macro file.
15008 This flag does not have a negative form, because it specifies a
15011 @item -fcall-used-@var{reg}
15012 @opindex fcall-used
15013 Treat the register named @var{reg} as an allocable register that is
15014 clobbered by function calls. It may be allocated for temporaries or
15015 variables that do not live across a call. Functions compiled this way
15016 will not save and restore the register @var{reg}.
15018 It is an error to used this flag with the frame pointer or stack pointer.
15019 Use of this flag for other registers that have fixed pervasive roles in
15020 the machine's execution model will produce disastrous results.
15022 This flag does not have a negative form, because it specifies a
15025 @item -fcall-saved-@var{reg}
15026 @opindex fcall-saved
15027 Treat the register named @var{reg} as an allocable register saved by
15028 functions. It may be allocated even for temporaries or variables that
15029 live across a call. Functions compiled this way will save and restore
15030 the register @var{reg} if they use it.
15032 It is an error to used this flag with the frame pointer or stack pointer.
15033 Use of this flag for other registers that have fixed pervasive roles in
15034 the machine's execution model will produce disastrous results.
15036 A different sort of disaster will result from the use of this flag for
15037 a register in which function values may be returned.
15039 This flag does not have a negative form, because it specifies a
15042 @item -fpack-struct[=@var{n}]
15043 @opindex fpack-struct
15044 Without a value specified, pack all structure members together without
15045 holes. When a value is specified (which must be a small power of two), pack
15046 structure members according to this value, representing the maximum
15047 alignment (that is, objects with default alignment requirements larger than
15048 this will be output potentially unaligned at the next fitting location.
15050 @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
15051 code that is not binary compatible with code generated without that switch.
15052 Additionally, it makes the code suboptimal.
15053 Use it to conform to a non-default application binary interface.
15055 @item -finstrument-functions
15056 @opindex finstrument-functions
15057 Generate instrumentation calls for entry and exit to functions. Just
15058 after function entry and just before function exit, the following
15059 profiling functions will be called with the address of the current
15060 function and its call site. (On some platforms,
15061 @code{__builtin_return_address} does not work beyond the current
15062 function, so the call site information may not be available to the
15063 profiling functions otherwise.)
15066 void __cyg_profile_func_enter (void *this_fn,
15068 void __cyg_profile_func_exit (void *this_fn,
15072 The first argument is the address of the start of the current function,
15073 which may be looked up exactly in the symbol table.
15075 This instrumentation is also done for functions expanded inline in other
15076 functions. The profiling calls will indicate where, conceptually, the
15077 inline function is entered and exited. This means that addressable
15078 versions of such functions must be available. If all your uses of a
15079 function are expanded inline, this may mean an additional expansion of
15080 code size. If you use @samp{extern inline} in your C code, an
15081 addressable version of such functions must be provided. (This is
15082 normally the case anyways, but if you get lucky and the optimizer always
15083 expands the functions inline, you might have gotten away without
15084 providing static copies.)
15086 A function may be given the attribute @code{no_instrument_function}, in
15087 which case this instrumentation will not be done. This can be used, for
15088 example, for the profiling functions listed above, high-priority
15089 interrupt routines, and any functions from which the profiling functions
15090 cannot safely be called (perhaps signal handlers, if the profiling
15091 routines generate output or allocate memory).
15093 @item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
15094 @opindex finstrument-functions-exclude-file-list
15096 Set the list of functions that are excluded from instrumentation (see
15097 the description of @code{-finstrument-functions}). If the file that
15098 contains a function definition matches with one of @var{file}, then
15099 that function is not instrumented. The match is done on substrings:
15100 if the @var{file} parameter is a substring of the file name, it is
15101 considered to be a match.
15104 @code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
15105 will exclude any inline function defined in files whose pathnames
15106 contain @code{/bits/stl} or @code{include/sys}.
15108 If, for some reason, you want to include letter @code{','} in one of
15109 @var{sym}, write @code{'\,'}. For example,
15110 @code{-finstrument-functions-exclude-file-list='\,\,tmp'}
15111 (note the single quote surrounding the option).
15113 @item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
15114 @opindex finstrument-functions-exclude-function-list
15116 This is similar to @code{-finstrument-functions-exclude-file-list},
15117 but this option sets the list of function names to be excluded from
15118 instrumentation. The function name to be matched is its user-visible
15119 name, such as @code{vector<int> blah(const vector<int> &)}, not the
15120 internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
15121 match is done on substrings: if the @var{sym} parameter is a substring
15122 of the function name, it is considered to be a match.
15124 @item -fstack-check
15125 @opindex fstack-check
15126 Generate code to verify that you do not go beyond the boundary of the
15127 stack. You should specify this flag if you are running in an
15128 environment with multiple threads, but only rarely need to specify it in
15129 a single-threaded environment since stack overflow is automatically
15130 detected on nearly all systems if there is only one stack.
15132 Note that this switch does not actually cause checking to be done; the
15133 operating system must do that. The switch causes generation of code
15134 to ensure that the operating system sees the stack being extended.
15136 @item -fstack-limit-register=@var{reg}
15137 @itemx -fstack-limit-symbol=@var{sym}
15138 @itemx -fno-stack-limit
15139 @opindex fstack-limit-register
15140 @opindex fstack-limit-symbol
15141 @opindex fno-stack-limit
15142 Generate code to ensure that the stack does not grow beyond a certain value,
15143 either the value of a register or the address of a symbol. If the stack
15144 would grow beyond the value, a signal is raised. For most targets,
15145 the signal is raised before the stack overruns the boundary, so
15146 it is possible to catch the signal without taking special precautions.
15148 For instance, if the stack starts at absolute address @samp{0x80000000}
15149 and grows downwards, you can use the flags
15150 @option{-fstack-limit-symbol=__stack_limit} and
15151 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
15152 of 128KB@. Note that this may only work with the GNU linker.
15154 @cindex aliasing of parameters
15155 @cindex parameters, aliased
15156 @item -fargument-alias
15157 @itemx -fargument-noalias
15158 @itemx -fargument-noalias-global
15159 @itemx -fargument-noalias-anything
15160 @opindex fargument-alias
15161 @opindex fargument-noalias
15162 @opindex fargument-noalias-global
15163 @opindex fargument-noalias-anything
15164 Specify the possible relationships among parameters and between
15165 parameters and global data.
15167 @option{-fargument-alias} specifies that arguments (parameters) may
15168 alias each other and may alias global storage.@*
15169 @option{-fargument-noalias} specifies that arguments do not alias
15170 each other, but may alias global storage.@*
15171 @option{-fargument-noalias-global} specifies that arguments do not
15172 alias each other and do not alias global storage.
15173 @option{-fargument-noalias-anything} specifies that arguments do not
15174 alias any other storage.
15176 Each language will automatically use whatever option is required by
15177 the language standard. You should not need to use these options yourself.
15179 @item -fleading-underscore
15180 @opindex fleading-underscore
15181 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
15182 change the way C symbols are represented in the object file. One use
15183 is to help link with legacy assembly code.
15185 @strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
15186 generate code that is not binary compatible with code generated without that
15187 switch. Use it to conform to a non-default application binary interface.
15188 Not all targets provide complete support for this switch.
15190 @item -ftls-model=@var{model}
15191 @opindex ftls-model
15192 Alter the thread-local storage model to be used (@pxref{Thread-Local}).
15193 The @var{model} argument should be one of @code{global-dynamic},
15194 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
15196 The default without @option{-fpic} is @code{initial-exec}; with
15197 @option{-fpic} the default is @code{global-dynamic}.
15199 @item -fvisibility=@var{default|internal|hidden|protected}
15200 @opindex fvisibility
15201 Set the default ELF image symbol visibility to the specified option---all
15202 symbols will be marked with this unless overridden within the code.
15203 Using this feature can very substantially improve linking and
15204 load times of shared object libraries, produce more optimized
15205 code, provide near-perfect API export and prevent symbol clashes.
15206 It is @strong{strongly} recommended that you use this in any shared objects
15209 Despite the nomenclature, @code{default} always means public ie;
15210 available to be linked against from outside the shared object.
15211 @code{protected} and @code{internal} are pretty useless in real-world
15212 usage so the only other commonly used option will be @code{hidden}.
15213 The default if @option{-fvisibility} isn't specified is
15214 @code{default}, i.e., make every
15215 symbol public---this causes the same behavior as previous versions of
15218 A good explanation of the benefits offered by ensuring ELF
15219 symbols have the correct visibility is given by ``How To Write
15220 Shared Libraries'' by Ulrich Drepper (which can be found at
15221 @w{@uref{http://people.redhat.com/~drepper/}})---however a superior
15222 solution made possible by this option to marking things hidden when
15223 the default is public is to make the default hidden and mark things
15224 public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
15225 and @code{__attribute__ ((visibility("default")))} instead of
15226 @code{__declspec(dllexport)} you get almost identical semantics with
15227 identical syntax. This is a great boon to those working with
15228 cross-platform projects.
15230 For those adding visibility support to existing code, you may find
15231 @samp{#pragma GCC visibility} of use. This works by you enclosing
15232 the declarations you wish to set visibility for with (for example)
15233 @samp{#pragma GCC visibility push(hidden)} and
15234 @samp{#pragma GCC visibility pop}.
15235 Bear in mind that symbol visibility should be viewed @strong{as
15236 part of the API interface contract} and thus all new code should
15237 always specify visibility when it is not the default ie; declarations
15238 only for use within the local DSO should @strong{always} be marked explicitly
15239 as hidden as so to avoid PLT indirection overheads---making this
15240 abundantly clear also aids readability and self-documentation of the code.
15241 Note that due to ISO C++ specification requirements, operator new and
15242 operator delete must always be of default visibility.
15244 Be aware that headers from outside your project, in particular system
15245 headers and headers from any other library you use, may not be
15246 expecting to be compiled with visibility other than the default. You
15247 may need to explicitly say @samp{#pragma GCC visibility push(default)}
15248 before including any such headers.
15250 @samp{extern} declarations are not affected by @samp{-fvisibility}, so
15251 a lot of code can be recompiled with @samp{-fvisibility=hidden} with
15252 no modifications. However, this means that calls to @samp{extern}
15253 functions with no explicit visibility will use the PLT, so it is more
15254 effective to use @samp{__attribute ((visibility))} and/or
15255 @samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
15256 declarations should be treated as hidden.
15258 Note that @samp{-fvisibility} does affect C++ vague linkage
15259 entities. This means that, for instance, an exception class that will
15260 be thrown between DSOs must be explicitly marked with default
15261 visibility so that the @samp{type_info} nodes will be unified between
15264 An overview of these techniques, their benefits and how to use them
15265 is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
15271 @node Environment Variables
15272 @section Environment Variables Affecting GCC
15273 @cindex environment variables
15275 @c man begin ENVIRONMENT
15276 This section describes several environment variables that affect how GCC
15277 operates. Some of them work by specifying directories or prefixes to use
15278 when searching for various kinds of files. Some are used to specify other
15279 aspects of the compilation environment.
15281 Note that you can also specify places to search using options such as
15282 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
15283 take precedence over places specified using environment variables, which
15284 in turn take precedence over those specified by the configuration of GCC@.
15285 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
15286 GNU Compiler Collection (GCC) Internals}.
15291 @c @itemx LC_COLLATE
15293 @c @itemx LC_MONETARY
15294 @c @itemx LC_NUMERIC
15299 @c @findex LC_COLLATE
15300 @findex LC_MESSAGES
15301 @c @findex LC_MONETARY
15302 @c @findex LC_NUMERIC
15306 These environment variables control the way that GCC uses
15307 localization information that allow GCC to work with different
15308 national conventions. GCC inspects the locale categories
15309 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
15310 so. These locale categories can be set to any value supported by your
15311 installation. A typical value is @samp{en_GB.UTF-8} for English in the United
15312 Kingdom encoded in UTF-8.
15314 The @env{LC_CTYPE} environment variable specifies character
15315 classification. GCC uses it to determine the character boundaries in
15316 a string; this is needed for some multibyte encodings that contain quote
15317 and escape characters that would otherwise be interpreted as a string
15320 The @env{LC_MESSAGES} environment variable specifies the language to
15321 use in diagnostic messages.
15323 If the @env{LC_ALL} environment variable is set, it overrides the value
15324 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
15325 and @env{LC_MESSAGES} default to the value of the @env{LANG}
15326 environment variable. If none of these variables are set, GCC
15327 defaults to traditional C English behavior.
15331 If @env{TMPDIR} is set, it specifies the directory to use for temporary
15332 files. GCC uses temporary files to hold the output of one stage of
15333 compilation which is to be used as input to the next stage: for example,
15334 the output of the preprocessor, which is the input to the compiler
15337 @item GCC_EXEC_PREFIX
15338 @findex GCC_EXEC_PREFIX
15339 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
15340 names of the subprograms executed by the compiler. No slash is added
15341 when this prefix is combined with the name of a subprogram, but you can
15342 specify a prefix that ends with a slash if you wish.
15344 If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
15345 an appropriate prefix to use based on the pathname it was invoked with.
15347 If GCC cannot find the subprogram using the specified prefix, it
15348 tries looking in the usual places for the subprogram.
15350 The default value of @env{GCC_EXEC_PREFIX} is
15351 @file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to
15352 the installed compiler. In many cases @var{prefix} is the value
15353 of @code{prefix} when you ran the @file{configure} script.
15355 Other prefixes specified with @option{-B} take precedence over this prefix.
15357 This prefix is also used for finding files such as @file{crt0.o} that are
15360 In addition, the prefix is used in an unusual way in finding the
15361 directories to search for header files. For each of the standard
15362 directories whose name normally begins with @samp{/usr/local/lib/gcc}
15363 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
15364 replacing that beginning with the specified prefix to produce an
15365 alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
15366 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
15367 These alternate directories are searched first; the standard directories
15368 come next. If a standard directory begins with the configured
15369 @var{prefix} then the value of @var{prefix} is replaced by
15370 @env{GCC_EXEC_PREFIX} when looking for header files.
15372 @item COMPILER_PATH
15373 @findex COMPILER_PATH
15374 The value of @env{COMPILER_PATH} is a colon-separated list of
15375 directories, much like @env{PATH}. GCC tries the directories thus
15376 specified when searching for subprograms, if it can't find the
15377 subprograms using @env{GCC_EXEC_PREFIX}.
15380 @findex LIBRARY_PATH
15381 The value of @env{LIBRARY_PATH} is a colon-separated list of
15382 directories, much like @env{PATH}. When configured as a native compiler,
15383 GCC tries the directories thus specified when searching for special
15384 linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
15385 using GCC also uses these directories when searching for ordinary
15386 libraries for the @option{-l} option (but directories specified with
15387 @option{-L} come first).
15391 @cindex locale definition
15392 This variable is used to pass locale information to the compiler. One way in
15393 which this information is used is to determine the character set to be used
15394 when character literals, string literals and comments are parsed in C and C++.
15395 When the compiler is configured to allow multibyte characters,
15396 the following values for @env{LANG} are recognized:
15400 Recognize JIS characters.
15402 Recognize SJIS characters.
15404 Recognize EUCJP characters.
15407 If @env{LANG} is not defined, or if it has some other value, then the
15408 compiler will use mblen and mbtowc as defined by the default locale to
15409 recognize and translate multibyte characters.
15413 Some additional environments variables affect the behavior of the
15416 @include cppenv.texi
15420 @node Precompiled Headers
15421 @section Using Precompiled Headers
15422 @cindex precompiled headers
15423 @cindex speed of compilation
15425 Often large projects have many header files that are included in every
15426 source file. The time the compiler takes to process these header files
15427 over and over again can account for nearly all of the time required to
15428 build the project. To make builds faster, GCC allows users to
15429 `precompile' a header file; then, if builds can use the precompiled
15430 header file they will be much faster.
15432 To create a precompiled header file, simply compile it as you would any
15433 other file, if necessary using the @option{-x} option to make the driver
15434 treat it as a C or C++ header file. You will probably want to use a
15435 tool like @command{make} to keep the precompiled header up-to-date when
15436 the headers it contains change.
15438 A precompiled header file will be searched for when @code{#include} is
15439 seen in the compilation. As it searches for the included file
15440 (@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
15441 compiler looks for a precompiled header in each directory just before it
15442 looks for the include file in that directory. The name searched for is
15443 the name specified in the @code{#include} with @samp{.gch} appended. If
15444 the precompiled header file can't be used, it is ignored.
15446 For instance, if you have @code{#include "all.h"}, and you have
15447 @file{all.h.gch} in the same directory as @file{all.h}, then the
15448 precompiled header file will be used if possible, and the original
15449 header will be used otherwise.
15451 Alternatively, you might decide to put the precompiled header file in a
15452 directory and use @option{-I} to ensure that directory is searched
15453 before (or instead of) the directory containing the original header.
15454 Then, if you want to check that the precompiled header file is always
15455 used, you can put a file of the same name as the original header in this
15456 directory containing an @code{#error} command.
15458 This also works with @option{-include}. So yet another way to use
15459 precompiled headers, good for projects not designed with precompiled
15460 header files in mind, is to simply take most of the header files used by
15461 a project, include them from another header file, precompile that header
15462 file, and @option{-include} the precompiled header. If the header files
15463 have guards against multiple inclusion, they will be skipped because
15464 they've already been included (in the precompiled header).
15466 If you need to precompile the same header file for different
15467 languages, targets, or compiler options, you can instead make a
15468 @emph{directory} named like @file{all.h.gch}, and put each precompiled
15469 header in the directory, perhaps using @option{-o}. It doesn't matter
15470 what you call the files in the directory, every precompiled header in
15471 the directory will be considered. The first precompiled header
15472 encountered in the directory that is valid for this compilation will
15473 be used; they're searched in no particular order.
15475 There are many other possibilities, limited only by your imagination,
15476 good sense, and the constraints of your build system.
15478 A precompiled header file can be used only when these conditions apply:
15482 Only one precompiled header can be used in a particular compilation.
15485 A precompiled header can't be used once the first C token is seen. You
15486 can have preprocessor directives before a precompiled header; you can
15487 even include a precompiled header from inside another header, so long as
15488 there are no C tokens before the @code{#include}.
15491 The precompiled header file must be produced for the same language as
15492 the current compilation. You can't use a C precompiled header for a C++
15496 The precompiled header file must have been produced by the same compiler
15497 binary as the current compilation is using.
15500 Any macros defined before the precompiled header is included must
15501 either be defined in the same way as when the precompiled header was
15502 generated, or must not affect the precompiled header, which usually
15503 means that they don't appear in the precompiled header at all.
15505 The @option{-D} option is one way to define a macro before a
15506 precompiled header is included; using a @code{#define} can also do it.
15507 There are also some options that define macros implicitly, like
15508 @option{-O} and @option{-Wdeprecated}; the same rule applies to macros
15511 @item If debugging information is output when using the precompiled
15512 header, using @option{-g} or similar, the same kind of debugging information
15513 must have been output when building the precompiled header. However,
15514 a precompiled header built using @option{-g} can be used in a compilation
15515 when no debugging information is being output.
15517 @item The same @option{-m} options must generally be used when building
15518 and using the precompiled header. @xref{Submodel Options},
15519 for any cases where this rule is relaxed.
15521 @item Each of the following options must be the same when building and using
15522 the precompiled header:
15524 @gccoptlist{-fexceptions -funit-at-a-time}
15527 Some other command-line options starting with @option{-f},
15528 @option{-p}, or @option{-O} must be defined in the same way as when
15529 the precompiled header was generated. At present, it's not clear
15530 which options are safe to change and which are not; the safest choice
15531 is to use exactly the same options when generating and using the
15532 precompiled header. The following are known to be safe:
15534 @gccoptlist{-fmessage-length= -fpreprocessed -fsched-interblock @gol
15535 -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous @gol
15536 -fsched-verbose=<number> -fschedule-insns -fvisibility= @gol
15541 For all of these except the last, the compiler will automatically
15542 ignore the precompiled header if the conditions aren't met. If you
15543 find an option combination that doesn't work and doesn't cause the
15544 precompiled header to be ignored, please consider filing a bug report,
15547 If you do use differing options when generating and using the
15548 precompiled header, the actual behavior will be a mixture of the
15549 behavior for the options. For instance, if you use @option{-g} to
15550 generate the precompiled header but not when using it, you may or may
15551 not get debugging information for routines in the precompiled header.
15553 @node Running Protoize
15554 @section Running Protoize
15556 The program @code{protoize} is an optional part of GCC@. You can use
15557 it to add prototypes to a program, thus converting the program to ISO
15558 C in one respect. The companion program @code{unprotoize} does the
15559 reverse: it removes argument types from any prototypes that are found.
15561 When you run these programs, you must specify a set of source files as
15562 command line arguments. The conversion programs start out by compiling
15563 these files to see what functions they define. The information gathered
15564 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
15566 After scanning comes actual conversion. The specified files are all
15567 eligible to be converted; any files they include (whether sources or
15568 just headers) are eligible as well.
15570 But not all the eligible files are converted. By default,
15571 @code{protoize} and @code{unprotoize} convert only source and header
15572 files in the current directory. You can specify additional directories
15573 whose files should be converted with the @option{-d @var{directory}}
15574 option. You can also specify particular files to exclude with the
15575 @option{-x @var{file}} option. A file is converted if it is eligible, its
15576 directory name matches one of the specified directory names, and its
15577 name within the directory has not been excluded.
15579 Basic conversion with @code{protoize} consists of rewriting most
15580 function definitions and function declarations to specify the types of
15581 the arguments. The only ones not rewritten are those for varargs
15584 @code{protoize} optionally inserts prototype declarations at the
15585 beginning of the source file, to make them available for any calls that
15586 precede the function's definition. Or it can insert prototype
15587 declarations with block scope in the blocks where undeclared functions
15590 Basic conversion with @code{unprotoize} consists of rewriting most
15591 function declarations to remove any argument types, and rewriting
15592 function definitions to the old-style pre-ISO form.
15594 Both conversion programs print a warning for any function declaration or
15595 definition that they can't convert. You can suppress these warnings
15598 The output from @code{protoize} or @code{unprotoize} replaces the
15599 original source file. The original file is renamed to a name ending
15600 with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
15601 without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
15602 for DOS) file already exists, then the source file is simply discarded.
15604 @code{protoize} and @code{unprotoize} both depend on GCC itself to
15605 scan the program and collect information about the functions it uses.
15606 So neither of these programs will work until GCC is installed.
15608 Here is a table of the options you can use with @code{protoize} and
15609 @code{unprotoize}. Each option works with both programs unless
15613 @item -B @var{directory}
15614 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
15615 usual directory (normally @file{/usr/local/lib}). This file contains
15616 prototype information about standard system functions. This option
15617 applies only to @code{protoize}.
15619 @item -c @var{compilation-options}
15620 Use @var{compilation-options} as the options when running @command{gcc} to
15621 produce the @samp{.X} files. The special option @option{-aux-info} is
15622 always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
15624 Note that the compilation options must be given as a single argument to
15625 @code{protoize} or @code{unprotoize}. If you want to specify several
15626 @command{gcc} options, you must quote the entire set of compilation options
15627 to make them a single word in the shell.
15629 There are certain @command{gcc} arguments that you cannot use, because they
15630 would produce the wrong kind of output. These include @option{-g},
15631 @option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
15632 the @var{compilation-options}, they are ignored.
15635 Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
15636 systems) instead of @samp{.c}. This is convenient if you are converting
15637 a C program to C++. This option applies only to @code{protoize}.
15640 Add explicit global declarations. This means inserting explicit
15641 declarations at the beginning of each source file for each function
15642 that is called in the file and was not declared. These declarations
15643 precede the first function definition that contains a call to an
15644 undeclared function. This option applies only to @code{protoize}.
15646 @item -i @var{string}
15647 Indent old-style parameter declarations with the string @var{string}.
15648 This option applies only to @code{protoize}.
15650 @code{unprotoize} converts prototyped function definitions to old-style
15651 function definitions, where the arguments are declared between the
15652 argument list and the initial @samp{@{}. By default, @code{unprotoize}
15653 uses five spaces as the indentation. If you want to indent with just
15654 one space instead, use @option{-i " "}.
15657 Keep the @samp{.X} files. Normally, they are deleted after conversion
15661 Add explicit local declarations. @code{protoize} with @option{-l} inserts
15662 a prototype declaration for each function in each block which calls the
15663 function without any declaration. This option applies only to
15667 Make no real changes. This mode just prints information about the conversions
15668 that would have been done without @option{-n}.
15671 Make no @samp{.save} files. The original files are simply deleted.
15672 Use this option with caution.
15674 @item -p @var{program}
15675 Use the program @var{program} as the compiler. Normally, the name
15676 @file{gcc} is used.
15679 Work quietly. Most warnings are suppressed.
15682 Print the version number, just like @option{-v} for @command{gcc}.
15685 If you need special compiler options to compile one of your program's
15686 source files, then you should generate that file's @samp{.X} file
15687 specially, by running @command{gcc} on that source file with the
15688 appropriate options and the option @option{-aux-info}. Then run
15689 @code{protoize} on the entire set of files. @code{protoize} will use
15690 the existing @samp{.X} file because it is newer than the source file.
15694 gcc -Dfoo=bar file1.c -aux-info file1.X
15699 You need to include the special files along with the rest in the
15700 @code{protoize} command, even though their @samp{.X} files already
15701 exist, because otherwise they won't get converted.
15703 @xref{Protoize Caveats}, for more information on how to use
15704 @code{protoize} successfully.