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, 2009, 2010
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, 2009, 2010
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{-dv} 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.
156 @section Option Summary
158 Here is a summary of all the options, grouped by type. Explanations are
159 in the following sections.
162 @item Overall Options
163 @xref{Overall Options,,Options Controlling the Kind of Output}.
164 @gccoptlist{-c -S -E -o @var{file} -combine -no-canonical-prefixes @gol
165 -pipe -pass-exit-codes @gol
166 -x @var{language} -v -### --help@r{[}=@var{class}@r{[},@dots{}@r{]]} --target-help @gol
167 --version -wrapper@@@var{file} -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg}}
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 -fno-pretty-templates @gol
193 -frepo -fno-rtti -fstats -ftemplate-depth=@var{n} @gol
194 -fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
195 -fno-default-inline -fvisibility-inlines-hidden @gol
196 -fvisibility-ms-compat @gol
197 -Wabi -Wconversion-null -Wctor-dtor-privacy @gol
198 -Wnon-virtual-dtor -Wreorder @gol
199 -Weffc++ -Wstrict-null-sentinel @gol
200 -Wno-non-template-friend -Wold-style-cast @gol
201 -Woverloaded-virtual -Wno-pmf-conversions @gol
204 @item Objective-C and Objective-C++ Language Options
205 @xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
206 Objective-C and Objective-C++ Dialects}.
207 @gccoptlist{-fconstant-string-class=@var{class-name} @gol
208 -fgnu-runtime -fnext-runtime @gol
209 -fno-nil-receivers @gol
210 -fobjc-call-cxx-cdtors @gol
211 -fobjc-direct-dispatch @gol
212 -fobjc-exceptions @gol
214 -freplace-objc-classes @gol
217 -Wassign-intercept @gol
218 -Wno-protocol -Wselector @gol
219 -Wstrict-selector-match @gol
220 -Wundeclared-selector}
222 @item Language Independent Options
223 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
224 @gccoptlist{-fmessage-length=@var{n} @gol
225 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
226 -fdiagnostics-show-option}
228 @item Warning Options
229 @xref{Warning Options,,Options to Request or Suppress Warnings}.
230 @gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
231 -w -Wextra -Wall -Waddress -Waggregate-return -Warray-bounds @gol
232 -Wno-attributes -Wno-builtin-macro-redefined @gol
233 -Wc++-compat -Wc++0x-compat -Wcast-align -Wcast-qual @gol
234 -Wchar-subscripts -Wclobbered -Wcomment @gol
235 -Wconversion -Wcoverage-mismatch -Wcpp -Wno-deprecated @gol
236 -Wno-deprecated-declarations -Wdisabled-optimization @gol
237 -Wno-div-by-zero -Wempty-body -Wenum-compare -Wno-endif-labels @gol
238 -Werror -Werror=* @gol
239 -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
240 -Wno-format-contains-nul -Wno-format-extra-args -Wformat-nonliteral @gol
241 -Wformat-security -Wformat-y2k @gol
242 -Wframe-larger-than=@var{len} -Wjump-misses-init -Wignored-qualifiers @gol
243 -Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
244 -Winit-self -Winline @gol
245 -Wno-int-to-pointer-cast -Wno-invalid-offsetof @gol
246 -Winvalid-pch -Wlarger-than=@var{len} -Wunsafe-loop-optimizations @gol
247 -Wlogical-op -Wlong-long @gol
248 -Wmain -Wmissing-braces -Wmissing-field-initializers @gol
249 -Wmissing-format-attribute -Wmissing-include-dirs @gol
250 -Wmissing-noreturn -Wno-mudflap @gol
251 -Wno-multichar -Wnonnull -Wno-overflow @gol
252 -Woverlength-strings -Wpacked -Wpacked-bitfield-compat -Wpadded @gol
253 -Wparentheses -Wpedantic-ms-format -Wno-pedantic-ms-format @gol
254 -Wpointer-arith -Wno-pointer-to-int-cast @gol
255 -Wredundant-decls @gol
256 -Wreturn-type -Wsequence-point -Wshadow @gol
257 -Wsign-compare -Wsign-conversion -Wstack-protector @gol
258 -Wstrict-aliasing -Wstrict-aliasing=n @gol
259 -Wstrict-overflow -Wstrict-overflow=@var{n} @gol
260 -Wsuggest-attribute=@r{[}const@r{|}pure@r{]} @gol
261 -Wswitch -Wswitch-default -Wswitch-enum -Wsync-nand @gol
262 -Wsystem-headers -Wtrigraphs -Wtype-limits -Wundef -Wuninitialized @gol
263 -Wunknown-pragmas -Wno-pragmas @gol
264 -Wunsuffixed-float-constants -Wunused -Wunused-function @gol
265 -Wunused-label -Wunused-parameter -Wno-unused-result -Wunused-value -Wunused-variable @gol
266 -Wunused-but-set-parameter -Wunused-but-set-variable -Wvariadic-macros -Wvla @gol
267 -Wvolatile-register-var -Wwrite-strings}
269 @item C and Objective-C-only Warning Options
270 @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
271 -Wmissing-parameter-type -Wmissing-prototypes -Wnested-externs @gol
272 -Wold-style-declaration -Wold-style-definition @gol
273 -Wstrict-prototypes -Wtraditional -Wtraditional-conversion @gol
274 -Wdeclaration-after-statement -Wpointer-sign}
276 @item Debugging Options
277 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
278 @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
279 -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
280 -fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol
281 -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
282 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
283 -fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol
284 -fdump-statistics @gol
286 -fdump-tree-original@r{[}-@var{n}@r{]} @gol
287 -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
288 -fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
290 -fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
291 -fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
292 -fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
293 -fdump-tree-dom@r{[}-@var{n}@r{]} @gol
294 -fdump-tree-dse@r{[}-@var{n}@r{]} @gol
295 -fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol
296 -fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
297 -fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
298 -fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
299 -fdump-tree-nrv -fdump-tree-vect @gol
300 -fdump-tree-sink @gol
301 -fdump-tree-sra@r{[}-@var{n}@r{]} @gol
302 -fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
303 -fdump-tree-fre@r{[}-@var{n}@r{]} @gol
304 -fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
305 -ftree-vectorizer-verbose=@var{n} @gol
306 -fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
307 -fdump-final-insns=@var{file} @gol
308 -fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol
309 -feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
310 -feliminate-unused-debug-symbols -femit-class-debug-always @gol
311 -fenable-icf-debug @gol
312 -fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol
313 -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
314 -fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol
315 -ftest-coverage -ftime-report -fvar-tracking @gol
316 -fvar-tracking-assignments -fvar-tracking-assignments-toggle @gol
317 -g -g@var{level} -gtoggle -gcoff -gdwarf-@var{version} @gol
318 -ggdb -gstabs -gstabs+ -gstrict-dwarf -gno-strict-dwarf @gol
319 -gvms -gxcoff -gxcoff+ @gol
320 -fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol
321 -fdebug-prefix-map=@var{old}=@var{new} @gol
322 -femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
323 -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
324 -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
325 -print-multi-directory -print-multi-lib -print-multi-os-directory @gol
326 -print-prog-name=@var{program} -print-search-dirs -Q @gol
327 -print-sysroot -print-sysroot-headers-suffix @gol
328 -save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}}
330 @item Optimization Options
331 @xref{Optimize Options,,Options that Control Optimization}.
333 -falign-functions[=@var{n}] -falign-jumps[=@var{n}] @gol
334 -falign-labels[=@var{n}] -falign-loops[=@var{n}] -fassociative-math @gol
335 -fauto-inc-dec -fbranch-probabilities -fbranch-target-load-optimize @gol
336 -fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves @gol
337 -fcheck-data-deps -fconserve-stack -fcprop-registers -fcrossjumping @gol
338 -fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules -fcx-limited-range @gol
339 -fdata-sections -fdce -fdce @gol
340 -fdelayed-branch -fdelete-null-pointer-checks -fdse -fdse @gol
341 -fearly-inlining -fipa-sra -fexpensive-optimizations -ffast-math @gol
342 -ffinite-math-only -ffloat-store -fexcess-precision=@var{style} @gol
343 -fforward-propagate -ffunction-sections @gol
344 -fgcse -fgcse-after-reload -fgcse-las -fgcse-lm @gol
345 -fgcse-sm -fif-conversion -fif-conversion2 -findirect-inlining @gol
346 -finline-functions -finline-functions-called-once -finline-limit=@var{n} @gol
347 -finline-small-functions -fipa-cp -fipa-cp-clone -fipa-matrix-reorg -fipa-pta @gol
348 -fipa-profile -fipa-pure-const -fipa-reference -fipa-struct-reorg @gol
349 -fira-algorithm=@var{algorithm} @gol
350 -fira-region=@var{region} -fira-coalesce @gol
351 -fira-loop-pressure -fno-ira-share-save-slots @gol
352 -fno-ira-share-spill-slots -fira-verbose=@var{n} @gol
353 -fivopts -fkeep-inline-functions -fkeep-static-consts @gol
354 -floop-block -floop-interchange -floop-strip-mine -fgraphite-identity @gol
355 -floop-parallelize-all -flto -flto-compression-level -flto-report -fltrans @gol
356 -fltrans-output-list -fmerge-all-constants -fmerge-constants -fmodulo-sched @gol
357 -fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap @gol
358 -fmudflapir -fmudflapth -fno-branch-count-reg -fno-default-inline @gol
359 -fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol
360 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
361 -fno-sched-interblock -fno-sched-spec -fno-signed-zeros @gol
362 -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
363 -fomit-frame-pointer -foptimize-register-move -foptimize-sibling-calls @gol
364 -fpeel-loops -fpredictive-commoning -fprefetch-loop-arrays @gol
365 -fprofile-correction -fprofile-dir=@var{path} -fprofile-generate @gol
366 -fprofile-generate=@var{path} @gol
367 -fprofile-use -fprofile-use=@var{path} -fprofile-values @gol
368 -freciprocal-math -fregmove -frename-registers -freorder-blocks @gol
369 -freorder-blocks-and-partition -freorder-functions @gol
370 -frerun-cse-after-loop -freschedule-modulo-scheduled-loops @gol
371 -frounding-math -fsched2-use-superblocks -fsched-pressure @gol
372 -fsched-spec-load -fsched-spec-load-dangerous @gol
373 -fsched-stalled-insns-dep[=@var{n}] -fsched-stalled-insns[=@var{n}] @gol
374 -fsched-group-heuristic -fsched-critical-path-heuristic @gol
375 -fsched-spec-insn-heuristic -fsched-rank-heuristic @gol
376 -fsched-last-insn-heuristic -fsched-dep-count-heuristic @gol
377 -fschedule-insns -fschedule-insns2 -fsection-anchors @gol
378 -fselective-scheduling -fselective-scheduling2 @gol
379 -fsel-sched-pipelining -fsel-sched-pipelining-outer-loops @gol
380 -fsignaling-nans -fsingle-precision-constant -fsplit-ivs-in-unroller @gol
381 -fsplit-wide-types -fstack-protector -fstack-protector-all @gol
382 -fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer @gol
383 -ftree-builtin-call-dce -ftree-ccp -ftree-ch -ftree-copy-prop @gol
384 -ftree-copyrename -ftree-dce @gol
385 -ftree-dominator-opts -ftree-dse -ftree-forwprop -ftree-fre -ftree-loop-im @gol
386 -ftree-phiprop -ftree-loop-distribution @gol
387 -ftree-loop-ivcanon -ftree-loop-linear -ftree-loop-optimize @gol
388 -ftree-parallelize-loops=@var{n} -ftree-pre -ftree-pta -ftree-reassoc @gol
389 -ftree-sink -ftree-sra -ftree-switch-conversion @gol
390 -ftree-ter -ftree-vect-loop-version -ftree-vectorize -ftree-vrp @gol
391 -funit-at-a-time -funroll-all-loops -funroll-loops @gol
392 -funsafe-loop-optimizations -funsafe-math-optimizations -funswitch-loops @gol
393 -fvariable-expansion-in-unroller -fvect-cost-model -fvpt -fweb @gol
394 -fwhole-program -fwhopr -fwpa -fuse-linker-plugin @gol
395 --param @var{name}=@var{value}
396 -O -O0 -O1 -O2 -O3 -Os}
398 @item Preprocessor Options
399 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
400 @gccoptlist{-A@var{question}=@var{answer} @gol
401 -A-@var{question}@r{[}=@var{answer}@r{]} @gol
402 -C -dD -dI -dM -dN @gol
403 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
404 -idirafter @var{dir} @gol
405 -include @var{file} -imacros @var{file} @gol
406 -iprefix @var{file} -iwithprefix @var{dir} @gol
407 -iwithprefixbefore @var{dir} -isystem @var{dir} @gol
408 -imultilib @var{dir} -isysroot @var{dir} @gol
409 -M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
410 -P -fworking-directory -remap @gol
411 -trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
412 -Xpreprocessor @var{option}}
414 @item Assembler Option
415 @xref{Assembler Options,,Passing Options to the Assembler}.
416 @gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
419 @xref{Link Options,,Options for Linking}.
420 @gccoptlist{@var{object-file-name} -l@var{library} @gol
421 -nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
422 -s -static -static-libgcc -static-libstdc++ -shared @gol
423 -shared-libgcc -symbolic @gol
424 -T @var{script} -Wl,@var{option} -Xlinker @var{option} @gol
427 @item Directory Options
428 @xref{Directory Options,,Options for Directory Search}.
429 @gccoptlist{-B@var{prefix} -I@var{dir} -iplugindir=@var{dir}}
430 -iquote@var{dir} -L@var{dir} -specs=@var{file} -I-
433 @item Machine Dependent Options
434 @xref{Submodel Options,,Hardware Models and Configurations}.
435 @c This list is ordered alphanumerically by subsection name.
436 @c Try and put the significant identifier (CPU or system) first,
437 @c so users have a clue at guessing where the ones they want will be.
440 @gccoptlist{-EB -EL @gol
441 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
442 -mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
445 @gccoptlist{-mapcs-frame -mno-apcs-frame @gol
446 -mabi=@var{name} @gol
447 -mapcs-stack-check -mno-apcs-stack-check @gol
448 -mapcs-float -mno-apcs-float @gol
449 -mapcs-reentrant -mno-apcs-reentrant @gol
450 -msched-prolog -mno-sched-prolog @gol
451 -mlittle-endian -mbig-endian -mwords-little-endian @gol
452 -mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
453 -mfp16-format=@var{name}
454 -mthumb-interwork -mno-thumb-interwork @gol
455 -mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
456 -mstructure-size-boundary=@var{n} @gol
457 -mabort-on-noreturn @gol
458 -mlong-calls -mno-long-calls @gol
459 -msingle-pic-base -mno-single-pic-base @gol
460 -mpic-register=@var{reg} @gol
461 -mnop-fun-dllimport @gol
462 -mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
463 -mpoke-function-name @gol
465 -mtpcs-frame -mtpcs-leaf-frame @gol
466 -mcaller-super-interworking -mcallee-super-interworking @gol
468 -mword-relocations @gol
469 -mfix-cortex-m3-ldrd}
472 @gccoptlist{-mmcu=@var{mcu} -mno-interrupts @gol
473 -mcall-prologues -mtiny-stack -mint8}
475 @emph{Blackfin Options}
476 @gccoptlist{-mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]} @gol
477 -msim -momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
478 -mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
479 -mlow-64k -mno-low64k -mstack-check-l1 -mid-shared-library @gol
480 -mno-id-shared-library -mshared-library-id=@var{n} @gol
481 -mleaf-id-shared-library -mno-leaf-id-shared-library @gol
482 -msep-data -mno-sep-data -mlong-calls -mno-long-calls @gol
483 -mfast-fp -minline-plt -mmulticore -mcorea -mcoreb -msdram @gol
487 @gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
488 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
489 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
490 -mstack-align -mdata-align -mconst-align @gol
491 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
492 -melf -maout -melinux -mlinux -sim -sim2 @gol
493 -mmul-bug-workaround -mno-mul-bug-workaround}
496 @gccoptlist{-mmac -mpush-args}
498 @emph{Darwin Options}
499 @gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
500 -arch_only -bind_at_load -bundle -bundle_loader @gol
501 -client_name -compatibility_version -current_version @gol
503 -dependency-file -dylib_file -dylinker_install_name @gol
504 -dynamic -dynamiclib -exported_symbols_list @gol
505 -filelist -flat_namespace -force_cpusubtype_ALL @gol
506 -force_flat_namespace -headerpad_max_install_names @gol
508 -image_base -init -install_name -keep_private_externs @gol
509 -multi_module -multiply_defined -multiply_defined_unused @gol
510 -noall_load -no_dead_strip_inits_and_terms @gol
511 -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
512 -pagezero_size -prebind -prebind_all_twolevel_modules @gol
513 -private_bundle -read_only_relocs -sectalign @gol
514 -sectobjectsymbols -whyload -seg1addr @gol
515 -sectcreate -sectobjectsymbols -sectorder @gol
516 -segaddr -segs_read_only_addr -segs_read_write_addr @gol
517 -seg_addr_table -seg_addr_table_filename -seglinkedit @gol
518 -segprot -segs_read_only_addr -segs_read_write_addr @gol
519 -single_module -static -sub_library -sub_umbrella @gol
520 -twolevel_namespace -umbrella -undefined @gol
521 -unexported_symbols_list -weak_reference_mismatches @gol
522 -whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
523 -mkernel -mone-byte-bool}
525 @emph{DEC Alpha Options}
526 @gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
527 -mieee -mieee-with-inexact -mieee-conformant @gol
528 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
529 -mtrap-precision=@var{mode} -mbuild-constants @gol
530 -mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
531 -mbwx -mmax -mfix -mcix @gol
532 -mfloat-vax -mfloat-ieee @gol
533 -mexplicit-relocs -msmall-data -mlarge-data @gol
534 -msmall-text -mlarge-text @gol
535 -mmemory-latency=@var{time}}
537 @emph{DEC Alpha/VMS Options}
538 @gccoptlist{-mvms-return-codes -mdebug-main=@var{prefix} -mmalloc64}
541 @gccoptlist{-msmall-model -mno-lsim}
544 @gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
545 -mhard-float -msoft-float @gol
546 -malloc-cc -mfixed-cc -mdword -mno-dword @gol
547 -mdouble -mno-double @gol
548 -mmedia -mno-media -mmuladd -mno-muladd @gol
549 -mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
550 -mlinked-fp -mlong-calls -malign-labels @gol
551 -mlibrary-pic -macc-4 -macc-8 @gol
552 -mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
553 -moptimize-membar -mno-optimize-membar @gol
554 -mscc -mno-scc -mcond-exec -mno-cond-exec @gol
555 -mvliw-branch -mno-vliw-branch @gol
556 -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
557 -mno-nested-cond-exec -mtomcat-stats @gol
561 @emph{GNU/Linux Options}
562 @gccoptlist{-muclibc}
564 @emph{H8/300 Options}
565 @gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
568 @gccoptlist{-march=@var{architecture-type} @gol
569 -mbig-switch -mdisable-fpregs -mdisable-indexing @gol
570 -mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
571 -mfixed-range=@var{register-range} @gol
572 -mjump-in-delay -mlinker-opt -mlong-calls @gol
573 -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
574 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
575 -mno-jump-in-delay -mno-long-load-store @gol
576 -mno-portable-runtime -mno-soft-float @gol
577 -mno-space-regs -msoft-float -mpa-risc-1-0 @gol
578 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
579 -mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
580 -munix=@var{unix-std} -nolibdld -static -threads}
582 @emph{i386 and x86-64 Options}
583 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
584 -mfpmath=@var{unit} @gol
585 -masm=@var{dialect} -mno-fancy-math-387 @gol
586 -mno-fp-ret-in-387 -msoft-float @gol
587 -mno-wide-multiply -mrtd -malign-double @gol
588 -mpreferred-stack-boundary=@var{num}
589 -mincoming-stack-boundary=@var{num}
590 -mcld -mcx16 -msahf -mmovbe -mcrc32 -mrecip @gol
591 -mmmx -msse -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 -mavx @gol
592 -maes -mpclmul -mfused-madd @gol
593 -msse4a -m3dnow -mpopcnt -mabm -mfma4 -mxop -mlwp @gol
594 -mthreads -mno-align-stringops -minline-all-stringops @gol
595 -minline-stringops-dynamically -mstringop-strategy=@var{alg} @gol
596 -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
597 -m96bit-long-double -mregparm=@var{num} -msseregparm @gol
598 -mveclibabi=@var{type} -mpc32 -mpc64 -mpc80 -mstackrealign @gol
599 -momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
600 -mcmodel=@var{code-model} -mabi=@var{name} @gol
601 -m32 -m64 -mlarge-data-threshold=@var{num} @gol
605 @gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
606 -mvolatile-asm-stop -mregister-names -msdata -mno-sdata @gol
607 -mconstant-gp -mauto-pic -mfused-madd @gol
608 -minline-float-divide-min-latency @gol
609 -minline-float-divide-max-throughput @gol
610 -mno-inline-float-divide @gol
611 -minline-int-divide-min-latency @gol
612 -minline-int-divide-max-throughput @gol
613 -mno-inline-int-divide @gol
614 -minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
615 -mno-inline-sqrt @gol
616 -mdwarf2-asm -mearly-stop-bits @gol
617 -mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
618 -mtune=@var{cpu-type} -milp32 -mlp64 @gol
619 -msched-br-data-spec -msched-ar-data-spec -msched-control-spec @gol
620 -msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
621 -msched-spec-ldc -msched-spec-control-ldc @gol
622 -msched-prefer-non-data-spec-insns -msched-prefer-non-control-spec-insns @gol
623 -msched-stop-bits-after-every-cycle -msched-count-spec-in-critical-path @gol
624 -msel-sched-dont-check-control-spec -msched-fp-mem-deps-zero-cost @gol
625 -msched-max-memory-insns-hard-limit -msched-max-memory-insns=@var{max-insns}}
627 @emph{IA-64/VMS Options}
628 @gccoptlist{-mvms-return-codes -mdebug-main=@var{prefix} -mmalloc64}
631 @gccoptlist{-mbarrel-shift-enabled -mdivide-enabled -mmultiply-enabled @gol
632 -msign-extend-enabled -muser-enabled}
634 @emph{M32R/D Options}
635 @gccoptlist{-m32r2 -m32rx -m32r @gol
637 -malign-loops -mno-align-loops @gol
638 -missue-rate=@var{number} @gol
639 -mbranch-cost=@var{number} @gol
640 -mmodel=@var{code-size-model-type} @gol
641 -msdata=@var{sdata-type} @gol
642 -mno-flush-func -mflush-func=@var{name} @gol
643 -mno-flush-trap -mflush-trap=@var{number} @gol
647 @gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
649 @emph{M680x0 Options}
650 @gccoptlist{-march=@var{arch} -mcpu=@var{cpu} -mtune=@var{tune}
651 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
652 -m68060 -mcpu32 -m5200 -m5206e -m528x -m5307 -m5407 @gol
653 -mcfv4e -mbitfield -mno-bitfield -mc68000 -mc68020 @gol
654 -mnobitfield -mrtd -mno-rtd -mdiv -mno-div -mshort @gol
655 -mno-short -mhard-float -m68881 -msoft-float -mpcrel @gol
656 -malign-int -mstrict-align -msep-data -mno-sep-data @gol
657 -mshared-library-id=n -mid-shared-library -mno-id-shared-library @gol
660 @emph{M68hc1x Options}
661 @gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
662 -mauto-incdec -minmax -mlong-calls -mshort @gol
663 -msoft-reg-count=@var{count}}
666 @gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
667 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
668 -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
669 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
670 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
673 @gccoptlist{-mabsdiff -mall-opts -maverage -mbased=@var{n} -mbitops @gol
674 -mc=@var{n} -mclip -mconfig=@var{name} -mcop -mcop32 -mcop64 -mivc2 @gol
675 -mdc -mdiv -meb -mel -mio-volatile -ml -mleadz -mm -mminmax @gol
676 -mmult -mno-opts -mrepeat -ms -msatur -msdram -msim -msimnovec -mtf @gol
680 @gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
681 -mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 @gol
682 -mips64 -mips64r2 @gol
683 -mips16 -mno-mips16 -mflip-mips16 @gol
684 -minterlink-mips16 -mno-interlink-mips16 @gol
685 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
686 -mshared -mno-shared -mplt -mno-plt -mxgot -mno-xgot @gol
687 -mgp32 -mgp64 -mfp32 -mfp64 -mhard-float -msoft-float @gol
688 -msingle-float -mdouble-float -mdsp -mno-dsp -mdspr2 -mno-dspr2 @gol
689 -mfpu=@var{fpu-type} @gol
690 -msmartmips -mno-smartmips @gol
691 -mpaired-single -mno-paired-single -mdmx -mno-mdmx @gol
692 -mips3d -mno-mips3d -mmt -mno-mt -mllsc -mno-llsc @gol
693 -mlong64 -mlong32 -msym32 -mno-sym32 @gol
694 -G@var{num} -mlocal-sdata -mno-local-sdata @gol
695 -mextern-sdata -mno-extern-sdata -mgpopt -mno-gopt @gol
696 -membedded-data -mno-embedded-data @gol
697 -muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
698 -mcode-readable=@var{setting} @gol
699 -msplit-addresses -mno-split-addresses @gol
700 -mexplicit-relocs -mno-explicit-relocs @gol
701 -mcheck-zero-division -mno-check-zero-division @gol
702 -mdivide-traps -mdivide-breaks @gol
703 -mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
704 -mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
705 -mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
706 -mfix-r10000 -mno-fix-r10000 -mfix-vr4120 -mno-fix-vr4120 @gol
707 -mfix-vr4130 -mno-fix-vr4130 -mfix-sb1 -mno-fix-sb1 @gol
708 -mflush-func=@var{func} -mno-flush-func @gol
709 -mbranch-cost=@var{num} -mbranch-likely -mno-branch-likely @gol
710 -mfp-exceptions -mno-fp-exceptions @gol
711 -mvr4130-align -mno-vr4130-align -msynci -mno-synci @gol
712 -mrelax-pic-calls -mno-relax-pic-calls -mmcount-ra-address}
715 @gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
716 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
717 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
718 -mno-base-addresses -msingle-exit -mno-single-exit}
720 @emph{MN10300 Options}
721 @gccoptlist{-mmult-bug -mno-mult-bug @gol
722 -mam33 -mno-am33 @gol
723 -mam33-2 -mno-am33-2 @gol
724 -mreturn-pointer-on-d0 @gol
727 @emph{PDP-11 Options}
728 @gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
729 -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
730 -mint16 -mno-int32 -mfloat32 -mno-float64 @gol
731 -mfloat64 -mno-float32 -mabshi -mno-abshi @gol
732 -mbranch-expensive -mbranch-cheap @gol
733 -msplit -mno-split -munix-asm -mdec-asm}
735 @emph{picoChip Options}
736 @gccoptlist{-mae=@var{ae_type} -mvliw-lookahead=@var{N}
737 -msymbol-as-address -mno-inefficient-warnings}
739 @emph{PowerPC Options}
740 See RS/6000 and PowerPC Options.
742 @emph{RS/6000 and PowerPC Options}
743 @gccoptlist{-mcpu=@var{cpu-type} @gol
744 -mtune=@var{cpu-type} @gol
745 -mpower -mno-power -mpower2 -mno-power2 @gol
746 -mpowerpc -mpowerpc64 -mno-powerpc @gol
747 -maltivec -mno-altivec @gol
748 -mpowerpc-gpopt -mno-powerpc-gpopt @gol
749 -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
750 -mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mpopcntd -mno-popcntd @gol
751 -mfprnd -mno-fprnd @gol
752 -mcmpb -mno-cmpb -mmfpgpr -mno-mfpgpr -mhard-dfp -mno-hard-dfp @gol
753 -mnew-mnemonics -mold-mnemonics @gol
754 -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
755 -m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
756 -malign-power -malign-natural @gol
757 -msoft-float -mhard-float -mmultiple -mno-multiple @gol
758 -msingle-float -mdouble-float -msimple-fpu @gol
759 -mstring -mno-string -mupdate -mno-update @gol
760 -mavoid-indexed-addresses -mno-avoid-indexed-addresses @gol
761 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
762 -mstrict-align -mno-strict-align -mrelocatable @gol
763 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
764 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
765 -mdynamic-no-pic -maltivec -mswdiv @gol
766 -mprioritize-restricted-insns=@var{priority} @gol
767 -msched-costly-dep=@var{dependence_type} @gol
768 -minsert-sched-nops=@var{scheme} @gol
769 -mcall-sysv -mcall-netbsd @gol
770 -maix-struct-return -msvr4-struct-return @gol
771 -mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
772 -misel -mno-isel @gol
773 -misel=yes -misel=no @gol
775 -mspe=yes -mspe=no @gol
777 -mgen-cell-microcode -mwarn-cell-microcode @gol
778 -mvrsave -mno-vrsave @gol
779 -mmulhw -mno-mulhw @gol
780 -mdlmzb -mno-dlmzb @gol
781 -mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
782 -mprototype -mno-prototype @gol
783 -msim -mmvme -mads -myellowknife -memb -msdata @gol
784 -msdata=@var{opt} -mvxworks -G @var{num} -pthread}
787 @gccoptlist{-m64bit-doubles -m32bit-doubles -fpu -nofpu@gol
789 -mbig-endian-data -mlittle-endian-data @gol
792 -mas100-syntax -mno-as100-syntax@gol
794 -mmax-constant-size=@gol
796 -msave-acc-in-interrupts}
798 @emph{S/390 and zSeries Options}
799 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
800 -mhard-float -msoft-float -mhard-dfp -mno-hard-dfp @gol
801 -mlong-double-64 -mlong-double-128 @gol
802 -mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
803 -msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
804 -m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
805 -mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
806 -mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
809 @gccoptlist{-meb -mel @gol
813 -mscore5 -mscore5u -mscore7 -mscore7d}
816 @gccoptlist{-m1 -m2 -m2e @gol
817 -m2a-nofpu -m2a-single-only -m2a-single -m2a @gol
819 -m4-nofpu -m4-single-only -m4-single -m4 @gol
820 -m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
821 -m5-64media -m5-64media-nofpu @gol
822 -m5-32media -m5-32media-nofpu @gol
823 -m5-compact -m5-compact-nofpu @gol
824 -mb -ml -mdalign -mrelax @gol
825 -mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
826 -mieee -mbitops -misize -minline-ic_invalidate -mpadstruct -mspace @gol
827 -mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
828 -mdivsi3_libfunc=@var{name} -mfixed-range=@var{register-range} @gol
829 -madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
830 -maccumulate-outgoing-args -minvalid-symbols}
833 @gccoptlist{-mcpu=@var{cpu-type} @gol
834 -mtune=@var{cpu-type} @gol
835 -mcmodel=@var{code-model} @gol
836 -m32 -m64 -mapp-regs -mno-app-regs @gol
837 -mfaster-structs -mno-faster-structs @gol
838 -mfpu -mno-fpu -mhard-float -msoft-float @gol
839 -mhard-quad-float -msoft-quad-float @gol
840 -mimpure-text -mno-impure-text -mlittle-endian @gol
841 -mstack-bias -mno-stack-bias @gol
842 -munaligned-doubles -mno-unaligned-doubles @gol
843 -mv8plus -mno-v8plus -mvis -mno-vis
844 -threads -pthreads -pthread}
847 @gccoptlist{-mwarn-reloc -merror-reloc @gol
848 -msafe-dma -munsafe-dma @gol
850 -msmall-mem -mlarge-mem -mstdmain @gol
851 -mfixed-range=@var{register-range} @gol
853 -maddress-space-conversion -mno-address-space-conversion @gol
854 -mcache-size=@var{cache-size} @gol
855 -matomic-updates -mno-atomic-updates}
857 @emph{System V Options}
858 @gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
861 @gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
862 -mprolog-function -mno-prolog-function -mspace @gol
863 -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
864 -mapp-regs -mno-app-regs @gol
865 -mdisable-callt -mno-disable-callt @gol
871 @gccoptlist{-mg -mgnu -munix}
873 @emph{VxWorks Options}
874 @gccoptlist{-mrtp -non-static -Bstatic -Bdynamic @gol
875 -Xbind-lazy -Xbind-now}
877 @emph{x86-64 Options}
878 See i386 and x86-64 Options.
880 @emph{i386 and x86-64 Windows Options}
881 @gccoptlist{-mconsole -mcygwin -mno-cygwin -mdll
882 -mnop-fun-dllimport -mthread -municode -mwin32 -mwindows
883 -fno-set-stack-executable}
885 @emph{Xstormy16 Options}
888 @emph{Xtensa Options}
889 @gccoptlist{-mconst16 -mno-const16 @gol
890 -mfused-madd -mno-fused-madd @gol
891 -mserialize-volatile -mno-serialize-volatile @gol
892 -mtext-section-literals -mno-text-section-literals @gol
893 -mtarget-align -mno-target-align @gol
894 -mlongcalls -mno-longcalls}
896 @emph{zSeries Options}
897 See S/390 and zSeries Options.
899 @item Code Generation Options
900 @xref{Code Gen Options,,Options for Code Generation Conventions}.
901 @gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
902 -ffixed-@var{reg} -fexceptions @gol
903 -fnon-call-exceptions -funwind-tables @gol
904 -fasynchronous-unwind-tables @gol
905 -finhibit-size-directive -finstrument-functions @gol
906 -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
907 -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol
908 -fno-common -fno-ident @gol
909 -fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
910 -fno-jump-tables @gol
911 -frecord-gcc-switches @gol
912 -freg-struct-return -fshort-enums @gol
913 -fshort-double -fshort-wchar @gol
914 -fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
915 -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
916 -fno-stack-limit @gol
917 -fleading-underscore -ftls-model=@var{model} @gol
918 -ftrapv -fwrapv -fbounds-check @gol
923 * Overall Options:: Controlling the kind of output:
924 an executable, object files, assembler files,
925 or preprocessed source.
926 * C Dialect Options:: Controlling the variant of C language compiled.
927 * C++ Dialect Options:: Variations on C++.
928 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
930 * Language Independent Options:: Controlling how diagnostics should be
932 * Warning Options:: How picky should the compiler be?
933 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
934 * Optimize Options:: How much optimization?
935 * Preprocessor Options:: Controlling header files and macro definitions.
936 Also, getting dependency information for Make.
937 * Assembler Options:: Passing options to the assembler.
938 * Link Options:: Specifying libraries and so on.
939 * Directory Options:: Where to find header files and libraries.
940 Where to find the compiler executable files.
941 * Spec Files:: How to pass switches to sub-processes.
942 * Target Options:: Running a cross-compiler, or an old version of GCC.
945 @node Overall Options
946 @section Options Controlling the Kind of Output
948 Compilation can involve up to four stages: preprocessing, compilation
949 proper, assembly and linking, always in that order. GCC is capable of
950 preprocessing and compiling several files either into several
951 assembler input files, or into one assembler input file; then each
952 assembler input file produces an object file, and linking combines all
953 the object files (those newly compiled, and those specified as input)
954 into an executable file.
956 @cindex file name suffix
957 For any given input file, the file name suffix determines what kind of
962 C source code which must be preprocessed.
965 C source code which should not be preprocessed.
968 C++ source code which should not be preprocessed.
971 Objective-C source code. Note that you must link with the @file{libobjc}
972 library to make an Objective-C program work.
975 Objective-C source code which should not be preprocessed.
979 Objective-C++ source code. Note that you must link with the @file{libobjc}
980 library to make an Objective-C++ program work. Note that @samp{.M} refers
981 to a literal capital M@.
984 Objective-C++ source code which should not be preprocessed.
987 C, C++, Objective-C or Objective-C++ header file to be turned into a
992 @itemx @var{file}.cxx
993 @itemx @var{file}.cpp
994 @itemx @var{file}.CPP
995 @itemx @var{file}.c++
997 C++ source code which must be preprocessed. Note that in @samp{.cxx},
998 the last two letters must both be literally @samp{x}. Likewise,
999 @samp{.C} refers to a literal capital C@.
1003 Objective-C++ source code which must be preprocessed.
1005 @item @var{file}.mii
1006 Objective-C++ source code which should not be preprocessed.
1010 @itemx @var{file}.hp
1011 @itemx @var{file}.hxx
1012 @itemx @var{file}.hpp
1013 @itemx @var{file}.HPP
1014 @itemx @var{file}.h++
1015 @itemx @var{file}.tcc
1016 C++ header file to be turned into a precompiled header.
1019 @itemx @var{file}.for
1020 @itemx @var{file}.ftn
1021 Fixed form Fortran source code which should not be preprocessed.
1024 @itemx @var{file}.FOR
1025 @itemx @var{file}.fpp
1026 @itemx @var{file}.FPP
1027 @itemx @var{file}.FTN
1028 Fixed form Fortran source code which must be preprocessed (with the traditional
1031 @item @var{file}.f90
1032 @itemx @var{file}.f95
1033 @itemx @var{file}.f03
1034 @itemx @var{file}.f08
1035 Free form Fortran source code which should not be preprocessed.
1037 @item @var{file}.F90
1038 @itemx @var{file}.F95
1039 @itemx @var{file}.F03
1040 @itemx @var{file}.F08
1041 Free form Fortran source code which must be preprocessed (with the
1042 traditional preprocessor).
1044 @c FIXME: Descriptions of Java file types.
1050 @item @var{file}.ads
1051 Ada source code file which contains a library unit declaration (a
1052 declaration of a package, subprogram, or generic, or a generic
1053 instantiation), or a library unit renaming declaration (a package,
1054 generic, or subprogram renaming declaration). Such files are also
1057 @item @var{file}.adb
1058 Ada source code file containing a library unit body (a subprogram or
1059 package body). Such files are also called @dfn{bodies}.
1061 @c GCC also knows about some suffixes for languages not yet included:
1072 @itemx @var{file}.sx
1073 Assembler code which must be preprocessed.
1076 An object file to be fed straight into linking.
1077 Any file name with no recognized suffix is treated this way.
1081 You can specify the input language explicitly with the @option{-x} option:
1084 @item -x @var{language}
1085 Specify explicitly the @var{language} for the following input files
1086 (rather than letting the compiler choose a default based on the file
1087 name suffix). This option applies to all following input files until
1088 the next @option{-x} option. Possible values for @var{language} are:
1090 c c-header c-cpp-output
1091 c++ c++-header c++-cpp-output
1092 objective-c objective-c-header objective-c-cpp-output
1093 objective-c++ objective-c++-header objective-c++-cpp-output
1094 assembler assembler-with-cpp
1096 f77 f77-cpp-input f95 f95-cpp-input
1101 Turn off any specification of a language, so that subsequent files are
1102 handled according to their file name suffixes (as they are if @option{-x}
1103 has not been used at all).
1105 @item -pass-exit-codes
1106 @opindex pass-exit-codes
1107 Normally the @command{gcc} program will exit with the code of 1 if any
1108 phase of the compiler returns a non-success return code. If you specify
1109 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
1110 numerically highest error produced by any phase that returned an error
1111 indication. The C, C++, and Fortran frontends return 4, if an internal
1112 compiler error is encountered.
1115 If you only want some of the stages of compilation, you can use
1116 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
1117 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
1118 @command{gcc} is to stop. Note that some combinations (for example,
1119 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
1124 Compile or assemble the source files, but do not link. The linking
1125 stage simply is not done. The ultimate output is in the form of an
1126 object file for each source file.
1128 By default, the object file name for a source file is made by replacing
1129 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
1131 Unrecognized input files, not requiring compilation or assembly, are
1136 Stop after the stage of compilation proper; do not assemble. The output
1137 is in the form of an assembler code file for each non-assembler input
1140 By default, the assembler file name for a source file is made by
1141 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1143 Input files that don't require compilation are ignored.
1147 Stop after the preprocessing stage; do not run the compiler proper. The
1148 output is in the form of preprocessed source code, which is sent to the
1151 Input files which don't require preprocessing are ignored.
1153 @cindex output file option
1156 Place output in file @var{file}. This applies regardless to whatever
1157 sort of output is being produced, whether it be an executable file,
1158 an object file, an assembler file or preprocessed C code.
1160 If @option{-o} is not specified, the default is to put an executable
1161 file in @file{a.out}, the object file for
1162 @file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1163 assembler file in @file{@var{source}.s}, a precompiled header file in
1164 @file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1169 Print (on standard error output) the commands executed to run the stages
1170 of compilation. Also print the version number of the compiler driver
1171 program and of the preprocessor and the compiler proper.
1175 Like @option{-v} except the commands are not executed and arguments
1176 are quoted unless they contain only alphanumeric characters or @code{./-_}.
1177 This is useful for shell scripts to capture the driver-generated command lines.
1181 Use pipes rather than temporary files for communication between the
1182 various stages of compilation. This fails to work on some systems where
1183 the assembler is unable to read from a pipe; but the GNU assembler has
1188 If you are compiling multiple source files, this option tells the driver
1189 to pass all the source files to the compiler at once (for those
1190 languages for which the compiler can handle this). This will allow
1191 intermodule analysis (IMA) to be performed by the compiler. Currently the only
1192 language for which this is supported is C@. If you pass source files for
1193 multiple languages to the driver, using this option, the driver will invoke
1194 the compiler(s) that support IMA once each, passing each compiler all the
1195 source files appropriate for it. For those languages that do not support
1196 IMA this option will be ignored, and the compiler will be invoked once for
1197 each source file in that language. If you use this option in conjunction
1198 with @option{-save-temps}, the compiler will generate multiple
1200 (one for each source file), but only one (combined) @file{.o} or
1205 Print (on the standard output) a description of the command line options
1206 understood by @command{gcc}. If the @option{-v} option is also specified
1207 then @option{--help} will also be passed on to the various processes
1208 invoked by @command{gcc}, so that they can display the command line options
1209 they accept. If the @option{-Wextra} option has also been specified
1210 (prior to the @option{--help} option), then command line options which
1211 have no documentation associated with them will also be displayed.
1214 @opindex target-help
1215 Print (on the standard output) a description of target-specific command
1216 line options for each tool. For some targets extra target-specific
1217 information may also be printed.
1219 @item --help=@{@var{class}@r{|[}^@r{]}@var{qualifier}@}@r{[},@dots{}@r{]}
1220 Print (on the standard output) a description of the command line
1221 options understood by the compiler that fit into all specified classes
1222 and qualifiers. These are the supported classes:
1225 @item @samp{optimizers}
1226 This will display all of the optimization options supported by the
1229 @item @samp{warnings}
1230 This will display all of the options controlling warning messages
1231 produced by the compiler.
1234 This will display target-specific options. Unlike the
1235 @option{--target-help} option however, target-specific options of the
1236 linker and assembler will not be displayed. This is because those
1237 tools do not currently support the extended @option{--help=} syntax.
1240 This will display the values recognized by the @option{--param}
1243 @item @var{language}
1244 This will display the options supported for @var{language}, where
1245 @var{language} is the name of one of the languages supported in this
1249 This will display the options that are common to all languages.
1252 These are the supported qualifiers:
1255 @item @samp{undocumented}
1256 Display only those options which are undocumented.
1259 Display options which take an argument that appears after an equal
1260 sign in the same continuous piece of text, such as:
1261 @samp{--help=target}.
1263 @item @samp{separate}
1264 Display options which take an argument that appears as a separate word
1265 following the original option, such as: @samp{-o output-file}.
1268 Thus for example to display all the undocumented target-specific
1269 switches supported by the compiler the following can be used:
1272 --help=target,undocumented
1275 The sense of a qualifier can be inverted by prefixing it with the
1276 @samp{^} character, so for example to display all binary warning
1277 options (i.e., ones that are either on or off and that do not take an
1278 argument), which have a description the following can be used:
1281 --help=warnings,^joined,^undocumented
1284 The argument to @option{--help=} should not consist solely of inverted
1287 Combining several classes is possible, although this usually
1288 restricts the output by so much that there is nothing to display. One
1289 case where it does work however is when one of the classes is
1290 @var{target}. So for example to display all the target-specific
1291 optimization options the following can be used:
1294 --help=target,optimizers
1297 The @option{--help=} option can be repeated on the command line. Each
1298 successive use will display its requested class of options, skipping
1299 those that have already been displayed.
1301 If the @option{-Q} option appears on the command line before the
1302 @option{--help=} option, then the descriptive text displayed by
1303 @option{--help=} is changed. Instead of describing the displayed
1304 options, an indication is given as to whether the option is enabled,
1305 disabled or set to a specific value (assuming that the compiler
1306 knows this at the point where the @option{--help=} option is used).
1308 Here is a truncated example from the ARM port of @command{gcc}:
1311 % gcc -Q -mabi=2 --help=target -c
1312 The following options are target specific:
1314 -mabort-on-noreturn [disabled]
1318 The output is sensitive to the effects of previous command line
1319 options, so for example it is possible to find out which optimizations
1320 are enabled at @option{-O2} by using:
1323 -Q -O2 --help=optimizers
1326 Alternatively you can discover which binary optimizations are enabled
1327 by @option{-O3} by using:
1330 gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
1331 gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
1332 diff /tmp/O2-opts /tmp/O3-opts | grep enabled
1335 @item -no-canonical-prefixes
1336 @opindex no-canonical-prefixes
1337 Do not expand any symbolic links, resolve references to @samp{/../}
1338 or @samp{/./}, or make the path absolute when generating a relative
1343 Display the version number and copyrights of the invoked GCC@.
1347 Invoke all subcommands under a wrapper program. It takes a single
1348 comma separated list as an argument, which will be used to invoke
1352 gcc -c t.c -wrapper gdb,--args
1355 This will invoke all subprograms of gcc under "gdb --args",
1356 thus cc1 invocation will be "gdb --args cc1 ...".
1358 @item -fplugin=@var{name}.so
1359 Load the plugin code in file @var{name}.so, assumed to be a
1360 shared object to be dlopen'd by the compiler. The base name of
1361 the shared object file is used to identify the plugin for the
1362 purposes of argument parsing (See
1363 @option{-fplugin-arg-@var{name}-@var{key}=@var{value}} below).
1364 Each plugin should define the callback functions specified in the
1367 @item -fplugin-arg-@var{name}-@var{key}=@var{value}
1368 Define an argument called @var{key} with a value of @var{value}
1369 for the plugin called @var{name}.
1371 @include @value{srcdir}/../libiberty/at-file.texi
1375 @section Compiling C++ Programs
1377 @cindex suffixes for C++ source
1378 @cindex C++ source file suffixes
1379 C++ source files conventionally use one of the suffixes @samp{.C},
1380 @samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1381 @samp{.cxx}; C++ header files often use @samp{.hh}, @samp{.hpp},
1382 @samp{.H}, or (for shared template code) @samp{.tcc}; and
1383 preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1384 files with these names and compiles them as C++ programs even if you
1385 call the compiler the same way as for compiling C programs (usually
1386 with the name @command{gcc}).
1390 However, the use of @command{gcc} does not add the C++ library.
1391 @command{g++} is a program that calls GCC and treats @samp{.c},
1392 @samp{.h} and @samp{.i} files as C++ source files instead of C source
1393 files unless @option{-x} is used, and automatically specifies linking
1394 against the C++ library. This program is also useful when
1395 precompiling a C header file with a @samp{.h} extension for use in C++
1396 compilations. On many systems, @command{g++} is also installed with
1397 the name @command{c++}.
1399 @cindex invoking @command{g++}
1400 When you compile C++ programs, you may specify many of the same
1401 command-line options that you use for compiling programs in any
1402 language; or command-line options meaningful for C and related
1403 languages; or options that are meaningful only for C++ programs.
1404 @xref{C Dialect Options,,Options Controlling C Dialect}, for
1405 explanations of options for languages related to C@.
1406 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1407 explanations of options that are meaningful only for C++ programs.
1409 @node C Dialect Options
1410 @section Options Controlling C Dialect
1411 @cindex dialect options
1412 @cindex language dialect options
1413 @cindex options, dialect
1415 The following options control the dialect of C (or languages derived
1416 from C, such as C++, Objective-C and Objective-C++) that the compiler
1420 @cindex ANSI support
1424 In C mode, this is equivalent to @samp{-std=c90}. In C++ mode, it is
1425 equivalent to @samp{-std=c++98}.
1427 This turns off certain features of GCC that are incompatible with ISO
1428 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1429 such as the @code{asm} and @code{typeof} keywords, and
1430 predefined macros such as @code{unix} and @code{vax} that identify the
1431 type of system you are using. It also enables the undesirable and
1432 rarely used ISO trigraph feature. For the C compiler,
1433 it disables recognition of C++ style @samp{//} comments as well as
1434 the @code{inline} keyword.
1436 The alternate keywords @code{__asm__}, @code{__extension__},
1437 @code{__inline__} and @code{__typeof__} continue to work despite
1438 @option{-ansi}. You would not want to use them in an ISO C program, of
1439 course, but it is useful to put them in header files that might be included
1440 in compilations done with @option{-ansi}. Alternate predefined macros
1441 such as @code{__unix__} and @code{__vax__} are also available, with or
1442 without @option{-ansi}.
1444 The @option{-ansi} option does not cause non-ISO programs to be
1445 rejected gratuitously. For that, @option{-pedantic} is required in
1446 addition to @option{-ansi}. @xref{Warning Options}.
1448 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1449 option is used. Some header files may notice this macro and refrain
1450 from declaring certain functions or defining certain macros that the
1451 ISO standard doesn't call for; this is to avoid interfering with any
1452 programs that might use these names for other things.
1454 Functions that would normally be built in but do not have semantics
1455 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1456 functions when @option{-ansi} is used. @xref{Other Builtins,,Other
1457 built-in functions provided by GCC}, for details of the functions
1462 Determine the language standard. @xref{Standards,,Language Standards
1463 Supported by GCC}, for details of these standard versions. This option
1464 is currently only supported when compiling C or C++.
1466 The compiler can accept several base standards, such as @samp{c90} or
1467 @samp{c++98}, and GNU dialects of those standards, such as
1468 @samp{gnu90} or @samp{gnu++98}. By specifying a base standard, the
1469 compiler will accept all programs following that standard and those
1470 using GNU extensions that do not contradict it. For example,
1471 @samp{-std=c90} turns off certain features of GCC that are
1472 incompatible with ISO C90, such as the @code{asm} and @code{typeof}
1473 keywords, but not other GNU extensions that do not have a meaning in
1474 ISO C90, such as omitting the middle term of a @code{?:}
1475 expression. On the other hand, by specifying a GNU dialect of a
1476 standard, all features the compiler support are enabled, even when
1477 those features change the meaning of the base standard and some
1478 strict-conforming programs may be rejected. The particular standard
1479 is used by @option{-pedantic} to identify which features are GNU
1480 extensions given that version of the standard. For example
1481 @samp{-std=gnu90 -pedantic} would warn about C++ style @samp{//}
1482 comments, while @samp{-std=gnu99 -pedantic} would not.
1484 A value for this option must be provided; possible values are
1490 Support all ISO C90 programs (certain GNU extensions that conflict
1491 with ISO C90 are disabled). Same as @option{-ansi} for C code.
1493 @item iso9899:199409
1494 ISO C90 as modified in amendment 1.
1500 ISO C99. Note that this standard is not yet fully supported; see
1501 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The
1502 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1505 ISO C1X, the draft of the next revision of the ISO C standard.
1506 Support is limited and experimental and features enabled by this
1507 option may be changed or removed if changed in or removed from the
1512 GNU dialect of ISO C90 (including some C99 features). This
1513 is the default for C code.
1517 GNU dialect of ISO C99. When ISO C99 is fully implemented in GCC,
1518 this will become the default. The name @samp{gnu9x} is deprecated.
1521 GNU dialect of ISO C1X. Support is limited and experimental and
1522 features enabled by this option may be changed or removed if changed
1523 in or removed from the standard draft.
1526 The 1998 ISO C++ standard plus amendments. Same as @option{-ansi} for
1530 GNU dialect of @option{-std=c++98}. This is the default for
1534 The working draft of the upcoming ISO C++0x standard. This option
1535 enables experimental features that are likely to be included in
1536 C++0x. The working draft is constantly changing, and any feature that is
1537 enabled by this flag may be removed from future versions of GCC if it is
1538 not part of the C++0x standard.
1541 GNU dialect of @option{-std=c++0x}. This option enables
1542 experimental features that may be removed in future versions of GCC.
1545 @item -fgnu89-inline
1546 @opindex fgnu89-inline
1547 The option @option{-fgnu89-inline} tells GCC to use the traditional
1548 GNU semantics for @code{inline} functions when in C99 mode.
1549 @xref{Inline,,An Inline Function is As Fast As a Macro}. This option
1550 is accepted and ignored by GCC versions 4.1.3 up to but not including
1551 4.3. In GCC versions 4.3 and later it changes the behavior of GCC in
1552 C99 mode. Using this option is roughly equivalent to adding the
1553 @code{gnu_inline} function attribute to all inline functions
1554 (@pxref{Function Attributes}).
1556 The option @option{-fno-gnu89-inline} explicitly tells GCC to use the
1557 C99 semantics for @code{inline} when in C99 or gnu99 mode (i.e., it
1558 specifies the default behavior). This option was first supported in
1559 GCC 4.3. This option is not supported in @option{-std=c90} or
1560 @option{-std=gnu90} mode.
1562 The preprocessor macros @code{__GNUC_GNU_INLINE__} and
1563 @code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1564 in effect for @code{inline} functions. @xref{Common Predefined
1565 Macros,,,cpp,The C Preprocessor}.
1567 @item -aux-info @var{filename}
1569 Output to the given filename prototyped declarations for all functions
1570 declared and/or defined in a translation unit, including those in header
1571 files. This option is silently ignored in any language other than C@.
1573 Besides declarations, the file indicates, in comments, the origin of
1574 each declaration (source file and line), whether the declaration was
1575 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1576 @samp{O} for old, respectively, in the first character after the line
1577 number and the colon), and whether it came from a declaration or a
1578 definition (@samp{C} or @samp{F}, respectively, in the following
1579 character). In the case of function definitions, a K&R-style list of
1580 arguments followed by their declarations is also provided, inside
1581 comments, after the declaration.
1585 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1586 keyword, so that code can use these words as identifiers. You can use
1587 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1588 instead. @option{-ansi} implies @option{-fno-asm}.
1590 In C++, this switch only affects the @code{typeof} keyword, since
1591 @code{asm} and @code{inline} are standard keywords. You may want to
1592 use the @option{-fno-gnu-keywords} flag instead, which has the same
1593 effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1594 switch only affects the @code{asm} and @code{typeof} keywords, since
1595 @code{inline} is a standard keyword in ISO C99.
1598 @itemx -fno-builtin-@var{function}
1599 @opindex fno-builtin
1600 @cindex built-in functions
1601 Don't recognize built-in functions that do not begin with
1602 @samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1603 functions provided by GCC}, for details of the functions affected,
1604 including those which are not built-in functions when @option{-ansi} or
1605 @option{-std} options for strict ISO C conformance are used because they
1606 do not have an ISO standard meaning.
1608 GCC normally generates special code to handle certain built-in functions
1609 more efficiently; for instance, calls to @code{alloca} may become single
1610 instructions that adjust the stack directly, and calls to @code{memcpy}
1611 may become inline copy loops. The resulting code is often both smaller
1612 and faster, but since the function calls no longer appear as such, you
1613 cannot set a breakpoint on those calls, nor can you change the behavior
1614 of the functions by linking with a different library. In addition,
1615 when a function is recognized as a built-in function, GCC may use
1616 information about that function to warn about problems with calls to
1617 that function, or to generate more efficient code, even if the
1618 resulting code still contains calls to that function. For example,
1619 warnings are given with @option{-Wformat} for bad calls to
1620 @code{printf}, when @code{printf} is built in, and @code{strlen} is
1621 known not to modify global memory.
1623 With the @option{-fno-builtin-@var{function}} option
1624 only the built-in function @var{function} is
1625 disabled. @var{function} must not begin with @samp{__builtin_}. If a
1626 function is named that is not built-in in this version of GCC, this
1627 option is ignored. There is no corresponding
1628 @option{-fbuiltin-@var{function}} option; if you wish to enable
1629 built-in functions selectively when using @option{-fno-builtin} or
1630 @option{-ffreestanding}, you may define macros such as:
1633 #define abs(n) __builtin_abs ((n))
1634 #define strcpy(d, s) __builtin_strcpy ((d), (s))
1639 @cindex hosted environment
1641 Assert that compilation takes place in a hosted environment. This implies
1642 @option{-fbuiltin}. A hosted environment is one in which the
1643 entire standard library is available, and in which @code{main} has a return
1644 type of @code{int}. Examples are nearly everything except a kernel.
1645 This is equivalent to @option{-fno-freestanding}.
1647 @item -ffreestanding
1648 @opindex ffreestanding
1649 @cindex hosted environment
1651 Assert that compilation takes place in a freestanding environment. This
1652 implies @option{-fno-builtin}. A freestanding environment
1653 is one in which the standard library may not exist, and program startup may
1654 not necessarily be at @code{main}. The most obvious example is an OS kernel.
1655 This is equivalent to @option{-fno-hosted}.
1657 @xref{Standards,,Language Standards Supported by GCC}, for details of
1658 freestanding and hosted environments.
1662 @cindex openmp parallel
1663 Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1664 @code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1665 compiler generates parallel code according to the OpenMP Application
1666 Program Interface v3.0 @w{@uref{http://www.openmp.org/}}. This option
1667 implies @option{-pthread}, and thus is only supported on targets that
1668 have support for @option{-pthread}.
1670 @item -fms-extensions
1671 @opindex fms-extensions
1672 Accept some non-standard constructs used in Microsoft header files.
1674 Some cases of unnamed fields in structures and unions are only
1675 accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1676 fields within structs/unions}, for details.
1680 Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1681 options for strict ISO C conformance) implies @option{-trigraphs}.
1683 @item -no-integrated-cpp
1684 @opindex no-integrated-cpp
1685 Performs a compilation in two passes: preprocessing and compiling. This
1686 option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1687 @option{-B} option. The user supplied compilation step can then add in
1688 an additional preprocessing step after normal preprocessing but before
1689 compiling. The default is to use the integrated cpp (internal cpp)
1691 The semantics of this option will change if "cc1", "cc1plus", and
1692 "cc1obj" are merged.
1694 @cindex traditional C language
1695 @cindex C language, traditional
1697 @itemx -traditional-cpp
1698 @opindex traditional-cpp
1699 @opindex traditional
1700 Formerly, these options caused GCC to attempt to emulate a pre-standard
1701 C compiler. They are now only supported with the @option{-E} switch.
1702 The preprocessor continues to support a pre-standard mode. See the GNU
1703 CPP manual for details.
1705 @item -fcond-mismatch
1706 @opindex fcond-mismatch
1707 Allow conditional expressions with mismatched types in the second and
1708 third arguments. The value of such an expression is void. This option
1709 is not supported for C++.
1711 @item -flax-vector-conversions
1712 @opindex flax-vector-conversions
1713 Allow implicit conversions between vectors with differing numbers of
1714 elements and/or incompatible element types. This option should not be
1717 @item -funsigned-char
1718 @opindex funsigned-char
1719 Let the type @code{char} be unsigned, like @code{unsigned char}.
1721 Each kind of machine has a default for what @code{char} should
1722 be. It is either like @code{unsigned char} by default or like
1723 @code{signed char} by default.
1725 Ideally, a portable program should always use @code{signed char} or
1726 @code{unsigned char} when it depends on the signedness of an object.
1727 But many programs have been written to use plain @code{char} and
1728 expect it to be signed, or expect it to be unsigned, depending on the
1729 machines they were written for. This option, and its inverse, let you
1730 make such a program work with the opposite default.
1732 The type @code{char} is always a distinct type from each of
1733 @code{signed char} or @code{unsigned char}, even though its behavior
1734 is always just like one of those two.
1737 @opindex fsigned-char
1738 Let the type @code{char} be signed, like @code{signed char}.
1740 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1741 the negative form of @option{-funsigned-char}. Likewise, the option
1742 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1744 @item -fsigned-bitfields
1745 @itemx -funsigned-bitfields
1746 @itemx -fno-signed-bitfields
1747 @itemx -fno-unsigned-bitfields
1748 @opindex fsigned-bitfields
1749 @opindex funsigned-bitfields
1750 @opindex fno-signed-bitfields
1751 @opindex fno-unsigned-bitfields
1752 These options control whether a bit-field is signed or unsigned, when the
1753 declaration does not use either @code{signed} or @code{unsigned}. By
1754 default, such a bit-field is signed, because this is consistent: the
1755 basic integer types such as @code{int} are signed types.
1758 @node C++ Dialect Options
1759 @section Options Controlling C++ Dialect
1761 @cindex compiler options, C++
1762 @cindex C++ options, command line
1763 @cindex options, C++
1764 This section describes the command-line options that are only meaningful
1765 for C++ programs; but you can also use most of the GNU compiler options
1766 regardless of what language your program is in. For example, you
1767 might compile a file @code{firstClass.C} like this:
1770 g++ -g -frepo -O -c firstClass.C
1774 In this example, only @option{-frepo} is an option meant
1775 only for C++ programs; you can use the other options with any
1776 language supported by GCC@.
1778 Here is a list of options that are @emph{only} for compiling C++ programs:
1782 @item -fabi-version=@var{n}
1783 @opindex fabi-version
1784 Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1785 C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1786 the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1787 the version that conforms most closely to the C++ ABI specification.
1788 Therefore, the ABI obtained using version 0 will change as ABI bugs
1791 The default is version 2.
1793 Version 3 corrects an error in mangling a constant address as a
1796 Version 4 implements a standard mangling for vector types.
1798 See also @option{-Wabi}.
1800 @item -fno-access-control
1801 @opindex fno-access-control
1802 Turn off all access checking. This switch is mainly useful for working
1803 around bugs in the access control code.
1807 Check that the pointer returned by @code{operator new} is non-null
1808 before attempting to modify the storage allocated. This check is
1809 normally unnecessary because the C++ standard specifies that
1810 @code{operator new} will only return @code{0} if it is declared
1811 @samp{throw()}, in which case the compiler will always check the
1812 return value even without this option. In all other cases, when
1813 @code{operator new} has a non-empty exception specification, memory
1814 exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1815 @samp{new (nothrow)}.
1817 @item -fconserve-space
1818 @opindex fconserve-space
1819 Put uninitialized or runtime-initialized global variables into the
1820 common segment, as C does. This saves space in the executable at the
1821 cost of not diagnosing duplicate definitions. If you compile with this
1822 flag and your program mysteriously crashes after @code{main()} has
1823 completed, you may have an object that is being destroyed twice because
1824 two definitions were merged.
1826 This option is no longer useful on most targets, now that support has
1827 been added for putting variables into BSS without making them common.
1829 @item -fno-deduce-init-list
1830 @opindex fno-deduce-init-list
1831 Disable deduction of a template type parameter as
1832 std::initializer_list from a brace-enclosed initializer list, i.e.
1835 template <class T> auto forward(T t) -> decltype (realfn (t))
1842 forward(@{1,2@}); // call forward<std::initializer_list<int>>
1846 This option is present because this deduction is an extension to the
1847 current specification in the C++0x working draft, and there was
1848 some concern about potential overload resolution problems.
1850 @item -ffriend-injection
1851 @opindex ffriend-injection
1852 Inject friend functions into the enclosing namespace, so that they are
1853 visible outside the scope of the class in which they are declared.
1854 Friend functions were documented to work this way in the old Annotated
1855 C++ Reference Manual, and versions of G++ before 4.1 always worked
1856 that way. However, in ISO C++ a friend function which is not declared
1857 in an enclosing scope can only be found using argument dependent
1858 lookup. This option causes friends to be injected as they were in
1861 This option is for compatibility, and may be removed in a future
1864 @item -fno-elide-constructors
1865 @opindex fno-elide-constructors
1866 The C++ standard allows an implementation to omit creating a temporary
1867 which is only used to initialize another object of the same type.
1868 Specifying this option disables that optimization, and forces G++ to
1869 call the copy constructor in all cases.
1871 @item -fno-enforce-eh-specs
1872 @opindex fno-enforce-eh-specs
1873 Don't generate code to check for violation of exception specifications
1874 at runtime. This option violates the C++ standard, but may be useful
1875 for reducing code size in production builds, much like defining
1876 @samp{NDEBUG}. This does not give user code permission to throw
1877 exceptions in violation of the exception specifications; the compiler
1878 will still optimize based on the specifications, so throwing an
1879 unexpected exception will result in undefined behavior.
1882 @itemx -fno-for-scope
1884 @opindex fno-for-scope
1885 If @option{-ffor-scope} is specified, the scope of variables declared in
1886 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1887 as specified by the C++ standard.
1888 If @option{-fno-for-scope} is specified, the scope of variables declared in
1889 a @i{for-init-statement} extends to the end of the enclosing scope,
1890 as was the case in old versions of G++, and other (traditional)
1891 implementations of C++.
1893 The default if neither flag is given to follow the standard,
1894 but to allow and give a warning for old-style code that would
1895 otherwise be invalid, or have different behavior.
1897 @item -fno-gnu-keywords
1898 @opindex fno-gnu-keywords
1899 Do not recognize @code{typeof} as a keyword, so that code can use this
1900 word as an identifier. You can use the keyword @code{__typeof__} instead.
1901 @option{-ansi} implies @option{-fno-gnu-keywords}.
1903 @item -fno-implicit-templates
1904 @opindex fno-implicit-templates
1905 Never emit code for non-inline templates which are instantiated
1906 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1907 @xref{Template Instantiation}, for more information.
1909 @item -fno-implicit-inline-templates
1910 @opindex fno-implicit-inline-templates
1911 Don't emit code for implicit instantiations of inline templates, either.
1912 The default is to handle inlines differently so that compiles with and
1913 without optimization will need the same set of explicit instantiations.
1915 @item -fno-implement-inlines
1916 @opindex fno-implement-inlines
1917 To save space, do not emit out-of-line copies of inline functions
1918 controlled by @samp{#pragma implementation}. This will cause linker
1919 errors if these functions are not inlined everywhere they are called.
1921 @item -fms-extensions
1922 @opindex fms-extensions
1923 Disable pedantic warnings about constructs used in MFC, such as implicit
1924 int and getting a pointer to member function via non-standard syntax.
1926 @item -fno-nonansi-builtins
1927 @opindex fno-nonansi-builtins
1928 Disable built-in declarations of functions that are not mandated by
1929 ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1930 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1933 @opindex fnothrow-opt
1934 Treat a @code{throw()} exception specification as though it were a
1935 @code{noexcept} specification to reduce or eliminate the text size
1936 overhead relative to a function with no exception specification. The
1937 semantic effect is that an exception thrown out of a function with
1938 such an exception specification will result in a call to
1939 @code{terminate} rather than @code{unexpected}.
1941 @item -fno-operator-names
1942 @opindex fno-operator-names
1943 Do not treat the operator name keywords @code{and}, @code{bitand},
1944 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1945 synonyms as keywords.
1947 @item -fno-optional-diags
1948 @opindex fno-optional-diags
1949 Disable diagnostics that the standard says a compiler does not need to
1950 issue. Currently, the only such diagnostic issued by G++ is the one for
1951 a name having multiple meanings within a class.
1954 @opindex fpermissive
1955 Downgrade some diagnostics about nonconformant code from errors to
1956 warnings. Thus, using @option{-fpermissive} will allow some
1957 nonconforming code to compile.
1959 @item -fno-pretty-templates
1960 @opindex fno-pretty-templates
1961 When an error message refers to a specialization of a function
1962 template, the compiler will normally print the signature of the
1963 template followed by the template arguments and any typedefs or
1964 typenames in the signature (e.g. @code{void f(T) [with T = int]}
1965 rather than @code{void f(int)}) so that it's clear which template is
1966 involved. When an error message refers to a specialization of a class
1967 template, the compiler will omit any template arguments which match
1968 the default template arguments for that template. If either of these
1969 behaviors make it harder to understand the error message rather than
1970 easier, using @option{-fno-pretty-templates} will disable them.
1974 Enable automatic template instantiation at link time. This option also
1975 implies @option{-fno-implicit-templates}. @xref{Template
1976 Instantiation}, for more information.
1980 Disable generation of information about every class with virtual
1981 functions for use by the C++ runtime type identification features
1982 (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1983 of the language, you can save some space by using this flag. Note that
1984 exception handling uses the same information, but it will generate it as
1985 needed. The @samp{dynamic_cast} operator can still be used for casts that
1986 do not require runtime type information, i.e.@: casts to @code{void *} or to
1987 unambiguous base classes.
1991 Emit statistics about front-end processing at the end of the compilation.
1992 This information is generally only useful to the G++ development team.
1994 @item -fstrict-enums
1995 @opindex fstrict-enums
1996 Allow the compiler to optimize using the assumption that a value of
1997 enumeration type can only be one of the values of the enumeration (as
1998 defined in the C++ standard; basically, a value which can be
1999 represented in the minimum number of bits needed to represent all the
2000 enumerators). This assumption may not be valid if the program uses a
2001 cast to convert an arbitrary integer value to the enumeration type.
2003 @item -ftemplate-depth=@var{n}
2004 @opindex ftemplate-depth
2005 Set the maximum instantiation depth for template classes to @var{n}.
2006 A limit on the template instantiation depth is needed to detect
2007 endless recursions during template class instantiation. ANSI/ISO C++
2008 conforming programs must not rely on a maximum depth greater than 17
2009 (changed to 1024 in C++0x).
2011 @item -fno-threadsafe-statics
2012 @opindex fno-threadsafe-statics
2013 Do not emit the extra code to use the routines specified in the C++
2014 ABI for thread-safe initialization of local statics. You can use this
2015 option to reduce code size slightly in code that doesn't need to be
2018 @item -fuse-cxa-atexit
2019 @opindex fuse-cxa-atexit
2020 Register destructors for objects with static storage duration with the
2021 @code{__cxa_atexit} function rather than the @code{atexit} function.
2022 This option is required for fully standards-compliant handling of static
2023 destructors, but will only work if your C library supports
2024 @code{__cxa_atexit}.
2026 @item -fno-use-cxa-get-exception-ptr
2027 @opindex fno-use-cxa-get-exception-ptr
2028 Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
2029 will cause @code{std::uncaught_exception} to be incorrect, but is necessary
2030 if the runtime routine is not available.
2032 @item -fvisibility-inlines-hidden
2033 @opindex fvisibility-inlines-hidden
2034 This switch declares that the user does not attempt to compare
2035 pointers to inline methods where the addresses of the two functions
2036 were taken in different shared objects.
2038 The effect of this is that GCC may, effectively, mark inline methods with
2039 @code{__attribute__ ((visibility ("hidden")))} so that they do not
2040 appear in the export table of a DSO and do not require a PLT indirection
2041 when used within the DSO@. Enabling this option can have a dramatic effect
2042 on load and link times of a DSO as it massively reduces the size of the
2043 dynamic export table when the library makes heavy use of templates.
2045 The behavior of this switch is not quite the same as marking the
2046 methods as hidden directly, because it does not affect static variables
2047 local to the function or cause the compiler to deduce that
2048 the function is defined in only one shared object.
2050 You may mark a method as having a visibility explicitly to negate the
2051 effect of the switch for that method. For example, if you do want to
2052 compare pointers to a particular inline method, you might mark it as
2053 having default visibility. Marking the enclosing class with explicit
2054 visibility will have no effect.
2056 Explicitly instantiated inline methods are unaffected by this option
2057 as their linkage might otherwise cross a shared library boundary.
2058 @xref{Template Instantiation}.
2060 @item -fvisibility-ms-compat
2061 @opindex fvisibility-ms-compat
2062 This flag attempts to use visibility settings to make GCC's C++
2063 linkage model compatible with that of Microsoft Visual Studio.
2065 The flag makes these changes to GCC's linkage model:
2069 It sets the default visibility to @code{hidden}, like
2070 @option{-fvisibility=hidden}.
2073 Types, but not their members, are not hidden by default.
2076 The One Definition Rule is relaxed for types without explicit
2077 visibility specifications which are defined in more than one different
2078 shared object: those declarations are permitted if they would have
2079 been permitted when this option was not used.
2082 In new code it is better to use @option{-fvisibility=hidden} and
2083 export those classes which are intended to be externally visible.
2084 Unfortunately it is possible for code to rely, perhaps accidentally,
2085 on the Visual Studio behavior.
2087 Among the consequences of these changes are that static data members
2088 of the same type with the same name but defined in different shared
2089 objects will be different, so changing one will not change the other;
2090 and that pointers to function members defined in different shared
2091 objects may not compare equal. When this flag is given, it is a
2092 violation of the ODR to define types with the same name differently.
2096 Do not use weak symbol support, even if it is provided by the linker.
2097 By default, G++ will use weak symbols if they are available. This
2098 option exists only for testing, and should not be used by end-users;
2099 it will result in inferior code and has no benefits. This option may
2100 be removed in a future release of G++.
2104 Do not search for header files in the standard directories specific to
2105 C++, but do still search the other standard directories. (This option
2106 is used when building the C++ library.)
2109 In addition, these optimization, warning, and code generation options
2110 have meanings only for C++ programs:
2113 @item -fno-default-inline
2114 @opindex fno-default-inline
2115 Do not assume @samp{inline} for functions defined inside a class scope.
2116 @xref{Optimize Options,,Options That Control Optimization}. Note that these
2117 functions will have linkage like inline functions; they just won't be
2120 @item -Wabi @r{(C, Objective-C, C++ and Objective-C++ only)}
2123 Warn when G++ generates code that is probably not compatible with the
2124 vendor-neutral C++ ABI@. Although an effort has been made to warn about
2125 all such cases, there are probably some cases that are not warned about,
2126 even though G++ is generating incompatible code. There may also be
2127 cases where warnings are emitted even though the code that is generated
2130 You should rewrite your code to avoid these warnings if you are
2131 concerned about the fact that code generated by G++ may not be binary
2132 compatible with code generated by other compilers.
2134 The known incompatibilities in @option{-fabi-version=2} (the default) include:
2139 A template with a non-type template parameter of reference type is
2140 mangled incorrectly:
2143 template <int &> struct S @{@};
2147 This is fixed in @option{-fabi-version=3}.
2150 SIMD vector types declared using @code{__attribute ((vector_size))} are
2151 mangled in a non-standard way that does not allow for overloading of
2152 functions taking vectors of different sizes.
2154 The mangling is changed in @option{-fabi-version=4}.
2157 The known incompatibilities in @option{-fabi-version=1} include:
2162 Incorrect handling of tail-padding for bit-fields. G++ may attempt to
2163 pack data into the same byte as a base class. For example:
2166 struct A @{ virtual void f(); int f1 : 1; @};
2167 struct B : public A @{ int f2 : 1; @};
2171 In this case, G++ will place @code{B::f2} into the same byte
2172 as@code{A::f1}; other compilers will not. You can avoid this problem
2173 by explicitly padding @code{A} so that its size is a multiple of the
2174 byte size on your platform; that will cause G++ and other compilers to
2175 layout @code{B} identically.
2178 Incorrect handling of tail-padding for virtual bases. G++ does not use
2179 tail padding when laying out virtual bases. For example:
2182 struct A @{ virtual void f(); char c1; @};
2183 struct B @{ B(); char c2; @};
2184 struct C : public A, public virtual B @{@};
2188 In this case, G++ will not place @code{B} into the tail-padding for
2189 @code{A}; other compilers will. You can avoid this problem by
2190 explicitly padding @code{A} so that its size is a multiple of its
2191 alignment (ignoring virtual base classes); that will cause G++ and other
2192 compilers to layout @code{C} identically.
2195 Incorrect handling of bit-fields with declared widths greater than that
2196 of their underlying types, when the bit-fields appear in a union. For
2200 union U @{ int i : 4096; @};
2204 Assuming that an @code{int} does not have 4096 bits, G++ will make the
2205 union too small by the number of bits in an @code{int}.
2208 Empty classes can be placed at incorrect offsets. For example:
2218 struct C : public B, public A @{@};
2222 G++ will place the @code{A} base class of @code{C} at a nonzero offset;
2223 it should be placed at offset zero. G++ mistakenly believes that the
2224 @code{A} data member of @code{B} is already at offset zero.
2227 Names of template functions whose types involve @code{typename} or
2228 template template parameters can be mangled incorrectly.
2231 template <typename Q>
2232 void f(typename Q::X) @{@}
2234 template <template <typename> class Q>
2235 void f(typename Q<int>::X) @{@}
2239 Instantiations of these templates may be mangled incorrectly.
2243 It also warns psABI related changes. The known psABI changes at this
2249 For SYSV/x86-64, when passing union with long double, it is changed to
2250 pass in memory as specified in psABI. For example:
2260 @code{union U} will always be passed in memory.
2264 @item -Wctor-dtor-privacy @r{(C++ and Objective-C++ only)}
2265 @opindex Wctor-dtor-privacy
2266 @opindex Wno-ctor-dtor-privacy
2267 Warn when a class seems unusable because all the constructors or
2268 destructors in that class are private, and it has neither friends nor
2269 public static member functions.
2271 @item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}
2272 @opindex Wnon-virtual-dtor
2273 @opindex Wno-non-virtual-dtor
2274 Warn when a class has virtual functions and accessible non-virtual
2275 destructor, in which case it would be possible but unsafe to delete
2276 an instance of a derived class through a pointer to the base class.
2277 This warning is also enabled if -Weffc++ is specified.
2279 @item -Wreorder @r{(C++ and Objective-C++ only)}
2281 @opindex Wno-reorder
2282 @cindex reordering, warning
2283 @cindex warning for reordering of member initializers
2284 Warn when the order of member initializers given in the code does not
2285 match the order in which they must be executed. For instance:
2291 A(): j (0), i (1) @{ @}
2295 The compiler will rearrange the member initializers for @samp{i}
2296 and @samp{j} to match the declaration order of the members, emitting
2297 a warning to that effect. This warning is enabled by @option{-Wall}.
2300 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
2303 @item -Weffc++ @r{(C++ and Objective-C++ only)}
2306 Warn about violations of the following style guidelines from Scott Meyers'
2307 @cite{Effective C++} book:
2311 Item 11: Define a copy constructor and an assignment operator for classes
2312 with dynamically allocated memory.
2315 Item 12: Prefer initialization to assignment in constructors.
2318 Item 14: Make destructors virtual in base classes.
2321 Item 15: Have @code{operator=} return a reference to @code{*this}.
2324 Item 23: Don't try to return a reference when you must return an object.
2328 Also warn about violations of the following style guidelines from
2329 Scott Meyers' @cite{More Effective C++} book:
2333 Item 6: Distinguish between prefix and postfix forms of increment and
2334 decrement operators.
2337 Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
2341 When selecting this option, be aware that the standard library
2342 headers do not obey all of these guidelines; use @samp{grep -v}
2343 to filter out those warnings.
2345 @item -Wstrict-null-sentinel @r{(C++ and Objective-C++ only)}
2346 @opindex Wstrict-null-sentinel
2347 @opindex Wno-strict-null-sentinel
2348 Warn also about the use of an uncasted @code{NULL} as sentinel. When
2349 compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
2350 to @code{__null}. Although it is a null pointer constant not a null pointer,
2351 it is guaranteed to be of the same size as a pointer. But this use is
2352 not portable across different compilers.
2354 @item -Wno-non-template-friend @r{(C++ and Objective-C++ only)}
2355 @opindex Wno-non-template-friend
2356 @opindex Wnon-template-friend
2357 Disable warnings when non-templatized friend functions are declared
2358 within a template. Since the advent of explicit template specification
2359 support in G++, if the name of the friend is an unqualified-id (i.e.,
2360 @samp{friend foo(int)}), the C++ language specification demands that the
2361 friend declare or define an ordinary, nontemplate function. (Section
2362 14.5.3). Before G++ implemented explicit specification, unqualified-ids
2363 could be interpreted as a particular specialization of a templatized
2364 function. Because this non-conforming behavior is no longer the default
2365 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
2366 check existing code for potential trouble spots and is on by default.
2367 This new compiler behavior can be turned off with
2368 @option{-Wno-non-template-friend} which keeps the conformant compiler code
2369 but disables the helpful warning.
2371 @item -Wold-style-cast @r{(C++ and Objective-C++ only)}
2372 @opindex Wold-style-cast
2373 @opindex Wno-old-style-cast
2374 Warn if an old-style (C-style) cast to a non-void type is used within
2375 a C++ program. The new-style casts (@samp{dynamic_cast},
2376 @samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
2377 less vulnerable to unintended effects and much easier to search for.
2379 @item -Woverloaded-virtual @r{(C++ and Objective-C++ only)}
2380 @opindex Woverloaded-virtual
2381 @opindex Wno-overloaded-virtual
2382 @cindex overloaded virtual fn, warning
2383 @cindex warning for overloaded virtual fn
2384 Warn when a function declaration hides virtual functions from a
2385 base class. For example, in:
2392 struct B: public A @{
2397 the @code{A} class version of @code{f} is hidden in @code{B}, and code
2405 will fail to compile.
2407 @item -Wno-pmf-conversions @r{(C++ and Objective-C++ only)}
2408 @opindex Wno-pmf-conversions
2409 @opindex Wpmf-conversions
2410 Disable the diagnostic for converting a bound pointer to member function
2413 @item -Wsign-promo @r{(C++ and Objective-C++ only)}
2414 @opindex Wsign-promo
2415 @opindex Wno-sign-promo
2416 Warn when overload resolution chooses a promotion from unsigned or
2417 enumerated type to a signed type, over a conversion to an unsigned type of
2418 the same size. Previous versions of G++ would try to preserve
2419 unsignedness, but the standard mandates the current behavior.
2424 A& operator = (int);
2434 In this example, G++ will synthesize a default @samp{A& operator =
2435 (const A&);}, while cfront will use the user-defined @samp{operator =}.
2438 @node Objective-C and Objective-C++ Dialect Options
2439 @section Options Controlling Objective-C and Objective-C++ Dialects
2441 @cindex compiler options, Objective-C and Objective-C++
2442 @cindex Objective-C and Objective-C++ options, command line
2443 @cindex options, Objective-C and Objective-C++
2444 (NOTE: This manual does not describe the Objective-C and Objective-C++
2445 languages themselves. See @xref{Standards,,Language Standards
2446 Supported by GCC}, for references.)
2448 This section describes the command-line options that are only meaningful
2449 for Objective-C and Objective-C++ programs, but you can also use most of
2450 the language-independent GNU compiler options.
2451 For example, you might compile a file @code{some_class.m} like this:
2454 gcc -g -fgnu-runtime -O -c some_class.m
2458 In this example, @option{-fgnu-runtime} is an option meant only for
2459 Objective-C and Objective-C++ programs; you can use the other options with
2460 any language supported by GCC@.
2462 Note that since Objective-C is an extension of the C language, Objective-C
2463 compilations may also use options specific to the C front-end (e.g.,
2464 @option{-Wtraditional}). Similarly, Objective-C++ compilations may use
2465 C++-specific options (e.g., @option{-Wabi}).
2467 Here is a list of options that are @emph{only} for compiling Objective-C
2468 and Objective-C++ programs:
2471 @item -fconstant-string-class=@var{class-name}
2472 @opindex fconstant-string-class
2473 Use @var{class-name} as the name of the class to instantiate for each
2474 literal string specified with the syntax @code{@@"@dots{}"}. The default
2475 class name is @code{NXConstantString} if the GNU runtime is being used, and
2476 @code{NSConstantString} if the NeXT runtime is being used (see below). The
2477 @option{-fconstant-cfstrings} option, if also present, will override the
2478 @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
2479 to be laid out as constant CoreFoundation strings.
2482 @opindex fgnu-runtime
2483 Generate object code compatible with the standard GNU Objective-C
2484 runtime. This is the default for most types of systems.
2486 @item -fnext-runtime
2487 @opindex fnext-runtime
2488 Generate output compatible with the NeXT runtime. This is the default
2489 for NeXT-based systems, including Darwin and Mac OS X@. The macro
2490 @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
2493 @item -fno-nil-receivers
2494 @opindex fno-nil-receivers
2495 Assume that all Objective-C message dispatches (e.g.,
2496 @code{[receiver message:arg]}) in this translation unit ensure that the receiver
2497 is not @code{nil}. This allows for more efficient entry points in the runtime
2498 to be used. Currently, this option is only available in conjunction with
2499 the NeXT runtime on Mac OS X 10.3 and later.
2501 @item -fobjc-call-cxx-cdtors
2502 @opindex fobjc-call-cxx-cdtors
2503 For each Objective-C class, check if any of its instance variables is a
2504 C++ object with a non-trivial default constructor. If so, synthesize a
2505 special @code{- (id) .cxx_construct} instance method that will run
2506 non-trivial default constructors on any such instance variables, in order,
2507 and then return @code{self}. Similarly, check if any instance variable
2508 is a C++ object with a non-trivial destructor, and if so, synthesize a
2509 special @code{- (void) .cxx_destruct} method that will run
2510 all such default destructors, in reverse order.
2512 The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
2513 thusly generated will only operate on instance variables declared in the
2514 current Objective-C class, and not those inherited from superclasses. It
2515 is the responsibility of the Objective-C runtime to invoke all such methods
2516 in an object's inheritance hierarchy. The @code{- (id) .cxx_construct} methods
2517 will be invoked by the runtime immediately after a new object
2518 instance is allocated; the @code{- (void) .cxx_destruct} methods will
2519 be invoked immediately before the runtime deallocates an object instance.
2521 As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
2522 support for invoking the @code{- (id) .cxx_construct} and
2523 @code{- (void) .cxx_destruct} methods.
2525 @item -fobjc-direct-dispatch
2526 @opindex fobjc-direct-dispatch
2527 Allow fast jumps to the message dispatcher. On Darwin this is
2528 accomplished via the comm page.
2530 @item -fobjc-exceptions
2531 @opindex fobjc-exceptions
2532 Enable syntactic support for structured exception handling in Objective-C,
2533 similar to what is offered by C++ and Java. This option is
2534 unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2543 @@catch (AnObjCClass *exc) @{
2550 @@catch (AnotherClass *exc) @{
2553 @@catch (id allOthers) @{
2563 The @code{@@throw} statement may appear anywhere in an Objective-C or
2564 Objective-C++ program; when used inside of a @code{@@catch} block, the
2565 @code{@@throw} may appear without an argument (as shown above), in which case
2566 the object caught by the @code{@@catch} will be rethrown.
2568 Note that only (pointers to) Objective-C objects may be thrown and
2569 caught using this scheme. When an object is thrown, it will be caught
2570 by the nearest @code{@@catch} clause capable of handling objects of that type,
2571 analogously to how @code{catch} blocks work in C++ and Java. A
2572 @code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2573 any and all Objective-C exceptions not caught by previous @code{@@catch}
2576 The @code{@@finally} clause, if present, will be executed upon exit from the
2577 immediately preceding @code{@@try @dots{} @@catch} section. This will happen
2578 regardless of whether any exceptions are thrown, caught or rethrown
2579 inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2580 of the @code{finally} clause in Java.
2582 There are several caveats to using the new exception mechanism:
2586 Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2587 idioms provided by the @code{NSException} class, the new
2588 exceptions can only be used on Mac OS X 10.3 (Panther) and later
2589 systems, due to additional functionality needed in the (NeXT) Objective-C
2593 As mentioned above, the new exceptions do not support handling
2594 types other than Objective-C objects. Furthermore, when used from
2595 Objective-C++, the Objective-C exception model does not interoperate with C++
2596 exceptions at this time. This means you cannot @code{@@throw} an exception
2597 from Objective-C and @code{catch} it in C++, or vice versa
2598 (i.e., @code{throw @dots{} @@catch}).
2601 The @option{-fobjc-exceptions} switch also enables the use of synchronization
2602 blocks for thread-safe execution:
2605 @@synchronized (ObjCClass *guard) @{
2610 Upon entering the @code{@@synchronized} block, a thread of execution shall
2611 first check whether a lock has been placed on the corresponding @code{guard}
2612 object by another thread. If it has, the current thread shall wait until
2613 the other thread relinquishes its lock. Once @code{guard} becomes available,
2614 the current thread will place its own lock on it, execute the code contained in
2615 the @code{@@synchronized} block, and finally relinquish the lock (thereby
2616 making @code{guard} available to other threads).
2618 Unlike Java, Objective-C does not allow for entire methods to be marked
2619 @code{@@synchronized}. Note that throwing exceptions out of
2620 @code{@@synchronized} blocks is allowed, and will cause the guarding object
2621 to be unlocked properly.
2625 Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2627 @item -freplace-objc-classes
2628 @opindex freplace-objc-classes
2629 Emit a special marker instructing @command{ld(1)} not to statically link in
2630 the resulting object file, and allow @command{dyld(1)} to load it in at
2631 run time instead. This is used in conjunction with the Fix-and-Continue
2632 debugging mode, where the object file in question may be recompiled and
2633 dynamically reloaded in the course of program execution, without the need
2634 to restart the program itself. Currently, Fix-and-Continue functionality
2635 is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2640 When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2641 to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2642 compile time) with static class references that get initialized at load time,
2643 which improves run-time performance. Specifying the @option{-fzero-link} flag
2644 suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2645 to be retained. This is useful in Zero-Link debugging mode, since it allows
2646 for individual class implementations to be modified during program execution.
2650 Dump interface declarations for all classes seen in the source file to a
2651 file named @file{@var{sourcename}.decl}.
2653 @item -Wassign-intercept @r{(Objective-C and Objective-C++ only)}
2654 @opindex Wassign-intercept
2655 @opindex Wno-assign-intercept
2656 Warn whenever an Objective-C assignment is being intercepted by the
2659 @item -Wno-protocol @r{(Objective-C and Objective-C++ only)}
2660 @opindex Wno-protocol
2662 If a class is declared to implement a protocol, a warning is issued for
2663 every method in the protocol that is not implemented by the class. The
2664 default behavior is to issue a warning for every method not explicitly
2665 implemented in the class, even if a method implementation is inherited
2666 from the superclass. If you use the @option{-Wno-protocol} option, then
2667 methods inherited from the superclass are considered to be implemented,
2668 and no warning is issued for them.
2670 @item -Wselector @r{(Objective-C and Objective-C++ only)}
2672 @opindex Wno-selector
2673 Warn if multiple methods of different types for the same selector are
2674 found during compilation. The check is performed on the list of methods
2675 in the final stage of compilation. Additionally, a check is performed
2676 for each selector appearing in a @code{@@selector(@dots{})}
2677 expression, and a corresponding method for that selector has been found
2678 during compilation. Because these checks scan the method table only at
2679 the end of compilation, these warnings are not produced if the final
2680 stage of compilation is not reached, for example because an error is
2681 found during compilation, or because the @option{-fsyntax-only} option is
2684 @item -Wstrict-selector-match @r{(Objective-C and Objective-C++ only)}
2685 @opindex Wstrict-selector-match
2686 @opindex Wno-strict-selector-match
2687 Warn if multiple methods with differing argument and/or return types are
2688 found for a given selector when attempting to send a message using this
2689 selector to a receiver of type @code{id} or @code{Class}. When this flag
2690 is off (which is the default behavior), the compiler will omit such warnings
2691 if any differences found are confined to types which share the same size
2694 @item -Wundeclared-selector @r{(Objective-C and Objective-C++ only)}
2695 @opindex Wundeclared-selector
2696 @opindex Wno-undeclared-selector
2697 Warn if a @code{@@selector(@dots{})} expression referring to an
2698 undeclared selector is found. A selector is considered undeclared if no
2699 method with that name has been declared before the
2700 @code{@@selector(@dots{})} expression, either explicitly in an
2701 @code{@@interface} or @code{@@protocol} declaration, or implicitly in
2702 an @code{@@implementation} section. This option always performs its
2703 checks as soon as a @code{@@selector(@dots{})} expression is found,
2704 while @option{-Wselector} only performs its checks in the final stage of
2705 compilation. This also enforces the coding style convention
2706 that methods and selectors must be declared before being used.
2708 @item -print-objc-runtime-info
2709 @opindex print-objc-runtime-info
2710 Generate C header describing the largest structure that is passed by
2715 @node Language Independent Options
2716 @section Options to Control Diagnostic Messages Formatting
2717 @cindex options to control diagnostics formatting
2718 @cindex diagnostic messages
2719 @cindex message formatting
2721 Traditionally, diagnostic messages have been formatted irrespective of
2722 the output device's aspect (e.g.@: its width, @dots{}). The options described
2723 below can be used to control the diagnostic messages formatting
2724 algorithm, e.g.@: how many characters per line, how often source location
2725 information should be reported. Right now, only the C++ front end can
2726 honor these options. However it is expected, in the near future, that
2727 the remaining front ends would be able to digest them correctly.
2730 @item -fmessage-length=@var{n}
2731 @opindex fmessage-length
2732 Try to format error messages so that they fit on lines of about @var{n}
2733 characters. The default is 72 characters for @command{g++} and 0 for the rest of
2734 the front ends supported by GCC@. If @var{n} is zero, then no
2735 line-wrapping will be done; each error message will appear on a single
2738 @opindex fdiagnostics-show-location
2739 @item -fdiagnostics-show-location=once
2740 Only meaningful in line-wrapping mode. Instructs the diagnostic messages
2741 reporter to emit @emph{once} source location information; that is, in
2742 case the message is too long to fit on a single physical line and has to
2743 be wrapped, the source location won't be emitted (as prefix) again,
2744 over and over, in subsequent continuation lines. This is the default
2747 @item -fdiagnostics-show-location=every-line
2748 Only meaningful in line-wrapping mode. Instructs the diagnostic
2749 messages reporter to emit the same source location information (as
2750 prefix) for physical lines that result from the process of breaking
2751 a message which is too long to fit on a single line.
2753 @item -fdiagnostics-show-option
2754 @opindex fdiagnostics-show-option
2755 This option instructs the diagnostic machinery to add text to each
2756 diagnostic emitted, which indicates which command line option directly
2757 controls that diagnostic, when such an option is known to the
2758 diagnostic machinery.
2760 @item -Wcoverage-mismatch
2761 @opindex Wcoverage-mismatch
2762 Warn if feedback profiles do not match when using the
2763 @option{-fprofile-use} option.
2764 If a source file was changed between @option{-fprofile-gen} and
2765 @option{-fprofile-use}, the files with the profile feedback can fail
2766 to match the source file and GCC can not use the profile feedback
2767 information. By default, this warning is enabled and is treated as an
2768 error. @option{-Wno-coverage-mismatch} can be used to disable the
2769 warning or @option{-Wno-error=coverage-mismatch} can be used to
2770 disable the error. Disable the error for this warning can result in
2771 poorly optimized code, so disabling the error is useful only in the
2772 case of very minor changes such as bug fixes to an existing code-base.
2773 Completely disabling the warning is not recommended.
2777 @node Warning Options
2778 @section Options to Request or Suppress Warnings
2779 @cindex options to control warnings
2780 @cindex warning messages
2781 @cindex messages, warning
2782 @cindex suppressing warnings
2784 Warnings are diagnostic messages that report constructions which
2785 are not inherently erroneous but which are risky or suggest there
2786 may have been an error.
2788 The following language-independent options do not enable specific
2789 warnings but control the kinds of diagnostics produced by GCC.
2792 @cindex syntax checking
2794 @opindex fsyntax-only
2795 Check the code for syntax errors, but don't do anything beyond that.
2799 Inhibit all warning messages.
2804 Make all warnings into errors.
2809 Make the specified warning into an error. The specifier for a warning
2810 is appended, for example @option{-Werror=switch} turns the warnings
2811 controlled by @option{-Wswitch} into errors. This switch takes a
2812 negative form, to be used to negate @option{-Werror} for specific
2813 warnings, for example @option{-Wno-error=switch} makes
2814 @option{-Wswitch} warnings not be errors, even when @option{-Werror}
2815 is in effect. You can use the @option{-fdiagnostics-show-option}
2816 option to have each controllable warning amended with the option which
2817 controls it, to determine what to use with this option.
2819 Note that specifying @option{-Werror=}@var{foo} automatically implies
2820 @option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
2823 @item -Wfatal-errors
2824 @opindex Wfatal-errors
2825 @opindex Wno-fatal-errors
2826 This option causes the compiler to abort compilation on the first error
2827 occurred rather than trying to keep going and printing further error
2832 You can request many specific warnings with options beginning
2833 @samp{-W}, for example @option{-Wimplicit} to request warnings on
2834 implicit declarations. Each of these specific warning options also
2835 has a negative form beginning @samp{-Wno-} to turn off warnings; for
2836 example, @option{-Wno-implicit}. This manual lists only one of the
2837 two forms, whichever is not the default. For further,
2838 language-specific options also refer to @ref{C++ Dialect Options} and
2839 @ref{Objective-C and Objective-C++ Dialect Options}.
2841 When an unrecognized warning label is requested (e.g.,
2842 @option{-Wunknown-warning}), GCC will emit a diagnostic stating
2843 that the option is not recognized. However, if the @samp{-Wno-} form
2844 is used, the behavior is slightly different: No diagnostic will be
2845 produced for @option{-Wno-unknown-warning} unless other diagnostics
2846 are being produced. This allows the use of new @option{-Wno-} options
2847 with old compilers, but if something goes wrong, the compiler will
2848 warn that an unrecognized option was used.
2853 Issue all the warnings demanded by strict ISO C and ISO C++;
2854 reject all programs that use forbidden extensions, and some other
2855 programs that do not follow ISO C and ISO C++. For ISO C, follows the
2856 version of the ISO C standard specified by any @option{-std} option used.
2858 Valid ISO C and ISO C++ programs should compile properly with or without
2859 this option (though a rare few will require @option{-ansi} or a
2860 @option{-std} option specifying the required version of ISO C)@. However,
2861 without this option, certain GNU extensions and traditional C and C++
2862 features are supported as well. With this option, they are rejected.
2864 @option{-pedantic} does not cause warning messages for use of the
2865 alternate keywords whose names begin and end with @samp{__}. Pedantic
2866 warnings are also disabled in the expression that follows
2867 @code{__extension__}. However, only system header files should use
2868 these escape routes; application programs should avoid them.
2869 @xref{Alternate Keywords}.
2871 Some users try to use @option{-pedantic} to check programs for strict ISO
2872 C conformance. They soon find that it does not do quite what they want:
2873 it finds some non-ISO practices, but not all---only those for which
2874 ISO C @emph{requires} a diagnostic, and some others for which
2875 diagnostics have been added.
2877 A feature to report any failure to conform to ISO C might be useful in
2878 some instances, but would require considerable additional work and would
2879 be quite different from @option{-pedantic}. We don't have plans to
2880 support such a feature in the near future.
2882 Where the standard specified with @option{-std} represents a GNU
2883 extended dialect of C, such as @samp{gnu90} or @samp{gnu99}, there is a
2884 corresponding @dfn{base standard}, the version of ISO C on which the GNU
2885 extended dialect is based. Warnings from @option{-pedantic} are given
2886 where they are required by the base standard. (It would not make sense
2887 for such warnings to be given only for features not in the specified GNU
2888 C dialect, since by definition the GNU dialects of C include all
2889 features the compiler supports with the given option, and there would be
2890 nothing to warn about.)
2892 @item -pedantic-errors
2893 @opindex pedantic-errors
2894 Like @option{-pedantic}, except that errors are produced rather than
2900 This enables all the warnings about constructions that some users
2901 consider questionable, and that are easy to avoid (or modify to
2902 prevent the warning), even in conjunction with macros. This also
2903 enables some language-specific warnings described in @ref{C++ Dialect
2904 Options} and @ref{Objective-C and Objective-C++ Dialect Options}.
2906 @option{-Wall} turns on the following warning flags:
2908 @gccoptlist{-Waddress @gol
2909 -Warray-bounds @r{(only with} @option{-O2}@r{)} @gol
2911 -Wchar-subscripts @gol
2912 -Wenum-compare @r{(in C/Objc; this is on by default in C++)} @gol
2913 -Wimplicit-int @r{(C and Objective-C only)} @gol
2914 -Wimplicit-function-declaration @r{(C and Objective-C only)} @gol
2917 -Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)} @gol
2918 -Wmissing-braces @gol
2924 -Wsequence-point @gol
2925 -Wsign-compare @r{(only in C++)} @gol
2926 -Wstrict-aliasing @gol
2927 -Wstrict-overflow=1 @gol
2930 -Wuninitialized @gol
2931 -Wunknown-pragmas @gol
2932 -Wunused-function @gol
2935 -Wunused-variable @gol
2936 -Wvolatile-register-var @gol
2939 Note that some warning flags are not implied by @option{-Wall}. Some of
2940 them warn about constructions that users generally do not consider
2941 questionable, but which occasionally you might wish to check for;
2942 others warn about constructions that are necessary or hard to avoid in
2943 some cases, and there is no simple way to modify the code to suppress
2944 the warning. Some of them are enabled by @option{-Wextra} but many of
2945 them must be enabled individually.
2951 This enables some extra warning flags that are not enabled by
2952 @option{-Wall}. (This option used to be called @option{-W}. The older
2953 name is still supported, but the newer name is more descriptive.)
2955 @gccoptlist{-Wclobbered @gol
2957 -Wignored-qualifiers @gol
2958 -Wmissing-field-initializers @gol
2959 -Wmissing-parameter-type @r{(C only)} @gol
2960 -Wold-style-declaration @r{(C only)} @gol
2961 -Woverride-init @gol
2964 -Wuninitialized @gol
2965 -Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
2966 -Wunused-but-set-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
2969 The option @option{-Wextra} also prints warning messages for the
2975 A pointer is compared against integer zero with @samp{<}, @samp{<=},
2976 @samp{>}, or @samp{>=}.
2979 (C++ only) An enumerator and a non-enumerator both appear in a
2980 conditional expression.
2983 (C++ only) Ambiguous virtual bases.
2986 (C++ only) Subscripting an array which has been declared @samp{register}.
2989 (C++ only) Taking the address of a variable which has been declared
2993 (C++ only) A base class is not initialized in a derived class' copy
2998 @item -Wchar-subscripts
2999 @opindex Wchar-subscripts
3000 @opindex Wno-char-subscripts
3001 Warn if an array subscript has type @code{char}. This is a common cause
3002 of error, as programmers often forget that this type is signed on some
3004 This warning is enabled by @option{-Wall}.
3008 @opindex Wno-comment
3009 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
3010 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
3011 This warning is enabled by @option{-Wall}.
3014 @r{(C, Objective-C, C++, Objective-C++ and Fortran only)}
3016 Suppress warning messages emitted by @code{#warning} directives.
3021 @opindex ffreestanding
3022 @opindex fno-builtin
3023 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
3024 the arguments supplied have types appropriate to the format string
3025 specified, and that the conversions specified in the format string make
3026 sense. This includes standard functions, and others specified by format
3027 attributes (@pxref{Function Attributes}), in the @code{printf},
3028 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
3029 not in the C standard) families (or other target-specific families).
3030 Which functions are checked without format attributes having been
3031 specified depends on the standard version selected, and such checks of
3032 functions without the attribute specified are disabled by
3033 @option{-ffreestanding} or @option{-fno-builtin}.
3035 The formats are checked against the format features supported by GNU
3036 libc version 2.2. These include all ISO C90 and C99 features, as well
3037 as features from the Single Unix Specification and some BSD and GNU
3038 extensions. Other library implementations may not support all these
3039 features; GCC does not support warning about features that go beyond a
3040 particular library's limitations. However, if @option{-pedantic} is used
3041 with @option{-Wformat}, warnings will be given about format features not
3042 in the selected standard version (but not for @code{strfmon} formats,
3043 since those are not in any version of the C standard). @xref{C Dialect
3044 Options,,Options Controlling C Dialect}.
3046 Since @option{-Wformat} also checks for null format arguments for
3047 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
3049 @option{-Wformat} is included in @option{-Wall}. For more control over some
3050 aspects of format checking, the options @option{-Wformat-y2k},
3051 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
3052 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
3053 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
3056 @opindex Wformat-y2k
3057 @opindex Wno-format-y2k
3058 If @option{-Wformat} is specified, also warn about @code{strftime}
3059 formats which may yield only a two-digit year.
3061 @item -Wno-format-contains-nul
3062 @opindex Wno-format-contains-nul
3063 @opindex Wformat-contains-nul
3064 If @option{-Wformat} is specified, do not warn about format strings that
3067 @item -Wno-format-extra-args
3068 @opindex Wno-format-extra-args
3069 @opindex Wformat-extra-args
3070 If @option{-Wformat} is specified, do not warn about excess arguments to a
3071 @code{printf} or @code{scanf} format function. The C standard specifies
3072 that such arguments are ignored.
3074 Where the unused arguments lie between used arguments that are
3075 specified with @samp{$} operand number specifications, normally
3076 warnings are still given, since the implementation could not know what
3077 type to pass to @code{va_arg} to skip the unused arguments. However,
3078 in the case of @code{scanf} formats, this option will suppress the
3079 warning if the unused arguments are all pointers, since the Single
3080 Unix Specification says that such unused arguments are allowed.
3082 @item -Wno-format-zero-length @r{(C and Objective-C only)}
3083 @opindex Wno-format-zero-length
3084 @opindex Wformat-zero-length
3085 If @option{-Wformat} is specified, do not warn about zero-length formats.
3086 The C standard specifies that zero-length formats are allowed.
3088 @item -Wformat-nonliteral
3089 @opindex Wformat-nonliteral
3090 @opindex Wno-format-nonliteral
3091 If @option{-Wformat} is specified, also warn if the format string is not a
3092 string literal and so cannot be checked, unless the format function
3093 takes its format arguments as a @code{va_list}.
3095 @item -Wformat-security
3096 @opindex Wformat-security
3097 @opindex Wno-format-security
3098 If @option{-Wformat} is specified, also warn about uses of format
3099 functions that represent possible security problems. At present, this
3100 warns about calls to @code{printf} and @code{scanf} functions where the
3101 format string is not a string literal and there are no format arguments,
3102 as in @code{printf (foo);}. This may be a security hole if the format
3103 string came from untrusted input and contains @samp{%n}. (This is
3104 currently a subset of what @option{-Wformat-nonliteral} warns about, but
3105 in future warnings may be added to @option{-Wformat-security} that are not
3106 included in @option{-Wformat-nonliteral}.)
3110 @opindex Wno-format=2
3111 Enable @option{-Wformat} plus format checks not included in
3112 @option{-Wformat}. Currently equivalent to @samp{-Wformat
3113 -Wformat-nonliteral -Wformat-security -Wformat-y2k}.
3115 @item -Wnonnull @r{(C and Objective-C only)}
3117 @opindex Wno-nonnull
3118 Warn about passing a null pointer for arguments marked as
3119 requiring a non-null value by the @code{nonnull} function attribute.
3121 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
3122 can be disabled with the @option{-Wno-nonnull} option.
3124 @item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
3126 @opindex Wno-init-self
3127 Warn about uninitialized variables which are initialized with themselves.
3128 Note this option can only be used with the @option{-Wuninitialized} option.
3130 For example, GCC will warn about @code{i} being uninitialized in the
3131 following snippet only when @option{-Winit-self} has been specified:
3142 @item -Wimplicit-int @r{(C and Objective-C only)}
3143 @opindex Wimplicit-int
3144 @opindex Wno-implicit-int
3145 Warn when a declaration does not specify a type.
3146 This warning is enabled by @option{-Wall}.
3148 @item -Wimplicit-function-declaration @r{(C and Objective-C only)}
3149 @opindex Wimplicit-function-declaration
3150 @opindex Wno-implicit-function-declaration
3151 Give a warning whenever a function is used before being declared. In
3152 C99 mode (@option{-std=c99} or @option{-std=gnu99}), this warning is
3153 enabled by default and it is made into an error by
3154 @option{-pedantic-errors}. This warning is also enabled by
3157 @item -Wimplicit @r{(C and Objective-C only)}
3159 @opindex Wno-implicit
3160 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
3161 This warning is enabled by @option{-Wall}.
3163 @item -Wignored-qualifiers @r{(C and C++ only)}
3164 @opindex Wignored-qualifiers
3165 @opindex Wno-ignored-qualifiers
3166 Warn if the return type of a function has a type qualifier
3167 such as @code{const}. For ISO C such a type qualifier has no effect,
3168 since the value returned by a function is not an lvalue.
3169 For C++, the warning is only emitted for scalar types or @code{void}.
3170 ISO C prohibits qualified @code{void} return types on function
3171 definitions, so such return types always receive a warning
3172 even without this option.
3174 This warning is also enabled by @option{-Wextra}.
3179 Warn if the type of @samp{main} is suspicious. @samp{main} should be
3180 a function with external linkage, returning int, taking either zero
3181 arguments, two, or three arguments of appropriate types. This warning
3182 is enabled by default in C++ and is enabled by either @option{-Wall}
3183 or @option{-pedantic}.
3185 @item -Wmissing-braces
3186 @opindex Wmissing-braces
3187 @opindex Wno-missing-braces
3188 Warn if an aggregate or union initializer is not fully bracketed. In
3189 the following example, the initializer for @samp{a} is not fully
3190 bracketed, but that for @samp{b} is fully bracketed.
3193 int a[2][2] = @{ 0, 1, 2, 3 @};
3194 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
3197 This warning is enabled by @option{-Wall}.
3199 @item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
3200 @opindex Wmissing-include-dirs
3201 @opindex Wno-missing-include-dirs
3202 Warn if a user-supplied include directory does not exist.
3205 @opindex Wparentheses
3206 @opindex Wno-parentheses
3207 Warn if parentheses are omitted in certain contexts, such
3208 as when there is an assignment in a context where a truth value
3209 is expected, or when operators are nested whose precedence people
3210 often get confused about.
3212 Also warn if a comparison like @samp{x<=y<=z} appears; this is
3213 equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
3214 interpretation from that of ordinary mathematical notation.
3216 Also warn about constructions where there may be confusion to which
3217 @code{if} statement an @code{else} branch belongs. Here is an example of
3232 In C/C++, every @code{else} branch belongs to the innermost possible
3233 @code{if} statement, which in this example is @code{if (b)}. This is
3234 often not what the programmer expected, as illustrated in the above
3235 example by indentation the programmer chose. When there is the
3236 potential for this confusion, GCC will issue a warning when this flag
3237 is specified. To eliminate the warning, add explicit braces around
3238 the innermost @code{if} statement so there is no way the @code{else}
3239 could belong to the enclosing @code{if}. The resulting code would
3256 This warning is enabled by @option{-Wall}.
3258 @item -Wsequence-point
3259 @opindex Wsequence-point
3260 @opindex Wno-sequence-point
3261 Warn about code that may have undefined semantics because of violations
3262 of sequence point rules in the C and C++ standards.
3264 The C and C++ standards defines the order in which expressions in a C/C++
3265 program are evaluated in terms of @dfn{sequence points}, which represent
3266 a partial ordering between the execution of parts of the program: those
3267 executed before the sequence point, and those executed after it. These
3268 occur after the evaluation of a full expression (one which is not part
3269 of a larger expression), after the evaluation of the first operand of a
3270 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
3271 function is called (but after the evaluation of its arguments and the
3272 expression denoting the called function), and in certain other places.
3273 Other than as expressed by the sequence point rules, the order of
3274 evaluation of subexpressions of an expression is not specified. All
3275 these rules describe only a partial order rather than a total order,
3276 since, for example, if two functions are called within one expression
3277 with no sequence point between them, the order in which the functions
3278 are called is not specified. However, the standards committee have
3279 ruled that function calls do not overlap.
3281 It is not specified when between sequence points modifications to the
3282 values of objects take effect. Programs whose behavior depends on this
3283 have undefined behavior; the C and C++ standards specify that ``Between
3284 the previous and next sequence point an object shall have its stored
3285 value modified at most once by the evaluation of an expression.
3286 Furthermore, the prior value shall be read only to determine the value
3287 to be stored.''. If a program breaks these rules, the results on any
3288 particular implementation are entirely unpredictable.
3290 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
3291 = b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
3292 diagnosed by this option, and it may give an occasional false positive
3293 result, but in general it has been found fairly effective at detecting
3294 this sort of problem in programs.
3296 The standard is worded confusingly, therefore there is some debate
3297 over the precise meaning of the sequence point rules in subtle cases.
3298 Links to discussions of the problem, including proposed formal
3299 definitions, may be found on the GCC readings page, at
3300 @w{@uref{http://gcc.gnu.org/readings.html}}.
3302 This warning is enabled by @option{-Wall} for C and C++.
3305 @opindex Wreturn-type
3306 @opindex Wno-return-type
3307 Warn whenever a function is defined with a return-type that defaults
3308 to @code{int}. Also warn about any @code{return} statement with no
3309 return-value in a function whose return-type is not @code{void}
3310 (falling off the end of the function body is considered returning
3311 without a value), and about a @code{return} statement with an
3312 expression in a function whose return-type is @code{void}.
3314 For C++, a function without return type always produces a diagnostic
3315 message, even when @option{-Wno-return-type} is specified. The only
3316 exceptions are @samp{main} and functions defined in system headers.
3318 This warning is enabled by @option{-Wall}.
3323 Warn whenever a @code{switch} statement has an index of enumerated type
3324 and lacks a @code{case} for one or more of the named codes of that
3325 enumeration. (The presence of a @code{default} label prevents this
3326 warning.) @code{case} labels outside the enumeration range also
3327 provoke warnings when this option is used (even if there is a
3328 @code{default} label).
3329 This warning is enabled by @option{-Wall}.
3331 @item -Wswitch-default
3332 @opindex Wswitch-default
3333 @opindex Wno-switch-default
3334 Warn whenever a @code{switch} statement does not have a @code{default}
3338 @opindex Wswitch-enum
3339 @opindex Wno-switch-enum
3340 Warn whenever a @code{switch} statement has an index of enumerated type
3341 and lacks a @code{case} for one or more of the named codes of that
3342 enumeration. @code{case} labels outside the enumeration range also
3343 provoke warnings when this option is used. The only difference
3344 between @option{-Wswitch} and this option is that this option gives a
3345 warning about an omitted enumeration code even if there is a
3346 @code{default} label.
3348 @item -Wsync-nand @r{(C and C++ only)}
3350 @opindex Wno-sync-nand
3351 Warn when @code{__sync_fetch_and_nand} and @code{__sync_nand_and_fetch}
3352 built-in functions are used. These functions changed semantics in GCC 4.4.
3356 @opindex Wno-trigraphs
3357 Warn if any trigraphs are encountered that might change the meaning of
3358 the program (trigraphs within comments are not warned about).
3359 This warning is enabled by @option{-Wall}.
3361 @item -Wunused-but-set-parameter
3362 @opindex Wunused-but-set-parameter
3363 @opindex Wno-unused-but-set-parameter
3364 Warn whenever a function parameter is assigned to, but otherwise unused
3365 (aside from its declaration).
3367 To suppress this warning use the @samp{unused} attribute
3368 (@pxref{Variable Attributes}).
3370 This warning is also enabled by @option{-Wunused} together with
3373 @item -Wunused-but-set-variable
3374 @opindex Wunused-but-set-variable
3375 @opindex Wno-unused-but-set-variable
3376 Warn whenever a local variable is assigned to, but otherwise unused
3377 (aside from its declaration).
3378 This warning is enabled by @option{-Wall}.
3380 To suppress this warning use the @samp{unused} attribute
3381 (@pxref{Variable Attributes}).
3383 This warning is also enabled by @option{-Wunused}, which is enabled
3386 @item -Wunused-function
3387 @opindex Wunused-function
3388 @opindex Wno-unused-function
3389 Warn whenever a static function is declared but not defined or a
3390 non-inline static function is unused.
3391 This warning is enabled by @option{-Wall}.
3393 @item -Wunused-label
3394 @opindex Wunused-label
3395 @opindex Wno-unused-label
3396 Warn whenever a label is declared but not used.
3397 This warning is enabled by @option{-Wall}.
3399 To suppress this warning use the @samp{unused} attribute
3400 (@pxref{Variable Attributes}).
3402 @item -Wunused-parameter
3403 @opindex Wunused-parameter
3404 @opindex Wno-unused-parameter
3405 Warn whenever a function parameter is unused aside from its declaration.
3407 To suppress this warning use the @samp{unused} attribute
3408 (@pxref{Variable Attributes}).
3410 @item -Wno-unused-result
3411 @opindex Wunused-result
3412 @opindex Wno-unused-result
3413 Do not warn if a caller of a function marked with attribute
3414 @code{warn_unused_result} (@pxref{Variable Attributes}) does not use
3415 its return value. The default is @option{-Wunused-result}.
3417 @item -Wunused-variable
3418 @opindex Wunused-variable
3419 @opindex Wno-unused-variable
3420 Warn whenever a local variable or non-constant static variable is unused
3421 aside from its declaration.
3422 This warning is enabled by @option{-Wall}.
3424 To suppress this warning use the @samp{unused} attribute
3425 (@pxref{Variable Attributes}).
3427 @item -Wunused-value
3428 @opindex Wunused-value
3429 @opindex Wno-unused-value
3430 Warn whenever a statement computes a result that is explicitly not
3431 used. To suppress this warning cast the unused expression to
3432 @samp{void}. This includes an expression-statement or the left-hand
3433 side of a comma expression that contains no side effects. For example,
3434 an expression such as @samp{x[i,j]} will cause a warning, while
3435 @samp{x[(void)i,j]} will not.
3437 This warning is enabled by @option{-Wall}.
3442 All the above @option{-Wunused} options combined.
3444 In order to get a warning about an unused function parameter, you must
3445 either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
3446 @samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
3448 @item -Wuninitialized
3449 @opindex Wuninitialized
3450 @opindex Wno-uninitialized
3451 Warn if an automatic variable is used without first being initialized
3452 or if a variable may be clobbered by a @code{setjmp} call. In C++,
3453 warn if a non-static reference or non-static @samp{const} member
3454 appears in a class without constructors.
3456 If you want to warn about code which uses the uninitialized value of the
3457 variable in its own initializer, use the @option{-Winit-self} option.
3459 These warnings occur for individual uninitialized or clobbered
3460 elements of structure, union or array variables as well as for
3461 variables which are uninitialized or clobbered as a whole. They do
3462 not occur for variables or elements declared @code{volatile}. Because
3463 these warnings depend on optimization, the exact variables or elements
3464 for which there are warnings will depend on the precise optimization
3465 options and version of GCC used.
3467 Note that there may be no warning about a variable that is used only
3468 to compute a value that itself is never used, because such
3469 computations may be deleted by data flow analysis before the warnings
3472 These warnings are made optional because GCC is not smart
3473 enough to see all the reasons why the code might be correct
3474 despite appearing to have an error. Here is one example of how
3495 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
3496 always initialized, but GCC doesn't know this. Here is
3497 another common case:
3502 if (change_y) save_y = y, y = new_y;
3504 if (change_y) y = save_y;
3509 This has no bug because @code{save_y} is used only if it is set.
3511 @cindex @code{longjmp} warnings
3512 This option also warns when a non-volatile automatic variable might be
3513 changed by a call to @code{longjmp}. These warnings as well are possible
3514 only in optimizing compilation.
3516 The compiler sees only the calls to @code{setjmp}. It cannot know
3517 where @code{longjmp} will be called; in fact, a signal handler could
3518 call it at any point in the code. As a result, you may get a warning
3519 even when there is in fact no problem because @code{longjmp} cannot
3520 in fact be called at the place which would cause a problem.
3522 Some spurious warnings can be avoided if you declare all the functions
3523 you use that never return as @code{noreturn}. @xref{Function
3526 This warning is enabled by @option{-Wall} or @option{-Wextra}.
3528 @item -Wunknown-pragmas
3529 @opindex Wunknown-pragmas
3530 @opindex Wno-unknown-pragmas
3531 @cindex warning for unknown pragmas
3532 @cindex unknown pragmas, warning
3533 @cindex pragmas, warning of unknown
3534 Warn when a #pragma directive is encountered which is not understood by
3535 GCC@. If this command line option is used, warnings will even be issued
3536 for unknown pragmas in system header files. This is not the case if
3537 the warnings were only enabled by the @option{-Wall} command line option.
3540 @opindex Wno-pragmas
3542 Do not warn about misuses of pragmas, such as incorrect parameters,
3543 invalid syntax, or conflicts between pragmas. See also
3544 @samp{-Wunknown-pragmas}.
3546 @item -Wstrict-aliasing
3547 @opindex Wstrict-aliasing
3548 @opindex Wno-strict-aliasing
3549 This option is only active when @option{-fstrict-aliasing} is active.
3550 It warns about code which might break the strict aliasing rules that the
3551 compiler is using for optimization. The warning does not catch all
3552 cases, but does attempt to catch the more common pitfalls. It is
3553 included in @option{-Wall}.
3554 It is equivalent to @option{-Wstrict-aliasing=3}
3556 @item -Wstrict-aliasing=n
3557 @opindex Wstrict-aliasing=n
3558 @opindex Wno-strict-aliasing=n
3559 This option is only active when @option{-fstrict-aliasing} is active.
3560 It warns about code which might break the strict aliasing rules that the
3561 compiler is using for optimization.
3562 Higher levels correspond to higher accuracy (fewer false positives).
3563 Higher levels also correspond to more effort, similar to the way -O works.
3564 @option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
3567 Level 1: Most aggressive, quick, least accurate.
3568 Possibly useful when higher levels
3569 do not warn but -fstrict-aliasing still breaks the code, as it has very few
3570 false negatives. However, it has many false positives.
3571 Warns for all pointer conversions between possibly incompatible types,
3572 even if never dereferenced. Runs in the frontend only.
3574 Level 2: Aggressive, quick, not too precise.
3575 May still have many false positives (not as many as level 1 though),
3576 and few false negatives (but possibly more than level 1).
3577 Unlike level 1, it only warns when an address is taken. Warns about
3578 incomplete types. Runs in the frontend only.
3580 Level 3 (default for @option{-Wstrict-aliasing}):
3581 Should have very few false positives and few false
3582 negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
3583 Takes care of the common pun+dereference pattern in the frontend:
3584 @code{*(int*)&some_float}.
3585 If optimization is enabled, it also runs in the backend, where it deals
3586 with multiple statement cases using flow-sensitive points-to information.
3587 Only warns when the converted pointer is dereferenced.
3588 Does not warn about incomplete types.
3590 @item -Wstrict-overflow
3591 @itemx -Wstrict-overflow=@var{n}
3592 @opindex Wstrict-overflow
3593 @opindex Wno-strict-overflow
3594 This option is only active when @option{-fstrict-overflow} is active.
3595 It warns about cases where the compiler optimizes based on the
3596 assumption that signed overflow does not occur. Note that it does not
3597 warn about all cases where the code might overflow: it only warns
3598 about cases where the compiler implements some optimization. Thus
3599 this warning depends on the optimization level.
3601 An optimization which assumes that signed overflow does not occur is
3602 perfectly safe if the values of the variables involved are such that
3603 overflow never does, in fact, occur. Therefore this warning can
3604 easily give a false positive: a warning about code which is not
3605 actually a problem. To help focus on important issues, several
3606 warning levels are defined. No warnings are issued for the use of
3607 undefined signed overflow when estimating how many iterations a loop
3608 will require, in particular when determining whether a loop will be
3612 @item -Wstrict-overflow=1
3613 Warn about cases which are both questionable and easy to avoid. For
3614 example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
3615 compiler will simplify this to @code{1}. This level of
3616 @option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
3617 are not, and must be explicitly requested.
3619 @item -Wstrict-overflow=2
3620 Also warn about other cases where a comparison is simplified to a
3621 constant. For example: @code{abs (x) >= 0}. This can only be
3622 simplified when @option{-fstrict-overflow} is in effect, because
3623 @code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
3624 zero. @option{-Wstrict-overflow} (with no level) is the same as
3625 @option{-Wstrict-overflow=2}.
3627 @item -Wstrict-overflow=3
3628 Also warn about other cases where a comparison is simplified. For
3629 example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
3631 @item -Wstrict-overflow=4
3632 Also warn about other simplifications not covered by the above cases.
3633 For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
3635 @item -Wstrict-overflow=5
3636 Also warn about cases where the compiler reduces the magnitude of a
3637 constant involved in a comparison. For example: @code{x + 2 > y} will
3638 be simplified to @code{x + 1 >= y}. This is reported only at the
3639 highest warning level because this simplification applies to many
3640 comparisons, so this warning level will give a very large number of
3644 @item -Wsuggest-attribute=@r{[}const@r{|}pure@r{]}
3645 @opindex Wsuggest-attribute=
3646 @opindex Wno-suggest-attribute=
3647 Warn for cases where adding an attribute may be beneficial. The
3648 attributes currently supported are listed below.
3651 @item -Wsuggest-attribute=pure
3652 @itemx -Wsuggest-attribute=const
3653 @opindex Wsuggest-attribute=pure
3654 @opindex Wno-suggest-attribute=pure
3655 @opindex Wsuggest-attribute=const
3656 @opindex Wno-suggest-attribute=const
3658 Warn about functions which might be candidates for attributes
3659 @code{pure} or @code{const}. The compiler only warns for functions
3660 visible in other compilation units or if it cannot prove that the
3661 function returns normally. A function returns normally if it doesn't
3662 contain an infinite loop nor returns abnormally by throwing, calling
3663 @code{abort()} or trapping. This analysis requires option
3664 @option{-fipa-pure-const}, which is enabled by default at @option{-O}
3665 and higher. Higher optimization levels improve the accuracy of the
3669 @item -Warray-bounds
3670 @opindex Wno-array-bounds
3671 @opindex Warray-bounds
3672 This option is only active when @option{-ftree-vrp} is active
3673 (default for @option{-O2} and above). It warns about subscripts to arrays
3674 that are always out of bounds. This warning is enabled by @option{-Wall}.
3676 @item -Wno-div-by-zero
3677 @opindex Wno-div-by-zero
3678 @opindex Wdiv-by-zero
3679 Do not warn about compile-time integer division by zero. Floating point
3680 division by zero is not warned about, as it can be a legitimate way of
3681 obtaining infinities and NaNs.
3683 @item -Wsystem-headers
3684 @opindex Wsystem-headers
3685 @opindex Wno-system-headers
3686 @cindex warnings from system headers
3687 @cindex system headers, warnings from
3688 Print warning messages for constructs found in system header files.
3689 Warnings from system headers are normally suppressed, on the assumption
3690 that they usually do not indicate real problems and would only make the
3691 compiler output harder to read. Using this command line option tells
3692 GCC to emit warnings from system headers as if they occurred in user
3693 code. However, note that using @option{-Wall} in conjunction with this
3694 option will @emph{not} warn about unknown pragmas in system
3695 headers---for that, @option{-Wunknown-pragmas} must also be used.
3698 @opindex Wfloat-equal
3699 @opindex Wno-float-equal
3700 Warn if floating point values are used in equality comparisons.
3702 The idea behind this is that sometimes it is convenient (for the
3703 programmer) to consider floating-point values as approximations to
3704 infinitely precise real numbers. If you are doing this, then you need
3705 to compute (by analyzing the code, or in some other way) the maximum or
3706 likely maximum error that the computation introduces, and allow for it
3707 when performing comparisons (and when producing output, but that's a
3708 different problem). In particular, instead of testing for equality, you
3709 would check to see whether the two values have ranges that overlap; and
3710 this is done with the relational operators, so equality comparisons are
3713 @item -Wtraditional @r{(C and Objective-C only)}
3714 @opindex Wtraditional
3715 @opindex Wno-traditional
3716 Warn about certain constructs that behave differently in traditional and
3717 ISO C@. Also warn about ISO C constructs that have no traditional C
3718 equivalent, and/or problematic constructs which should be avoided.
3722 Macro parameters that appear within string literals in the macro body.
3723 In traditional C macro replacement takes place within string literals,
3724 but does not in ISO C@.
3727 In traditional C, some preprocessor directives did not exist.
3728 Traditional preprocessors would only consider a line to be a directive
3729 if the @samp{#} appeared in column 1 on the line. Therefore
3730 @option{-Wtraditional} warns about directives that traditional C
3731 understands but would ignore because the @samp{#} does not appear as the
3732 first character on the line. It also suggests you hide directives like
3733 @samp{#pragma} not understood by traditional C by indenting them. Some
3734 traditional implementations would not recognize @samp{#elif}, so it
3735 suggests avoiding it altogether.
3738 A function-like macro that appears without arguments.
3741 The unary plus operator.
3744 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
3745 constant suffixes. (Traditional C does support the @samp{L} suffix on integer
3746 constants.) Note, these suffixes appear in macros defined in the system
3747 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
3748 Use of these macros in user code might normally lead to spurious
3749 warnings, however GCC's integrated preprocessor has enough context to
3750 avoid warning in these cases.
3753 A function declared external in one block and then used after the end of
3757 A @code{switch} statement has an operand of type @code{long}.
3760 A non-@code{static} function declaration follows a @code{static} one.
3761 This construct is not accepted by some traditional C compilers.
3764 The ISO type of an integer constant has a different width or
3765 signedness from its traditional type. This warning is only issued if
3766 the base of the constant is ten. I.e.@: hexadecimal or octal values, which
3767 typically represent bit patterns, are not warned about.
3770 Usage of ISO string concatenation is detected.
3773 Initialization of automatic aggregates.
3776 Identifier conflicts with labels. Traditional C lacks a separate
3777 namespace for labels.
3780 Initialization of unions. If the initializer is zero, the warning is
3781 omitted. This is done under the assumption that the zero initializer in
3782 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
3783 initializer warnings and relies on default initialization to zero in the
3787 Conversions by prototypes between fixed/floating point values and vice
3788 versa. The absence of these prototypes when compiling with traditional
3789 C would cause serious problems. This is a subset of the possible
3790 conversion warnings, for the full set use @option{-Wtraditional-conversion}.
3793 Use of ISO C style function definitions. This warning intentionally is
3794 @emph{not} issued for prototype declarations or variadic functions
3795 because these ISO C features will appear in your code when using
3796 libiberty's traditional C compatibility macros, @code{PARAMS} and
3797 @code{VPARAMS}. This warning is also bypassed for nested functions
3798 because that feature is already a GCC extension and thus not relevant to
3799 traditional C compatibility.
3802 @item -Wtraditional-conversion @r{(C and Objective-C only)}
3803 @opindex Wtraditional-conversion
3804 @opindex Wno-traditional-conversion
3805 Warn if a prototype causes a type conversion that is different from what
3806 would happen to the same argument in the absence of a prototype. This
3807 includes conversions of fixed point to floating and vice versa, and
3808 conversions changing the width or signedness of a fixed point argument
3809 except when the same as the default promotion.
3811 @item -Wdeclaration-after-statement @r{(C and Objective-C only)}
3812 @opindex Wdeclaration-after-statement
3813 @opindex Wno-declaration-after-statement
3814 Warn when a declaration is found after a statement in a block. This
3815 construct, known from C++, was introduced with ISO C99 and is by default
3816 allowed in GCC@. It is not supported by ISO C90 and was not supported by
3817 GCC versions before GCC 3.0. @xref{Mixed Declarations}.
3822 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3824 @item -Wno-endif-labels
3825 @opindex Wno-endif-labels
3826 @opindex Wendif-labels
3827 Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3832 Warn whenever a local variable shadows another local variable, parameter or
3833 global variable or whenever a built-in function is shadowed.
3835 @item -Wlarger-than=@var{len}
3836 @opindex Wlarger-than=@var{len}
3837 @opindex Wlarger-than-@var{len}
3838 Warn whenever an object of larger than @var{len} bytes is defined.
3840 @item -Wframe-larger-than=@var{len}
3841 @opindex Wframe-larger-than
3842 Warn if the size of a function frame is larger than @var{len} bytes.
3843 The computation done to determine the stack frame size is approximate
3844 and not conservative.
3845 The actual requirements may be somewhat greater than @var{len}
3846 even if you do not get a warning. In addition, any space allocated
3847 via @code{alloca}, variable-length arrays, or related constructs
3848 is not included by the compiler when determining
3849 whether or not to issue a warning.
3851 @item -Wunsafe-loop-optimizations
3852 @opindex Wunsafe-loop-optimizations
3853 @opindex Wno-unsafe-loop-optimizations
3854 Warn if the loop cannot be optimized because the compiler could not
3855 assume anything on the bounds of the loop indices. With
3856 @option{-funsafe-loop-optimizations} warn if the compiler made
3859 @item -Wno-pedantic-ms-format @r{(MinGW targets only)}
3860 @opindex Wno-pedantic-ms-format
3861 @opindex Wpedantic-ms-format
3862 Disables the warnings about non-ISO @code{printf} / @code{scanf} format
3863 width specifiers @code{I32}, @code{I64}, and @code{I} used on Windows targets
3864 depending on the MS runtime, when you are using the options @option{-Wformat}
3865 and @option{-pedantic} without gnu-extensions.
3867 @item -Wpointer-arith
3868 @opindex Wpointer-arith
3869 @opindex Wno-pointer-arith
3870 Warn about anything that depends on the ``size of'' a function type or
3871 of @code{void}. GNU C assigns these types a size of 1, for
3872 convenience in calculations with @code{void *} pointers and pointers
3873 to functions. In C++, warn also when an arithmetic operation involves
3874 @code{NULL}. This warning is also enabled by @option{-pedantic}.
3877 @opindex Wtype-limits
3878 @opindex Wno-type-limits
3879 Warn if a comparison is always true or always false due to the limited
3880 range of the data type, but do not warn for constant expressions. For
3881 example, warn if an unsigned variable is compared against zero with
3882 @samp{<} or @samp{>=}. This warning is also enabled by
3885 @item -Wbad-function-cast @r{(C and Objective-C only)}
3886 @opindex Wbad-function-cast
3887 @opindex Wno-bad-function-cast
3888 Warn whenever a function call is cast to a non-matching type.
3889 For example, warn if @code{int malloc()} is cast to @code{anything *}.
3891 @item -Wc++-compat @r{(C and Objective-C only)}
3892 Warn about ISO C constructs that are outside of the common subset of
3893 ISO C and ISO C++, e.g.@: request for implicit conversion from
3894 @code{void *} to a pointer to non-@code{void} type.
3896 @item -Wc++0x-compat @r{(C++ and Objective-C++ only)}
3897 Warn about C++ constructs whose meaning differs between ISO C++ 1998 and
3898 ISO C++ 200x, e.g., identifiers in ISO C++ 1998 that will become keywords
3899 in ISO C++ 200x. This warning is enabled by @option{-Wall}.
3903 @opindex Wno-cast-qual
3904 Warn whenever a pointer is cast so as to remove a type qualifier from
3905 the target type. For example, warn if a @code{const char *} is cast
3906 to an ordinary @code{char *}.
3908 Also warn when making a cast which introduces a type qualifier in an
3909 unsafe way. For example, casting @code{char **} to @code{const char **}
3910 is unsafe, as in this example:
3913 /* p is char ** value. */
3914 const char **q = (const char **) p;
3915 /* Assignment of readonly string to const char * is OK. */
3917 /* Now char** pointer points to read-only memory. */
3922 @opindex Wcast-align
3923 @opindex Wno-cast-align
3924 Warn whenever a pointer is cast such that the required alignment of the
3925 target is increased. For example, warn if a @code{char *} is cast to
3926 an @code{int *} on machines where integers can only be accessed at
3927 two- or four-byte boundaries.
3929 @item -Wwrite-strings
3930 @opindex Wwrite-strings
3931 @opindex Wno-write-strings
3932 When compiling C, give string constants the type @code{const
3933 char[@var{length}]} so that copying the address of one into a
3934 non-@code{const} @code{char *} pointer will get a warning. These
3935 warnings will help you find at compile time code that can try to write
3936 into a string constant, but only if you have been very careful about
3937 using @code{const} in declarations and prototypes. Otherwise, it will
3938 just be a nuisance. This is why we did not make @option{-Wall} request
3941 When compiling C++, warn about the deprecated conversion from string
3942 literals to @code{char *}. This warning is enabled by default for C++
3947 @opindex Wno-clobbered
3948 Warn for variables that might be changed by @samp{longjmp} or
3949 @samp{vfork}. This warning is also enabled by @option{-Wextra}.
3952 @opindex Wconversion
3953 @opindex Wno-conversion
3954 Warn for implicit conversions that may alter a value. This includes
3955 conversions between real and integer, like @code{abs (x)} when
3956 @code{x} is @code{double}; conversions between signed and unsigned,
3957 like @code{unsigned ui = -1}; and conversions to smaller types, like
3958 @code{sqrtf (M_PI)}. Do not warn for explicit casts like @code{abs
3959 ((int) x)} and @code{ui = (unsigned) -1}, or if the value is not
3960 changed by the conversion like in @code{abs (2.0)}. Warnings about
3961 conversions between signed and unsigned integers can be disabled by
3962 using @option{-Wno-sign-conversion}.
3964 For C++, also warn for confusing overload resolution for user-defined
3965 conversions; and conversions that will never use a type conversion
3966 operator: conversions to @code{void}, the same type, a base class or a
3967 reference to them. Warnings about conversions between signed and
3968 unsigned integers are disabled by default in C++ unless
3969 @option{-Wsign-conversion} is explicitly enabled.
3971 @item -Wno-conversion-null @r{(C++ and Objective-C++ only)}
3972 @opindex Wconversion-null
3973 @opindex Wno-conversion-null
3974 Do not warn for conversions between @code{NULL} and non-pointer
3975 types. @option{-Wconversion-null} is enabled by default.
3978 @opindex Wempty-body
3979 @opindex Wno-empty-body
3980 Warn if an empty body occurs in an @samp{if}, @samp{else} or @samp{do
3981 while} statement. This warning is also enabled by @option{-Wextra}.
3983 @item -Wenum-compare
3984 @opindex Wenum-compare
3985 @opindex Wno-enum-compare
3986 Warn about a comparison between values of different enum types. In C++
3987 this warning is enabled by default. In C this warning is enabled by
3990 @item -Wjump-misses-init @r{(C, Objective-C only)}
3991 @opindex Wjump-misses-init
3992 @opindex Wno-jump-misses-init
3993 Warn if a @code{goto} statement or a @code{switch} statement jumps
3994 forward across the initialization of a variable, or jumps backward to a
3995 label after the variable has been initialized. This only warns about
3996 variables which are initialized when they are declared. This warning is
3997 only supported for C and Objective C; in C++ this sort of branch is an
4000 @option{-Wjump-misses-init} is included in @option{-Wc++-compat}. It
4001 can be disabled with the @option{-Wno-jump-misses-init} option.
4003 @item -Wsign-compare
4004 @opindex Wsign-compare
4005 @opindex Wno-sign-compare
4006 @cindex warning for comparison of signed and unsigned values
4007 @cindex comparison of signed and unsigned values, warning
4008 @cindex signed and unsigned values, comparison warning
4009 Warn when a comparison between signed and unsigned values could produce
4010 an incorrect result when the signed value is converted to unsigned.
4011 This warning is also enabled by @option{-Wextra}; to get the other warnings
4012 of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
4014 @item -Wsign-conversion
4015 @opindex Wsign-conversion
4016 @opindex Wno-sign-conversion
4017 Warn for implicit conversions that may change the sign of an integer
4018 value, like assigning a signed integer expression to an unsigned
4019 integer variable. An explicit cast silences the warning. In C, this
4020 option is enabled also by @option{-Wconversion}.
4024 @opindex Wno-address
4025 Warn about suspicious uses of memory addresses. These include using
4026 the address of a function in a conditional expression, such as
4027 @code{void func(void); if (func)}, and comparisons against the memory
4028 address of a string literal, such as @code{if (x == "abc")}. Such
4029 uses typically indicate a programmer error: the address of a function
4030 always evaluates to true, so their use in a conditional usually
4031 indicate that the programmer forgot the parentheses in a function
4032 call; and comparisons against string literals result in unspecified
4033 behavior and are not portable in C, so they usually indicate that the
4034 programmer intended to use @code{strcmp}. This warning is enabled by
4038 @opindex Wlogical-op
4039 @opindex Wno-logical-op
4040 Warn about suspicious uses of logical operators in expressions.
4041 This includes using logical operators in contexts where a
4042 bit-wise operator is likely to be expected.
4044 @item -Waggregate-return
4045 @opindex Waggregate-return
4046 @opindex Wno-aggregate-return
4047 Warn if any functions that return structures or unions are defined or
4048 called. (In languages where you can return an array, this also elicits
4051 @item -Wno-attributes
4052 @opindex Wno-attributes
4053 @opindex Wattributes
4054 Do not warn if an unexpected @code{__attribute__} is used, such as
4055 unrecognized attributes, function attributes applied to variables,
4056 etc. This will not stop errors for incorrect use of supported
4059 @item -Wno-builtin-macro-redefined
4060 @opindex Wno-builtin-macro-redefined
4061 @opindex Wbuiltin-macro-redefined
4062 Do not warn if certain built-in macros are redefined. This suppresses
4063 warnings for redefinition of @code{__TIMESTAMP__}, @code{__TIME__},
4064 @code{__DATE__}, @code{__FILE__}, and @code{__BASE_FILE__}.
4066 @item -Wstrict-prototypes @r{(C and Objective-C only)}
4067 @opindex Wstrict-prototypes
4068 @opindex Wno-strict-prototypes
4069 Warn if a function is declared or defined without specifying the
4070 argument types. (An old-style function definition is permitted without
4071 a warning if preceded by a declaration which specifies the argument
4074 @item -Wold-style-declaration @r{(C and Objective-C only)}
4075 @opindex Wold-style-declaration
4076 @opindex Wno-old-style-declaration
4077 Warn for obsolescent usages, according to the C Standard, in a
4078 declaration. For example, warn if storage-class specifiers like
4079 @code{static} are not the first things in a declaration. This warning
4080 is also enabled by @option{-Wextra}.
4082 @item -Wold-style-definition @r{(C and Objective-C only)}
4083 @opindex Wold-style-definition
4084 @opindex Wno-old-style-definition
4085 Warn if an old-style function definition is used. A warning is given
4086 even if there is a previous prototype.
4088 @item -Wmissing-parameter-type @r{(C and Objective-C only)}
4089 @opindex Wmissing-parameter-type
4090 @opindex Wno-missing-parameter-type
4091 A function parameter is declared without a type specifier in K&R-style
4098 This warning is also enabled by @option{-Wextra}.
4100 @item -Wmissing-prototypes @r{(C and Objective-C only)}
4101 @opindex Wmissing-prototypes
4102 @opindex Wno-missing-prototypes
4103 Warn if a global function is defined without a previous prototype
4104 declaration. This warning is issued even if the definition itself
4105 provides a prototype. The aim is to detect global functions that fail
4106 to be declared in header files.
4108 @item -Wmissing-declarations
4109 @opindex Wmissing-declarations
4110 @opindex Wno-missing-declarations
4111 Warn if a global function is defined without a previous declaration.
4112 Do so even if the definition itself provides a prototype.
4113 Use this option to detect global functions that are not declared in
4114 header files. In C++, no warnings are issued for function templates,
4115 or for inline functions, or for functions in anonymous namespaces.
4117 @item -Wmissing-field-initializers
4118 @opindex Wmissing-field-initializers
4119 @opindex Wno-missing-field-initializers
4123 Warn if a structure's initializer has some fields missing. For
4124 example, the following code would cause such a warning, because
4125 @code{x.h} is implicitly zero:
4128 struct s @{ int f, g, h; @};
4129 struct s x = @{ 3, 4 @};
4132 This option does not warn about designated initializers, so the following
4133 modification would not trigger a warning:
4136 struct s @{ int f, g, h; @};
4137 struct s x = @{ .f = 3, .g = 4 @};
4140 This warning is included in @option{-Wextra}. To get other @option{-Wextra}
4141 warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
4143 @item -Wmissing-noreturn
4144 @opindex Wmissing-noreturn
4145 @opindex Wno-missing-noreturn
4146 Warn about functions which might be candidates for attribute @code{noreturn}.
4147 Note these are only possible candidates, not absolute ones. Care should
4148 be taken to manually verify functions actually do not ever return before
4149 adding the @code{noreturn} attribute, otherwise subtle code generation
4150 bugs could be introduced. You will not get a warning for @code{main} in
4151 hosted C environments.
4153 @item -Wmissing-format-attribute
4154 @opindex Wmissing-format-attribute
4155 @opindex Wno-missing-format-attribute
4158 Warn about function pointers which might be candidates for @code{format}
4159 attributes. Note these are only possible candidates, not absolute ones.
4160 GCC will guess that function pointers with @code{format} attributes that
4161 are used in assignment, initialization, parameter passing or return
4162 statements should have a corresponding @code{format} attribute in the
4163 resulting type. I.e.@: the left-hand side of the assignment or
4164 initialization, the type of the parameter variable, or the return type
4165 of the containing function respectively should also have a @code{format}
4166 attribute to avoid the warning.
4168 GCC will also warn about function definitions which might be
4169 candidates for @code{format} attributes. Again, these are only
4170 possible candidates. GCC will guess that @code{format} attributes
4171 might be appropriate for any function that calls a function like
4172 @code{vprintf} or @code{vscanf}, but this might not always be the
4173 case, and some functions for which @code{format} attributes are
4174 appropriate may not be detected.
4176 @item -Wno-multichar
4177 @opindex Wno-multichar
4179 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
4180 Usually they indicate a typo in the user's code, as they have
4181 implementation-defined values, and should not be used in portable code.
4183 @item -Wnormalized=<none|id|nfc|nfkc>
4184 @opindex Wnormalized=
4187 @cindex character set, input normalization
4188 In ISO C and ISO C++, two identifiers are different if they are
4189 different sequences of characters. However, sometimes when characters
4190 outside the basic ASCII character set are used, you can have two
4191 different character sequences that look the same. To avoid confusion,
4192 the ISO 10646 standard sets out some @dfn{normalization rules} which
4193 when applied ensure that two sequences that look the same are turned into
4194 the same sequence. GCC can warn you if you are using identifiers which
4195 have not been normalized; this option controls that warning.
4197 There are four levels of warning that GCC supports. The default is
4198 @option{-Wnormalized=nfc}, which warns about any identifier which is
4199 not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
4200 recommended form for most uses.
4202 Unfortunately, there are some characters which ISO C and ISO C++ allow
4203 in identifiers that when turned into NFC aren't allowable as
4204 identifiers. That is, there's no way to use these symbols in portable
4205 ISO C or C++ and have all your identifiers in NFC@.
4206 @option{-Wnormalized=id} suppresses the warning for these characters.
4207 It is hoped that future versions of the standards involved will correct
4208 this, which is why this option is not the default.
4210 You can switch the warning off for all characters by writing
4211 @option{-Wnormalized=none}. You would only want to do this if you
4212 were using some other normalization scheme (like ``D''), because
4213 otherwise you can easily create bugs that are literally impossible to see.
4215 Some characters in ISO 10646 have distinct meanings but look identical
4216 in some fonts or display methodologies, especially once formatting has
4217 been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
4218 LETTER N'', will display just like a regular @code{n} which has been
4219 placed in a superscript. ISO 10646 defines the @dfn{NFKC}
4220 normalization scheme to convert all these into a standard form as
4221 well, and GCC will warn if your code is not in NFKC if you use
4222 @option{-Wnormalized=nfkc}. This warning is comparable to warning
4223 about every identifier that contains the letter O because it might be
4224 confused with the digit 0, and so is not the default, but may be
4225 useful as a local coding convention if the programming environment is
4226 unable to be fixed to display these characters distinctly.
4228 @item -Wno-deprecated
4229 @opindex Wno-deprecated
4230 @opindex Wdeprecated
4231 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
4233 @item -Wno-deprecated-declarations
4234 @opindex Wno-deprecated-declarations
4235 @opindex Wdeprecated-declarations
4236 Do not warn about uses of functions (@pxref{Function Attributes}),
4237 variables (@pxref{Variable Attributes}), and types (@pxref{Type
4238 Attributes}) marked as deprecated by using the @code{deprecated}
4242 @opindex Wno-overflow
4244 Do not warn about compile-time overflow in constant expressions.
4246 @item -Woverride-init @r{(C and Objective-C only)}
4247 @opindex Woverride-init
4248 @opindex Wno-override-init
4252 Warn if an initialized field without side effects is overridden when
4253 using designated initializers (@pxref{Designated Inits, , Designated
4256 This warning is included in @option{-Wextra}. To get other
4257 @option{-Wextra} warnings without this one, use @samp{-Wextra
4258 -Wno-override-init}.
4263 Warn if a structure is given the packed attribute, but the packed
4264 attribute has no effect on the layout or size of the structure.
4265 Such structures may be mis-aligned for little benefit. For
4266 instance, in this code, the variable @code{f.x} in @code{struct bar}
4267 will be misaligned even though @code{struct bar} does not itself
4268 have the packed attribute:
4275 @} __attribute__((packed));
4283 @item -Wpacked-bitfield-compat
4284 @opindex Wpacked-bitfield-compat
4285 @opindex Wno-packed-bitfield-compat
4286 The 4.1, 4.2 and 4.3 series of GCC ignore the @code{packed} attribute
4287 on bit-fields of type @code{char}. This has been fixed in GCC 4.4 but
4288 the change can lead to differences in the structure layout. GCC
4289 informs you when the offset of such a field has changed in GCC 4.4.
4290 For example there is no longer a 4-bit padding between field @code{a}
4291 and @code{b} in this structure:
4298 @} __attribute__ ((packed));
4301 This warning is enabled by default. Use
4302 @option{-Wno-packed-bitfield-compat} to disable this warning.
4307 Warn if padding is included in a structure, either to align an element
4308 of the structure or to align the whole structure. Sometimes when this
4309 happens it is possible to rearrange the fields of the structure to
4310 reduce the padding and so make the structure smaller.
4312 @item -Wredundant-decls
4313 @opindex Wredundant-decls
4314 @opindex Wno-redundant-decls
4315 Warn if anything is declared more than once in the same scope, even in
4316 cases where multiple declaration is valid and changes nothing.
4318 @item -Wnested-externs @r{(C and Objective-C only)}
4319 @opindex Wnested-externs
4320 @opindex Wno-nested-externs
4321 Warn if an @code{extern} declaration is encountered within a function.
4326 Warn if a function can not be inlined and it was declared as inline.
4327 Even with this option, the compiler will not warn about failures to
4328 inline functions declared in system headers.
4330 The compiler uses a variety of heuristics to determine whether or not
4331 to inline a function. For example, the compiler takes into account
4332 the size of the function being inlined and the amount of inlining
4333 that has already been done in the current function. Therefore,
4334 seemingly insignificant changes in the source program can cause the
4335 warnings produced by @option{-Winline} to appear or disappear.
4337 @item -Wno-invalid-offsetof @r{(C++ and Objective-C++ only)}
4338 @opindex Wno-invalid-offsetof
4339 @opindex Winvalid-offsetof
4340 Suppress warnings from applying the @samp{offsetof} macro to a non-POD
4341 type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
4342 to a non-POD type is undefined. In existing C++ implementations,
4343 however, @samp{offsetof} typically gives meaningful results even when
4344 applied to certain kinds of non-POD types. (Such as a simple
4345 @samp{struct} that fails to be a POD type only by virtue of having a
4346 constructor.) This flag is for users who are aware that they are
4347 writing nonportable code and who have deliberately chosen to ignore the
4350 The restrictions on @samp{offsetof} may be relaxed in a future version
4351 of the C++ standard.
4353 @item -Wno-int-to-pointer-cast
4354 @opindex Wno-int-to-pointer-cast
4355 @opindex Wint-to-pointer-cast
4356 Suppress warnings from casts to pointer type of an integer of a
4357 different size. In C++, casting to a pointer type of smaller size is
4358 an error. @option{Wint-to-pointer-cast} is enabled by default.
4361 @item -Wno-pointer-to-int-cast @r{(C and Objective-C only)}
4362 @opindex Wno-pointer-to-int-cast
4363 @opindex Wpointer-to-int-cast
4364 Suppress warnings from casts from a pointer to an integer type of a
4368 @opindex Winvalid-pch
4369 @opindex Wno-invalid-pch
4370 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
4371 the search path but can't be used.
4375 @opindex Wno-long-long
4376 Warn if @samp{long long} type is used. This is enabled by either
4377 @option{-pedantic} or @option{-Wtraditional} in ISO C90 and C++98
4378 modes. To inhibit the warning messages, use @option{-Wno-long-long}.
4380 @item -Wvariadic-macros
4381 @opindex Wvariadic-macros
4382 @opindex Wno-variadic-macros
4383 Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
4384 alternate syntax when in pedantic ISO C99 mode. This is default.
4385 To inhibit the warning messages, use @option{-Wno-variadic-macros}.
4390 Warn if variable length array is used in the code.
4391 @option{-Wno-vla} will prevent the @option{-pedantic} warning of
4392 the variable length array.
4394 @item -Wvolatile-register-var
4395 @opindex Wvolatile-register-var
4396 @opindex Wno-volatile-register-var
4397 Warn if a register variable is declared volatile. The volatile
4398 modifier does not inhibit all optimizations that may eliminate reads
4399 and/or writes to register variables. This warning is enabled by
4402 @item -Wdisabled-optimization
4403 @opindex Wdisabled-optimization
4404 @opindex Wno-disabled-optimization
4405 Warn if a requested optimization pass is disabled. This warning does
4406 not generally indicate that there is anything wrong with your code; it
4407 merely indicates that GCC's optimizers were unable to handle the code
4408 effectively. Often, the problem is that your code is too big or too
4409 complex; GCC will refuse to optimize programs when the optimization
4410 itself is likely to take inordinate amounts of time.
4412 @item -Wpointer-sign @r{(C and Objective-C only)}
4413 @opindex Wpointer-sign
4414 @opindex Wno-pointer-sign
4415 Warn for pointer argument passing or assignment with different signedness.
4416 This option is only supported for C and Objective-C@. It is implied by
4417 @option{-Wall} and by @option{-pedantic}, which can be disabled with
4418 @option{-Wno-pointer-sign}.
4420 @item -Wstack-protector
4421 @opindex Wstack-protector
4422 @opindex Wno-stack-protector
4423 This option is only active when @option{-fstack-protector} is active. It
4424 warns about functions that will not be protected against stack smashing.
4427 @opindex Wno-mudflap
4428 Suppress warnings about constructs that cannot be instrumented by
4431 @item -Woverlength-strings
4432 @opindex Woverlength-strings
4433 @opindex Wno-overlength-strings
4434 Warn about string constants which are longer than the ``minimum
4435 maximum'' length specified in the C standard. Modern compilers
4436 generally allow string constants which are much longer than the
4437 standard's minimum limit, but very portable programs should avoid
4438 using longer strings.
4440 The limit applies @emph{after} string constant concatenation, and does
4441 not count the trailing NUL@. In C90, the limit was 509 characters; in
4442 C99, it was raised to 4095. C++98 does not specify a normative
4443 minimum maximum, so we do not diagnose overlength strings in C++@.
4445 This option is implied by @option{-pedantic}, and can be disabled with
4446 @option{-Wno-overlength-strings}.
4448 @item -Wunsuffixed-float-constants @r{(C and Objective-C only)}
4449 @opindex Wunsuffixed-float-constants
4451 GCC will issue a warning for any floating constant that does not have
4452 a suffix. When used together with @option{-Wsystem-headers} it will
4453 warn about such constants in system header files. This can be useful
4454 when preparing code to use with the @code{FLOAT_CONST_DECIMAL64} pragma
4455 from the decimal floating-point extension to C99.
4458 @node Debugging Options
4459 @section Options for Debugging Your Program or GCC
4460 @cindex options, debugging
4461 @cindex debugging information options
4463 GCC has various special options that are used for debugging
4464 either your program or GCC:
4469 Produce debugging information in the operating system's native format
4470 (stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
4473 On most systems that use stabs format, @option{-g} enables use of extra
4474 debugging information that only GDB can use; this extra information
4475 makes debugging work better in GDB but will probably make other debuggers
4477 refuse to read the program. If you want to control for certain whether
4478 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
4479 @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
4481 GCC allows you to use @option{-g} with
4482 @option{-O}. The shortcuts taken by optimized code may occasionally
4483 produce surprising results: some variables you declared may not exist
4484 at all; flow of control may briefly move where you did not expect it;
4485 some statements may not be executed because they compute constant
4486 results or their values were already at hand; some statements may
4487 execute in different places because they were moved out of loops.
4489 Nevertheless it proves possible to debug optimized output. This makes
4490 it reasonable to use the optimizer for programs that might have bugs.
4492 The following options are useful when GCC is generated with the
4493 capability for more than one debugging format.
4497 Produce debugging information for use by GDB@. This means to use the
4498 most expressive format available (DWARF 2, stabs, or the native format
4499 if neither of those are supported), including GDB extensions if at all
4504 Produce debugging information in stabs format (if that is supported),
4505 without GDB extensions. This is the format used by DBX on most BSD
4506 systems. On MIPS, Alpha and System V Release 4 systems this option
4507 produces stabs debugging output which is not understood by DBX or SDB@.
4508 On System V Release 4 systems this option requires the GNU assembler.
4510 @item -feliminate-unused-debug-symbols
4511 @opindex feliminate-unused-debug-symbols
4512 Produce debugging information in stabs format (if that is supported),
4513 for only symbols that are actually used.
4515 @item -femit-class-debug-always
4516 Instead of emitting debugging information for a C++ class in only one
4517 object file, emit it in all object files using the class. This option
4518 should be used only with debuggers that are unable to handle the way GCC
4519 normally emits debugging information for classes because using this
4520 option will increase the size of debugging information by as much as a
4525 Produce debugging information in stabs format (if that is supported),
4526 using GNU extensions understood only by the GNU debugger (GDB)@. The
4527 use of these extensions is likely to make other debuggers crash or
4528 refuse to read the program.
4532 Produce debugging information in COFF format (if that is supported).
4533 This is the format used by SDB on most System V systems prior to
4538 Produce debugging information in XCOFF format (if that is supported).
4539 This is the format used by the DBX debugger on IBM RS/6000 systems.
4543 Produce debugging information in XCOFF format (if that is supported),
4544 using GNU extensions understood only by the GNU debugger (GDB)@. The
4545 use of these extensions is likely to make other debuggers crash or
4546 refuse to read the program, and may cause assemblers other than the GNU
4547 assembler (GAS) to fail with an error.
4549 @item -gdwarf-@var{version}
4550 @opindex gdwarf-@var{version}
4551 Produce debugging information in DWARF format (if that is
4552 supported). This is the format used by DBX on IRIX 6. The value
4553 of @var{version} may be either 2, 3 or 4; the default version is 2.
4555 Note that with DWARF version 2 some ports require, and will always
4556 use, some non-conflicting DWARF 3 extensions in the unwind tables.
4558 Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments}
4559 for maximum benefit.
4561 @item -gstrict-dwarf
4562 @opindex gstrict-dwarf
4563 Disallow using extensions of later DWARF standard version than selected
4564 with @option{-gdwarf-@var{version}}. On most targets using non-conflicting
4565 DWARF extensions from later standard versions is allowed.
4567 @item -gno-strict-dwarf
4568 @opindex gno-strict-dwarf
4569 Allow using extensions of later DWARF standard version than selected with
4570 @option{-gdwarf-@var{version}}.
4574 Produce debugging information in VMS debug format (if that is
4575 supported). This is the format used by DEBUG on VMS systems.
4578 @itemx -ggdb@var{level}
4579 @itemx -gstabs@var{level}
4580 @itemx -gcoff@var{level}
4581 @itemx -gxcoff@var{level}
4582 @itemx -gvms@var{level}
4583 Request debugging information and also use @var{level} to specify how
4584 much information. The default level is 2.
4586 Level 0 produces no debug information at all. Thus, @option{-g0} negates
4589 Level 1 produces minimal information, enough for making backtraces in
4590 parts of the program that you don't plan to debug. This includes
4591 descriptions of functions and external variables, but no information
4592 about local variables and no line numbers.
4594 Level 3 includes extra information, such as all the macro definitions
4595 present in the program. Some debuggers support macro expansion when
4596 you use @option{-g3}.
4598 @option{-gdwarf-2} does not accept a concatenated debug level, because
4599 GCC used to support an option @option{-gdwarf} that meant to generate
4600 debug information in version 1 of the DWARF format (which is very
4601 different from version 2), and it would have been too confusing. That
4602 debug format is long obsolete, but the option cannot be changed now.
4603 Instead use an additional @option{-g@var{level}} option to change the
4604 debug level for DWARF.
4608 Turn off generation of debug info, if leaving out this option would have
4609 generated it, or turn it on at level 2 otherwise. The position of this
4610 argument in the command line does not matter, it takes effect after all
4611 other options are processed, and it does so only once, no matter how
4612 many times it is given. This is mainly intended to be used with
4613 @option{-fcompare-debug}.
4615 @item -fdump-final-insns@r{[}=@var{file}@r{]}
4616 @opindex fdump-final-insns
4617 Dump the final internal representation (RTL) to @var{file}. If the
4618 optional argument is omitted (or if @var{file} is @code{.}), the name
4619 of the dump file will be determined by appending @code{.gkd} to the
4620 compilation output file name.
4622 @item -fcompare-debug@r{[}=@var{opts}@r{]}
4623 @opindex fcompare-debug
4624 @opindex fno-compare-debug
4625 If no error occurs during compilation, run the compiler a second time,
4626 adding @var{opts} and @option{-fcompare-debug-second} to the arguments
4627 passed to the second compilation. Dump the final internal
4628 representation in both compilations, and print an error if they differ.
4630 If the equal sign is omitted, the default @option{-gtoggle} is used.
4632 The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty
4633 and nonzero, implicitly enables @option{-fcompare-debug}. If
4634 @env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash,
4635 then it is used for @var{opts}, otherwise the default @option{-gtoggle}
4638 @option{-fcompare-debug=}, with the equal sign but without @var{opts},
4639 is equivalent to @option{-fno-compare-debug}, which disables the dumping
4640 of the final representation and the second compilation, preventing even
4641 @env{GCC_COMPARE_DEBUG} from taking effect.
4643 To verify full coverage during @option{-fcompare-debug} testing, set
4644 @env{GCC_COMPARE_DEBUG} to say @samp{-fcompare-debug-not-overridden},
4645 which GCC will reject as an invalid option in any actual compilation
4646 (rather than preprocessing, assembly or linking). To get just a
4647 warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug
4648 not overridden} will do.
4650 @item -fcompare-debug-second
4651 @opindex fcompare-debug-second
4652 This option is implicitly passed to the compiler for the second
4653 compilation requested by @option{-fcompare-debug}, along with options to
4654 silence warnings, and omitting other options that would cause
4655 side-effect compiler outputs to files or to the standard output. Dump
4656 files and preserved temporary files are renamed so as to contain the
4657 @code{.gk} additional extension during the second compilation, to avoid
4658 overwriting those generated by the first.
4660 When this option is passed to the compiler driver, it causes the
4661 @emph{first} compilation to be skipped, which makes it useful for little
4662 other than debugging the compiler proper.
4664 @item -feliminate-dwarf2-dups
4665 @opindex feliminate-dwarf2-dups
4666 Compress DWARF2 debugging information by eliminating duplicated
4667 information about each symbol. This option only makes sense when
4668 generating DWARF2 debugging information with @option{-gdwarf-2}.
4670 @item -femit-struct-debug-baseonly
4671 Emit debug information for struct-like types
4672 only when the base name of the compilation source file
4673 matches the base name of file in which the struct was defined.
4675 This option substantially reduces the size of debugging information,
4676 but at significant potential loss in type information to the debugger.
4677 See @option{-femit-struct-debug-reduced} for a less aggressive option.
4678 See @option{-femit-struct-debug-detailed} for more detailed control.
4680 This option works only with DWARF 2.
4682 @item -femit-struct-debug-reduced
4683 Emit debug information for struct-like types
4684 only when the base name of the compilation source file
4685 matches the base name of file in which the type was defined,
4686 unless the struct is a template or defined in a system header.
4688 This option significantly reduces the size of debugging information,
4689 with some potential loss in type information to the debugger.
4690 See @option{-femit-struct-debug-baseonly} for a more aggressive option.
4691 See @option{-femit-struct-debug-detailed} for more detailed control.
4693 This option works only with DWARF 2.
4695 @item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
4696 Specify the struct-like types
4697 for which the compiler will generate debug information.
4698 The intent is to reduce duplicate struct debug information
4699 between different object files within the same program.
4701 This option is a detailed version of
4702 @option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
4703 which will serve for most needs.
4705 A specification has the syntax
4706 [@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
4708 The optional first word limits the specification to
4709 structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
4710 A struct type is used directly when it is the type of a variable, member.
4711 Indirect uses arise through pointers to structs.
4712 That is, when use of an incomplete struct would be legal, the use is indirect.
4714 @samp{struct one direct; struct two * indirect;}.
4716 The optional second word limits the specification to
4717 ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
4718 Generic structs are a bit complicated to explain.
4719 For C++, these are non-explicit specializations of template classes,
4720 or non-template classes within the above.
4721 Other programming languages have generics,
4722 but @samp{-femit-struct-debug-detailed} does not yet implement them.
4724 The third word specifies the source files for those
4725 structs for which the compiler will emit debug information.
4726 The values @samp{none} and @samp{any} have the normal meaning.
4727 The value @samp{base} means that
4728 the base of name of the file in which the type declaration appears
4729 must match the base of the name of the main compilation file.
4730 In practice, this means that
4731 types declared in @file{foo.c} and @file{foo.h} will have debug information,
4732 but types declared in other header will not.
4733 The value @samp{sys} means those types satisfying @samp{base}
4734 or declared in system or compiler headers.
4736 You may need to experiment to determine the best settings for your application.
4738 The default is @samp{-femit-struct-debug-detailed=all}.
4740 This option works only with DWARF 2.
4742 @item -fenable-icf-debug
4743 @opindex fenable-icf-debug
4744 Generate additional debug information to support identical code folding (ICF).
4745 This option only works with DWARF version 2 or higher.
4747 @item -fno-merge-debug-strings
4748 @opindex fmerge-debug-strings
4749 @opindex fno-merge-debug-strings
4750 Direct the linker to not merge together strings in the debugging
4751 information which are identical in different object files. Merging is
4752 not supported by all assemblers or linkers. Merging decreases the size
4753 of the debug information in the output file at the cost of increasing
4754 link processing time. Merging is enabled by default.
4756 @item -fdebug-prefix-map=@var{old}=@var{new}
4757 @opindex fdebug-prefix-map
4758 When compiling files in directory @file{@var{old}}, record debugging
4759 information describing them as in @file{@var{new}} instead.
4761 @item -fno-dwarf2-cfi-asm
4762 @opindex fdwarf2-cfi-asm
4763 @opindex fno-dwarf2-cfi-asm
4764 Emit DWARF 2 unwind info as compiler generated @code{.eh_frame} section
4765 instead of using GAS @code{.cfi_*} directives.
4767 @cindex @command{prof}
4770 Generate extra code to write profile information suitable for the
4771 analysis program @command{prof}. You must use this option when compiling
4772 the source files you want data about, and you must also use it when
4775 @cindex @command{gprof}
4778 Generate extra code to write profile information suitable for the
4779 analysis program @command{gprof}. You must use this option when compiling
4780 the source files you want data about, and you must also use it when
4785 Makes the compiler print out each function name as it is compiled, and
4786 print some statistics about each pass when it finishes.
4789 @opindex ftime-report
4790 Makes the compiler print some statistics about the time consumed by each
4791 pass when it finishes.
4794 @opindex fmem-report
4795 Makes the compiler print some statistics about permanent memory
4796 allocation when it finishes.
4798 @item -fpre-ipa-mem-report
4799 @opindex fpre-ipa-mem-report
4800 @item -fpost-ipa-mem-report
4801 @opindex fpost-ipa-mem-report
4802 Makes the compiler print some statistics about permanent memory
4803 allocation before or after interprocedural optimization.
4805 @item -fprofile-arcs
4806 @opindex fprofile-arcs
4807 Add code so that program flow @dfn{arcs} are instrumented. During
4808 execution the program records how many times each branch and call is
4809 executed and how many times it is taken or returns. When the compiled
4810 program exits it saves this data to a file called
4811 @file{@var{auxname}.gcda} for each source file. The data may be used for
4812 profile-directed optimizations (@option{-fbranch-probabilities}), or for
4813 test coverage analysis (@option{-ftest-coverage}). Each object file's
4814 @var{auxname} is generated from the name of the output file, if
4815 explicitly specified and it is not the final executable, otherwise it is
4816 the basename of the source file. In both cases any suffix is removed
4817 (e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
4818 @file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
4819 @xref{Cross-profiling}.
4821 @cindex @command{gcov}
4825 This option is used to compile and link code instrumented for coverage
4826 analysis. The option is a synonym for @option{-fprofile-arcs}
4827 @option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
4828 linking). See the documentation for those options for more details.
4833 Compile the source files with @option{-fprofile-arcs} plus optimization
4834 and code generation options. For test coverage analysis, use the
4835 additional @option{-ftest-coverage} option. You do not need to profile
4836 every source file in a program.
4839 Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
4840 (the latter implies the former).
4843 Run the program on a representative workload to generate the arc profile
4844 information. This may be repeated any number of times. You can run
4845 concurrent instances of your program, and provided that the file system
4846 supports locking, the data files will be correctly updated. Also
4847 @code{fork} calls are detected and correctly handled (double counting
4851 For profile-directed optimizations, compile the source files again with
4852 the same optimization and code generation options plus
4853 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
4854 Control Optimization}).
4857 For test coverage analysis, use @command{gcov} to produce human readable
4858 information from the @file{.gcno} and @file{.gcda} files. Refer to the
4859 @command{gcov} documentation for further information.
4863 With @option{-fprofile-arcs}, for each function of your program GCC
4864 creates a program flow graph, then finds a spanning tree for the graph.
4865 Only arcs that are not on the spanning tree have to be instrumented: the
4866 compiler adds code to count the number of times that these arcs are
4867 executed. When an arc is the only exit or only entrance to a block, the
4868 instrumentation code can be added to the block; otherwise, a new basic
4869 block must be created to hold the instrumentation code.
4872 @item -ftest-coverage
4873 @opindex ftest-coverage
4874 Produce a notes file that the @command{gcov} code-coverage utility
4875 (@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
4876 show program coverage. Each source file's note file is called
4877 @file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
4878 above for a description of @var{auxname} and instructions on how to
4879 generate test coverage data. Coverage data will match the source files
4880 more closely, if you do not optimize.
4882 @item -fdbg-cnt-list
4883 @opindex fdbg-cnt-list
4884 Print the name and the counter upperbound for all debug counters.
4886 @item -fdbg-cnt=@var{counter-value-list}
4888 Set the internal debug counter upperbound. @var{counter-value-list}
4889 is a comma-separated list of @var{name}:@var{value} pairs
4890 which sets the upperbound of each debug counter @var{name} to @var{value}.
4891 All debug counters have the initial upperbound of @var{UINT_MAX},
4892 thus dbg_cnt() returns true always unless the upperbound is set by this option.
4893 e.g. With -fdbg-cnt=dce:10,tail_call:0
4894 dbg_cnt(dce) will return true only for first 10 invocations
4895 and dbg_cnt(tail_call) will return false always.
4897 @item -d@var{letters}
4898 @itemx -fdump-rtl-@var{pass}
4900 Says to make debugging dumps during compilation at times specified by
4901 @var{letters}. This is used for debugging the RTL-based passes of the
4902 compiler. The file names for most of the dumps are made by appending
4903 a pass number and a word to the @var{dumpname}, and the files are
4904 created in the directory of the output file. @var{dumpname} is
4905 generated from the name of the output file, if explicitly specified
4906 and it is not an executable, otherwise it is the basename of the
4907 source file. These switches may have different effects when
4908 @option{-E} is used for preprocessing.
4910 Debug dumps can be enabled with a @option{-fdump-rtl} switch or some
4911 @option{-d} option @var{letters}. Here are the possible
4912 letters for use in @var{pass} and @var{letters}, and their meanings:
4916 @item -fdump-rtl-alignments
4917 @opindex fdump-rtl-alignments
4918 Dump after branch alignments have been computed.
4920 @item -fdump-rtl-asmcons
4921 @opindex fdump-rtl-asmcons
4922 Dump after fixing rtl statements that have unsatisfied in/out constraints.
4924 @item -fdump-rtl-auto_inc_dec
4925 @opindex fdump-rtl-auto_inc_dec
4926 Dump after auto-inc-dec discovery. This pass is only run on
4927 architectures that have auto inc or auto dec instructions.
4929 @item -fdump-rtl-barriers
4930 @opindex fdump-rtl-barriers
4931 Dump after cleaning up the barrier instructions.
4933 @item -fdump-rtl-bbpart
4934 @opindex fdump-rtl-bbpart
4935 Dump after partitioning hot and cold basic blocks.
4937 @item -fdump-rtl-bbro
4938 @opindex fdump-rtl-bbro
4939 Dump after block reordering.
4941 @item -fdump-rtl-btl1
4942 @itemx -fdump-rtl-btl2
4943 @opindex fdump-rtl-btl2
4944 @opindex fdump-rtl-btl2
4945 @option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping
4946 after the two branch
4947 target load optimization passes.
4949 @item -fdump-rtl-bypass
4950 @opindex fdump-rtl-bypass
4951 Dump after jump bypassing and control flow optimizations.
4953 @item -fdump-rtl-combine
4954 @opindex fdump-rtl-combine
4955 Dump after the RTL instruction combination pass.
4957 @item -fdump-rtl-compgotos
4958 @opindex fdump-rtl-compgotos
4959 Dump after duplicating the computed gotos.
4961 @item -fdump-rtl-ce1
4962 @itemx -fdump-rtl-ce2
4963 @itemx -fdump-rtl-ce3
4964 @opindex fdump-rtl-ce1
4965 @opindex fdump-rtl-ce2
4966 @opindex fdump-rtl-ce3
4967 @option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and
4968 @option{-fdump-rtl-ce3} enable dumping after the three
4969 if conversion passes.
4971 @itemx -fdump-rtl-cprop_hardreg
4972 @opindex fdump-rtl-cprop_hardreg
4973 Dump after hard register copy propagation.
4975 @itemx -fdump-rtl-csa
4976 @opindex fdump-rtl-csa
4977 Dump after combining stack adjustments.
4979 @item -fdump-rtl-cse1
4980 @itemx -fdump-rtl-cse2
4981 @opindex fdump-rtl-cse1
4982 @opindex fdump-rtl-cse2
4983 @option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after
4984 the two common sub-expression elimination passes.
4986 @itemx -fdump-rtl-dce
4987 @opindex fdump-rtl-dce
4988 Dump after the standalone dead code elimination passes.
4990 @itemx -fdump-rtl-dbr
4991 @opindex fdump-rtl-dbr
4992 Dump after delayed branch scheduling.
4994 @item -fdump-rtl-dce1
4995 @itemx -fdump-rtl-dce2
4996 @opindex fdump-rtl-dce1
4997 @opindex fdump-rtl-dce2
4998 @option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after
4999 the two dead store elimination passes.
5002 @opindex fdump-rtl-eh
5003 Dump after finalization of EH handling code.
5005 @item -fdump-rtl-eh_ranges
5006 @opindex fdump-rtl-eh_ranges
5007 Dump after conversion of EH handling range regions.
5009 @item -fdump-rtl-expand
5010 @opindex fdump-rtl-expand
5011 Dump after RTL generation.
5013 @item -fdump-rtl-fwprop1
5014 @itemx -fdump-rtl-fwprop2
5015 @opindex fdump-rtl-fwprop1
5016 @opindex fdump-rtl-fwprop2
5017 @option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable
5018 dumping after the two forward propagation passes.
5020 @item -fdump-rtl-gcse1
5021 @itemx -fdump-rtl-gcse2
5022 @opindex fdump-rtl-gcse1
5023 @opindex fdump-rtl-gcse2
5024 @option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping
5025 after global common subexpression elimination.
5027 @item -fdump-rtl-init-regs
5028 @opindex fdump-rtl-init-regs
5029 Dump after the initialization of the registers.
5031 @item -fdump-rtl-initvals
5032 @opindex fdump-rtl-initvals
5033 Dump after the computation of the initial value sets.
5035 @itemx -fdump-rtl-into_cfglayout
5036 @opindex fdump-rtl-into_cfglayout
5037 Dump after converting to cfglayout mode.
5039 @item -fdump-rtl-ira
5040 @opindex fdump-rtl-ira
5041 Dump after iterated register allocation.
5043 @item -fdump-rtl-jump
5044 @opindex fdump-rtl-jump
5045 Dump after the second jump optimization.
5047 @item -fdump-rtl-loop2
5048 @opindex fdump-rtl-loop2
5049 @option{-fdump-rtl-loop2} enables dumping after the rtl
5050 loop optimization passes.
5052 @item -fdump-rtl-mach
5053 @opindex fdump-rtl-mach
5054 Dump after performing the machine dependent reorganization pass, if that
5057 @item -fdump-rtl-mode_sw
5058 @opindex fdump-rtl-mode_sw
5059 Dump after removing redundant mode switches.
5061 @item -fdump-rtl-rnreg
5062 @opindex fdump-rtl-rnreg
5063 Dump after register renumbering.
5065 @itemx -fdump-rtl-outof_cfglayout
5066 @opindex fdump-rtl-outof_cfglayout
5067 Dump after converting from cfglayout mode.
5069 @item -fdump-rtl-peephole2
5070 @opindex fdump-rtl-peephole2
5071 Dump after the peephole pass.
5073 @item -fdump-rtl-postreload
5074 @opindex fdump-rtl-postreload
5075 Dump after post-reload optimizations.
5077 @itemx -fdump-rtl-pro_and_epilogue
5078 @opindex fdump-rtl-pro_and_epilogue
5079 Dump after generating the function pro and epilogues.
5081 @item -fdump-rtl-regmove
5082 @opindex fdump-rtl-regmove
5083 Dump after the register move pass.
5085 @item -fdump-rtl-sched1
5086 @itemx -fdump-rtl-sched2
5087 @opindex fdump-rtl-sched1
5088 @opindex fdump-rtl-sched2
5089 @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping
5090 after the basic block scheduling passes.
5092 @item -fdump-rtl-see
5093 @opindex fdump-rtl-see
5094 Dump after sign extension elimination.
5096 @item -fdump-rtl-seqabstr
5097 @opindex fdump-rtl-seqabstr
5098 Dump after common sequence discovery.
5100 @item -fdump-rtl-shorten
5101 @opindex fdump-rtl-shorten
5102 Dump after shortening branches.
5104 @item -fdump-rtl-sibling
5105 @opindex fdump-rtl-sibling
5106 Dump after sibling call optimizations.
5108 @item -fdump-rtl-split1
5109 @itemx -fdump-rtl-split2
5110 @itemx -fdump-rtl-split3
5111 @itemx -fdump-rtl-split4
5112 @itemx -fdump-rtl-split5
5113 @opindex fdump-rtl-split1
5114 @opindex fdump-rtl-split2
5115 @opindex fdump-rtl-split3
5116 @opindex fdump-rtl-split4
5117 @opindex fdump-rtl-split5
5118 @option{-fdump-rtl-split1}, @option{-fdump-rtl-split2},
5119 @option{-fdump-rtl-split3}, @option{-fdump-rtl-split4} and
5120 @option{-fdump-rtl-split5} enable dumping after five rounds of
5121 instruction splitting.
5123 @item -fdump-rtl-sms
5124 @opindex fdump-rtl-sms
5125 Dump after modulo scheduling. This pass is only run on some
5128 @item -fdump-rtl-stack
5129 @opindex fdump-rtl-stack
5130 Dump after conversion from GCC's "flat register file" registers to the
5131 x87's stack-like registers. This pass is only run on x86 variants.
5133 @item -fdump-rtl-subreg1
5134 @itemx -fdump-rtl-subreg2
5135 @opindex fdump-rtl-subreg1
5136 @opindex fdump-rtl-subreg2
5137 @option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after
5138 the two subreg expansion passes.
5140 @item -fdump-rtl-unshare
5141 @opindex fdump-rtl-unshare
5142 Dump after all rtl has been unshared.
5144 @item -fdump-rtl-vartrack
5145 @opindex fdump-rtl-vartrack
5146 Dump after variable tracking.
5148 @item -fdump-rtl-vregs
5149 @opindex fdump-rtl-vregs
5150 Dump after converting virtual registers to hard registers.
5152 @item -fdump-rtl-web
5153 @opindex fdump-rtl-web
5154 Dump after live range splitting.
5156 @item -fdump-rtl-regclass
5157 @itemx -fdump-rtl-subregs_of_mode_init
5158 @itemx -fdump-rtl-subregs_of_mode_finish
5159 @itemx -fdump-rtl-dfinit
5160 @itemx -fdump-rtl-dfinish
5161 @opindex fdump-rtl-regclass
5162 @opindex fdump-rtl-subregs_of_mode_init
5163 @opindex fdump-rtl-subregs_of_mode_finish
5164 @opindex fdump-rtl-dfinit
5165 @opindex fdump-rtl-dfinish
5166 These dumps are defined but always produce empty files.
5168 @item -fdump-rtl-all
5169 @opindex fdump-rtl-all
5170 Produce all the dumps listed above.
5174 Annotate the assembler output with miscellaneous debugging information.
5178 Dump all macro definitions, at the end of preprocessing, in addition to
5183 Produce a core dump whenever an error occurs.
5187 Print statistics on memory usage, at the end of the run, to
5192 Annotate the assembler output with a comment indicating which
5193 pattern and alternative was used. The length of each instruction is
5198 Dump the RTL in the assembler output as a comment before each instruction.
5199 Also turns on @option{-dp} annotation.
5203 For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}),
5204 dump a representation of the control flow graph suitable for viewing with VCG
5205 to @file{@var{file}.@var{pass}.vcg}.
5209 Just generate RTL for a function instead of compiling it. Usually used
5210 with @option{-fdump-rtl-expand}.
5214 Dump debugging information during parsing, to standard error.
5218 @opindex fdump-noaddr
5219 When doing debugging dumps, suppress address output. This makes it more
5220 feasible to use diff on debugging dumps for compiler invocations with
5221 different compiler binaries and/or different
5222 text / bss / data / heap / stack / dso start locations.
5224 @item -fdump-unnumbered
5225 @opindex fdump-unnumbered
5226 When doing debugging dumps, suppress instruction numbers and address output.
5227 This makes it more feasible to use diff on debugging dumps for compiler
5228 invocations with different options, in particular with and without
5231 @item -fdump-unnumbered-links
5232 @opindex fdump-unnumbered-links
5233 When doing debugging dumps (see @option{-d} option above), suppress
5234 instruction numbers for the links to the previous and next instructions
5237 @item -fdump-translation-unit @r{(C++ only)}
5238 @itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
5239 @opindex fdump-translation-unit
5240 Dump a representation of the tree structure for the entire translation
5241 unit to a file. The file name is made by appending @file{.tu} to the
5242 source file name, and the file is created in the same directory as the
5243 output file. If the @samp{-@var{options}} form is used, @var{options}
5244 controls the details of the dump as described for the
5245 @option{-fdump-tree} options.
5247 @item -fdump-class-hierarchy @r{(C++ only)}
5248 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
5249 @opindex fdump-class-hierarchy
5250 Dump a representation of each class's hierarchy and virtual function
5251 table layout to a file. The file name is made by appending
5252 @file{.class} to the source file name, and the file is created in the
5253 same directory as the output file. If the @samp{-@var{options}} form
5254 is used, @var{options} controls the details of the dump as described
5255 for the @option{-fdump-tree} options.
5257 @item -fdump-ipa-@var{switch}
5259 Control the dumping at various stages of inter-procedural analysis
5260 language tree to a file. The file name is generated by appending a
5261 switch specific suffix to the source file name, and the file is created
5262 in the same directory as the output file. The following dumps are
5267 Enables all inter-procedural analysis dumps.
5270 Dumps information about call-graph optimization, unused function removal,
5271 and inlining decisions.
5274 Dump after function inlining.
5278 @item -fdump-statistics-@var{option}
5279 @opindex fdump-statistics
5280 Enable and control dumping of pass statistics in a separate file. The
5281 file name is generated by appending a suffix ending in
5282 @samp{.statistics} to the source file name, and the file is created in
5283 the same directory as the output file. If the @samp{-@var{option}}
5284 form is used, @samp{-stats} will cause counters to be summed over the
5285 whole compilation unit while @samp{-details} will dump every event as
5286 the passes generate them. The default with no option is to sum
5287 counters for each function compiled.
5289 @item -fdump-tree-@var{switch}
5290 @itemx -fdump-tree-@var{switch}-@var{options}
5292 Control the dumping at various stages of processing the intermediate
5293 language tree to a file. The file name is generated by appending a
5294 switch specific suffix to the source file name, and the file is
5295 created in the same directory as the output file. If the
5296 @samp{-@var{options}} form is used, @var{options} is a list of
5297 @samp{-} separated options that control the details of the dump. Not
5298 all options are applicable to all dumps, those which are not
5299 meaningful will be ignored. The following options are available
5303 Print the address of each node. Usually this is not meaningful as it
5304 changes according to the environment and source file. Its primary use
5305 is for tying up a dump file with a debug environment.
5307 If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that
5308 in the dump instead of @code{DECL_NAME}. Its primary use is ease of
5309 use working backward from mangled names in the assembly file.
5311 Inhibit dumping of members of a scope or body of a function merely
5312 because that scope has been reached. Only dump such items when they
5313 are directly reachable by some other path. When dumping pretty-printed
5314 trees, this option inhibits dumping the bodies of control structures.
5316 Print a raw representation of the tree. By default, trees are
5317 pretty-printed into a C-like representation.
5319 Enable more detailed dumps (not honored by every dump option).
5321 Enable dumping various statistics about the pass (not honored by every dump
5324 Enable showing basic block boundaries (disabled in raw dumps).
5326 Enable showing virtual operands for every statement.
5328 Enable showing line numbers for statements.
5330 Enable showing the unique ID (@code{DECL_UID}) for each variable.
5332 Enable showing the tree dump for each statement.
5334 Enable showing the EH region number holding each statement.
5336 Turn on all options, except @option{raw}, @option{slim}, @option{verbose}
5337 and @option{lineno}.
5340 The following tree dumps are possible:
5344 @opindex fdump-tree-original
5345 Dump before any tree based optimization, to @file{@var{file}.original}.
5348 @opindex fdump-tree-optimized
5349 Dump after all tree based optimization, to @file{@var{file}.optimized}.
5352 @opindex fdump-tree-gimple
5353 Dump each function before and after the gimplification pass to a file. The
5354 file name is made by appending @file{.gimple} to the source file name.
5357 @opindex fdump-tree-cfg
5358 Dump the control flow graph of each function to a file. The file name is
5359 made by appending @file{.cfg} to the source file name.
5362 @opindex fdump-tree-vcg
5363 Dump the control flow graph of each function to a file in VCG format. The
5364 file name is made by appending @file{.vcg} to the source file name. Note
5365 that if the file contains more than one function, the generated file cannot
5366 be used directly by VCG@. You will need to cut and paste each function's
5367 graph into its own separate file first.
5370 @opindex fdump-tree-ch
5371 Dump each function after copying loop headers. The file name is made by
5372 appending @file{.ch} to the source file name.
5375 @opindex fdump-tree-ssa
5376 Dump SSA related information to a file. The file name is made by appending
5377 @file{.ssa} to the source file name.
5380 @opindex fdump-tree-alias
5381 Dump aliasing information for each function. The file name is made by
5382 appending @file{.alias} to the source file name.
5385 @opindex fdump-tree-ccp
5386 Dump each function after CCP@. The file name is made by appending
5387 @file{.ccp} to the source file name.
5390 @opindex fdump-tree-storeccp
5391 Dump each function after STORE-CCP@. The file name is made by appending
5392 @file{.storeccp} to the source file name.
5395 @opindex fdump-tree-pre
5396 Dump trees after partial redundancy elimination. The file name is made
5397 by appending @file{.pre} to the source file name.
5400 @opindex fdump-tree-fre
5401 Dump trees after full redundancy elimination. The file name is made
5402 by appending @file{.fre} to the source file name.
5405 @opindex fdump-tree-copyprop
5406 Dump trees after copy propagation. The file name is made
5407 by appending @file{.copyprop} to the source file name.
5409 @item store_copyprop
5410 @opindex fdump-tree-store_copyprop
5411 Dump trees after store copy-propagation. The file name is made
5412 by appending @file{.store_copyprop} to the source file name.
5415 @opindex fdump-tree-dce
5416 Dump each function after dead code elimination. The file name is made by
5417 appending @file{.dce} to the source file name.
5420 @opindex fdump-tree-mudflap
5421 Dump each function after adding mudflap instrumentation. The file name is
5422 made by appending @file{.mudflap} to the source file name.
5425 @opindex fdump-tree-sra
5426 Dump each function after performing scalar replacement of aggregates. The
5427 file name is made by appending @file{.sra} to the source file name.
5430 @opindex fdump-tree-sink
5431 Dump each function after performing code sinking. The file name is made
5432 by appending @file{.sink} to the source file name.
5435 @opindex fdump-tree-dom
5436 Dump each function after applying dominator tree optimizations. The file
5437 name is made by appending @file{.dom} to the source file name.
5440 @opindex fdump-tree-dse
5441 Dump each function after applying dead store elimination. The file
5442 name is made by appending @file{.dse} to the source file name.
5445 @opindex fdump-tree-phiopt
5446 Dump each function after optimizing PHI nodes into straightline code. The file
5447 name is made by appending @file{.phiopt} to the source file name.
5450 @opindex fdump-tree-forwprop
5451 Dump each function after forward propagating single use variables. The file
5452 name is made by appending @file{.forwprop} to the source file name.
5455 @opindex fdump-tree-copyrename
5456 Dump each function after applying the copy rename optimization. The file
5457 name is made by appending @file{.copyrename} to the source file name.
5460 @opindex fdump-tree-nrv
5461 Dump each function after applying the named return value optimization on
5462 generic trees. The file name is made by appending @file{.nrv} to the source
5466 @opindex fdump-tree-vect
5467 Dump each function after applying vectorization of loops. The file name is
5468 made by appending @file{.vect} to the source file name.
5471 @opindex fdump-tree-slp
5472 Dump each function after applying vectorization of basic blocks. The file name
5473 is made by appending @file{.slp} to the source file name.
5476 @opindex fdump-tree-vrp
5477 Dump each function after Value Range Propagation (VRP). The file name
5478 is made by appending @file{.vrp} to the source file name.
5481 @opindex fdump-tree-all
5482 Enable all the available tree dumps with the flags provided in this option.
5485 @item -ftree-vectorizer-verbose=@var{n}
5486 @opindex ftree-vectorizer-verbose
5487 This option controls the amount of debugging output the vectorizer prints.
5488 This information is written to standard error, unless
5489 @option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
5490 in which case it is output to the usual dump listing file, @file{.vect}.
5491 For @var{n}=0 no diagnostic information is reported.
5492 If @var{n}=1 the vectorizer reports each loop that got vectorized,
5493 and the total number of loops that got vectorized.
5494 If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
5495 the first analysis phase (vect_analyze_loop_form) - i.e.@: countable,
5496 inner-most, single-bb, single-entry/exit loops. This is the same verbosity
5497 level that @option{-fdump-tree-vect-stats} uses.
5498 Higher verbosity levels mean either more information dumped for each
5499 reported loop, or same amount of information reported for more loops:
5500 if @var{n}=3, vectorizer cost model information is reported.
5501 If @var{n}=4, alignment related information is added to the reports.
5502 If @var{n}=5, data-references related information (e.g.@: memory dependences,
5503 memory access-patterns) is added to the reports.
5504 If @var{n}=6, the vectorizer reports also non-vectorized inner-most loops
5505 that did not pass the first analysis phase (i.e., may not be countable, or
5506 may have complicated control-flow).
5507 If @var{n}=7, the vectorizer reports also non-vectorized nested loops.
5508 If @var{n}=8, SLP related information is added to the reports.
5509 For @var{n}=9, all the information the vectorizer generates during its
5510 analysis and transformation is reported. This is the same verbosity level
5511 that @option{-fdump-tree-vect-details} uses.
5513 @item -frandom-seed=@var{string}
5514 @opindex frandom-seed
5515 This option provides a seed that GCC uses when it would otherwise use
5516 random numbers. It is used to generate certain symbol names
5517 that have to be different in every compiled file. It is also used to
5518 place unique stamps in coverage data files and the object files that
5519 produce them. You can use the @option{-frandom-seed} option to produce
5520 reproducibly identical object files.
5522 The @var{string} should be different for every file you compile.
5524 @item -fsched-verbose=@var{n}
5525 @opindex fsched-verbose
5526 On targets that use instruction scheduling, this option controls the
5527 amount of debugging output the scheduler prints. This information is
5528 written to standard error, unless @option{-fdump-rtl-sched1} or
5529 @option{-fdump-rtl-sched2} is specified, in which case it is output
5530 to the usual dump listing file, @file{.sched1} or @file{.sched2}
5531 respectively. However for @var{n} greater than nine, the output is
5532 always printed to standard error.
5534 For @var{n} greater than zero, @option{-fsched-verbose} outputs the
5535 same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}.
5536 For @var{n} greater than one, it also output basic block probabilities,
5537 detailed ready list information and unit/insn info. For @var{n} greater
5538 than two, it includes RTL at abort point, control-flow and regions info.
5539 And for @var{n} over four, @option{-fsched-verbose} also includes
5543 @itemx -save-temps=cwd
5545 Store the usual ``temporary'' intermediate files permanently; place them
5546 in the current directory and name them based on the source file. Thus,
5547 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
5548 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
5549 preprocessed @file{foo.i} output file even though the compiler now
5550 normally uses an integrated preprocessor.
5552 When used in combination with the @option{-x} command line option,
5553 @option{-save-temps} is sensible enough to avoid over writing an
5554 input source file with the same extension as an intermediate file.
5555 The corresponding intermediate file may be obtained by renaming the
5556 source file before using @option{-save-temps}.
5558 If you invoke GCC in parallel, compiling several different source
5559 files that share a common base name in different subdirectories or the
5560 same source file compiled for multiple output destinations, it is
5561 likely that the different parallel compilers will interfere with each
5562 other, and overwrite the temporary files. For instance:
5565 gcc -save-temps -o outdir1/foo.o indir1/foo.c&
5566 gcc -save-temps -o outdir2/foo.o indir2/foo.c&
5569 may result in @file{foo.i} and @file{foo.o} being written to
5570 simultaneously by both compilers.
5572 @item -save-temps=obj
5573 @opindex save-temps=obj
5574 Store the usual ``temporary'' intermediate files permanently. If the
5575 @option{-o} option is used, the temporary files are based on the
5576 object file. If the @option{-o} option is not used, the
5577 @option{-save-temps=obj} switch behaves like @option{-save-temps}.
5582 gcc -save-temps=obj -c foo.c
5583 gcc -save-temps=obj -c bar.c -o dir/xbar.o
5584 gcc -save-temps=obj foobar.c -o dir2/yfoobar
5587 would create @file{foo.i}, @file{foo.s}, @file{dir/xbar.i},
5588 @file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and
5589 @file{dir2/yfoobar.o}.
5591 @item -time@r{[}=@var{file}@r{]}
5593 Report the CPU time taken by each subprocess in the compilation
5594 sequence. For C source files, this is the compiler proper and assembler
5595 (plus the linker if linking is done).
5597 Without the specification of an output file, the output looks like this:
5604 The first number on each line is the ``user time'', that is time spent
5605 executing the program itself. The second number is ``system time'',
5606 time spent executing operating system routines on behalf of the program.
5607 Both numbers are in seconds.
5609 With the specification of an output file, the output is appended to the
5610 named file, and it looks like this:
5613 0.12 0.01 cc1 @var{options}
5614 0.00 0.01 as @var{options}
5617 The ``user time'' and the ``system time'' are moved before the program
5618 name, and the options passed to the program are displayed, so that one
5619 can later tell what file was being compiled, and with which options.
5621 @item -fvar-tracking
5622 @opindex fvar-tracking
5623 Run variable tracking pass. It computes where variables are stored at each
5624 position in code. Better debugging information is then generated
5625 (if the debugging information format supports this information).
5627 It is enabled by default when compiling with optimization (@option{-Os},
5628 @option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and
5629 the debug info format supports it.
5631 @item -fvar-tracking-assignments
5632 @opindex fvar-tracking-assignments
5633 @opindex fno-var-tracking-assignments
5634 Annotate assignments to user variables early in the compilation and
5635 attempt to carry the annotations over throughout the compilation all the
5636 way to the end, in an attempt to improve debug information while
5637 optimizing. Use of @option{-gdwarf-4} is recommended along with it.
5639 It can be enabled even if var-tracking is disabled, in which case
5640 annotations will be created and maintained, but discarded at the end.
5642 @item -fvar-tracking-assignments-toggle
5643 @opindex fvar-tracking-assignments-toggle
5644 @opindex fno-var-tracking-assignments-toggle
5645 Toggle @option{-fvar-tracking-assignments}, in the same way that
5646 @option{-gtoggle} toggles @option{-g}.
5648 @item -print-file-name=@var{library}
5649 @opindex print-file-name
5650 Print the full absolute name of the library file @var{library} that
5651 would be used when linking---and don't do anything else. With this
5652 option, GCC does not compile or link anything; it just prints the
5655 @item -print-multi-directory
5656 @opindex print-multi-directory
5657 Print the directory name corresponding to the multilib selected by any
5658 other switches present in the command line. This directory is supposed
5659 to exist in @env{GCC_EXEC_PREFIX}.
5661 @item -print-multi-lib
5662 @opindex print-multi-lib
5663 Print the mapping from multilib directory names to compiler switches
5664 that enable them. The directory name is separated from the switches by
5665 @samp{;}, and each switch starts with an @samp{@@} instead of the
5666 @samp{-}, without spaces between multiple switches. This is supposed to
5667 ease shell-processing.
5669 @item -print-multi-os-directory
5670 @opindex print-multi-os-directory
5671 Print the path to OS libraries for the selected
5672 multilib, relative to some @file{lib} subdirectory. If OS libraries are
5673 present in the @file{lib} subdirectory and no multilibs are used, this is
5674 usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}}
5675 sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or
5676 @file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}}
5677 subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}.
5679 @item -print-prog-name=@var{program}
5680 @opindex print-prog-name
5681 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
5683 @item -print-libgcc-file-name
5684 @opindex print-libgcc-file-name
5685 Same as @option{-print-file-name=libgcc.a}.
5687 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
5688 but you do want to link with @file{libgcc.a}. You can do
5691 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
5694 @item -print-search-dirs
5695 @opindex print-search-dirs
5696 Print the name of the configured installation directory and a list of
5697 program and library directories @command{gcc} will search---and don't do anything else.
5699 This is useful when @command{gcc} prints the error message
5700 @samp{installation problem, cannot exec cpp0: No such file or directory}.
5701 To resolve this you either need to put @file{cpp0} and the other compiler
5702 components where @command{gcc} expects to find them, or you can set the environment
5703 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
5704 Don't forget the trailing @samp{/}.
5705 @xref{Environment Variables}.
5707 @item -print-sysroot
5708 @opindex print-sysroot
5709 Print the target sysroot directory that will be used during
5710 compilation. This is the target sysroot specified either at configure
5711 time or using the @option{--sysroot} option, possibly with an extra
5712 suffix that depends on compilation options. If no target sysroot is
5713 specified, the option prints nothing.
5715 @item -print-sysroot-headers-suffix
5716 @opindex print-sysroot-headers-suffix
5717 Print the suffix added to the target sysroot when searching for
5718 headers, or give an error if the compiler is not configured with such
5719 a suffix---and don't do anything else.
5722 @opindex dumpmachine
5723 Print the compiler's target machine (for example,
5724 @samp{i686-pc-linux-gnu})---and don't do anything else.
5727 @opindex dumpversion
5728 Print the compiler version (for example, @samp{3.0})---and don't do
5733 Print the compiler's built-in specs---and don't do anything else. (This
5734 is used when GCC itself is being built.) @xref{Spec Files}.
5736 @item -feliminate-unused-debug-types
5737 @opindex feliminate-unused-debug-types
5738 Normally, when producing DWARF2 output, GCC will emit debugging
5739 information for all types declared in a compilation
5740 unit, regardless of whether or not they are actually used
5741 in that compilation unit. Sometimes this is useful, such as
5742 if, in the debugger, you want to cast a value to a type that is
5743 not actually used in your program (but is declared). More often,
5744 however, this results in a significant amount of wasted space.
5745 With this option, GCC will avoid producing debug symbol output
5746 for types that are nowhere used in the source file being compiled.
5749 @node Optimize Options
5750 @section Options That Control Optimization
5751 @cindex optimize options
5752 @cindex options, optimization
5754 These options control various sorts of optimizations.
5756 Without any optimization option, the compiler's goal is to reduce the
5757 cost of compilation and to make debugging produce the expected
5758 results. Statements are independent: if you stop the program with a
5759 breakpoint between statements, you can then assign a new value to any
5760 variable or change the program counter to any other statement in the
5761 function and get exactly the results you would expect from the source
5764 Turning on optimization flags makes the compiler attempt to improve
5765 the performance and/or code size at the expense of compilation time
5766 and possibly the ability to debug the program.
5768 The compiler performs optimization based on the knowledge it has of the
5769 program. Compiling multiple files at once to a single output file mode allows
5770 the compiler to use information gained from all of the files when compiling
5773 Not all optimizations are controlled directly by a flag. Only
5774 optimizations that have a flag are listed in this section.
5776 Most optimizations are only enabled if an @option{-O} level is set on
5777 the command line. Otherwise they are disabled, even if individual
5778 optimization flags are specified.
5780 Depending on the target and how GCC was configured, a slightly different
5781 set of optimizations may be enabled at each @option{-O} level than
5782 those listed here. You can invoke GCC with @samp{-Q --help=optimizers}
5783 to find out the exact set of optimizations that are enabled at each level.
5784 @xref{Overall Options}, for examples.
5791 Optimize. Optimizing compilation takes somewhat more time, and a lot
5792 more memory for a large function.
5794 With @option{-O}, the compiler tries to reduce code size and execution
5795 time, without performing any optimizations that take a great deal of
5798 @option{-O} turns on the following optimization flags:
5801 -fcprop-registers @gol
5804 -fdelayed-branch @gol
5806 -fguess-branch-probability @gol
5807 -fif-conversion2 @gol
5808 -fif-conversion @gol
5809 -fipa-pure-const @gol
5811 -fipa-reference @gol
5813 -fsplit-wide-types @gol
5814 -ftree-builtin-call-dce @gol
5817 -ftree-copyrename @gol
5819 -ftree-dominator-opts @gol
5821 -ftree-forwprop @gol
5829 @option{-O} also turns on @option{-fomit-frame-pointer} on machines
5830 where doing so does not interfere with debugging.
5834 Optimize even more. GCC performs nearly all supported optimizations
5835 that do not involve a space-speed tradeoff.
5836 As compared to @option{-O}, this option increases both compilation time
5837 and the performance of the generated code.
5839 @option{-O2} turns on all optimization flags specified by @option{-O}. It
5840 also turns on the following optimization flags:
5841 @gccoptlist{-fthread-jumps @gol
5842 -falign-functions -falign-jumps @gol
5843 -falign-loops -falign-labels @gol
5846 -fcse-follow-jumps -fcse-skip-blocks @gol
5847 -fdelete-null-pointer-checks @gol
5848 -fexpensive-optimizations @gol
5849 -fgcse -fgcse-lm @gol
5850 -finline-small-functions @gol
5851 -findirect-inlining @gol
5853 -foptimize-sibling-calls @gol
5856 -freorder-blocks -freorder-functions @gol
5857 -frerun-cse-after-loop @gol
5858 -fsched-interblock -fsched-spec @gol
5859 -fschedule-insns -fschedule-insns2 @gol
5860 -fstrict-aliasing -fstrict-overflow @gol
5861 -ftree-switch-conversion @gol
5865 Please note the warning under @option{-fgcse} about
5866 invoking @option{-O2} on programs that use computed gotos.
5870 Optimize yet more. @option{-O3} turns on all optimizations specified
5871 by @option{-O2} and also turns on the @option{-finline-functions},
5872 @option{-funswitch-loops}, @option{-fpredictive-commoning},
5873 @option{-fgcse-after-reload} and @option{-ftree-vectorize} options.
5877 Reduce compilation time and make debugging produce the expected
5878 results. This is the default.
5882 Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
5883 do not typically increase code size. It also performs further
5884 optimizations designed to reduce code size.
5886 @option{-Os} disables the following optimization flags:
5887 @gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
5888 -falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
5889 -fprefetch-loop-arrays -ftree-vect-loop-version}
5891 If you use multiple @option{-O} options, with or without level numbers,
5892 the last such option is the one that is effective.
5895 Options of the form @option{-f@var{flag}} specify machine-independent
5896 flags. Most flags have both positive and negative forms; the negative
5897 form of @option{-ffoo} would be @option{-fno-foo}. In the table
5898 below, only one of the forms is listed---the one you typically will
5899 use. You can figure out the other form by either removing @samp{no-}
5902 The following options control specific optimizations. They are either
5903 activated by @option{-O} options or are related to ones that are. You
5904 can use the following flags in the rare cases when ``fine-tuning'' of
5905 optimizations to be performed is desired.
5908 @item -fno-default-inline
5909 @opindex fno-default-inline
5910 Do not make member functions inline by default merely because they are
5911 defined inside the class scope (C++ only). Otherwise, when you specify
5912 @w{@option{-O}}, member functions defined inside class scope are compiled
5913 inline by default; i.e., you don't need to add @samp{inline} in front of
5914 the member function name.
5916 @item -fno-defer-pop
5917 @opindex fno-defer-pop
5918 Always pop the arguments to each function call as soon as that function
5919 returns. For machines which must pop arguments after a function call,
5920 the compiler normally lets arguments accumulate on the stack for several
5921 function calls and pops them all at once.
5923 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5925 @item -fforward-propagate
5926 @opindex fforward-propagate
5927 Perform a forward propagation pass on RTL@. The pass tries to combine two
5928 instructions and checks if the result can be simplified. If loop unrolling
5929 is active, two passes are performed and the second is scheduled after
5932 This option is enabled by default at optimization levels @option{-O},
5933 @option{-O2}, @option{-O3}, @option{-Os}.
5935 @item -fomit-frame-pointer
5936 @opindex fomit-frame-pointer
5937 Don't keep the frame pointer in a register for functions that
5938 don't need one. This avoids the instructions to save, set up and
5939 restore frame pointers; it also makes an extra register available
5940 in many functions. @strong{It also makes debugging impossible on
5943 On some machines, such as the VAX, this flag has no effect, because
5944 the standard calling sequence automatically handles the frame pointer
5945 and nothing is saved by pretending it doesn't exist. The
5946 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
5947 whether a target machine supports this flag. @xref{Registers,,Register
5948 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
5950 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5952 @item -foptimize-sibling-calls
5953 @opindex foptimize-sibling-calls
5954 Optimize sibling and tail recursive calls.
5956 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5960 Don't pay attention to the @code{inline} keyword. Normally this option
5961 is used to keep the compiler from expanding any functions inline.
5962 Note that if you are not optimizing, no functions can be expanded inline.
5964 @item -finline-small-functions
5965 @opindex finline-small-functions
5966 Integrate functions into their callers when their body is smaller than expected
5967 function call code (so overall size of program gets smaller). The compiler
5968 heuristically decides which functions are simple enough to be worth integrating
5971 Enabled at level @option{-O2}.
5973 @item -findirect-inlining
5974 @opindex findirect-inlining
5975 Inline also indirect calls that are discovered to be known at compile
5976 time thanks to previous inlining. This option has any effect only
5977 when inlining itself is turned on by the @option{-finline-functions}
5978 or @option{-finline-small-functions} options.
5980 Enabled at level @option{-O2}.
5982 @item -finline-functions
5983 @opindex finline-functions
5984 Integrate all simple functions into their callers. The compiler
5985 heuristically decides which functions are simple enough to be worth
5986 integrating in this way.
5988 If all calls to a given function are integrated, and the function is
5989 declared @code{static}, then the function is normally not output as
5990 assembler code in its own right.
5992 Enabled at level @option{-O3}.
5994 @item -finline-functions-called-once
5995 @opindex finline-functions-called-once
5996 Consider all @code{static} functions called once for inlining into their
5997 caller even if they are not marked @code{inline}. If a call to a given
5998 function is integrated, then the function is not output as assembler code
6001 Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os}.
6003 @item -fearly-inlining
6004 @opindex fearly-inlining
6005 Inline functions marked by @code{always_inline} and functions whose body seems
6006 smaller than the function call overhead early before doing
6007 @option{-fprofile-generate} instrumentation and real inlining pass. Doing so
6008 makes profiling significantly cheaper and usually inlining faster on programs
6009 having large chains of nested wrapper functions.
6015 Perform interprocedural scalar replacement of aggregates, removal of
6016 unused parameters and replacement of parameters passed by reference
6017 by parameters passed by value.
6019 Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}.
6021 @item -finline-limit=@var{n}
6022 @opindex finline-limit
6023 By default, GCC limits the size of functions that can be inlined. This flag
6024 allows coarse control of this limit. @var{n} is the size of functions that
6025 can be inlined in number of pseudo instructions.
6027 Inlining is actually controlled by a number of parameters, which may be
6028 specified individually by using @option{--param @var{name}=@var{value}}.
6029 The @option{-finline-limit=@var{n}} option sets some of these parameters
6033 @item max-inline-insns-single
6034 is set to @var{n}/2.
6035 @item max-inline-insns-auto
6036 is set to @var{n}/2.
6039 See below for a documentation of the individual
6040 parameters controlling inlining and for the defaults of these parameters.
6042 @emph{Note:} there may be no value to @option{-finline-limit} that results
6043 in default behavior.
6045 @emph{Note:} pseudo instruction represents, in this particular context, an
6046 abstract measurement of function's size. In no way does it represent a count
6047 of assembly instructions and as such its exact meaning might change from one
6048 release to an another.
6050 @item -fkeep-inline-functions
6051 @opindex fkeep-inline-functions
6052 In C, emit @code{static} functions that are declared @code{inline}
6053 into the object file, even if the function has been inlined into all
6054 of its callers. This switch does not affect functions using the
6055 @code{extern inline} extension in GNU C90@. In C++, emit any and all
6056 inline functions into the object file.
6058 @item -fkeep-static-consts
6059 @opindex fkeep-static-consts
6060 Emit variables declared @code{static const} when optimization isn't turned
6061 on, even if the variables aren't referenced.
6063 GCC enables this option by default. If you want to force the compiler to
6064 check if the variable was referenced, regardless of whether or not
6065 optimization is turned on, use the @option{-fno-keep-static-consts} option.
6067 @item -fmerge-constants
6068 @opindex fmerge-constants
6069 Attempt to merge identical constants (string constants and floating point
6070 constants) across compilation units.
6072 This option is the default for optimized compilation if the assembler and
6073 linker support it. Use @option{-fno-merge-constants} to inhibit this
6076 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6078 @item -fmerge-all-constants
6079 @opindex fmerge-all-constants
6080 Attempt to merge identical constants and identical variables.
6082 This option implies @option{-fmerge-constants}. In addition to
6083 @option{-fmerge-constants} this considers e.g.@: even constant initialized
6084 arrays or initialized constant variables with integral or floating point
6085 types. Languages like C or C++ require each variable, including multiple
6086 instances of the same variable in recursive calls, to have distinct locations,
6087 so using this option will result in non-conforming
6090 @item -fmodulo-sched
6091 @opindex fmodulo-sched
6092 Perform swing modulo scheduling immediately before the first scheduling
6093 pass. This pass looks at innermost loops and reorders their
6094 instructions by overlapping different iterations.
6096 @item -fmodulo-sched-allow-regmoves
6097 @opindex fmodulo-sched-allow-regmoves
6098 Perform more aggressive SMS based modulo scheduling with register moves
6099 allowed. By setting this flag certain anti-dependences edges will be
6100 deleted which will trigger the generation of reg-moves based on the
6101 life-range analysis. This option is effective only with
6102 @option{-fmodulo-sched} enabled.
6104 @item -fno-branch-count-reg
6105 @opindex fno-branch-count-reg
6106 Do not use ``decrement and branch'' instructions on a count register,
6107 but instead generate a sequence of instructions that decrement a
6108 register, compare it against zero, then branch based upon the result.
6109 This option is only meaningful on architectures that support such
6110 instructions, which include x86, PowerPC, IA-64 and S/390.
6112 The default is @option{-fbranch-count-reg}.
6114 @item -fno-function-cse
6115 @opindex fno-function-cse
6116 Do not put function addresses in registers; make each instruction that
6117 calls a constant function contain the function's address explicitly.
6119 This option results in less efficient code, but some strange hacks
6120 that alter the assembler output may be confused by the optimizations
6121 performed when this option is not used.
6123 The default is @option{-ffunction-cse}
6125 @item -fno-zero-initialized-in-bss
6126 @opindex fno-zero-initialized-in-bss
6127 If the target supports a BSS section, GCC by default puts variables that
6128 are initialized to zero into BSS@. This can save space in the resulting
6131 This option turns off this behavior because some programs explicitly
6132 rely on variables going to the data section. E.g., so that the
6133 resulting executable can find the beginning of that section and/or make
6134 assumptions based on that.
6136 The default is @option{-fzero-initialized-in-bss}.
6138 @item -fmudflap -fmudflapth -fmudflapir
6142 @cindex bounds checking
6144 For front-ends that support it (C and C++), instrument all risky
6145 pointer/array dereferencing operations, some standard library
6146 string/heap functions, and some other associated constructs with
6147 range/validity tests. Modules so instrumented should be immune to
6148 buffer overflows, invalid heap use, and some other classes of C/C++
6149 programming errors. The instrumentation relies on a separate runtime
6150 library (@file{libmudflap}), which will be linked into a program if
6151 @option{-fmudflap} is given at link time. Run-time behavior of the
6152 instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
6153 environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
6156 Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
6157 link if your program is multi-threaded. Use @option{-fmudflapir}, in
6158 addition to @option{-fmudflap} or @option{-fmudflapth}, if
6159 instrumentation should ignore pointer reads. This produces less
6160 instrumentation (and therefore faster execution) and still provides
6161 some protection against outright memory corrupting writes, but allows
6162 erroneously read data to propagate within a program.
6164 @item -fthread-jumps
6165 @opindex fthread-jumps
6166 Perform optimizations where we check to see if a jump branches to a
6167 location where another comparison subsumed by the first is found. If
6168 so, the first branch is redirected to either the destination of the
6169 second branch or a point immediately following it, depending on whether
6170 the condition is known to be true or false.
6172 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6174 @item -fsplit-wide-types
6175 @opindex fsplit-wide-types
6176 When using a type that occupies multiple registers, such as @code{long
6177 long} on a 32-bit system, split the registers apart and allocate them
6178 independently. This normally generates better code for those types,
6179 but may make debugging more difficult.
6181 Enabled at levels @option{-O}, @option{-O2}, @option{-O3},
6184 @item -fcse-follow-jumps
6185 @opindex fcse-follow-jumps
6186 In common subexpression elimination (CSE), scan through jump instructions
6187 when the target of the jump is not reached by any other path. For
6188 example, when CSE encounters an @code{if} statement with an
6189 @code{else} clause, CSE will follow the jump when the condition
6192 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6194 @item -fcse-skip-blocks
6195 @opindex fcse-skip-blocks
6196 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
6197 follow jumps which conditionally skip over blocks. When CSE
6198 encounters a simple @code{if} statement with no else clause,
6199 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
6200 body of the @code{if}.
6202 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6204 @item -frerun-cse-after-loop
6205 @opindex frerun-cse-after-loop
6206 Re-run common subexpression elimination after loop optimizations has been
6209 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6213 Perform a global common subexpression elimination pass.
6214 This pass also performs global constant and copy propagation.
6216 @emph{Note:} When compiling a program using computed gotos, a GCC
6217 extension, you may get better runtime performance if you disable
6218 the global common subexpression elimination pass by adding
6219 @option{-fno-gcse} to the command line.
6221 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6225 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
6226 attempt to move loads which are only killed by stores into themselves. This
6227 allows a loop containing a load/store sequence to be changed to a load outside
6228 the loop, and a copy/store within the loop.
6230 Enabled by default when gcse is enabled.
6234 When @option{-fgcse-sm} is enabled, a store motion pass is run after
6235 global common subexpression elimination. This pass will attempt to move
6236 stores out of loops. When used in conjunction with @option{-fgcse-lm},
6237 loops containing a load/store sequence can be changed to a load before
6238 the loop and a store after the loop.
6240 Not enabled at any optimization level.
6244 When @option{-fgcse-las} is enabled, the global common subexpression
6245 elimination pass eliminates redundant loads that come after stores to the
6246 same memory location (both partial and full redundancies).
6248 Not enabled at any optimization level.
6250 @item -fgcse-after-reload
6251 @opindex fgcse-after-reload
6252 When @option{-fgcse-after-reload} is enabled, a redundant load elimination
6253 pass is performed after reload. The purpose of this pass is to cleanup
6256 @item -funsafe-loop-optimizations
6257 @opindex funsafe-loop-optimizations
6258 If given, the loop optimizer will assume that loop indices do not
6259 overflow, and that the loops with nontrivial exit condition are not
6260 infinite. This enables a wider range of loop optimizations even if
6261 the loop optimizer itself cannot prove that these assumptions are valid.
6262 Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
6263 if it finds this kind of loop.
6265 @item -fcrossjumping
6266 @opindex fcrossjumping
6267 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
6268 resulting code may or may not perform better than without cross-jumping.
6270 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6272 @item -fauto-inc-dec
6273 @opindex fauto-inc-dec
6274 Combine increments or decrements of addresses with memory accesses.
6275 This pass is always skipped on architectures that do not have
6276 instructions to support this. Enabled by default at @option{-O} and
6277 higher on architectures that support this.
6281 Perform dead code elimination (DCE) on RTL@.
6282 Enabled by default at @option{-O} and higher.
6286 Perform dead store elimination (DSE) on RTL@.
6287 Enabled by default at @option{-O} and higher.
6289 @item -fif-conversion
6290 @opindex fif-conversion
6291 Attempt to transform conditional jumps into branch-less equivalents. This
6292 include use of conditional moves, min, max, set flags and abs instructions, and
6293 some tricks doable by standard arithmetics. The use of conditional execution
6294 on chips where it is available is controlled by @code{if-conversion2}.
6296 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6298 @item -fif-conversion2
6299 @opindex fif-conversion2
6300 Use conditional execution (where available) to transform conditional jumps into
6301 branch-less equivalents.
6303 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6305 @item -fdelete-null-pointer-checks
6306 @opindex fdelete-null-pointer-checks
6307 Assume that programs cannot safely dereference null pointers, and that
6308 no code or data element resides there. This enables simple constant
6309 folding optimizations at all optimization levels. In addition, other
6310 optimization passes in GCC use this flag to control global dataflow
6311 analyses that eliminate useless checks for null pointers; these assume
6312 that if a pointer is checked after it has already been dereferenced,
6315 Note however that in some environments this assumption is not true.
6316 Use @option{-fno-delete-null-pointer-checks} to disable this optimization
6317 for programs which depend on that behavior.
6319 Some targets, especially embedded ones, disable this option at all levels.
6320 Otherwise it is enabled at all levels: @option{-O0}, @option{-O1},
6321 @option{-O2}, @option{-O3}, @option{-Os}. Passes that use the information
6322 are enabled independently at different optimization levels.
6324 @item -fexpensive-optimizations
6325 @opindex fexpensive-optimizations
6326 Perform a number of minor optimizations that are relatively expensive.
6328 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6330 @item -foptimize-register-move
6332 @opindex foptimize-register-move
6334 Attempt to reassign register numbers in move instructions and as
6335 operands of other simple instructions in order to maximize the amount of
6336 register tying. This is especially helpful on machines with two-operand
6339 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
6342 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6344 @item -fira-algorithm=@var{algorithm}
6345 Use specified coloring algorithm for the integrated register
6346 allocator. The @var{algorithm} argument should be @code{priority} or
6347 @code{CB}. The first algorithm specifies Chow's priority coloring,
6348 the second one specifies Chaitin-Briggs coloring. The second
6349 algorithm can be unimplemented for some architectures. If it is
6350 implemented, it is the default because Chaitin-Briggs coloring as a
6351 rule generates a better code.
6353 @item -fira-region=@var{region}
6354 Use specified regions for the integrated register allocator. The
6355 @var{region} argument should be one of @code{all}, @code{mixed}, or
6356 @code{one}. The first value means using all loops as register
6357 allocation regions, the second value which is the default means using
6358 all loops except for loops with small register pressure as the
6359 regions, and third one means using all function as a single region.
6360 The first value can give best result for machines with small size and
6361 irregular register set, the third one results in faster and generates
6362 decent code and the smallest size code, and the default value usually
6363 give the best results in most cases and for most architectures.
6365 @item -fira-coalesce
6366 @opindex fira-coalesce
6367 Do optimistic register coalescing. This option might be profitable for
6368 architectures with big regular register files.
6370 @item -fira-loop-pressure
6371 @opindex fira-loop-pressure
6372 Use IRA to evaluate register pressure in loops for decision to move
6373 loop invariants. Usage of this option usually results in generation
6374 of faster and smaller code on machines with big register files (>= 32
6375 registers) but it can slow compiler down.
6377 This option is enabled at level @option{-O3} for some targets.
6379 @item -fno-ira-share-save-slots
6380 @opindex fno-ira-share-save-slots
6381 Switch off sharing stack slots used for saving call used hard
6382 registers living through a call. Each hard register will get a
6383 separate stack slot and as a result function stack frame will be
6386 @item -fno-ira-share-spill-slots
6387 @opindex fno-ira-share-spill-slots
6388 Switch off sharing stack slots allocated for pseudo-registers. Each
6389 pseudo-register which did not get a hard register will get a separate
6390 stack slot and as a result function stack frame will be bigger.
6392 @item -fira-verbose=@var{n}
6393 @opindex fira-verbose
6394 Set up how verbose dump file for the integrated register allocator
6395 will be. Default value is 5. If the value is greater or equal to 10,
6396 the dump file will be stderr as if the value were @var{n} minus 10.
6398 @item -fdelayed-branch
6399 @opindex fdelayed-branch
6400 If supported for the target machine, attempt to reorder instructions
6401 to exploit instruction slots available after delayed branch
6404 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6406 @item -fschedule-insns
6407 @opindex fschedule-insns
6408 If supported for the target machine, attempt to reorder instructions to
6409 eliminate execution stalls due to required data being unavailable. This
6410 helps machines that have slow floating point or memory load instructions
6411 by allowing other instructions to be issued until the result of the load
6412 or floating point instruction is required.
6414 Enabled at levels @option{-O2}, @option{-O3}.
6416 @item -fschedule-insns2
6417 @opindex fschedule-insns2
6418 Similar to @option{-fschedule-insns}, but requests an additional pass of
6419 instruction scheduling after register allocation has been done. This is
6420 especially useful on machines with a relatively small number of
6421 registers and where memory load instructions take more than one cycle.
6423 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6425 @item -fno-sched-interblock
6426 @opindex fno-sched-interblock
6427 Don't schedule instructions across basic blocks. This is normally
6428 enabled by default when scheduling before register allocation, i.e.@:
6429 with @option{-fschedule-insns} or at @option{-O2} or higher.
6431 @item -fno-sched-spec
6432 @opindex fno-sched-spec
6433 Don't allow speculative motion of non-load instructions. This is normally
6434 enabled by default when scheduling before register allocation, i.e.@:
6435 with @option{-fschedule-insns} or at @option{-O2} or higher.
6437 @item -fsched-pressure
6438 @opindex fsched-pressure
6439 Enable register pressure sensitive insn scheduling before the register
6440 allocation. This only makes sense when scheduling before register
6441 allocation is enabled, i.e.@: with @option{-fschedule-insns} or at
6442 @option{-O2} or higher. Usage of this option can improve the
6443 generated code and decrease its size by preventing register pressure
6444 increase above the number of available hard registers and as a
6445 consequence register spills in the register allocation.
6447 @item -fsched-spec-load
6448 @opindex fsched-spec-load
6449 Allow speculative motion of some load instructions. This only makes
6450 sense when scheduling before register allocation, i.e.@: with
6451 @option{-fschedule-insns} or at @option{-O2} or higher.
6453 @item -fsched-spec-load-dangerous
6454 @opindex fsched-spec-load-dangerous
6455 Allow speculative motion of more load instructions. This only makes
6456 sense when scheduling before register allocation, i.e.@: with
6457 @option{-fschedule-insns} or at @option{-O2} or higher.
6459 @item -fsched-stalled-insns
6460 @itemx -fsched-stalled-insns=@var{n}
6461 @opindex fsched-stalled-insns
6462 Define how many insns (if any) can be moved prematurely from the queue
6463 of stalled insns into the ready list, during the second scheduling pass.
6464 @option{-fno-sched-stalled-insns} means that no insns will be moved
6465 prematurely, @option{-fsched-stalled-insns=0} means there is no limit
6466 on how many queued insns can be moved prematurely.
6467 @option{-fsched-stalled-insns} without a value is equivalent to
6468 @option{-fsched-stalled-insns=1}.
6470 @item -fsched-stalled-insns-dep
6471 @itemx -fsched-stalled-insns-dep=@var{n}
6472 @opindex fsched-stalled-insns-dep
6473 Define how many insn groups (cycles) will be examined for a dependency
6474 on a stalled insn that is candidate for premature removal from the queue
6475 of stalled insns. This has an effect only during the second scheduling pass,
6476 and only if @option{-fsched-stalled-insns} is used.
6477 @option{-fno-sched-stalled-insns-dep} is equivalent to
6478 @option{-fsched-stalled-insns-dep=0}.
6479 @option{-fsched-stalled-insns-dep} without a value is equivalent to
6480 @option{-fsched-stalled-insns-dep=1}.
6482 @item -fsched2-use-superblocks
6483 @opindex fsched2-use-superblocks
6484 When scheduling after register allocation, do use superblock scheduling
6485 algorithm. Superblock scheduling allows motion across basic block boundaries
6486 resulting on faster schedules. This option is experimental, as not all machine
6487 descriptions used by GCC model the CPU closely enough to avoid unreliable
6488 results from the algorithm.
6490 This only makes sense when scheduling after register allocation, i.e.@: with
6491 @option{-fschedule-insns2} or at @option{-O2} or higher.
6493 @item -fsched-group-heuristic
6494 @opindex fsched-group-heuristic
6495 Enable the group heuristic in the scheduler. This heuristic favors
6496 the instruction that belongs to a schedule group. This is enabled
6497 by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns}
6498 or @option{-fschedule-insns2} or at @option{-O2} or higher.
6500 @item -fsched-critical-path-heuristic
6501 @opindex fsched-critical-path-heuristic
6502 Enable the critical-path heuristic in the scheduler. This heuristic favors
6503 instructions on the critical path. This is enabled by default when
6504 scheduling is enabled, i.e.@: with @option{-fschedule-insns}
6505 or @option{-fschedule-insns2} or at @option{-O2} or higher.
6507 @item -fsched-spec-insn-heuristic
6508 @opindex fsched-spec-insn-heuristic
6509 Enable the speculative instruction heuristic in the scheduler. This
6510 heuristic favors speculative instructions with greater dependency weakness.
6511 This is enabled by default when scheduling is enabled, i.e.@:
6512 with @option{-fschedule-insns} or @option{-fschedule-insns2}
6513 or at @option{-O2} or higher.
6515 @item -fsched-rank-heuristic
6516 @opindex fsched-rank-heuristic
6517 Enable the rank heuristic in the scheduler. This heuristic favors
6518 the instruction belonging to a basic block with greater size or frequency.
6519 This is enabled by default when scheduling is enabled, i.e.@:
6520 with @option{-fschedule-insns} or @option{-fschedule-insns2} or
6521 at @option{-O2} or higher.
6523 @item -fsched-last-insn-heuristic
6524 @opindex fsched-last-insn-heuristic
6525 Enable the last-instruction heuristic in the scheduler. This heuristic
6526 favors the instruction that is less dependent on the last instruction
6527 scheduled. This is enabled by default when scheduling is enabled,
6528 i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or
6529 at @option{-O2} or higher.
6531 @item -fsched-dep-count-heuristic
6532 @opindex fsched-dep-count-heuristic
6533 Enable the dependent-count heuristic in the scheduler. This heuristic
6534 favors the instruction that has more instructions depending on it.
6535 This is enabled by default when scheduling is enabled, i.e.@:
6536 with @option{-fschedule-insns} or @option{-fschedule-insns2} or
6537 at @option{-O2} or higher.
6539 @item -freschedule-modulo-scheduled-loops
6540 @opindex freschedule-modulo-scheduled-loops
6541 The modulo scheduling comes before the traditional scheduling, if a loop
6542 was modulo scheduled we may want to prevent the later scheduling passes
6543 from changing its schedule, we use this option to control that.
6545 @item -fselective-scheduling
6546 @opindex fselective-scheduling
6547 Schedule instructions using selective scheduling algorithm. Selective
6548 scheduling runs instead of the first scheduler pass.
6550 @item -fselective-scheduling2
6551 @opindex fselective-scheduling2
6552 Schedule instructions using selective scheduling algorithm. Selective
6553 scheduling runs instead of the second scheduler pass.
6555 @item -fsel-sched-pipelining
6556 @opindex fsel-sched-pipelining
6557 Enable software pipelining of innermost loops during selective scheduling.
6558 This option has no effect until one of @option{-fselective-scheduling} or
6559 @option{-fselective-scheduling2} is turned on.
6561 @item -fsel-sched-pipelining-outer-loops
6562 @opindex fsel-sched-pipelining-outer-loops
6563 When pipelining loops during selective scheduling, also pipeline outer loops.
6564 This option has no effect until @option{-fsel-sched-pipelining} is turned on.
6566 @item -fcaller-saves
6567 @opindex fcaller-saves
6568 Enable values to be allocated in registers that will be clobbered by
6569 function calls, by emitting extra instructions to save and restore the
6570 registers around such calls. Such allocation is done only when it
6571 seems to result in better code than would otherwise be produced.
6573 This option is always enabled by default on certain machines, usually
6574 those which have no call-preserved registers to use instead.
6576 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6578 @item -fconserve-stack
6579 @opindex fconserve-stack
6580 Attempt to minimize stack usage. The compiler will attempt to use less
6581 stack space, even if that makes the program slower. This option
6582 implies setting the @option{large-stack-frame} parameter to 100
6583 and the @option{large-stack-frame-growth} parameter to 400.
6585 @item -ftree-reassoc
6586 @opindex ftree-reassoc
6587 Perform reassociation on trees. This flag is enabled by default
6588 at @option{-O} and higher.
6592 Perform partial redundancy elimination (PRE) on trees. This flag is
6593 enabled by default at @option{-O2} and @option{-O3}.
6595 @item -ftree-forwprop
6596 @opindex ftree-forwprop
6597 Perform forward propagation on trees. This flag is enabled by default
6598 at @option{-O} and higher.
6602 Perform full redundancy elimination (FRE) on trees. The difference
6603 between FRE and PRE is that FRE only considers expressions
6604 that are computed on all paths leading to the redundant computation.
6605 This analysis is faster than PRE, though it exposes fewer redundancies.
6606 This flag is enabled by default at @option{-O} and higher.
6608 @item -ftree-phiprop
6609 @opindex ftree-phiprop
6610 Perform hoisting of loads from conditional pointers on trees. This
6611 pass is enabled by default at @option{-O} and higher.
6613 @item -ftree-copy-prop
6614 @opindex ftree-copy-prop
6615 Perform copy propagation on trees. This pass eliminates unnecessary
6616 copy operations. This flag is enabled by default at @option{-O} and
6619 @item -fipa-pure-const
6620 @opindex fipa-pure-const
6621 Discover which functions are pure or constant.
6622 Enabled by default at @option{-O} and higher.
6624 @item -fipa-reference
6625 @opindex fipa-reference
6626 Discover which static variables do not escape cannot escape the
6628 Enabled by default at @option{-O} and higher.
6630 @item -fipa-struct-reorg
6631 @opindex fipa-struct-reorg
6632 Perform structure reorganization optimization, that change C-like structures
6633 layout in order to better utilize spatial locality. This transformation is
6634 affective for programs containing arrays of structures. Available in two
6635 compilation modes: profile-based (enabled with @option{-fprofile-generate})
6636 or static (which uses built-in heuristics). It works only in whole program
6637 mode, so it requires @option{-fwhole-program} and @option{-combine} to be
6638 enabled. Structures considered @samp{cold} by this transformation are not
6639 affected (see @option{--param struct-reorg-cold-struct-ratio=@var{value}}).
6641 With this flag, the program debug info reflects a new structure layout.
6645 Perform interprocedural pointer analysis and interprocedural modification
6646 and reference analysis. This option can cause excessive memory and
6647 compile-time usage on large compilation units. It is not enabled by
6648 default at any optimization level.
6651 @opindex fipa-profile
6652 Perform interprocedural profile propagation. The functions called only from
6653 cold functions are marked as cold. Also functions executed once (such as
6654 @code{cold}, @code{noreturn}, static constructors or destructors) are identified. Cold
6655 functions and loop less parts of functions executed once are then optimized for
6657 Enabled by default at @option{-O} and higher.
6661 Perform interprocedural constant propagation.
6662 This optimization analyzes the program to determine when values passed
6663 to functions are constants and then optimizes accordingly.
6664 This optimization can substantially increase performance
6665 if the application has constants passed to functions.
6666 This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}.
6668 @item -fipa-cp-clone
6669 @opindex fipa-cp-clone
6670 Perform function cloning to make interprocedural constant propagation stronger.
6671 When enabled, interprocedural constant propagation will perform function cloning
6672 when externally visible function can be called with constant arguments.
6673 Because this optimization can create multiple copies of functions,
6674 it may significantly increase code size
6675 (see @option{--param ipcp-unit-growth=@var{value}}).
6676 This flag is enabled by default at @option{-O3}.
6678 @item -fipa-matrix-reorg
6679 @opindex fipa-matrix-reorg
6680 Perform matrix flattening and transposing.
6681 Matrix flattening tries to replace an @math{m}-dimensional matrix
6682 with its equivalent @math{n}-dimensional matrix, where @math{n < m}.
6683 This reduces the level of indirection needed for accessing the elements
6684 of the matrix. The second optimization is matrix transposing that
6685 attempts to change the order of the matrix's dimensions in order to
6686 improve cache locality.
6687 Both optimizations need the @option{-fwhole-program} flag.
6688 Transposing is enabled only if profiling information is available.
6692 Perform forward store motion on trees. This flag is
6693 enabled by default at @option{-O} and higher.
6697 Perform sparse conditional constant propagation (CCP) on trees. This
6698 pass only operates on local scalar variables and is enabled by default
6699 at @option{-O} and higher.
6701 @item -ftree-switch-conversion
6702 Perform conversion of simple initializations in a switch to
6703 initializations from a scalar array. This flag is enabled by default
6704 at @option{-O2} and higher.
6708 Perform dead code elimination (DCE) on trees. This flag is enabled by
6709 default at @option{-O} and higher.
6711 @item -ftree-builtin-call-dce
6712 @opindex ftree-builtin-call-dce
6713 Perform conditional dead code elimination (DCE) for calls to builtin functions
6714 that may set @code{errno} but are otherwise side-effect free. This flag is
6715 enabled by default at @option{-O2} and higher if @option{-Os} is not also
6718 @item -ftree-dominator-opts
6719 @opindex ftree-dominator-opts
6720 Perform a variety of simple scalar cleanups (constant/copy
6721 propagation, redundancy elimination, range propagation and expression
6722 simplification) based on a dominator tree traversal. This also
6723 performs jump threading (to reduce jumps to jumps). This flag is
6724 enabled by default at @option{-O} and higher.
6728 Perform dead store elimination (DSE) on trees. A dead store is a store into
6729 a memory location which will later be overwritten by another store without
6730 any intervening loads. In this case the earlier store can be deleted. This
6731 flag is enabled by default at @option{-O} and higher.
6735 Perform loop header copying on trees. This is beneficial since it increases
6736 effectiveness of code motion optimizations. It also saves one jump. This flag
6737 is enabled by default at @option{-O} and higher. It is not enabled
6738 for @option{-Os}, since it usually increases code size.
6740 @item -ftree-loop-optimize
6741 @opindex ftree-loop-optimize
6742 Perform loop optimizations on trees. This flag is enabled by default
6743 at @option{-O} and higher.
6745 @item -ftree-loop-linear
6746 @opindex ftree-loop-linear
6747 Perform linear loop transformations on tree. This flag can improve cache
6748 performance and allow further loop optimizations to take place.
6750 @item -floop-interchange
6751 Perform loop interchange transformations on loops. Interchanging two
6752 nested loops switches the inner and outer loops. For example, given a
6757 A(J, I) = A(J, I) * C
6761 loop interchange will transform the loop as if the user had written:
6765 A(J, I) = A(J, I) * C
6769 which can be beneficial when @code{N} is larger than the caches,
6770 because in Fortran, the elements of an array are stored in memory
6771 contiguously by column, and the original loop iterates over rows,
6772 potentially creating at each access a cache miss. This optimization
6773 applies to all the languages supported by GCC and is not limited to
6774 Fortran. To use this code transformation, GCC has to be configured
6775 with @option{--with-ppl} and @option{--with-cloog} to enable the
6776 Graphite loop transformation infrastructure.
6778 @item -floop-strip-mine
6779 Perform loop strip mining transformations on loops. Strip mining
6780 splits a loop into two nested loops. The outer loop has strides
6781 equal to the strip size and the inner loop has strides of the
6782 original loop within a strip. The strip length can be changed
6783 using the @option{loop-block-tile-size} parameter. For example,
6790 loop strip mining will transform the loop as if the user had written:
6793 DO I = II, min (II + 50, N)
6798 This optimization applies to all the languages supported by GCC and is
6799 not limited to Fortran. To use this code transformation, GCC has to
6800 be configured with @option{--with-ppl} and @option{--with-cloog} to
6801 enable the Graphite loop transformation infrastructure.
6804 Perform loop blocking transformations on loops. Blocking strip mines
6805 each loop in the loop nest such that the memory accesses of the
6806 element loops fit inside caches. The strip length can be changed
6807 using the @option{loop-block-tile-size} parameter. For example, given
6812 A(J, I) = B(I) + C(J)
6816 loop blocking will transform the loop as if the user had written:
6820 DO I = II, min (II + 50, N)
6821 DO J = JJ, min (JJ + 50, M)
6822 A(J, I) = B(I) + C(J)
6828 which can be beneficial when @code{M} is larger than the caches,
6829 because the innermost loop will iterate over a smaller amount of data
6830 that can be kept in the caches. This optimization applies to all the
6831 languages supported by GCC and is not limited to Fortran. To use this
6832 code transformation, GCC has to be configured with @option{--with-ppl}
6833 and @option{--with-cloog} to enable the Graphite loop transformation
6836 @item -fgraphite-identity
6837 @opindex fgraphite-identity
6838 Enable the identity transformation for graphite. For every SCoP we generate
6839 the polyhedral representation and transform it back to gimple. Using
6840 @option{-fgraphite-identity} we can check the costs or benefits of the
6841 GIMPLE -> GRAPHITE -> GIMPLE transformation. Some minimal optimizations
6842 are also performed by the code generator CLooG, like index splitting and
6843 dead code elimination in loops.
6845 @item -floop-parallelize-all
6846 Use the Graphite data dependence analysis to identify loops that can
6847 be parallelized. Parallelize all the loops that can be analyzed to
6848 not contain loop carried dependences without checking that it is
6849 profitable to parallelize the loops.
6851 @item -fcheck-data-deps
6852 @opindex fcheck-data-deps
6853 Compare the results of several data dependence analyzers. This option
6854 is used for debugging the data dependence analyzers.
6856 @item -ftree-loop-distribution
6857 Perform loop distribution. This flag can improve cache performance on
6858 big loop bodies and allow further loop optimizations, like
6859 parallelization or vectorization, to take place. For example, the loop
6876 @item -ftree-loop-im
6877 @opindex ftree-loop-im
6878 Perform loop invariant motion on trees. This pass moves only invariants that
6879 would be hard to handle at RTL level (function calls, operations that expand to
6880 nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
6881 operands of conditions that are invariant out of the loop, so that we can use
6882 just trivial invariantness analysis in loop unswitching. The pass also includes
6885 @item -ftree-loop-ivcanon
6886 @opindex ftree-loop-ivcanon
6887 Create a canonical counter for number of iterations in the loop for that
6888 determining number of iterations requires complicated analysis. Later
6889 optimizations then may determine the number easily. Useful especially
6890 in connection with unrolling.
6894 Perform induction variable optimizations (strength reduction, induction
6895 variable merging and induction variable elimination) on trees.
6897 @item -ftree-parallelize-loops=n
6898 @opindex ftree-parallelize-loops
6899 Parallelize loops, i.e., split their iteration space to run in n threads.
6900 This is only possible for loops whose iterations are independent
6901 and can be arbitrarily reordered. The optimization is only
6902 profitable on multiprocessor machines, for loops that are CPU-intensive,
6903 rather than constrained e.g.@: by memory bandwidth. This option
6904 implies @option{-pthread}, and thus is only supported on targets
6905 that have support for @option{-pthread}.
6909 Perform function-local points-to analysis on trees. This flag is
6910 enabled by default at @option{-O} and higher.
6914 Perform scalar replacement of aggregates. This pass replaces structure
6915 references with scalars to prevent committing structures to memory too
6916 early. This flag is enabled by default at @option{-O} and higher.
6918 @item -ftree-copyrename
6919 @opindex ftree-copyrename
6920 Perform copy renaming on trees. This pass attempts to rename compiler
6921 temporaries to other variables at copy locations, usually resulting in
6922 variable names which more closely resemble the original variables. This flag
6923 is enabled by default at @option{-O} and higher.
6927 Perform temporary expression replacement during the SSA->normal phase. Single
6928 use/single def temporaries are replaced at their use location with their
6929 defining expression. This results in non-GIMPLE code, but gives the expanders
6930 much more complex trees to work on resulting in better RTL generation. This is
6931 enabled by default at @option{-O} and higher.
6933 @item -ftree-vectorize
6934 @opindex ftree-vectorize
6935 Perform loop vectorization on trees. This flag is enabled by default at
6938 @item -ftree-slp-vectorize
6939 @opindex ftree-slp-vectorize
6940 Perform basic block vectorization on trees. This flag is enabled by default at
6941 @option{-O3} and when @option{-ftree-vectorize} is enabled.
6943 @item -ftree-vect-loop-version
6944 @opindex ftree-vect-loop-version
6945 Perform loop versioning when doing loop vectorization on trees. When a loop
6946 appears to be vectorizable except that data alignment or data dependence cannot
6947 be determined at compile time then vectorized and non-vectorized versions of
6948 the loop are generated along with runtime checks for alignment or dependence
6949 to control which version is executed. This option is enabled by default
6950 except at level @option{-Os} where it is disabled.
6952 @item -fvect-cost-model
6953 @opindex fvect-cost-model
6954 Enable cost model for vectorization.
6958 Perform Value Range Propagation on trees. This is similar to the
6959 constant propagation pass, but instead of values, ranges of values are
6960 propagated. This allows the optimizers to remove unnecessary range
6961 checks like array bound checks and null pointer checks. This is
6962 enabled by default at @option{-O2} and higher. Null pointer check
6963 elimination is only done if @option{-fdelete-null-pointer-checks} is
6968 Perform tail duplication to enlarge superblock size. This transformation
6969 simplifies the control flow of the function allowing other optimizations to do
6972 @item -funroll-loops
6973 @opindex funroll-loops
6974 Unroll loops whose number of iterations can be determined at compile
6975 time or upon entry to the loop. @option{-funroll-loops} implies
6976 @option{-frerun-cse-after-loop}. This option makes code larger,
6977 and may or may not make it run faster.
6979 @item -funroll-all-loops
6980 @opindex funroll-all-loops
6981 Unroll all loops, even if their number of iterations is uncertain when
6982 the loop is entered. This usually makes programs run more slowly.
6983 @option{-funroll-all-loops} implies the same options as
6984 @option{-funroll-loops},
6986 @item -fsplit-ivs-in-unroller
6987 @opindex fsplit-ivs-in-unroller
6988 Enables expressing of values of induction variables in later iterations
6989 of the unrolled loop using the value in the first iteration. This breaks
6990 long dependency chains, thus improving efficiency of the scheduling passes.
6992 Combination of @option{-fweb} and CSE is often sufficient to obtain the
6993 same effect. However in cases the loop body is more complicated than
6994 a single basic block, this is not reliable. It also does not work at all
6995 on some of the architectures due to restrictions in the CSE pass.
6997 This optimization is enabled by default.
6999 @item -fvariable-expansion-in-unroller
7000 @opindex fvariable-expansion-in-unroller
7001 With this option, the compiler will create multiple copies of some
7002 local variables when unrolling a loop which can result in superior code.
7004 @item -fpredictive-commoning
7005 @opindex fpredictive-commoning
7006 Perform predictive commoning optimization, i.e., reusing computations
7007 (especially memory loads and stores) performed in previous
7008 iterations of loops.
7010 This option is enabled at level @option{-O3}.
7012 @item -fprefetch-loop-arrays
7013 @opindex fprefetch-loop-arrays
7014 If supported by the target machine, generate instructions to prefetch
7015 memory to improve the performance of loops that access large arrays.
7017 This option may generate better or worse code; results are highly
7018 dependent on the structure of loops within the source code.
7020 Disabled at level @option{-Os}.
7023 @itemx -fno-peephole2
7024 @opindex fno-peephole
7025 @opindex fno-peephole2
7026 Disable any machine-specific peephole optimizations. The difference
7027 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
7028 are implemented in the compiler; some targets use one, some use the
7029 other, a few use both.
7031 @option{-fpeephole} is enabled by default.
7032 @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
7034 @item -fno-guess-branch-probability
7035 @opindex fno-guess-branch-probability
7036 Do not guess branch probabilities using heuristics.
7038 GCC will use heuristics to guess branch probabilities if they are
7039 not provided by profiling feedback (@option{-fprofile-arcs}). These
7040 heuristics are based on the control flow graph. If some branch probabilities
7041 are specified by @samp{__builtin_expect}, then the heuristics will be
7042 used to guess branch probabilities for the rest of the control flow graph,
7043 taking the @samp{__builtin_expect} info into account. The interactions
7044 between the heuristics and @samp{__builtin_expect} can be complex, and in
7045 some cases, it may be useful to disable the heuristics so that the effects
7046 of @samp{__builtin_expect} are easier to understand.
7048 The default is @option{-fguess-branch-probability} at levels
7049 @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
7051 @item -freorder-blocks
7052 @opindex freorder-blocks
7053 Reorder basic blocks in the compiled function in order to reduce number of
7054 taken branches and improve code locality.
7056 Enabled at levels @option{-O2}, @option{-O3}.
7058 @item -freorder-blocks-and-partition
7059 @opindex freorder-blocks-and-partition
7060 In addition to reordering basic blocks in the compiled function, in order
7061 to reduce number of taken branches, partitions hot and cold basic blocks
7062 into separate sections of the assembly and .o files, to improve
7063 paging and cache locality performance.
7065 This optimization is automatically turned off in the presence of
7066 exception handling, for linkonce sections, for functions with a user-defined
7067 section attribute and on any architecture that does not support named
7070 @item -freorder-functions
7071 @opindex freorder-functions
7072 Reorder functions in the object file in order to
7073 improve code locality. This is implemented by using special
7074 subsections @code{.text.hot} for most frequently executed functions and
7075 @code{.text.unlikely} for unlikely executed functions. Reordering is done by
7076 the linker so object file format must support named sections and linker must
7077 place them in a reasonable way.
7079 Also profile feedback must be available in to make this option effective. See
7080 @option{-fprofile-arcs} for details.
7082 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
7084 @item -fstrict-aliasing
7085 @opindex fstrict-aliasing
7086 Allow the compiler to assume the strictest aliasing rules applicable to
7087 the language being compiled. For C (and C++), this activates
7088 optimizations based on the type of expressions. In particular, an
7089 object of one type is assumed never to reside at the same address as an
7090 object of a different type, unless the types are almost the same. For
7091 example, an @code{unsigned int} can alias an @code{int}, but not a
7092 @code{void*} or a @code{double}. A character type may alias any other
7095 @anchor{Type-punning}Pay special attention to code like this:
7108 The practice of reading from a different union member than the one most
7109 recently written to (called ``type-punning'') is common. Even with
7110 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
7111 is accessed through the union type. So, the code above will work as
7112 expected. @xref{Structures unions enumerations and bit-fields
7113 implementation}. However, this code might not:
7124 Similarly, access by taking the address, casting the resulting pointer
7125 and dereferencing the result has undefined behavior, even if the cast
7126 uses a union type, e.g.:
7130 return ((union a_union *) &d)->i;
7134 The @option{-fstrict-aliasing} option is enabled at levels
7135 @option{-O2}, @option{-O3}, @option{-Os}.
7137 @item -fstrict-overflow
7138 @opindex fstrict-overflow
7139 Allow the compiler to assume strict signed overflow rules, depending
7140 on the language being compiled. For C (and C++) this means that
7141 overflow when doing arithmetic with signed numbers is undefined, which
7142 means that the compiler may assume that it will not happen. This
7143 permits various optimizations. For example, the compiler will assume
7144 that an expression like @code{i + 10 > i} will always be true for
7145 signed @code{i}. This assumption is only valid if signed overflow is
7146 undefined, as the expression is false if @code{i + 10} overflows when
7147 using twos complement arithmetic. When this option is in effect any
7148 attempt to determine whether an operation on signed numbers will
7149 overflow must be written carefully to not actually involve overflow.
7151 This option also allows the compiler to assume strict pointer
7152 semantics: given a pointer to an object, if adding an offset to that
7153 pointer does not produce a pointer to the same object, the addition is
7154 undefined. This permits the compiler to conclude that @code{p + u >
7155 p} is always true for a pointer @code{p} and unsigned integer
7156 @code{u}. This assumption is only valid because pointer wraparound is
7157 undefined, as the expression is false if @code{p + u} overflows using
7158 twos complement arithmetic.
7160 See also the @option{-fwrapv} option. Using @option{-fwrapv} means
7161 that integer signed overflow is fully defined: it wraps. When
7162 @option{-fwrapv} is used, there is no difference between
7163 @option{-fstrict-overflow} and @option{-fno-strict-overflow} for
7164 integers. With @option{-fwrapv} certain types of overflow are
7165 permitted. For example, if the compiler gets an overflow when doing
7166 arithmetic on constants, the overflowed value can still be used with
7167 @option{-fwrapv}, but not otherwise.
7169 The @option{-fstrict-overflow} option is enabled at levels
7170 @option{-O2}, @option{-O3}, @option{-Os}.
7172 @item -falign-functions
7173 @itemx -falign-functions=@var{n}
7174 @opindex falign-functions
7175 Align the start of functions to the next power-of-two greater than
7176 @var{n}, skipping up to @var{n} bytes. For instance,
7177 @option{-falign-functions=32} aligns functions to the next 32-byte
7178 boundary, but @option{-falign-functions=24} would align to the next
7179 32-byte boundary only if this can be done by skipping 23 bytes or less.
7181 @option{-fno-align-functions} and @option{-falign-functions=1} are
7182 equivalent and mean that functions will not be aligned.
7184 Some assemblers only support this flag when @var{n} is a power of two;
7185 in that case, it is rounded up.
7187 If @var{n} is not specified or is zero, use a machine-dependent default.
7189 Enabled at levels @option{-O2}, @option{-O3}.
7191 @item -falign-labels
7192 @itemx -falign-labels=@var{n}
7193 @opindex falign-labels
7194 Align all branch targets to a power-of-two boundary, skipping up to
7195 @var{n} bytes like @option{-falign-functions}. This option can easily
7196 make code slower, because it must insert dummy operations for when the
7197 branch target is reached in the usual flow of the code.
7199 @option{-fno-align-labels} and @option{-falign-labels=1} are
7200 equivalent and mean that labels will not be aligned.
7202 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
7203 are greater than this value, then their values are used instead.
7205 If @var{n} is not specified or is zero, use a machine-dependent default
7206 which is very likely to be @samp{1}, meaning no alignment.
7208 Enabled at levels @option{-O2}, @option{-O3}.
7211 @itemx -falign-loops=@var{n}
7212 @opindex falign-loops
7213 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
7214 like @option{-falign-functions}. The hope is that the loop will be
7215 executed many times, which will make up for any execution of the dummy
7218 @option{-fno-align-loops} and @option{-falign-loops=1} are
7219 equivalent and mean that loops will not be aligned.
7221 If @var{n} is not specified or is zero, use a machine-dependent default.
7223 Enabled at levels @option{-O2}, @option{-O3}.
7226 @itemx -falign-jumps=@var{n}
7227 @opindex falign-jumps
7228 Align branch targets to a power-of-two boundary, for branch targets
7229 where the targets can only be reached by jumping, skipping up to @var{n}
7230 bytes like @option{-falign-functions}. In this case, no dummy operations
7233 @option{-fno-align-jumps} and @option{-falign-jumps=1} are
7234 equivalent and mean that loops will not be aligned.
7236 If @var{n} is not specified or is zero, use a machine-dependent default.
7238 Enabled at levels @option{-O2}, @option{-O3}.
7240 @item -funit-at-a-time
7241 @opindex funit-at-a-time
7242 This option is left for compatibility reasons. @option{-funit-at-a-time}
7243 has no effect, while @option{-fno-unit-at-a-time} implies
7244 @option{-fno-toplevel-reorder} and @option{-fno-section-anchors}.
7248 @item -fno-toplevel-reorder
7249 @opindex fno-toplevel-reorder
7250 Do not reorder top-level functions, variables, and @code{asm}
7251 statements. Output them in the same order that they appear in the
7252 input file. When this option is used, unreferenced static variables
7253 will not be removed. This option is intended to support existing code
7254 which relies on a particular ordering. For new code, it is better to
7257 Enabled at level @option{-O0}. When disabled explicitly, it also imply
7258 @option{-fno-section-anchors} that is otherwise enabled at @option{-O0} on some
7263 Constructs webs as commonly used for register allocation purposes and assign
7264 each web individual pseudo register. This allows the register allocation pass
7265 to operate on pseudos directly, but also strengthens several other optimization
7266 passes, such as CSE, loop optimizer and trivial dead code remover. It can,
7267 however, make debugging impossible, since variables will no longer stay in a
7270 Enabled by default with @option{-funroll-loops}.
7272 @item -fwhole-program
7273 @opindex fwhole-program
7274 Assume that the current compilation unit represents the whole program being
7275 compiled. All public functions and variables with the exception of @code{main}
7276 and those merged by attribute @code{externally_visible} become static functions
7277 and in effect are optimized more aggressively by interprocedural optimizers.
7278 While this option is equivalent to proper use of the @code{static} keyword for
7279 programs consisting of a single file, in combination with option
7280 @option{-combine}, @option{-flto} or @option{-fwhopr} this flag can be used to
7281 compile many smaller scale programs since the functions and variables become
7282 local for the whole combined compilation unit, not for the single source file
7285 This option implies @option{-fwhole-file} for Fortran programs.
7289 This option runs the standard link-time optimizer. When invoked
7290 with source code, it generates GIMPLE (one of GCC's internal
7291 representations) and writes it to special ELF sections in the object
7292 file. When the object files are linked together, all the function
7293 bodies are read from these ELF sections and instantiated as if they
7294 had been part of the same translation unit.
7296 To use the link-timer optimizer, @option{-flto} needs to be specified at
7297 compile time and during the final link. For example,
7300 gcc -c -O2 -flto foo.c
7301 gcc -c -O2 -flto bar.c
7302 gcc -o myprog -flto -O2 foo.o bar.o
7305 The first two invocations to GCC will save a bytecode representation
7306 of GIMPLE into special ELF sections inside @file{foo.o} and
7307 @file{bar.o}. The final invocation will read the GIMPLE bytecode from
7308 @file{foo.o} and @file{bar.o}, merge the two files into a single
7309 internal image, and compile the result as usual. Since both
7310 @file{foo.o} and @file{bar.o} are merged into a single image, this
7311 causes all the inter-procedural analyses and optimizations in GCC to
7312 work across the two files as if they were a single one. This means,
7313 for example, that the inliner will be able to inline functions in
7314 @file{bar.o} into functions in @file{foo.o} and vice-versa.
7316 Another (simpler) way to enable link-time optimization is,
7319 gcc -o myprog -flto -O2 foo.c bar.c
7322 The above will generate bytecode for @file{foo.c} and @file{bar.c},
7323 merge them together into a single GIMPLE representation and optimize
7324 them as usual to produce @file{myprog}.
7326 The only important thing to keep in mind is that to enable link-time
7327 optimizations the @option{-flto} flag needs to be passed to both the
7328 compile and the link commands.
7330 Note that when a file is compiled with @option{-flto}, the generated
7331 object file will be larger than a regular object file because it will
7332 contain GIMPLE bytecodes and the usual final code. This means that
7333 object files with LTO information can be linked as a normal object
7334 file. So, in the previous example, if the final link is done with
7337 gcc -o myprog foo.o bar.o
7340 The only difference will be that no inter-procedural optimizations
7341 will be applied to produce @file{myprog}. The two object files
7342 @file{foo.o} and @file{bar.o} will be simply sent to the regular
7345 Additionally, the optimization flags used to compile individual files
7346 are not necessarily related to those used at link-time. For instance,
7349 gcc -c -O0 -flto foo.c
7350 gcc -c -O0 -flto bar.c
7351 gcc -o myprog -flto -O3 foo.o bar.o
7354 This will produce individual object files with unoptimized assembler
7355 code, but the resulting binary @file{myprog} will be optimized at
7356 @option{-O3}. Now, if the final binary is generated without
7357 @option{-flto}, then @file{myprog} will not be optimized.
7359 When producing the final binary with @option{-flto}, GCC will only
7360 apply link-time optimizations to those files that contain bytecode.
7361 Therefore, you can mix and match object files and libraries with
7362 GIMPLE bytecodes and final object code. GCC will automatically select
7363 which files to optimize in LTO mode and which files to link without
7366 There are some code generation flags that GCC will preserve when
7367 generating bytecodes, as they need to be used during the final link
7368 stage. Currently, the following options are saved into the GIMPLE
7369 bytecode files: @option{-fPIC}, @option{-fcommon} and all the
7370 @option{-m} target flags.
7372 At link time, these options are read-in and reapplied. Note that the
7373 current implementation makes no attempt at recognizing conflicting
7374 values for these options. If two or more files have a conflicting
7375 value (e.g., one file is compiled with @option{-fPIC} and another
7376 isn't), the compiler will simply use the last value read from the
7377 bytecode files. It is recommended, then, that all the files
7378 participating in the same link be compiled with the same options.
7380 Another feature of LTO is that it is possible to apply interprocedural
7381 optimizations on files written in different languages. This requires
7382 some support in the language front end. Currently, the C, C++ and
7383 Fortran front ends are capable of emitting GIMPLE bytecodes, so
7384 something like this should work
7389 gfortran -c -flto baz.f90
7390 g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran
7393 Notice that the final link is done with @command{g++} to get the C++
7394 runtime libraries and @option{-lgfortran} is added to get the Fortran
7395 runtime libraries. In general, when mixing languages in LTO mode, you
7396 should use the same link command used when mixing languages in a
7397 regular (non-LTO) compilation. This means that if your build process
7398 was mixing languages before, all you need to add is @option{-flto} to
7399 all the compile and link commands.
7401 If LTO encounters objects with C linkage declared with incompatible
7402 types in separate translation units to be linked together (undefined
7403 behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be
7404 issued. The behavior is still undefined at runtime.
7406 If object files containing GIMPLE bytecode are stored in a library
7407 archive, say @file{libfoo.a}, it is possible to extract and use them
7408 in an LTO link if you are using @command{gold} as the linker (which,
7409 in turn requires GCC to be configured with @option{--enable-gold}).
7410 To enable this feature, use the flag @option{-fuse-linker-plugin} at
7414 gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo
7417 With the linker plugin enabled, @command{gold} will extract the needed
7418 GIMPLE files from @file{libfoo.a} and pass them on to the running GCC
7419 to make them part of the aggregated GIMPLE image to be optimized.
7421 If you are not using @command{gold} and/or do not specify
7422 @option{-fuse-linker-plugin} then the objects inside @file{libfoo.a}
7423 will be extracted and linked as usual, but they will not participate
7424 in the LTO optimization process.
7426 Link time optimizations do not require the presence of the whole
7427 program to operate. If the program does not require any symbols to
7428 be exported, it is possible to combine @option{-flto} and
7429 @option{-fwhopr} with @option{-fwhole-program} to allow the
7430 interprocedural optimizers to use more aggressive assumptions which
7431 may lead to improved optimization opportunities.
7433 Regarding portability: the current implementation of LTO makes no
7434 attempt at generating bytecode that can be ported between different
7435 types of hosts. The bytecode files are versioned and there is a
7436 strict version check, so bytecode files generated in one version of
7437 GCC will not work with an older/newer version of GCC.
7439 Link time optimization does not play well with generating debugging
7440 information. Combining @option{-flto} or @option{-fwhopr} with
7441 @option{-g} is experimental.
7443 This option is disabled by default.
7447 This option is identical in functionality to @option{-flto} but it
7448 differs in how the final link stage is executed. Instead of loading
7449 all the function bodies in memory, the callgraph is analyzed and
7450 optimization decisions are made (whole program analysis or WPA). Once
7451 optimization decisions are made, the callgraph is partitioned and the
7452 different sections are compiled separately (local transformations or
7453 LTRANS)@. This process allows optimizations on very large programs
7454 that otherwise would not fit in memory. This option enables
7455 @option{-fwpa} and @option{-fltrans} automatically.
7457 Disabled by default.
7461 This is an internal option used by GCC when compiling with
7462 @option{-fwhopr}. You should never need to use it.
7464 This option runs the link-time optimizer in the whole-program-analysis
7465 (WPA) mode, which reads in summary information from all inputs and
7466 performs a whole-program analysis based on summary information only.
7467 It generates object files for subsequent runs of the link-time
7468 optimizer where individual object files are optimized using both
7469 summary information from the WPA mode and the actual function bodies.
7470 It then drives the LTRANS phase.
7472 Disabled by default.
7476 This is an internal option used by GCC when compiling with
7477 @option{-fwhopr}. You should never need to use it.
7479 This option runs the link-time optimizer in the local-transformation (LTRANS)
7480 mode, which reads in output from a previous run of the LTO in WPA mode.
7481 In the LTRANS mode, LTO optimizes an object and produces the final assembly.
7483 Disabled by default.
7485 @item -fltrans-output-list=@var{file}
7486 @opindex fltrans-output-list
7487 This is an internal option used by GCC when compiling with
7488 @option{-fwhopr}. You should never need to use it.
7490 This option specifies a file to which the names of LTRANS output files are
7491 written. This option is only meaningful in conjunction with @option{-fwpa}.
7493 Disabled by default.
7495 @item -flto-compression-level=@var{n}
7496 This option specifies the level of compression used for intermediate
7497 language written to LTO object files, and is only meaningful in
7498 conjunction with LTO mode (@option{-fwhopr}, @option{-flto}). Valid
7499 values are 0 (no compression) to 9 (maximum compression). Values
7500 outside this range are clamped to either 0 or 9. If the option is not
7501 given, a default balanced compression setting is used.
7504 Prints a report with internal details on the workings of the link-time
7505 optimizer. The contents of this report vary from version to version,
7506 it is meant to be useful to GCC developers when processing object
7507 files in LTO mode (via @option{-fwhopr} or @option{-flto}).
7509 Disabled by default.
7511 @item -fuse-linker-plugin
7512 Enables the extraction of objects with GIMPLE bytecode information
7513 from library archives. This option relies on features available only
7514 in @command{gold}, so to use this you must configure GCC with
7515 @option{--enable-gold}. See @option{-flto} for a description on the
7516 effect of this flag and how to use it.
7518 Disabled by default.
7520 @item -fcprop-registers
7521 @opindex fcprop-registers
7522 After register allocation and post-register allocation instruction splitting,
7523 we perform a copy-propagation pass to try to reduce scheduling dependencies
7524 and occasionally eliminate the copy.
7526 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
7528 @item -fprofile-correction
7529 @opindex fprofile-correction
7530 Profiles collected using an instrumented binary for multi-threaded programs may
7531 be inconsistent due to missed counter updates. When this option is specified,
7532 GCC will use heuristics to correct or smooth out such inconsistencies. By
7533 default, GCC will emit an error message when an inconsistent profile is detected.
7535 @item -fprofile-dir=@var{path}
7536 @opindex fprofile-dir
7538 Set the directory to search the profile data files in to @var{path}.
7539 This option affects only the profile data generated by
7540 @option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs}
7541 and used by @option{-fprofile-use} and @option{-fbranch-probabilities}
7542 and its related options.
7543 By default, GCC will use the current directory as @var{path}
7544 thus the profile data file will appear in the same directory as the object file.
7546 @item -fprofile-generate
7547 @itemx -fprofile-generate=@var{path}
7548 @opindex fprofile-generate
7550 Enable options usually used for instrumenting application to produce
7551 profile useful for later recompilation with profile feedback based
7552 optimization. You must use @option{-fprofile-generate} both when
7553 compiling and when linking your program.
7555 The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
7557 If @var{path} is specified, GCC will look at the @var{path} to find
7558 the profile feedback data files. See @option{-fprofile-dir}.
7561 @itemx -fprofile-use=@var{path}
7562 @opindex fprofile-use
7563 Enable profile feedback directed optimizations, and optimizations
7564 generally profitable only with profile feedback available.
7566 The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
7567 @code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
7569 By default, GCC emits an error message if the feedback profiles do not
7570 match the source code. This error can be turned into a warning by using
7571 @option{-Wcoverage-mismatch}. Note this may result in poorly optimized
7574 If @var{path} is specified, GCC will look at the @var{path} to find
7575 the profile feedback data files. See @option{-fprofile-dir}.
7578 The following options control compiler behavior regarding floating
7579 point arithmetic. These options trade off between speed and
7580 correctness. All must be specifically enabled.
7584 @opindex ffloat-store
7585 Do not store floating point variables in registers, and inhibit other
7586 options that might change whether a floating point value is taken from a
7589 @cindex floating point precision
7590 This option prevents undesirable excess precision on machines such as
7591 the 68000 where the floating registers (of the 68881) keep more
7592 precision than a @code{double} is supposed to have. Similarly for the
7593 x86 architecture. For most programs, the excess precision does only
7594 good, but a few programs rely on the precise definition of IEEE floating
7595 point. Use @option{-ffloat-store} for such programs, after modifying
7596 them to store all pertinent intermediate computations into variables.
7598 @item -fexcess-precision=@var{style}
7599 @opindex fexcess-precision
7600 This option allows further control over excess precision on machines
7601 where floating-point registers have more precision than the IEEE
7602 @code{float} and @code{double} types and the processor does not
7603 support operations rounding to those types. By default,
7604 @option{-fexcess-precision=fast} is in effect; this means that
7605 operations are carried out in the precision of the registers and that
7606 it is unpredictable when rounding to the types specified in the source
7607 code takes place. When compiling C, if
7608 @option{-fexcess-precision=standard} is specified then excess
7609 precision will follow the rules specified in ISO C99; in particular,
7610 both casts and assignments cause values to be rounded to their
7611 semantic types (whereas @option{-ffloat-store} only affects
7612 assignments). This option is enabled by default for C if a strict
7613 conformance option such as @option{-std=c99} is used.
7616 @option{-fexcess-precision=standard} is not implemented for languages
7617 other than C, and has no effect if
7618 @option{-funsafe-math-optimizations} or @option{-ffast-math} is
7619 specified. On the x86, it also has no effect if @option{-mfpmath=sse}
7620 or @option{-mfpmath=sse+387} is specified; in the former case, IEEE
7621 semantics apply without excess precision, and in the latter, rounding
7626 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations},
7627 @option{-ffinite-math-only}, @option{-fno-rounding-math},
7628 @option{-fno-signaling-nans} and @option{-fcx-limited-range}.
7630 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
7632 This option is not turned on by any @option{-O} option since
7633 it can result in incorrect output for programs which depend on
7634 an exact implementation of IEEE or ISO rules/specifications for
7635 math functions. It may, however, yield faster code for programs
7636 that do not require the guarantees of these specifications.
7638 @item -fno-math-errno
7639 @opindex fno-math-errno
7640 Do not set ERRNO after calling math functions that are executed
7641 with a single instruction, e.g., sqrt. A program that relies on
7642 IEEE exceptions for math error handling may want to use this flag
7643 for speed while maintaining IEEE arithmetic compatibility.
7645 This option is not turned on by any @option{-O} option since
7646 it can result in incorrect output for programs which depend on
7647 an exact implementation of IEEE or ISO rules/specifications for
7648 math functions. It may, however, yield faster code for programs
7649 that do not require the guarantees of these specifications.
7651 The default is @option{-fmath-errno}.
7653 On Darwin systems, the math library never sets @code{errno}. There is
7654 therefore no reason for the compiler to consider the possibility that
7655 it might, and @option{-fno-math-errno} is the default.
7657 @item -funsafe-math-optimizations
7658 @opindex funsafe-math-optimizations
7660 Allow optimizations for floating-point arithmetic that (a) assume
7661 that arguments and results are valid and (b) may violate IEEE or
7662 ANSI standards. When used at link-time, it may include libraries
7663 or startup files that change the default FPU control word or other
7664 similar optimizations.
7666 This option is not turned on by any @option{-O} option since
7667 it can result in incorrect output for programs which depend on
7668 an exact implementation of IEEE or ISO rules/specifications for
7669 math functions. It may, however, yield faster code for programs
7670 that do not require the guarantees of these specifications.
7671 Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math},
7672 @option{-fassociative-math} and @option{-freciprocal-math}.
7674 The default is @option{-fno-unsafe-math-optimizations}.
7676 @item -fassociative-math
7677 @opindex fassociative-math
7679 Allow re-association of operands in series of floating-point operations.
7680 This violates the ISO C and C++ language standard by possibly changing
7681 computation result. NOTE: re-ordering may change the sign of zero as
7682 well as ignore NaNs and inhibit or create underflow or overflow (and
7683 thus cannot be used on a code which relies on rounding behavior like
7684 @code{(x + 2**52) - 2**52)}. May also reorder floating-point comparisons
7685 and thus may not be used when ordered comparisons are required.
7686 This option requires that both @option{-fno-signed-zeros} and
7687 @option{-fno-trapping-math} be in effect. Moreover, it doesn't make
7688 much sense with @option{-frounding-math}. For Fortran the option
7689 is automatically enabled when both @option{-fno-signed-zeros} and
7690 @option{-fno-trapping-math} are in effect.
7692 The default is @option{-fno-associative-math}.
7694 @item -freciprocal-math
7695 @opindex freciprocal-math
7697 Allow the reciprocal of a value to be used instead of dividing by
7698 the value if this enables optimizations. For example @code{x / y}
7699 can be replaced with @code{x * (1/y)} which is useful if @code{(1/y)}
7700 is subject to common subexpression elimination. Note that this loses
7701 precision and increases the number of flops operating on the value.
7703 The default is @option{-fno-reciprocal-math}.
7705 @item -ffinite-math-only
7706 @opindex ffinite-math-only
7707 Allow optimizations for floating-point arithmetic that assume
7708 that arguments and results are not NaNs or +-Infs.
7710 This option is not turned on by any @option{-O} option since
7711 it can result in incorrect output for programs which depend on
7712 an exact implementation of IEEE or ISO rules/specifications for
7713 math functions. It may, however, yield faster code for programs
7714 that do not require the guarantees of these specifications.
7716 The default is @option{-fno-finite-math-only}.
7718 @item -fno-signed-zeros
7719 @opindex fno-signed-zeros
7720 Allow optimizations for floating point arithmetic that ignore the
7721 signedness of zero. IEEE arithmetic specifies the behavior of
7722 distinct +0.0 and @minus{}0.0 values, which then prohibits simplification
7723 of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}).
7724 This option implies that the sign of a zero result isn't significant.
7726 The default is @option{-fsigned-zeros}.
7728 @item -fno-trapping-math
7729 @opindex fno-trapping-math
7730 Compile code assuming that floating-point operations cannot generate
7731 user-visible traps. These traps include division by zero, overflow,
7732 underflow, inexact result and invalid operation. This option requires
7733 that @option{-fno-signaling-nans} be in effect. Setting this option may
7734 allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example.
7736 This option should never be turned on by any @option{-O} option since
7737 it can result in incorrect output for programs which depend on
7738 an exact implementation of IEEE or ISO rules/specifications for
7741 The default is @option{-ftrapping-math}.
7743 @item -frounding-math
7744 @opindex frounding-math
7745 Disable transformations and optimizations that assume default floating
7746 point rounding behavior. This is round-to-zero for all floating point
7747 to integer conversions, and round-to-nearest for all other arithmetic
7748 truncations. This option should be specified for programs that change
7749 the FP rounding mode dynamically, or that may be executed with a
7750 non-default rounding mode. This option disables constant folding of
7751 floating point expressions at compile-time (which may be affected by
7752 rounding mode) and arithmetic transformations that are unsafe in the
7753 presence of sign-dependent rounding modes.
7755 The default is @option{-fno-rounding-math}.
7757 This option is experimental and does not currently guarantee to
7758 disable all GCC optimizations that are affected by rounding mode.
7759 Future versions of GCC may provide finer control of this setting
7760 using C99's @code{FENV_ACCESS} pragma. This command line option
7761 will be used to specify the default state for @code{FENV_ACCESS}.
7763 @item -fsignaling-nans
7764 @opindex fsignaling-nans
7765 Compile code assuming that IEEE signaling NaNs may generate user-visible
7766 traps during floating-point operations. Setting this option disables
7767 optimizations that may change the number of exceptions visible with
7768 signaling NaNs. This option implies @option{-ftrapping-math}.
7770 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
7773 The default is @option{-fno-signaling-nans}.
7775 This option is experimental and does not currently guarantee to
7776 disable all GCC optimizations that affect signaling NaN behavior.
7778 @item -fsingle-precision-constant
7779 @opindex fsingle-precision-constant
7780 Treat floating point constant as single precision constant instead of
7781 implicitly converting it to double precision constant.
7783 @item -fcx-limited-range
7784 @opindex fcx-limited-range
7785 When enabled, this option states that a range reduction step is not
7786 needed when performing complex division. Also, there is no checking
7787 whether the result of a complex multiplication or division is @code{NaN
7788 + I*NaN}, with an attempt to rescue the situation in that case. The
7789 default is @option{-fno-cx-limited-range}, but is enabled by
7790 @option{-ffast-math}.
7792 This option controls the default setting of the ISO C99
7793 @code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
7796 @item -fcx-fortran-rules
7797 @opindex fcx-fortran-rules
7798 Complex multiplication and division follow Fortran rules. Range
7799 reduction is done as part of complex division, but there is no checking
7800 whether the result of a complex multiplication or division is @code{NaN
7801 + I*NaN}, with an attempt to rescue the situation in that case.
7803 The default is @option{-fno-cx-fortran-rules}.
7807 The following options control optimizations that may improve
7808 performance, but are not enabled by any @option{-O} options. This
7809 section includes experimental options that may produce broken code.
7812 @item -fbranch-probabilities
7813 @opindex fbranch-probabilities
7814 After running a program compiled with @option{-fprofile-arcs}
7815 (@pxref{Debugging Options,, Options for Debugging Your Program or
7816 @command{gcc}}), you can compile it a second time using
7817 @option{-fbranch-probabilities}, to improve optimizations based on
7818 the number of times each branch was taken. When the program
7819 compiled with @option{-fprofile-arcs} exits it saves arc execution
7820 counts to a file called @file{@var{sourcename}.gcda} for each source
7821 file. The information in this data file is very dependent on the
7822 structure of the generated code, so you must use the same source code
7823 and the same optimization options for both compilations.
7825 With @option{-fbranch-probabilities}, GCC puts a
7826 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
7827 These can be used to improve optimization. Currently, they are only
7828 used in one place: in @file{reorg.c}, instead of guessing which path a
7829 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
7830 exactly determine which path is taken more often.
7832 @item -fprofile-values
7833 @opindex fprofile-values
7834 If combined with @option{-fprofile-arcs}, it adds code so that some
7835 data about values of expressions in the program is gathered.
7837 With @option{-fbranch-probabilities}, it reads back the data gathered
7838 from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
7839 notes to instructions for their later usage in optimizations.
7841 Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
7845 If combined with @option{-fprofile-arcs}, it instructs the compiler to add
7846 a code to gather information about values of expressions.
7848 With @option{-fbranch-probabilities}, it reads back the data gathered
7849 and actually performs the optimizations based on them.
7850 Currently the optimizations include specialization of division operation
7851 using the knowledge about the value of the denominator.
7853 @item -frename-registers
7854 @opindex frename-registers
7855 Attempt to avoid false dependencies in scheduled code by making use
7856 of registers left over after register allocation. This optimization
7857 will most benefit processors with lots of registers. Depending on the
7858 debug information format adopted by the target, however, it can
7859 make debugging impossible, since variables will no longer stay in
7860 a ``home register''.
7862 Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}.
7866 Perform tail duplication to enlarge superblock size. This transformation
7867 simplifies the control flow of the function allowing other optimizations to do
7870 Enabled with @option{-fprofile-use}.
7872 @item -funroll-loops
7873 @opindex funroll-loops
7874 Unroll loops whose number of iterations can be determined at compile time or
7875 upon entry to the loop. @option{-funroll-loops} implies
7876 @option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
7877 It also turns on complete loop peeling (i.e.@: complete removal of loops with
7878 small constant number of iterations). This option makes code larger, and may
7879 or may not make it run faster.
7881 Enabled with @option{-fprofile-use}.
7883 @item -funroll-all-loops
7884 @opindex funroll-all-loops
7885 Unroll all loops, even if their number of iterations is uncertain when
7886 the loop is entered. This usually makes programs run more slowly.
7887 @option{-funroll-all-loops} implies the same options as
7888 @option{-funroll-loops}.
7891 @opindex fpeel-loops
7892 Peels the loops for that there is enough information that they do not
7893 roll much (from profile feedback). It also turns on complete loop peeling
7894 (i.e.@: complete removal of loops with small constant number of iterations).
7896 Enabled with @option{-fprofile-use}.
7898 @item -fmove-loop-invariants
7899 @opindex fmove-loop-invariants
7900 Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
7901 at level @option{-O1}
7903 @item -funswitch-loops
7904 @opindex funswitch-loops
7905 Move branches with loop invariant conditions out of the loop, with duplicates
7906 of the loop on both branches (modified according to result of the condition).
7908 @item -ffunction-sections
7909 @itemx -fdata-sections
7910 @opindex ffunction-sections
7911 @opindex fdata-sections
7912 Place each function or data item into its own section in the output
7913 file if the target supports arbitrary sections. The name of the
7914 function or the name of the data item determines the section's name
7917 Use these options on systems where the linker can perform optimizations
7918 to improve locality of reference in the instruction space. Most systems
7919 using the ELF object format and SPARC processors running Solaris 2 have
7920 linkers with such optimizations. AIX may have these optimizations in
7923 Only use these options when there are significant benefits from doing
7924 so. When you specify these options, the assembler and linker will
7925 create larger object and executable files and will also be slower.
7926 You will not be able to use @code{gprof} on all systems if you
7927 specify this option and you may have problems with debugging if
7928 you specify both this option and @option{-g}.
7930 @item -fbranch-target-load-optimize
7931 @opindex fbranch-target-load-optimize
7932 Perform branch target register load optimization before prologue / epilogue
7934 The use of target registers can typically be exposed only during reload,
7935 thus hoisting loads out of loops and doing inter-block scheduling needs
7936 a separate optimization pass.
7938 @item -fbranch-target-load-optimize2
7939 @opindex fbranch-target-load-optimize2
7940 Perform branch target register load optimization after prologue / epilogue
7943 @item -fbtr-bb-exclusive
7944 @opindex fbtr-bb-exclusive
7945 When performing branch target register load optimization, don't reuse
7946 branch target registers in within any basic block.
7948 @item -fstack-protector
7949 @opindex fstack-protector
7950 Emit extra code to check for buffer overflows, such as stack smashing
7951 attacks. This is done by adding a guard variable to functions with
7952 vulnerable objects. This includes functions that call alloca, and
7953 functions with buffers larger than 8 bytes. The guards are initialized
7954 when a function is entered and then checked when the function exits.
7955 If a guard check fails, an error message is printed and the program exits.
7957 @item -fstack-protector-all
7958 @opindex fstack-protector-all
7959 Like @option{-fstack-protector} except that all functions are protected.
7961 @item -fsection-anchors
7962 @opindex fsection-anchors
7963 Try to reduce the number of symbolic address calculations by using
7964 shared ``anchor'' symbols to address nearby objects. This transformation
7965 can help to reduce the number of GOT entries and GOT accesses on some
7968 For example, the implementation of the following function @code{foo}:
7972 int foo (void) @{ return a + b + c; @}
7975 would usually calculate the addresses of all three variables, but if you
7976 compile it with @option{-fsection-anchors}, it will access the variables
7977 from a common anchor point instead. The effect is similar to the
7978 following pseudocode (which isn't valid C):
7983 register int *xr = &x;
7984 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
7988 Not all targets support this option.
7990 @item --param @var{name}=@var{value}
7992 In some places, GCC uses various constants to control the amount of
7993 optimization that is done. For example, GCC will not inline functions
7994 that contain more that a certain number of instructions. You can
7995 control some of these constants on the command-line using the
7996 @option{--param} option.
7998 The names of specific parameters, and the meaning of the values, are
7999 tied to the internals of the compiler, and are subject to change
8000 without notice in future releases.
8002 In each case, the @var{value} is an integer. The allowable choices for
8003 @var{name} are given in the following table:
8006 @item struct-reorg-cold-struct-ratio
8007 The threshold ratio (as a percentage) between a structure frequency
8008 and the frequency of the hottest structure in the program. This parameter
8009 is used by struct-reorg optimization enabled by @option{-fipa-struct-reorg}.
8010 We say that if the ratio of a structure frequency, calculated by profiling,
8011 to the hottest structure frequency in the program is less than this
8012 parameter, then structure reorganization is not applied to this structure.
8015 @item predictable-branch-outcome
8016 When branch is predicted to be taken with probability lower than this threshold
8017 (in percent), then it is considered well predictable. The default is 10.
8019 @item max-crossjump-edges
8020 The maximum number of incoming edges to consider for crossjumping.
8021 The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
8022 the number of edges incoming to each block. Increasing values mean
8023 more aggressive optimization, making the compile time increase with
8024 probably small improvement in executable size.
8026 @item min-crossjump-insns
8027 The minimum number of instructions which must be matched at the end
8028 of two blocks before crossjumping will be performed on them. This
8029 value is ignored in the case where all instructions in the block being
8030 crossjumped from are matched. The default value is 5.
8032 @item max-grow-copy-bb-insns
8033 The maximum code size expansion factor when copying basic blocks
8034 instead of jumping. The expansion is relative to a jump instruction.
8035 The default value is 8.
8037 @item max-goto-duplication-insns
8038 The maximum number of instructions to duplicate to a block that jumps
8039 to a computed goto. To avoid @math{O(N^2)} behavior in a number of
8040 passes, GCC factors computed gotos early in the compilation process,
8041 and unfactors them as late as possible. Only computed jumps at the
8042 end of a basic blocks with no more than max-goto-duplication-insns are
8043 unfactored. The default value is 8.
8045 @item max-delay-slot-insn-search
8046 The maximum number of instructions to consider when looking for an
8047 instruction to fill a delay slot. If more than this arbitrary number of
8048 instructions is searched, the time savings from filling the delay slot
8049 will be minimal so stop searching. Increasing values mean more
8050 aggressive optimization, making the compile time increase with probably
8051 small improvement in executable run time.
8053 @item max-delay-slot-live-search
8054 When trying to fill delay slots, the maximum number of instructions to
8055 consider when searching for a block with valid live register
8056 information. Increasing this arbitrarily chosen value means more
8057 aggressive optimization, increasing the compile time. This parameter
8058 should be removed when the delay slot code is rewritten to maintain the
8061 @item max-gcse-memory
8062 The approximate maximum amount of memory that will be allocated in
8063 order to perform the global common subexpression elimination
8064 optimization. If more memory than specified is required, the
8065 optimization will not be done.
8067 @item max-pending-list-length
8068 The maximum number of pending dependencies scheduling will allow
8069 before flushing the current state and starting over. Large functions
8070 with few branches or calls can create excessively large lists which
8071 needlessly consume memory and resources.
8073 @item max-inline-insns-single
8074 Several parameters control the tree inliner used in gcc.
8075 This number sets the maximum number of instructions (counted in GCC's
8076 internal representation) in a single function that the tree inliner
8077 will consider for inlining. This only affects functions declared
8078 inline and methods implemented in a class declaration (C++).
8079 The default value is 300.
8081 @item max-inline-insns-auto
8082 When you use @option{-finline-functions} (included in @option{-O3}),
8083 a lot of functions that would otherwise not be considered for inlining
8084 by the compiler will be investigated. To those functions, a different
8085 (more restrictive) limit compared to functions declared inline can
8087 The default value is 50.
8089 @item large-function-insns
8090 The limit specifying really large functions. For functions larger than this
8091 limit after inlining, inlining is constrained by
8092 @option{--param large-function-growth}. This parameter is useful primarily
8093 to avoid extreme compilation time caused by non-linear algorithms used by the
8095 The default value is 2700.
8097 @item large-function-growth
8098 Specifies maximal growth of large function caused by inlining in percents.
8099 The default value is 100 which limits large function growth to 2.0 times
8102 @item large-unit-insns
8103 The limit specifying large translation unit. Growth caused by inlining of
8104 units larger than this limit is limited by @option{--param inline-unit-growth}.
8105 For small units this might be too tight (consider unit consisting of function A
8106 that is inline and B that just calls A three time. If B is small relative to
8107 A, the growth of unit is 300\% and yet such inlining is very sane. For very
8108 large units consisting of small inlineable functions however the overall unit
8109 growth limit is needed to avoid exponential explosion of code size. Thus for
8110 smaller units, the size is increased to @option{--param large-unit-insns}
8111 before applying @option{--param inline-unit-growth}. The default is 10000
8113 @item inline-unit-growth
8114 Specifies maximal overall growth of the compilation unit caused by inlining.
8115 The default value is 30 which limits unit growth to 1.3 times the original
8118 @item ipcp-unit-growth
8119 Specifies maximal overall growth of the compilation unit caused by
8120 interprocedural constant propagation. The default value is 10 which limits
8121 unit growth to 1.1 times the original size.
8123 @item large-stack-frame
8124 The limit specifying large stack frames. While inlining the algorithm is trying
8125 to not grow past this limit too much. Default value is 256 bytes.
8127 @item large-stack-frame-growth
8128 Specifies maximal growth of large stack frames caused by inlining in percents.
8129 The default value is 1000 which limits large stack frame growth to 11 times
8132 @item max-inline-insns-recursive
8133 @itemx max-inline-insns-recursive-auto
8134 Specifies maximum number of instructions out-of-line copy of self recursive inline
8135 function can grow into by performing recursive inlining.
8137 For functions declared inline @option{--param max-inline-insns-recursive} is
8138 taken into account. For function not declared inline, recursive inlining
8139 happens only when @option{-finline-functions} (included in @option{-O3}) is
8140 enabled and @option{--param max-inline-insns-recursive-auto} is used. The
8141 default value is 450.
8143 @item max-inline-recursive-depth
8144 @itemx max-inline-recursive-depth-auto
8145 Specifies maximum recursion depth used by the recursive inlining.
8147 For functions declared inline @option{--param max-inline-recursive-depth} is
8148 taken into account. For function not declared inline, recursive inlining
8149 happens only when @option{-finline-functions} (included in @option{-O3}) is
8150 enabled and @option{--param max-inline-recursive-depth-auto} is used. The
8153 @item min-inline-recursive-probability
8154 Recursive inlining is profitable only for function having deep recursion
8155 in average and can hurt for function having little recursion depth by
8156 increasing the prologue size or complexity of function body to other
8159 When profile feedback is available (see @option{-fprofile-generate}) the actual
8160 recursion depth can be guessed from probability that function will recurse via
8161 given call expression. This parameter limits inlining only to call expression
8162 whose probability exceeds given threshold (in percents). The default value is
8165 @item early-inlining-insns
8166 Specify growth that early inliner can make. In effect it increases amount of
8167 inlining for code having large abstraction penalty. The default value is 8.
8169 @item max-early-inliner-iterations
8170 @itemx max-early-inliner-iterations
8171 Limit of iterations of early inliner. This basically bounds number of nested
8172 indirect calls early inliner can resolve. Deeper chains are still handled by
8175 @item min-vect-loop-bound
8176 The minimum number of iterations under which a loop will not get vectorized
8177 when @option{-ftree-vectorize} is used. The number of iterations after
8178 vectorization needs to be greater than the value specified by this option
8179 to allow vectorization. The default value is 0.
8181 @item max-unrolled-insns
8182 The maximum number of instructions that a loop should have if that loop
8183 is unrolled, and if the loop is unrolled, it determines how many times
8184 the loop code is unrolled.
8186 @item max-average-unrolled-insns
8187 The maximum number of instructions biased by probabilities of their execution
8188 that a loop should have if that loop is unrolled, and if the loop is unrolled,
8189 it determines how many times the loop code is unrolled.
8191 @item max-unroll-times
8192 The maximum number of unrollings of a single loop.
8194 @item max-peeled-insns
8195 The maximum number of instructions that a loop should have if that loop
8196 is peeled, and if the loop is peeled, it determines how many times
8197 the loop code is peeled.
8199 @item max-peel-times
8200 The maximum number of peelings of a single loop.
8202 @item max-completely-peeled-insns
8203 The maximum number of insns of a completely peeled loop.
8205 @item max-completely-peel-times
8206 The maximum number of iterations of a loop to be suitable for complete peeling.
8208 @item max-completely-peel-loop-nest-depth
8209 The maximum depth of a loop nest suitable for complete peeling.
8211 @item max-unswitch-insns
8212 The maximum number of insns of an unswitched loop.
8214 @item max-unswitch-level
8215 The maximum number of branches unswitched in a single loop.
8218 The minimum cost of an expensive expression in the loop invariant motion.
8220 @item iv-consider-all-candidates-bound
8221 Bound on number of candidates for induction variables below that
8222 all candidates are considered for each use in induction variable
8223 optimizations. Only the most relevant candidates are considered
8224 if there are more candidates, to avoid quadratic time complexity.
8226 @item iv-max-considered-uses
8227 The induction variable optimizations give up on loops that contain more
8228 induction variable uses.
8230 @item iv-always-prune-cand-set-bound
8231 If number of candidates in the set is smaller than this value,
8232 we always try to remove unnecessary ivs from the set during its
8233 optimization when a new iv is added to the set.
8235 @item scev-max-expr-size
8236 Bound on size of expressions used in the scalar evolutions analyzer.
8237 Large expressions slow the analyzer.
8239 @item omega-max-vars
8240 The maximum number of variables in an Omega constraint system.
8241 The default value is 128.
8243 @item omega-max-geqs
8244 The maximum number of inequalities in an Omega constraint system.
8245 The default value is 256.
8248 The maximum number of equalities in an Omega constraint system.
8249 The default value is 128.
8251 @item omega-max-wild-cards
8252 The maximum number of wildcard variables that the Omega solver will
8253 be able to insert. The default value is 18.
8255 @item omega-hash-table-size
8256 The size of the hash table in the Omega solver. The default value is
8259 @item omega-max-keys
8260 The maximal number of keys used by the Omega solver. The default
8263 @item omega-eliminate-redundant-constraints
8264 When set to 1, use expensive methods to eliminate all redundant
8265 constraints. The default value is 0.
8267 @item vect-max-version-for-alignment-checks
8268 The maximum number of runtime checks that can be performed when
8269 doing loop versioning for alignment in the vectorizer. See option
8270 ftree-vect-loop-version for more information.
8272 @item vect-max-version-for-alias-checks
8273 The maximum number of runtime checks that can be performed when
8274 doing loop versioning for alias in the vectorizer. See option
8275 ftree-vect-loop-version for more information.
8277 @item max-iterations-to-track
8279 The maximum number of iterations of a loop the brute force algorithm
8280 for analysis of # of iterations of the loop tries to evaluate.
8282 @item hot-bb-count-fraction
8283 Select fraction of the maximal count of repetitions of basic block in program
8284 given basic block needs to have to be considered hot.
8286 @item hot-bb-frequency-fraction
8287 Select fraction of the maximal frequency of executions of basic block in
8288 function given basic block needs to have to be considered hot
8290 @item max-predicted-iterations
8291 The maximum number of loop iterations we predict statically. This is useful
8292 in cases where function contain single loop with known bound and other loop
8293 with unknown. We predict the known number of iterations correctly, while
8294 the unknown number of iterations average to roughly 10. This means that the
8295 loop without bounds would appear artificially cold relative to the other one.
8297 @item align-threshold
8299 Select fraction of the maximal frequency of executions of basic block in
8300 function given basic block will get aligned.
8302 @item align-loop-iterations
8304 A loop expected to iterate at lest the selected number of iterations will get
8307 @item tracer-dynamic-coverage
8308 @itemx tracer-dynamic-coverage-feedback
8310 This value is used to limit superblock formation once the given percentage of
8311 executed instructions is covered. This limits unnecessary code size
8314 The @option{tracer-dynamic-coverage-feedback} is used only when profile
8315 feedback is available. The real profiles (as opposed to statically estimated
8316 ones) are much less balanced allowing the threshold to be larger value.
8318 @item tracer-max-code-growth
8319 Stop tail duplication once code growth has reached given percentage. This is
8320 rather hokey argument, as most of the duplicates will be eliminated later in
8321 cross jumping, so it may be set to much higher values than is the desired code
8324 @item tracer-min-branch-ratio
8326 Stop reverse growth when the reverse probability of best edge is less than this
8327 threshold (in percent).
8329 @item tracer-min-branch-ratio
8330 @itemx tracer-min-branch-ratio-feedback
8332 Stop forward growth if the best edge do have probability lower than this
8335 Similarly to @option{tracer-dynamic-coverage} two values are present, one for
8336 compilation for profile feedback and one for compilation without. The value
8337 for compilation with profile feedback needs to be more conservative (higher) in
8338 order to make tracer effective.
8340 @item max-cse-path-length
8342 Maximum number of basic blocks on path that cse considers. The default is 10.
8345 The maximum instructions CSE process before flushing. The default is 1000.
8347 @item ggc-min-expand
8349 GCC uses a garbage collector to manage its own memory allocation. This
8350 parameter specifies the minimum percentage by which the garbage
8351 collector's heap should be allowed to expand between collections.
8352 Tuning this may improve compilation speed; it has no effect on code
8355 The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
8356 RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
8357 the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
8358 GCC is not able to calculate RAM on a particular platform, the lower
8359 bound of 30% is used. Setting this parameter and
8360 @option{ggc-min-heapsize} to zero causes a full collection to occur at
8361 every opportunity. This is extremely slow, but can be useful for
8364 @item ggc-min-heapsize
8366 Minimum size of the garbage collector's heap before it begins bothering
8367 to collect garbage. The first collection occurs after the heap expands
8368 by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
8369 tuning this may improve compilation speed, and has no effect on code
8372 The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
8373 tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
8374 with a lower bound of 4096 (four megabytes) and an upper bound of
8375 131072 (128 megabytes). If GCC is not able to calculate RAM on a
8376 particular platform, the lower bound is used. Setting this parameter
8377 very large effectively disables garbage collection. Setting this
8378 parameter and @option{ggc-min-expand} to zero causes a full collection
8379 to occur at every opportunity.
8381 @item max-reload-search-insns
8382 The maximum number of instruction reload should look backward for equivalent
8383 register. Increasing values mean more aggressive optimization, making the
8384 compile time increase with probably slightly better performance. The default
8387 @item max-cselib-memory-locations
8388 The maximum number of memory locations cselib should take into account.
8389 Increasing values mean more aggressive optimization, making the compile time
8390 increase with probably slightly better performance. The default value is 500.
8392 @item reorder-blocks-duplicate
8393 @itemx reorder-blocks-duplicate-feedback
8395 Used by basic block reordering pass to decide whether to use unconditional
8396 branch or duplicate the code on its destination. Code is duplicated when its
8397 estimated size is smaller than this value multiplied by the estimated size of
8398 unconditional jump in the hot spots of the program.
8400 The @option{reorder-block-duplicate-feedback} is used only when profile
8401 feedback is available and may be set to higher values than
8402 @option{reorder-block-duplicate} since information about the hot spots is more
8405 @item max-sched-ready-insns
8406 The maximum number of instructions ready to be issued the scheduler should
8407 consider at any given time during the first scheduling pass. Increasing
8408 values mean more thorough searches, making the compilation time increase
8409 with probably little benefit. The default value is 100.
8411 @item max-sched-region-blocks
8412 The maximum number of blocks in a region to be considered for
8413 interblock scheduling. The default value is 10.
8415 @item max-pipeline-region-blocks
8416 The maximum number of blocks in a region to be considered for
8417 pipelining in the selective scheduler. The default value is 15.
8419 @item max-sched-region-insns
8420 The maximum number of insns in a region to be considered for
8421 interblock scheduling. The default value is 100.
8423 @item max-pipeline-region-insns
8424 The maximum number of insns in a region to be considered for
8425 pipelining in the selective scheduler. The default value is 200.
8428 The minimum probability (in percents) of reaching a source block
8429 for interblock speculative scheduling. The default value is 40.
8431 @item max-sched-extend-regions-iters
8432 The maximum number of iterations through CFG to extend regions.
8433 0 - disable region extension,
8434 N - do at most N iterations.
8435 The default value is 0.
8437 @item max-sched-insn-conflict-delay
8438 The maximum conflict delay for an insn to be considered for speculative motion.
8439 The default value is 3.
8441 @item sched-spec-prob-cutoff
8442 The minimal probability of speculation success (in percents), so that
8443 speculative insn will be scheduled.
8444 The default value is 40.
8446 @item sched-mem-true-dep-cost
8447 Minimal distance (in CPU cycles) between store and load targeting same
8448 memory locations. The default value is 1.
8450 @item selsched-max-lookahead
8451 The maximum size of the lookahead window of selective scheduling. It is a
8452 depth of search for available instructions.
8453 The default value is 50.
8455 @item selsched-max-sched-times
8456 The maximum number of times that an instruction will be scheduled during
8457 selective scheduling. This is the limit on the number of iterations
8458 through which the instruction may be pipelined. The default value is 2.
8460 @item selsched-max-insns-to-rename
8461 The maximum number of best instructions in the ready list that are considered
8462 for renaming in the selective scheduler. The default value is 2.
8464 @item max-last-value-rtl
8465 The maximum size measured as number of RTLs that can be recorded in an expression
8466 in combiner for a pseudo register as last known value of that register. The default
8469 @item integer-share-limit
8470 Small integer constants can use a shared data structure, reducing the
8471 compiler's memory usage and increasing its speed. This sets the maximum
8472 value of a shared integer constant. The default value is 256.
8474 @item min-virtual-mappings
8475 Specifies the minimum number of virtual mappings in the incremental
8476 SSA updater that should be registered to trigger the virtual mappings
8477 heuristic defined by virtual-mappings-ratio. The default value is
8480 @item virtual-mappings-ratio
8481 If the number of virtual mappings is virtual-mappings-ratio bigger
8482 than the number of virtual symbols to be updated, then the incremental
8483 SSA updater switches to a full update for those symbols. The default
8486 @item ssp-buffer-size
8487 The minimum size of buffers (i.e.@: arrays) that will receive stack smashing
8488 protection when @option{-fstack-protection} is used.
8490 @item max-jump-thread-duplication-stmts
8491 Maximum number of statements allowed in a block that needs to be
8492 duplicated when threading jumps.
8494 @item max-fields-for-field-sensitive
8495 Maximum number of fields in a structure we will treat in
8496 a field sensitive manner during pointer analysis. The default is zero
8497 for -O0, and -O1 and 100 for -Os, -O2, and -O3.
8499 @item prefetch-latency
8500 Estimate on average number of instructions that are executed before
8501 prefetch finishes. The distance we prefetch ahead is proportional
8502 to this constant. Increasing this number may also lead to less
8503 streams being prefetched (see @option{simultaneous-prefetches}).
8505 @item simultaneous-prefetches
8506 Maximum number of prefetches that can run at the same time.
8508 @item l1-cache-line-size
8509 The size of cache line in L1 cache, in bytes.
8512 The size of L1 cache, in kilobytes.
8515 The size of L2 cache, in kilobytes.
8517 @item min-insn-to-prefetch-ratio
8518 The minimum ratio between the number of instructions and the
8519 number of prefetches to enable prefetching in a loop.
8521 @item prefetch-min-insn-to-mem-ratio
8522 The minimum ratio between the number of instructions and the
8523 number of memory references to enable prefetching in a loop.
8525 @item use-canonical-types
8526 Whether the compiler should use the ``canonical'' type system. By
8527 default, this should always be 1, which uses a more efficient internal
8528 mechanism for comparing types in C++ and Objective-C++. However, if
8529 bugs in the canonical type system are causing compilation failures,
8530 set this value to 0 to disable canonical types.
8532 @item switch-conversion-max-branch-ratio
8533 Switch initialization conversion will refuse to create arrays that are
8534 bigger than @option{switch-conversion-max-branch-ratio} times the number of
8535 branches in the switch.
8537 @item max-partial-antic-length
8538 Maximum length of the partial antic set computed during the tree
8539 partial redundancy elimination optimization (@option{-ftree-pre}) when
8540 optimizing at @option{-O3} and above. For some sorts of source code
8541 the enhanced partial redundancy elimination optimization can run away,
8542 consuming all of the memory available on the host machine. This
8543 parameter sets a limit on the length of the sets that are computed,
8544 which prevents the runaway behavior. Setting a value of 0 for
8545 this parameter will allow an unlimited set length.
8547 @item sccvn-max-scc-size
8548 Maximum size of a strongly connected component (SCC) during SCCVN
8549 processing. If this limit is hit, SCCVN processing for the whole
8550 function will not be done and optimizations depending on it will
8551 be disabled. The default maximum SCC size is 10000.
8553 @item ira-max-loops-num
8554 IRA uses a regional register allocation by default. If a function
8555 contains loops more than number given by the parameter, only at most
8556 given number of the most frequently executed loops will form regions
8557 for the regional register allocation. The default value of the
8560 @item ira-max-conflict-table-size
8561 Although IRA uses a sophisticated algorithm of compression conflict
8562 table, the table can be still big for huge functions. If the conflict
8563 table for a function could be more than size in MB given by the
8564 parameter, the conflict table is not built and faster, simpler, and
8565 lower quality register allocation algorithm will be used. The
8566 algorithm do not use pseudo-register conflicts. The default value of
8567 the parameter is 2000.
8569 @item ira-loop-reserved-regs
8570 IRA can be used to evaluate more accurate register pressure in loops
8571 for decision to move loop invariants (see @option{-O3}). The number
8572 of available registers reserved for some other purposes is described
8573 by this parameter. The default value of the parameter is 2 which is
8574 minimal number of registers needed for execution of typical
8575 instruction. This value is the best found from numerous experiments.
8577 @item loop-invariant-max-bbs-in-loop
8578 Loop invariant motion can be very expensive, both in compile time and
8579 in amount of needed compile time memory, with very large loops. Loops
8580 with more basic blocks than this parameter won't have loop invariant
8581 motion optimization performed on them. The default value of the
8582 parameter is 1000 for -O1 and 10000 for -O2 and above.
8584 @item max-vartrack-size
8585 Sets a maximum number of hash table slots to use during variable
8586 tracking dataflow analysis of any function. If this limit is exceeded
8587 with variable tracking at assignments enabled, analysis for that
8588 function is retried without it, after removing all debug insns from
8589 the function. If the limit is exceeded even without debug insns, var
8590 tracking analysis is completely disabled for the function. Setting
8591 the parameter to zero makes it unlimited.
8593 @item min-nondebug-insn-uid
8594 Use uids starting at this parameter for nondebug insns. The range below
8595 the parameter is reserved exclusively for debug insns created by
8596 @option{-fvar-tracking-assignments}, but debug insns may get
8597 (non-overlapping) uids above it if the reserved range is exhausted.
8599 @item ipa-sra-ptr-growth-factor
8600 IPA-SRA will replace a pointer to an aggregate with one or more new
8601 parameters only when their cumulative size is less or equal to
8602 @option{ipa-sra-ptr-growth-factor} times the size of the original
8605 @item graphite-max-nb-scop-params
8606 To avoid exponential effects in the Graphite loop transforms, the
8607 number of parameters in a Static Control Part (SCoP) is bounded. The
8608 default value is 10 parameters. A variable whose value is unknown at
8609 compile time and defined outside a SCoP is a parameter of the SCoP.
8611 @item graphite-max-bbs-per-function
8612 To avoid exponential effects in the detection of SCoPs, the size of
8613 the functions analyzed by Graphite is bounded. The default value is
8616 @item loop-block-tile-size
8617 Loop blocking or strip mining transforms, enabled with
8618 @option{-floop-block} or @option{-floop-strip-mine}, strip mine each
8619 loop in the loop nest by a given number of iterations. The strip
8620 length can be changed using the @option{loop-block-tile-size}
8621 parameter. The default value is 51 iterations.
8626 @node Preprocessor Options
8627 @section Options Controlling the Preprocessor
8628 @cindex preprocessor options
8629 @cindex options, preprocessor
8631 These options control the C preprocessor, which is run on each C source
8632 file before actual compilation.
8634 If you use the @option{-E} option, nothing is done except preprocessing.
8635 Some of these options make sense only together with @option{-E} because
8636 they cause the preprocessor output to be unsuitable for actual
8640 @item -Wp,@var{option}
8642 You can use @option{-Wp,@var{option}} to bypass the compiler driver
8643 and pass @var{option} directly through to the preprocessor. If
8644 @var{option} contains commas, it is split into multiple options at the
8645 commas. However, many options are modified, translated or interpreted
8646 by the compiler driver before being passed to the preprocessor, and
8647 @option{-Wp} forcibly bypasses this phase. The preprocessor's direct
8648 interface is undocumented and subject to change, so whenever possible
8649 you should avoid using @option{-Wp} and let the driver handle the
8652 @item -Xpreprocessor @var{option}
8653 @opindex Xpreprocessor
8654 Pass @var{option} as an option to the preprocessor. You can use this to
8655 supply system-specific preprocessor options which GCC does not know how to
8658 If you want to pass an option that takes an argument, you must use
8659 @option{-Xpreprocessor} twice, once for the option and once for the argument.
8662 @include cppopts.texi
8664 @node Assembler Options
8665 @section Passing Options to the Assembler
8667 @c prevent bad page break with this line
8668 You can pass options to the assembler.
8671 @item -Wa,@var{option}
8673 Pass @var{option} as an option to the assembler. If @var{option}
8674 contains commas, it is split into multiple options at the commas.
8676 @item -Xassembler @var{option}
8678 Pass @var{option} as an option to the assembler. You can use this to
8679 supply system-specific assembler options which GCC does not know how to
8682 If you want to pass an option that takes an argument, you must use
8683 @option{-Xassembler} twice, once for the option and once for the argument.
8688 @section Options for Linking
8689 @cindex link options
8690 @cindex options, linking
8692 These options come into play when the compiler links object files into
8693 an executable output file. They are meaningless if the compiler is
8694 not doing a link step.
8698 @item @var{object-file-name}
8699 A file name that does not end in a special recognized suffix is
8700 considered to name an object file or library. (Object files are
8701 distinguished from libraries by the linker according to the file
8702 contents.) If linking is done, these object files are used as input
8711 If any of these options is used, then the linker is not run, and
8712 object file names should not be used as arguments. @xref{Overall
8716 @item -l@var{library}
8717 @itemx -l @var{library}
8719 Search the library named @var{library} when linking. (The second
8720 alternative with the library as a separate argument is only for
8721 POSIX compliance and is not recommended.)
8723 It makes a difference where in the command you write this option; the
8724 linker searches and processes libraries and object files in the order they
8725 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
8726 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
8727 to functions in @samp{z}, those functions may not be loaded.
8729 The linker searches a standard list of directories for the library,
8730 which is actually a file named @file{lib@var{library}.a}. The linker
8731 then uses this file as if it had been specified precisely by name.
8733 The directories searched include several standard system directories
8734 plus any that you specify with @option{-L}.
8736 Normally the files found this way are library files---archive files
8737 whose members are object files. The linker handles an archive file by
8738 scanning through it for members which define symbols that have so far
8739 been referenced but not defined. But if the file that is found is an
8740 ordinary object file, it is linked in the usual fashion. The only
8741 difference between using an @option{-l} option and specifying a file name
8742 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
8743 and searches several directories.
8747 You need this special case of the @option{-l} option in order to
8748 link an Objective-C or Objective-C++ program.
8751 @opindex nostartfiles
8752 Do not use the standard system startup files when linking.
8753 The standard system libraries are used normally, unless @option{-nostdlib}
8754 or @option{-nodefaultlibs} is used.
8756 @item -nodefaultlibs
8757 @opindex nodefaultlibs
8758 Do not use the standard system libraries when linking.
8759 Only the libraries you specify will be passed to the linker, options
8760 specifying linkage of the system libraries, such as @code{-static-libgcc}
8761 or @code{-shared-libgcc}, will be ignored.
8762 The standard startup files are used normally, unless @option{-nostartfiles}
8763 is used. The compiler may generate calls to @code{memcmp},
8764 @code{memset}, @code{memcpy} and @code{memmove}.
8765 These entries are usually resolved by entries in
8766 libc. These entry points should be supplied through some other
8767 mechanism when this option is specified.
8771 Do not use the standard system startup files or libraries when linking.
8772 No startup files and only the libraries you specify will be passed to
8773 the linker, options specifying linkage of the system libraries, such as
8774 @code{-static-libgcc} or @code{-shared-libgcc}, will be ignored.
8775 The compiler may generate calls to @code{memcmp}, @code{memset},
8776 @code{memcpy} and @code{memmove}.
8777 These entries are usually resolved by entries in
8778 libc. These entry points should be supplied through some other
8779 mechanism when this option is specified.
8781 @cindex @option{-lgcc}, use with @option{-nostdlib}
8782 @cindex @option{-nostdlib} and unresolved references
8783 @cindex unresolved references and @option{-nostdlib}
8784 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
8785 @cindex @option{-nodefaultlibs} and unresolved references
8786 @cindex unresolved references and @option{-nodefaultlibs}
8787 One of the standard libraries bypassed by @option{-nostdlib} and
8788 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
8789 that GCC uses to overcome shortcomings of particular machines, or special
8790 needs for some languages.
8791 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
8792 Collection (GCC) Internals},
8793 for more discussion of @file{libgcc.a}.)
8794 In most cases, you need @file{libgcc.a} even when you want to avoid
8795 other standard libraries. In other words, when you specify @option{-nostdlib}
8796 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
8797 This ensures that you have no unresolved references to internal GCC
8798 library subroutines. (For example, @samp{__main}, used to ensure C++
8799 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
8800 GNU Compiler Collection (GCC) Internals}.)
8804 Produce a position independent executable on targets which support it.
8805 For predictable results, you must also specify the same set of options
8806 that were used to generate code (@option{-fpie}, @option{-fPIE},
8807 or model suboptions) when you specify this option.
8811 Pass the flag @option{-export-dynamic} to the ELF linker, on targets
8812 that support it. This instructs the linker to add all symbols, not
8813 only used ones, to the dynamic symbol table. This option is needed
8814 for some uses of @code{dlopen} or to allow obtaining backtraces
8815 from within a program.
8819 Remove all symbol table and relocation information from the executable.
8823 On systems that support dynamic linking, this prevents linking with the shared
8824 libraries. On other systems, this option has no effect.
8828 Produce a shared object which can then be linked with other objects to
8829 form an executable. Not all systems support this option. For predictable
8830 results, you must also specify the same set of options that were used to
8831 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
8832 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
8833 needs to build supplementary stub code for constructors to work. On
8834 multi-libbed systems, @samp{gcc -shared} must select the correct support
8835 libraries to link against. Failing to supply the correct flags may lead
8836 to subtle defects. Supplying them in cases where they are not necessary
8839 @item -shared-libgcc
8840 @itemx -static-libgcc
8841 @opindex shared-libgcc
8842 @opindex static-libgcc
8843 On systems that provide @file{libgcc} as a shared library, these options
8844 force the use of either the shared or static version respectively.
8845 If no shared version of @file{libgcc} was built when the compiler was
8846 configured, these options have no effect.
8848 There are several situations in which an application should use the
8849 shared @file{libgcc} instead of the static version. The most common
8850 of these is when the application wishes to throw and catch exceptions
8851 across different shared libraries. In that case, each of the libraries
8852 as well as the application itself should use the shared @file{libgcc}.
8854 Therefore, the G++ and GCJ drivers automatically add
8855 @option{-shared-libgcc} whenever you build a shared library or a main
8856 executable, because C++ and Java programs typically use exceptions, so
8857 this is the right thing to do.
8859 If, instead, you use the GCC driver to create shared libraries, you may
8860 find that they will not always be linked with the shared @file{libgcc}.
8861 If GCC finds, at its configuration time, that you have a non-GNU linker
8862 or a GNU linker that does not support option @option{--eh-frame-hdr},
8863 it will link the shared version of @file{libgcc} into shared libraries
8864 by default. Otherwise, it will take advantage of the linker and optimize
8865 away the linking with the shared version of @file{libgcc}, linking with
8866 the static version of libgcc by default. This allows exceptions to
8867 propagate through such shared libraries, without incurring relocation
8868 costs at library load time.
8870 However, if a library or main executable is supposed to throw or catch
8871 exceptions, you must link it using the G++ or GCJ driver, as appropriate
8872 for the languages used in the program, or using the option
8873 @option{-shared-libgcc}, such that it is linked with the shared
8876 @item -static-libstdc++
8877 When the @command{g++} program is used to link a C++ program, it will
8878 normally automatically link against @option{libstdc++}. If
8879 @file{libstdc++} is available as a shared library, and the
8880 @option{-static} option is not used, then this will link against the
8881 shared version of @file{libstdc++}. That is normally fine. However, it
8882 is sometimes useful to freeze the version of @file{libstdc++} used by
8883 the program without going all the way to a fully static link. The
8884 @option{-static-libstdc++} option directs the @command{g++} driver to
8885 link @file{libstdc++} statically, without necessarily linking other
8886 libraries statically.
8890 Bind references to global symbols when building a shared object. Warn
8891 about any unresolved references (unless overridden by the link editor
8892 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
8895 @item -T @var{script}
8897 @cindex linker script
8898 Use @var{script} as the linker script. This option is supported by most
8899 systems using the GNU linker. On some targets, such as bare-board
8900 targets without an operating system, the @option{-T} option may be required
8901 when linking to avoid references to undefined symbols.
8903 @item -Xlinker @var{option}
8905 Pass @var{option} as an option to the linker. You can use this to
8906 supply system-specific linker options which GCC does not know how to
8909 If you want to pass an option that takes a separate argument, you must use
8910 @option{-Xlinker} twice, once for the option and once for the argument.
8911 For example, to pass @option{-assert definitions}, you must write
8912 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
8913 @option{-Xlinker "-assert definitions"}, because this passes the entire
8914 string as a single argument, which is not what the linker expects.
8916 When using the GNU linker, it is usually more convenient to pass
8917 arguments to linker options using the @option{@var{option}=@var{value}}
8918 syntax than as separate arguments. For example, you can specify
8919 @samp{-Xlinker -Map=output.map} rather than
8920 @samp{-Xlinker -Map -Xlinker output.map}. Other linkers may not support
8921 this syntax for command-line options.
8923 @item -Wl,@var{option}
8925 Pass @var{option} as an option to the linker. If @var{option} contains
8926 commas, it is split into multiple options at the commas. You can use this
8927 syntax to pass an argument to the option.
8928 For example, @samp{-Wl,-Map,output.map} passes @samp{-Map output.map} to the
8929 linker. When using the GNU linker, you can also get the same effect with
8930 @samp{-Wl,-Map=output.map}.
8932 @item -u @var{symbol}
8934 Pretend the symbol @var{symbol} is undefined, to force linking of
8935 library modules to define it. You can use @option{-u} multiple times with
8936 different symbols to force loading of additional library modules.
8939 @node Directory Options
8940 @section Options for Directory Search
8941 @cindex directory options
8942 @cindex options, directory search
8945 These options specify directories to search for header files, for
8946 libraries and for parts of the compiler:
8951 Add the directory @var{dir} to the head of the list of directories to be
8952 searched for header files. This can be used to override a system header
8953 file, substituting your own version, since these directories are
8954 searched before the system header file directories. However, you should
8955 not use this option to add directories that contain vendor-supplied
8956 system header files (use @option{-isystem} for that). If you use more than
8957 one @option{-I} option, the directories are scanned in left-to-right
8958 order; the standard system directories come after.
8960 If a standard system include directory, or a directory specified with
8961 @option{-isystem}, is also specified with @option{-I}, the @option{-I}
8962 option will be ignored. The directory will still be searched but as a
8963 system directory at its normal position in the system include chain.
8964 This is to ensure that GCC's procedure to fix buggy system headers and
8965 the ordering for the include_next directive are not inadvertently changed.
8966 If you really need to change the search order for system directories,
8967 use the @option{-nostdinc} and/or @option{-isystem} options.
8969 @item -iplugindir=@var{dir}
8970 Set the directory to search for plugins which are passed
8971 by @option{-fplugin=@var{name}} instead of
8972 @option{-fplugin=@var{path}/@var{name}.so}. This option is not meant
8973 to be used by the user, but only passed by the driver.
8975 @item -iquote@var{dir}
8977 Add the directory @var{dir} to the head of the list of directories to
8978 be searched for header files only for the case of @samp{#include
8979 "@var{file}"}; they are not searched for @samp{#include <@var{file}>},
8980 otherwise just like @option{-I}.
8984 Add directory @var{dir} to the list of directories to be searched
8987 @item -B@var{prefix}
8989 This option specifies where to find the executables, libraries,
8990 include files, and data files of the compiler itself.
8992 The compiler driver program runs one or more of the subprograms
8993 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
8994 @var{prefix} as a prefix for each program it tries to run, both with and
8995 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
8997 For each subprogram to be run, the compiler driver first tries the
8998 @option{-B} prefix, if any. If that name is not found, or if @option{-B}
8999 was not specified, the driver tries two standard prefixes, which are
9000 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
9001 those results in a file name that is found, the unmodified program
9002 name is searched for using the directories specified in your
9003 @env{PATH} environment variable.
9005 The compiler will check to see if the path provided by the @option{-B}
9006 refers to a directory, and if necessary it will add a directory
9007 separator character at the end of the path.
9009 @option{-B} prefixes that effectively specify directory names also apply
9010 to libraries in the linker, because the compiler translates these
9011 options into @option{-L} options for the linker. They also apply to
9012 includes files in the preprocessor, because the compiler translates these
9013 options into @option{-isystem} options for the preprocessor. In this case,
9014 the compiler appends @samp{include} to the prefix.
9016 The run-time support file @file{libgcc.a} can also be searched for using
9017 the @option{-B} prefix, if needed. If it is not found there, the two
9018 standard prefixes above are tried, and that is all. The file is left
9019 out of the link if it is not found by those means.
9021 Another way to specify a prefix much like the @option{-B} prefix is to use
9022 the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
9025 As a special kludge, if the path provided by @option{-B} is
9026 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
9027 9, then it will be replaced by @file{[dir/]include}. This is to help
9028 with boot-strapping the compiler.
9030 @item -specs=@var{file}
9032 Process @var{file} after the compiler reads in the standard @file{specs}
9033 file, in order to override the defaults that the @file{gcc} driver
9034 program uses when determining what switches to pass to @file{cc1},
9035 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
9036 @option{-specs=@var{file}} can be specified on the command line, and they
9037 are processed in order, from left to right.
9039 @item --sysroot=@var{dir}
9041 Use @var{dir} as the logical root directory for headers and libraries.
9042 For example, if the compiler would normally search for headers in
9043 @file{/usr/include} and libraries in @file{/usr/lib}, it will instead
9044 search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
9046 If you use both this option and the @option{-isysroot} option, then
9047 the @option{--sysroot} option will apply to libraries, but the
9048 @option{-isysroot} option will apply to header files.
9050 The GNU linker (beginning with version 2.16) has the necessary support
9051 for this option. If your linker does not support this option, the
9052 header file aspect of @option{--sysroot} will still work, but the
9053 library aspect will not.
9057 This option has been deprecated. Please use @option{-iquote} instead for
9058 @option{-I} directories before the @option{-I-} and remove the @option{-I-}.
9059 Any directories you specify with @option{-I} options before the @option{-I-}
9060 option are searched only for the case of @samp{#include "@var{file}"};
9061 they are not searched for @samp{#include <@var{file}>}.
9063 If additional directories are specified with @option{-I} options after
9064 the @option{-I-}, these directories are searched for all @samp{#include}
9065 directives. (Ordinarily @emph{all} @option{-I} directories are used
9068 In addition, the @option{-I-} option inhibits the use of the current
9069 directory (where the current input file came from) as the first search
9070 directory for @samp{#include "@var{file}"}. There is no way to
9071 override this effect of @option{-I-}. With @option{-I.} you can specify
9072 searching the directory which was current when the compiler was
9073 invoked. That is not exactly the same as what the preprocessor does
9074 by default, but it is often satisfactory.
9076 @option{-I-} does not inhibit the use of the standard system directories
9077 for header files. Thus, @option{-I-} and @option{-nostdinc} are
9084 @section Specifying subprocesses and the switches to pass to them
9087 @command{gcc} is a driver program. It performs its job by invoking a
9088 sequence of other programs to do the work of compiling, assembling and
9089 linking. GCC interprets its command-line parameters and uses these to
9090 deduce which programs it should invoke, and which command-line options
9091 it ought to place on their command lines. This behavior is controlled
9092 by @dfn{spec strings}. In most cases there is one spec string for each
9093 program that GCC can invoke, but a few programs have multiple spec
9094 strings to control their behavior. The spec strings built into GCC can
9095 be overridden by using the @option{-specs=} command-line switch to specify
9098 @dfn{Spec files} are plaintext files that are used to construct spec
9099 strings. They consist of a sequence of directives separated by blank
9100 lines. The type of directive is determined by the first non-whitespace
9101 character on the line and it can be one of the following:
9104 @item %@var{command}
9105 Issues a @var{command} to the spec file processor. The commands that can
9109 @item %include <@var{file}>
9111 Search for @var{file} and insert its text at the current point in the
9114 @item %include_noerr <@var{file}>
9115 @cindex %include_noerr
9116 Just like @samp{%include}, but do not generate an error message if the include
9117 file cannot be found.
9119 @item %rename @var{old_name} @var{new_name}
9121 Rename the spec string @var{old_name} to @var{new_name}.
9125 @item *[@var{spec_name}]:
9126 This tells the compiler to create, override or delete the named spec
9127 string. All lines after this directive up to the next directive or
9128 blank line are considered to be the text for the spec string. If this
9129 results in an empty string then the spec will be deleted. (Or, if the
9130 spec did not exist, then nothing will happened.) Otherwise, if the spec
9131 does not currently exist a new spec will be created. If the spec does
9132 exist then its contents will be overridden by the text of this
9133 directive, unless the first character of that text is the @samp{+}
9134 character, in which case the text will be appended to the spec.
9136 @item [@var{suffix}]:
9137 Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
9138 and up to the next directive or blank line are considered to make up the
9139 spec string for the indicated suffix. When the compiler encounters an
9140 input file with the named suffix, it will processes the spec string in
9141 order to work out how to compile that file. For example:
9148 This says that any input file whose name ends in @samp{.ZZ} should be
9149 passed to the program @samp{z-compile}, which should be invoked with the
9150 command-line switch @option{-input} and with the result of performing the
9151 @samp{%i} substitution. (See below.)
9153 As an alternative to providing a spec string, the text that follows a
9154 suffix directive can be one of the following:
9157 @item @@@var{language}
9158 This says that the suffix is an alias for a known @var{language}. This is
9159 similar to using the @option{-x} command-line switch to GCC to specify a
9160 language explicitly. For example:
9167 Says that .ZZ files are, in fact, C++ source files.
9170 This causes an error messages saying:
9173 @var{name} compiler not installed on this system.
9177 GCC already has an extensive list of suffixes built into it.
9178 This directive will add an entry to the end of the list of suffixes, but
9179 since the list is searched from the end backwards, it is effectively
9180 possible to override earlier entries using this technique.
9184 GCC has the following spec strings built into it. Spec files can
9185 override these strings or create their own. Note that individual
9186 targets can also add their own spec strings to this list.
9189 asm Options to pass to the assembler
9190 asm_final Options to pass to the assembler post-processor
9191 cpp Options to pass to the C preprocessor
9192 cc1 Options to pass to the C compiler
9193 cc1plus Options to pass to the C++ compiler
9194 endfile Object files to include at the end of the link
9195 link Options to pass to the linker
9196 lib Libraries to include on the command line to the linker
9197 libgcc Decides which GCC support library to pass to the linker
9198 linker Sets the name of the linker
9199 predefines Defines to be passed to the C preprocessor
9200 signed_char Defines to pass to CPP to say whether @code{char} is signed
9202 startfile Object files to include at the start of the link
9205 Here is a small example of a spec file:
9211 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
9214 This example renames the spec called @samp{lib} to @samp{old_lib} and
9215 then overrides the previous definition of @samp{lib} with a new one.
9216 The new definition adds in some extra command-line options before
9217 including the text of the old definition.
9219 @dfn{Spec strings} are a list of command-line options to be passed to their
9220 corresponding program. In addition, the spec strings can contain
9221 @samp{%}-prefixed sequences to substitute variable text or to
9222 conditionally insert text into the command line. Using these constructs
9223 it is possible to generate quite complex command lines.
9225 Here is a table of all defined @samp{%}-sequences for spec
9226 strings. Note that spaces are not generated automatically around the
9227 results of expanding these sequences. Therefore you can concatenate them
9228 together or combine them with constant text in a single argument.
9232 Substitute one @samp{%} into the program name or argument.
9235 Substitute the name of the input file being processed.
9238 Substitute the basename of the input file being processed.
9239 This is the substring up to (and not including) the last period
9240 and not including the directory.
9243 This is the same as @samp{%b}, but include the file suffix (text after
9247 Marks the argument containing or following the @samp{%d} as a
9248 temporary file name, so that that file will be deleted if GCC exits
9249 successfully. Unlike @samp{%g}, this contributes no text to the
9252 @item %g@var{suffix}
9253 Substitute a file name that has suffix @var{suffix} and is chosen
9254 once per compilation, and mark the argument in the same way as
9255 @samp{%d}. To reduce exposure to denial-of-service attacks, the file
9256 name is now chosen in a way that is hard to predict even when previously
9257 chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
9258 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
9259 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
9260 treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
9261 was simply substituted with a file name chosen once per compilation,
9262 without regard to any appended suffix (which was therefore treated
9263 just like ordinary text), making such attacks more likely to succeed.
9265 @item %u@var{suffix}
9266 Like @samp{%g}, but generates a new temporary file name even if
9267 @samp{%u@var{suffix}} was already seen.
9269 @item %U@var{suffix}
9270 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
9271 new one if there is no such last file name. In the absence of any
9272 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
9273 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
9274 would involve the generation of two distinct file names, one
9275 for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
9276 simply substituted with a file name chosen for the previous @samp{%u},
9277 without regard to any appended suffix.
9279 @item %j@var{suffix}
9280 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
9281 writable, and if save-temps is off; otherwise, substitute the name
9282 of a temporary file, just like @samp{%u}. This temporary file is not
9283 meant for communication between processes, but rather as a junk
9286 @item %|@var{suffix}
9287 @itemx %m@var{suffix}
9288 Like @samp{%g}, except if @option{-pipe} is in effect. In that case
9289 @samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
9290 all. These are the two most common ways to instruct a program that it
9291 should read from standard input or write to standard output. If you
9292 need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
9293 construct: see for example @file{f/lang-specs.h}.
9295 @item %.@var{SUFFIX}
9296 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
9297 when it is subsequently output with @samp{%*}. @var{SUFFIX} is
9298 terminated by the next space or %.
9301 Marks the argument containing or following the @samp{%w} as the
9302 designated output file of this compilation. This puts the argument
9303 into the sequence of arguments that @samp{%o} will substitute later.
9306 Substitutes the names of all the output files, with spaces
9307 automatically placed around them. You should write spaces
9308 around the @samp{%o} as well or the results are undefined.
9309 @samp{%o} is for use in the specs for running the linker.
9310 Input files whose names have no recognized suffix are not compiled
9311 at all, but they are included among the output files, so they will
9315 Substitutes the suffix for object files. Note that this is
9316 handled specially when it immediately follows @samp{%g, %u, or %U},
9317 because of the need for those to form complete file names. The
9318 handling is such that @samp{%O} is treated exactly as if it had already
9319 been substituted, except that @samp{%g, %u, and %U} do not currently
9320 support additional @var{suffix} characters following @samp{%O} as they would
9321 following, for example, @samp{.o}.
9324 Substitutes the standard macro predefinitions for the
9325 current target machine. Use this when running @code{cpp}.
9328 Like @samp{%p}, but puts @samp{__} before and after the name of each
9329 predefined macro, except for macros that start with @samp{__} or with
9330 @samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
9334 Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
9335 @option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
9336 @option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
9337 and @option{-imultilib} as necessary.
9340 Current argument is the name of a library or startup file of some sort.
9341 Search for that file in a standard list of directories and substitute
9342 the full name found. The current working directory is included in the
9343 list of directories scanned.
9346 Current argument is the name of a linker script. Search for that file
9347 in the current list of directories to scan for libraries. If the file
9348 is located insert a @option{--script} option into the command line
9349 followed by the full path name found. If the file is not found then
9350 generate an error message. Note: the current working directory is not
9354 Print @var{str} as an error message. @var{str} is terminated by a newline.
9355 Use this when inconsistent options are detected.
9358 Substitute the contents of spec string @var{name} at this point.
9361 Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
9363 @item %x@{@var{option}@}
9364 Accumulate an option for @samp{%X}.
9367 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
9371 Output the accumulated assembler options specified by @option{-Wa}.
9374 Output the accumulated preprocessor options specified by @option{-Wp}.
9377 Process the @code{asm} spec. This is used to compute the
9378 switches to be passed to the assembler.
9381 Process the @code{asm_final} spec. This is a spec string for
9382 passing switches to an assembler post-processor, if such a program is
9386 Process the @code{link} spec. This is the spec for computing the
9387 command line passed to the linker. Typically it will make use of the
9388 @samp{%L %G %S %D and %E} sequences.
9391 Dump out a @option{-L} option for each directory that GCC believes might
9392 contain startup files. If the target supports multilibs then the
9393 current multilib directory will be prepended to each of these paths.
9396 Process the @code{lib} spec. This is a spec string for deciding which
9397 libraries should be included on the command line to the linker.
9400 Process the @code{libgcc} spec. This is a spec string for deciding
9401 which GCC support library should be included on the command line to the linker.
9404 Process the @code{startfile} spec. This is a spec for deciding which
9405 object files should be the first ones passed to the linker. Typically
9406 this might be a file named @file{crt0.o}.
9409 Process the @code{endfile} spec. This is a spec string that specifies
9410 the last object files that will be passed to the linker.
9413 Process the @code{cpp} spec. This is used to construct the arguments
9414 to be passed to the C preprocessor.
9417 Process the @code{cc1} spec. This is used to construct the options to be
9418 passed to the actual C compiler (@samp{cc1}).
9421 Process the @code{cc1plus} spec. This is used to construct the options to be
9422 passed to the actual C++ compiler (@samp{cc1plus}).
9425 Substitute the variable part of a matched option. See below.
9426 Note that each comma in the substituted string is replaced by
9430 Remove all occurrences of @code{-S} from the command line. Note---this
9431 command is position dependent. @samp{%} commands in the spec string
9432 before this one will see @code{-S}, @samp{%} commands in the spec string
9433 after this one will not.
9435 @item %:@var{function}(@var{args})
9436 Call the named function @var{function}, passing it @var{args}.
9437 @var{args} is first processed as a nested spec string, then split
9438 into an argument vector in the usual fashion. The function returns
9439 a string which is processed as if it had appeared literally as part
9440 of the current spec.
9442 The following built-in spec functions are provided:
9446 The @code{getenv} spec function takes two arguments: an environment
9447 variable name and a string. If the environment variable is not
9448 defined, a fatal error is issued. Otherwise, the return value is the
9449 value of the environment variable concatenated with the string. For
9450 example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
9453 %:getenv(TOPDIR /include)
9456 expands to @file{/path/to/top/include}.
9458 @item @code{if-exists}
9459 The @code{if-exists} spec function takes one argument, an absolute
9460 pathname to a file. If the file exists, @code{if-exists} returns the
9461 pathname. Here is a small example of its usage:
9465 crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
9468 @item @code{if-exists-else}
9469 The @code{if-exists-else} spec function is similar to the @code{if-exists}
9470 spec function, except that it takes two arguments. The first argument is
9471 an absolute pathname to a file. If the file exists, @code{if-exists-else}
9472 returns the pathname. If it does not exist, it returns the second argument.
9473 This way, @code{if-exists-else} can be used to select one file or another,
9474 based on the existence of the first. Here is a small example of its usage:
9478 crt0%O%s %:if-exists(crti%O%s) \
9479 %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
9482 @item @code{replace-outfile}
9483 The @code{replace-outfile} spec function takes two arguments. It looks for the
9484 first argument in the outfiles array and replaces it with the second argument. Here
9485 is a small example of its usage:
9488 %@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
9491 @item @code{print-asm-header}
9492 The @code{print-asm-header} function takes no arguments and simply
9493 prints a banner like:
9499 Use "-Wa,OPTION" to pass "OPTION" to the assembler.
9502 It is used to separate compiler options from assembler options
9503 in the @option{--target-help} output.
9507 Substitutes the @code{-S} switch, if that switch was given to GCC@.
9508 If that switch was not specified, this substitutes nothing. Note that
9509 the leading dash is omitted when specifying this option, and it is
9510 automatically inserted if the substitution is performed. Thus the spec
9511 string @samp{%@{foo@}} would match the command-line option @option{-foo}
9512 and would output the command line option @option{-foo}.
9514 @item %W@{@code{S}@}
9515 Like %@{@code{S}@} but mark last argument supplied within as a file to be
9518 @item %@{@code{S}*@}
9519 Substitutes all the switches specified to GCC whose names start
9520 with @code{-S}, but which also take an argument. This is used for
9521 switches like @option{-o}, @option{-D}, @option{-I}, etc.
9522 GCC considers @option{-o foo} as being
9523 one switch whose names starts with @samp{o}. %@{o*@} would substitute this
9524 text, including the space. Thus two arguments would be generated.
9526 @item %@{@code{S}*&@code{T}*@}
9527 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
9528 (the order of @code{S} and @code{T} in the spec is not significant).
9529 There can be any number of ampersand-separated variables; for each the
9530 wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
9532 @item %@{@code{S}:@code{X}@}
9533 Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
9535 @item %@{!@code{S}:@code{X}@}
9536 Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
9538 @item %@{@code{S}*:@code{X}@}
9539 Substitutes @code{X} if one or more switches whose names start with
9540 @code{-S} are specified to GCC@. Normally @code{X} is substituted only
9541 once, no matter how many such switches appeared. However, if @code{%*}
9542 appears somewhere in @code{X}, then @code{X} will be substituted once
9543 for each matching switch, with the @code{%*} replaced by the part of
9544 that switch that matched the @code{*}.
9546 @item %@{.@code{S}:@code{X}@}
9547 Substitutes @code{X}, if processing a file with suffix @code{S}.
9549 @item %@{!.@code{S}:@code{X}@}
9550 Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
9552 @item %@{,@code{S}:@code{X}@}
9553 Substitutes @code{X}, if processing a file for language @code{S}.
9555 @item %@{!,@code{S}:@code{X}@}
9556 Substitutes @code{X}, if not processing a file for language @code{S}.
9558 @item %@{@code{S}|@code{P}:@code{X}@}
9559 Substitutes @code{X} if either @code{-S} or @code{-P} was given to
9560 GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and
9561 @code{*} sequences as well, although they have a stronger binding than
9562 the @samp{|}. If @code{%*} appears in @code{X}, all of the
9563 alternatives must be starred, and only the first matching alternative
9566 For example, a spec string like this:
9569 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
9572 will output the following command-line options from the following input
9573 command-line options:
9578 -d fred.c -foo -baz -boggle
9579 -d jim.d -bar -baz -boggle
9582 @item %@{S:X; T:Y; :D@}
9584 If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
9585 given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
9586 be as many clauses as you need. This may be combined with @code{.},
9587 @code{,}, @code{!}, @code{|}, and @code{*} as needed.
9592 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
9593 construct may contain other nested @samp{%} constructs or spaces, or
9594 even newlines. They are processed as usual, as described above.
9595 Trailing white space in @code{X} is ignored. White space may also
9596 appear anywhere on the left side of the colon in these constructs,
9597 except between @code{.} or @code{*} and the corresponding word.
9599 The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
9600 handled specifically in these constructs. If another value of
9601 @option{-O} or the negated form of a @option{-f}, @option{-m}, or
9602 @option{-W} switch is found later in the command line, the earlier
9603 switch value is ignored, except with @{@code{S}*@} where @code{S} is
9604 just one letter, which passes all matching options.
9606 The character @samp{|} at the beginning of the predicate text is used to
9607 indicate that a command should be piped to the following command, but
9608 only if @option{-pipe} is specified.
9610 It is built into GCC which switches take arguments and which do not.
9611 (You might think it would be useful to generalize this to allow each
9612 compiler's spec to say which switches take arguments. But this cannot
9613 be done in a consistent fashion. GCC cannot even decide which input
9614 files have been specified without knowing which switches take arguments,
9615 and it must know which input files to compile in order to tell which
9618 GCC also knows implicitly that arguments starting in @option{-l} are to be
9619 treated as compiler output files, and passed to the linker in their
9620 proper position among the other output files.
9622 @c man begin OPTIONS
9624 @node Target Options
9625 @section Specifying Target Machine and Compiler Version
9626 @cindex target options
9627 @cindex cross compiling
9628 @cindex specifying machine version
9629 @cindex specifying compiler version and target machine
9630 @cindex compiler version, specifying
9631 @cindex target machine, specifying
9633 The usual way to run GCC is to run the executable called @file{gcc}, or
9634 @file{<machine>-gcc} when cross-compiling, or
9635 @file{<machine>-gcc-<version>} to run a version other than the one that
9638 @node Submodel Options
9639 @section Hardware Models and Configurations
9640 @cindex submodel options
9641 @cindex specifying hardware config
9642 @cindex hardware models and configurations, specifying
9643 @cindex machine dependent options
9645 Each target machine types can have its own
9646 special options, starting with @samp{-m}, to choose among various
9647 hardware models or configurations---for example, 68010 vs 68020,
9648 floating coprocessor or none. A single installed version of the
9649 compiler can compile for any model or configuration, according to the
9652 Some configurations of the compiler also support additional special
9653 options, usually for compatibility with other compilers on the same
9656 @c This list is ordered alphanumerically by subsection name.
9657 @c It should be the same order and spelling as these options are listed
9658 @c in Machine Dependent Options
9664 * Blackfin Options::
9668 * DEC Alpha Options::
9669 * DEC Alpha/VMS Options::
9672 * GNU/Linux Options::
9675 * i386 and x86-64 Options::
9676 * i386 and x86-64 Windows Options::
9678 * IA-64/VMS Options::
9690 * picoChip Options::
9692 * RS/6000 and PowerPC Options::
9694 * S/390 and zSeries Options::
9699 * System V Options::
9704 * Xstormy16 Options::
9710 @subsection ARC Options
9713 These options are defined for ARC implementations:
9718 Compile code for little endian mode. This is the default.
9722 Compile code for big endian mode.
9725 @opindex mmangle-cpu
9726 Prepend the name of the cpu to all public symbol names.
9727 In multiple-processor systems, there are many ARC variants with different
9728 instruction and register set characteristics. This flag prevents code
9729 compiled for one cpu to be linked with code compiled for another.
9730 No facility exists for handling variants that are ``almost identical''.
9731 This is an all or nothing option.
9733 @item -mcpu=@var{cpu}
9735 Compile code for ARC variant @var{cpu}.
9736 Which variants are supported depend on the configuration.
9737 All variants support @option{-mcpu=base}, this is the default.
9739 @item -mtext=@var{text-section}
9740 @itemx -mdata=@var{data-section}
9741 @itemx -mrodata=@var{readonly-data-section}
9745 Put functions, data, and readonly data in @var{text-section},
9746 @var{data-section}, and @var{readonly-data-section} respectively
9747 by default. This can be overridden with the @code{section} attribute.
9748 @xref{Variable Attributes}.
9753 @subsection ARM Options
9756 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
9760 @item -mabi=@var{name}
9762 Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
9763 @samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
9766 @opindex mapcs-frame
9767 Generate a stack frame that is compliant with the ARM Procedure Call
9768 Standard for all functions, even if this is not strictly necessary for
9769 correct execution of the code. Specifying @option{-fomit-frame-pointer}
9770 with this option will cause the stack frames not to be generated for
9771 leaf functions. The default is @option{-mno-apcs-frame}.
9775 This is a synonym for @option{-mapcs-frame}.
9778 @c not currently implemented
9779 @item -mapcs-stack-check
9780 @opindex mapcs-stack-check
9781 Generate code to check the amount of stack space available upon entry to
9782 every function (that actually uses some stack space). If there is
9783 insufficient space available then either the function
9784 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
9785 called, depending upon the amount of stack space required. The run time
9786 system is required to provide these functions. The default is
9787 @option{-mno-apcs-stack-check}, since this produces smaller code.
9789 @c not currently implemented
9791 @opindex mapcs-float
9792 Pass floating point arguments using the float point registers. This is
9793 one of the variants of the APCS@. This option is recommended if the
9794 target hardware has a floating point unit or if a lot of floating point
9795 arithmetic is going to be performed by the code. The default is
9796 @option{-mno-apcs-float}, since integer only code is slightly increased in
9797 size if @option{-mapcs-float} is used.
9799 @c not currently implemented
9800 @item -mapcs-reentrant
9801 @opindex mapcs-reentrant
9802 Generate reentrant, position independent code. The default is
9803 @option{-mno-apcs-reentrant}.
9806 @item -mthumb-interwork
9807 @opindex mthumb-interwork
9808 Generate code which supports calling between the ARM and Thumb
9809 instruction sets. Without this option the two instruction sets cannot
9810 be reliably used inside one program. The default is
9811 @option{-mno-thumb-interwork}, since slightly larger code is generated
9812 when @option{-mthumb-interwork} is specified.
9814 @item -mno-sched-prolog
9815 @opindex mno-sched-prolog
9816 Prevent the reordering of instructions in the function prolog, or the
9817 merging of those instruction with the instructions in the function's
9818 body. This means that all functions will start with a recognizable set
9819 of instructions (or in fact one of a choice from a small set of
9820 different function prologues), and this information can be used to
9821 locate the start if functions inside an executable piece of code. The
9822 default is @option{-msched-prolog}.
9824 @item -mfloat-abi=@var{name}
9826 Specifies which floating-point ABI to use. Permissible values
9827 are: @samp{soft}, @samp{softfp} and @samp{hard}.
9829 Specifying @samp{soft} causes GCC to generate output containing
9830 library calls for floating-point operations.
9831 @samp{softfp} allows the generation of code using hardware floating-point
9832 instructions, but still uses the soft-float calling conventions.
9833 @samp{hard} allows generation of floating-point instructions
9834 and uses FPU-specific calling conventions.
9836 The default depends on the specific target configuration. Note that
9837 the hard-float and soft-float ABIs are not link-compatible; you must
9838 compile your entire program with the same ABI, and link with a
9839 compatible set of libraries.
9842 @opindex mhard-float
9843 Equivalent to @option{-mfloat-abi=hard}.
9846 @opindex msoft-float
9847 Equivalent to @option{-mfloat-abi=soft}.
9849 @item -mlittle-endian
9850 @opindex mlittle-endian
9851 Generate code for a processor running in little-endian mode. This is
9852 the default for all standard configurations.
9855 @opindex mbig-endian
9856 Generate code for a processor running in big-endian mode; the default is
9857 to compile code for a little-endian processor.
9859 @item -mwords-little-endian
9860 @opindex mwords-little-endian
9861 This option only applies when generating code for big-endian processors.
9862 Generate code for a little-endian word order but a big-endian byte
9863 order. That is, a byte order of the form @samp{32107654}. Note: this
9864 option should only be used if you require compatibility with code for
9865 big-endian ARM processors generated by versions of the compiler prior to
9868 @item -mcpu=@var{name}
9870 This specifies the name of the target ARM processor. GCC uses this name
9871 to determine what kind of instructions it can emit when generating
9872 assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
9873 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
9874 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
9875 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
9876 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
9878 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
9879 @samp{arm710t}, @samp{arm720t}, @samp{arm740t},
9880 @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
9881 @samp{strongarm1110},
9882 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
9883 @samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
9884 @samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
9885 @samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
9886 @samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
9887 @samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
9888 @samp{arm1156t2-s}, @samp{arm1156t2f-s}, @samp{arm1176jz-s}, @samp{arm1176jzf-s},
9889 @samp{cortex-a5}, @samp{cortex-a8}, @samp{cortex-a9},
9890 @samp{cortex-r4}, @samp{cortex-r4f}, @samp{cortex-m3},
9893 @samp{xscale}, @samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312}.
9895 @item -mtune=@var{name}
9897 This option is very similar to the @option{-mcpu=} option, except that
9898 instead of specifying the actual target processor type, and hence
9899 restricting which instructions can be used, it specifies that GCC should
9900 tune the performance of the code as if the target were of the type
9901 specified in this option, but still choosing the instructions that it
9902 will generate based on the cpu specified by a @option{-mcpu=} option.
9903 For some ARM implementations better performance can be obtained by using
9906 @item -march=@var{name}
9908 This specifies the name of the target ARM architecture. GCC uses this
9909 name to determine what kind of instructions it can emit when generating
9910 assembly code. This option can be used in conjunction with or instead
9911 of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
9912 @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
9913 @samp{armv5}, @samp{armv5t}, @samp{armv5e}, @samp{armv5te},
9914 @samp{armv6}, @samp{armv6j},
9915 @samp{armv6t2}, @samp{armv6z}, @samp{armv6zk}, @samp{armv6-m},
9916 @samp{armv7}, @samp{armv7-a}, @samp{armv7-r}, @samp{armv7-m},
9917 @samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312}.
9919 @item -mfpu=@var{name}
9920 @itemx -mfpe=@var{number}
9921 @itemx -mfp=@var{number}
9925 This specifies what floating point hardware (or hardware emulation) is
9926 available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
9927 @samp{fpe3}, @samp{maverick}, @samp{vfp}, @samp{vfpv3}, @samp{vfpv3-fp16},
9928 @samp{vfpv3-d16}, @samp{vfpv3-d16-fp16}, @samp{vfpv3xd}, @samp{vfpv3xd-fp16},
9929 @samp{neon}, @samp{neon-fp16}, @samp{vfpv4}, @samp{vfpv4-d16},
9930 @samp{fpv4-sp-d16} and @samp{neon-vfpv4}.
9931 @option{-mfp} and @option{-mfpe} are synonyms for
9932 @option{-mfpu}=@samp{fpe}@var{number}, for compatibility with older versions
9935 If @option{-msoft-float} is specified this specifies the format of
9936 floating point values.
9938 @item -mfp16-format=@var{name}
9939 @opindex mfp16-format
9940 Specify the format of the @code{__fp16} half-precision floating-point type.
9941 Permissible names are @samp{none}, @samp{ieee}, and @samp{alternative};
9942 the default is @samp{none}, in which case the @code{__fp16} type is not
9943 defined. @xref{Half-Precision}, for more information.
9945 @item -mstructure-size-boundary=@var{n}
9946 @opindex mstructure-size-boundary
9947 The size of all structures and unions will be rounded up to a multiple
9948 of the number of bits set by this option. Permissible values are 8, 32
9949 and 64. The default value varies for different toolchains. For the COFF
9950 targeted toolchain the default value is 8. A value of 64 is only allowed
9951 if the underlying ABI supports it.
9953 Specifying the larger number can produce faster, more efficient code, but
9954 can also increase the size of the program. Different values are potentially
9955 incompatible. Code compiled with one value cannot necessarily expect to
9956 work with code or libraries compiled with another value, if they exchange
9957 information using structures or unions.
9959 @item -mabort-on-noreturn
9960 @opindex mabort-on-noreturn
9961 Generate a call to the function @code{abort} at the end of a
9962 @code{noreturn} function. It will be executed if the function tries to
9966 @itemx -mno-long-calls
9967 @opindex mlong-calls
9968 @opindex mno-long-calls
9969 Tells the compiler to perform function calls by first loading the
9970 address of the function into a register and then performing a subroutine
9971 call on this register. This switch is needed if the target function
9972 will lie outside of the 64 megabyte addressing range of the offset based
9973 version of subroutine call instruction.
9975 Even if this switch is enabled, not all function calls will be turned
9976 into long calls. The heuristic is that static functions, functions
9977 which have the @samp{short-call} attribute, functions that are inside
9978 the scope of a @samp{#pragma no_long_calls} directive and functions whose
9979 definitions have already been compiled within the current compilation
9980 unit, will not be turned into long calls. The exception to this rule is
9981 that weak function definitions, functions with the @samp{long-call}
9982 attribute or the @samp{section} attribute, and functions that are within
9983 the scope of a @samp{#pragma long_calls} directive, will always be
9984 turned into long calls.
9986 This feature is not enabled by default. Specifying
9987 @option{-mno-long-calls} will restore the default behavior, as will
9988 placing the function calls within the scope of a @samp{#pragma
9989 long_calls_off} directive. Note these switches have no effect on how
9990 the compiler generates code to handle function calls via function
9993 @item -msingle-pic-base
9994 @opindex msingle-pic-base
9995 Treat the register used for PIC addressing as read-only, rather than
9996 loading it in the prologue for each function. The run-time system is
9997 responsible for initializing this register with an appropriate value
9998 before execution begins.
10000 @item -mpic-register=@var{reg}
10001 @opindex mpic-register
10002 Specify the register to be used for PIC addressing. The default is R10
10003 unless stack-checking is enabled, when R9 is used.
10005 @item -mcirrus-fix-invalid-insns
10006 @opindex mcirrus-fix-invalid-insns
10007 @opindex mno-cirrus-fix-invalid-insns
10008 Insert NOPs into the instruction stream to in order to work around
10009 problems with invalid Maverick instruction combinations. This option
10010 is only valid if the @option{-mcpu=ep9312} option has been used to
10011 enable generation of instructions for the Cirrus Maverick floating
10012 point co-processor. This option is not enabled by default, since the
10013 problem is only present in older Maverick implementations. The default
10014 can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
10017 @item -mpoke-function-name
10018 @opindex mpoke-function-name
10019 Write the name of each function into the text section, directly
10020 preceding the function prologue. The generated code is similar to this:
10024 .ascii "arm_poke_function_name", 0
10027 .word 0xff000000 + (t1 - t0)
10028 arm_poke_function_name
10030 stmfd sp!, @{fp, ip, lr, pc@}
10034 When performing a stack backtrace, code can inspect the value of
10035 @code{pc} stored at @code{fp + 0}. If the trace function then looks at
10036 location @code{pc - 12} and the top 8 bits are set, then we know that
10037 there is a function name embedded immediately preceding this location
10038 and has length @code{((pc[-3]) & 0xff000000)}.
10042 Generate code for the Thumb instruction set. The default is to
10043 use the 32-bit ARM instruction set.
10044 This option automatically enables either 16-bit Thumb-1 or
10045 mixed 16/32-bit Thumb-2 instructions based on the @option{-mcpu=@var{name}}
10046 and @option{-march=@var{name}} options. This option is not passed to the
10047 assembler. If you want to force assembler files to be interpreted as Thumb code,
10048 either add a @samp{.thumb} directive to the source or pass the @option{-mthumb}
10049 option directly to the assembler by prefixing it with @option{-Wa}.
10052 @opindex mtpcs-frame
10053 Generate a stack frame that is compliant with the Thumb Procedure Call
10054 Standard for all non-leaf functions. (A leaf function is one that does
10055 not call any other functions.) The default is @option{-mno-tpcs-frame}.
10057 @item -mtpcs-leaf-frame
10058 @opindex mtpcs-leaf-frame
10059 Generate a stack frame that is compliant with the Thumb Procedure Call
10060 Standard for all leaf functions. (A leaf function is one that does
10061 not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
10063 @item -mcallee-super-interworking
10064 @opindex mcallee-super-interworking
10065 Gives all externally visible functions in the file being compiled an ARM
10066 instruction set header which switches to Thumb mode before executing the
10067 rest of the function. This allows these functions to be called from
10068 non-interworking code. This option is not valid in AAPCS configurations
10069 because interworking is enabled by default.
10071 @item -mcaller-super-interworking
10072 @opindex mcaller-super-interworking
10073 Allows calls via function pointers (including virtual functions) to
10074 execute correctly regardless of whether the target code has been
10075 compiled for interworking or not. There is a small overhead in the cost
10076 of executing a function pointer if this option is enabled. This option
10077 is not valid in AAPCS configurations because interworking is enabled
10080 @item -mtp=@var{name}
10082 Specify the access model for the thread local storage pointer. The valid
10083 models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
10084 @option{cp15}, which fetches the thread pointer from @code{cp15} directly
10085 (supported in the arm6k architecture), and @option{auto}, which uses the
10086 best available method for the selected processor. The default setting is
10089 @item -mword-relocations
10090 @opindex mword-relocations
10091 Only generate absolute relocations on word sized values (i.e. R_ARM_ABS32).
10092 This is enabled by default on targets (uClinux, SymbianOS) where the runtime
10093 loader imposes this restriction, and when @option{-fpic} or @option{-fPIC}
10096 @item -mfix-cortex-m3-ldrd
10097 @opindex mfix-cortex-m3-ldrd
10098 Some Cortex-M3 cores can cause data corruption when @code{ldrd} instructions
10099 with overlapping destination and base registers are used. This option avoids
10100 generating these instructions. This option is enabled by default when
10101 @option{-mcpu=cortex-m3} is specified.
10106 @subsection AVR Options
10107 @cindex AVR Options
10109 These options are defined for AVR implementations:
10112 @item -mmcu=@var{mcu}
10114 Specify ATMEL AVR instruction set or MCU type.
10116 Instruction set avr1 is for the minimal AVR core, not supported by the C
10117 compiler, only for assembler programs (MCU types: at90s1200, attiny10,
10118 attiny11, attiny12, attiny15, attiny28).
10120 Instruction set avr2 (default) is for the classic AVR core with up to
10121 8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
10122 at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
10123 at90c8534, at90s8535).
10125 Instruction set avr3 is for the classic AVR core with up to 128K program
10126 memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
10128 Instruction set avr4 is for the enhanced AVR core with up to 8K program
10129 memory space (MCU types: atmega8, atmega83, atmega85).
10131 Instruction set avr5 is for the enhanced AVR core with up to 128K program
10132 memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
10133 atmega64, atmega128, at43usb355, at94k).
10135 @item -mno-interrupts
10136 @opindex mno-interrupts
10137 Generated code is not compatible with hardware interrupts.
10138 Code size will be smaller.
10140 @item -mcall-prologues
10141 @opindex mcall-prologues
10142 Functions prologues/epilogues expanded as call to appropriate
10143 subroutines. Code size will be smaller.
10146 @opindex mtiny-stack
10147 Change only the low 8 bits of the stack pointer.
10151 Assume int to be 8 bit integer. This affects the sizes of all types: A
10152 char will be 1 byte, an int will be 1 byte, a long will be 2 bytes
10153 and long long will be 4 bytes. Please note that this option does not
10154 comply to the C standards, but it will provide you with smaller code
10158 @node Blackfin Options
10159 @subsection Blackfin Options
10160 @cindex Blackfin Options
10163 @item -mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]}
10165 Specifies the name of the target Blackfin processor. Currently, @var{cpu}
10166 can be one of @samp{bf512}, @samp{bf514}, @samp{bf516}, @samp{bf518},
10167 @samp{bf522}, @samp{bf523}, @samp{bf524}, @samp{bf525}, @samp{bf526},
10168 @samp{bf527}, @samp{bf531}, @samp{bf532}, @samp{bf533},
10169 @samp{bf534}, @samp{bf536}, @samp{bf537}, @samp{bf538}, @samp{bf539},
10170 @samp{bf542}, @samp{bf544}, @samp{bf547}, @samp{bf548}, @samp{bf549},
10171 @samp{bf542m}, @samp{bf544m}, @samp{bf547m}, @samp{bf548m}, @samp{bf549m},
10173 The optional @var{sirevision} specifies the silicon revision of the target
10174 Blackfin processor. Any workarounds available for the targeted silicon revision
10175 will be enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled.
10176 If @var{sirevision} is @samp{any}, all workarounds for the targeted processor
10177 will be enabled. The @code{__SILICON_REVISION__} macro is defined to two
10178 hexadecimal digits representing the major and minor numbers in the silicon
10179 revision. If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__}
10180 is not defined. If @var{sirevision} is @samp{any}, the
10181 @code{__SILICON_REVISION__} is defined to be @code{0xffff}.
10182 If this optional @var{sirevision} is not used, GCC assumes the latest known
10183 silicon revision of the targeted Blackfin processor.
10185 Support for @samp{bf561} is incomplete. For @samp{bf561},
10186 Only the processor macro is defined.
10187 Without this option, @samp{bf532} is used as the processor by default.
10188 The corresponding predefined processor macros for @var{cpu} is to
10189 be defined. And for @samp{bfin-elf} toolchain, this causes the hardware BSP
10190 provided by libgloss to be linked in if @option{-msim} is not given.
10194 Specifies that the program will be run on the simulator. This causes
10195 the simulator BSP provided by libgloss to be linked in. This option
10196 has effect only for @samp{bfin-elf} toolchain.
10197 Certain other options, such as @option{-mid-shared-library} and
10198 @option{-mfdpic}, imply @option{-msim}.
10200 @item -momit-leaf-frame-pointer
10201 @opindex momit-leaf-frame-pointer
10202 Don't keep the frame pointer in a register for leaf functions. This
10203 avoids the instructions to save, set up and restore frame pointers and
10204 makes an extra register available in leaf functions. The option
10205 @option{-fomit-frame-pointer} removes the frame pointer for all functions
10206 which might make debugging harder.
10208 @item -mspecld-anomaly
10209 @opindex mspecld-anomaly
10210 When enabled, the compiler will ensure that the generated code does not
10211 contain speculative loads after jump instructions. If this option is used,
10212 @code{__WORKAROUND_SPECULATIVE_LOADS} is defined.
10214 @item -mno-specld-anomaly
10215 @opindex mno-specld-anomaly
10216 Don't generate extra code to prevent speculative loads from occurring.
10218 @item -mcsync-anomaly
10219 @opindex mcsync-anomaly
10220 When enabled, the compiler will ensure that the generated code does not
10221 contain CSYNC or SSYNC instructions too soon after conditional branches.
10222 If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined.
10224 @item -mno-csync-anomaly
10225 @opindex mno-csync-anomaly
10226 Don't generate extra code to prevent CSYNC or SSYNC instructions from
10227 occurring too soon after a conditional branch.
10231 When enabled, the compiler is free to take advantage of the knowledge that
10232 the entire program fits into the low 64k of memory.
10235 @opindex mno-low-64k
10236 Assume that the program is arbitrarily large. This is the default.
10238 @item -mstack-check-l1
10239 @opindex mstack-check-l1
10240 Do stack checking using information placed into L1 scratchpad memory by the
10243 @item -mid-shared-library
10244 @opindex mid-shared-library
10245 Generate code that supports shared libraries via the library ID method.
10246 This allows for execute in place and shared libraries in an environment
10247 without virtual memory management. This option implies @option{-fPIC}.
10248 With a @samp{bfin-elf} target, this option implies @option{-msim}.
10250 @item -mno-id-shared-library
10251 @opindex mno-id-shared-library
10252 Generate code that doesn't assume ID based shared libraries are being used.
10253 This is the default.
10255 @item -mleaf-id-shared-library
10256 @opindex mleaf-id-shared-library
10257 Generate code that supports shared libraries via the library ID method,
10258 but assumes that this library or executable won't link against any other
10259 ID shared libraries. That allows the compiler to use faster code for jumps
10262 @item -mno-leaf-id-shared-library
10263 @opindex mno-leaf-id-shared-library
10264 Do not assume that the code being compiled won't link against any ID shared
10265 libraries. Slower code will be generated for jump and call insns.
10267 @item -mshared-library-id=n
10268 @opindex mshared-library-id
10269 Specified the identification number of the ID based shared library being
10270 compiled. Specifying a value of 0 will generate more compact code, specifying
10271 other values will force the allocation of that number to the current
10272 library but is no more space or time efficient than omitting this option.
10276 Generate code that allows the data segment to be located in a different
10277 area of memory from the text segment. This allows for execute in place in
10278 an environment without virtual memory management by eliminating relocations
10279 against the text section.
10281 @item -mno-sep-data
10282 @opindex mno-sep-data
10283 Generate code that assumes that the data segment follows the text segment.
10284 This is the default.
10287 @itemx -mno-long-calls
10288 @opindex mlong-calls
10289 @opindex mno-long-calls
10290 Tells the compiler to perform function calls by first loading the
10291 address of the function into a register and then performing a subroutine
10292 call on this register. This switch is needed if the target function
10293 will lie outside of the 24 bit addressing range of the offset based
10294 version of subroutine call instruction.
10296 This feature is not enabled by default. Specifying
10297 @option{-mno-long-calls} will restore the default behavior. Note these
10298 switches have no effect on how the compiler generates code to handle
10299 function calls via function pointers.
10303 Link with the fast floating-point library. This library relaxes some of
10304 the IEEE floating-point standard's rules for checking inputs against
10305 Not-a-Number (NAN), in the interest of performance.
10308 @opindex minline-plt
10309 Enable inlining of PLT entries in function calls to functions that are
10310 not known to bind locally. It has no effect without @option{-mfdpic}.
10313 @opindex mmulticore
10314 Build standalone application for multicore Blackfin processor. Proper
10315 start files and link scripts will be used to support multicore.
10316 This option defines @code{__BFIN_MULTICORE}. It can only be used with
10317 @option{-mcpu=bf561@r{[}-@var{sirevision}@r{]}}. It can be used with
10318 @option{-mcorea} or @option{-mcoreb}. If it's used without
10319 @option{-mcorea} or @option{-mcoreb}, single application/dual core
10320 programming model is used. In this model, the main function of Core B
10321 should be named as coreb_main. If it's used with @option{-mcorea} or
10322 @option{-mcoreb}, one application per core programming model is used.
10323 If this option is not used, single core application programming
10328 Build standalone application for Core A of BF561 when using
10329 one application per core programming model. Proper start files
10330 and link scripts will be used to support Core A. This option
10331 defines @code{__BFIN_COREA}. It must be used with @option{-mmulticore}.
10335 Build standalone application for Core B of BF561 when using
10336 one application per core programming model. Proper start files
10337 and link scripts will be used to support Core B. This option
10338 defines @code{__BFIN_COREB}. When this option is used, coreb_main
10339 should be used instead of main. It must be used with
10340 @option{-mmulticore}.
10344 Build standalone application for SDRAM. Proper start files and
10345 link scripts will be used to put the application into SDRAM.
10346 Loader should initialize SDRAM before loading the application
10347 into SDRAM. This option defines @code{__BFIN_SDRAM}.
10351 Assume that ICPLBs are enabled at runtime. This has an effect on certain
10352 anomaly workarounds. For Linux targets, the default is to assume ICPLBs
10353 are enabled; for standalone applications the default is off.
10357 @subsection CRIS Options
10358 @cindex CRIS Options
10360 These options are defined specifically for the CRIS ports.
10363 @item -march=@var{architecture-type}
10364 @itemx -mcpu=@var{architecture-type}
10367 Generate code for the specified architecture. The choices for
10368 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
10369 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
10370 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
10373 @item -mtune=@var{architecture-type}
10375 Tune to @var{architecture-type} everything applicable about the generated
10376 code, except for the ABI and the set of available instructions. The
10377 choices for @var{architecture-type} are the same as for
10378 @option{-march=@var{architecture-type}}.
10380 @item -mmax-stack-frame=@var{n}
10381 @opindex mmax-stack-frame
10382 Warn when the stack frame of a function exceeds @var{n} bytes.
10388 The options @option{-metrax4} and @option{-metrax100} are synonyms for
10389 @option{-march=v3} and @option{-march=v8} respectively.
10391 @item -mmul-bug-workaround
10392 @itemx -mno-mul-bug-workaround
10393 @opindex mmul-bug-workaround
10394 @opindex mno-mul-bug-workaround
10395 Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
10396 models where it applies. This option is active by default.
10400 Enable CRIS-specific verbose debug-related information in the assembly
10401 code. This option also has the effect to turn off the @samp{#NO_APP}
10402 formatted-code indicator to the assembler at the beginning of the
10407 Do not use condition-code results from previous instruction; always emit
10408 compare and test instructions before use of condition codes.
10410 @item -mno-side-effects
10411 @opindex mno-side-effects
10412 Do not emit instructions with side-effects in addressing modes other than
10415 @item -mstack-align
10416 @itemx -mno-stack-align
10417 @itemx -mdata-align
10418 @itemx -mno-data-align
10419 @itemx -mconst-align
10420 @itemx -mno-const-align
10421 @opindex mstack-align
10422 @opindex mno-stack-align
10423 @opindex mdata-align
10424 @opindex mno-data-align
10425 @opindex mconst-align
10426 @opindex mno-const-align
10427 These options (no-options) arranges (eliminate arrangements) for the
10428 stack-frame, individual data and constants to be aligned for the maximum
10429 single data access size for the chosen CPU model. The default is to
10430 arrange for 32-bit alignment. ABI details such as structure layout are
10431 not affected by these options.
10439 Similar to the stack- data- and const-align options above, these options
10440 arrange for stack-frame, writable data and constants to all be 32-bit,
10441 16-bit or 8-bit aligned. The default is 32-bit alignment.
10443 @item -mno-prologue-epilogue
10444 @itemx -mprologue-epilogue
10445 @opindex mno-prologue-epilogue
10446 @opindex mprologue-epilogue
10447 With @option{-mno-prologue-epilogue}, the normal function prologue and
10448 epilogue that sets up the stack-frame are omitted and no return
10449 instructions or return sequences are generated in the code. Use this
10450 option only together with visual inspection of the compiled code: no
10451 warnings or errors are generated when call-saved registers must be saved,
10452 or storage for local variable needs to be allocated.
10456 @opindex mno-gotplt
10458 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
10459 instruction sequences that load addresses for functions from the PLT part
10460 of the GOT rather than (traditional on other architectures) calls to the
10461 PLT@. The default is @option{-mgotplt}.
10465 Legacy no-op option only recognized with the cris-axis-elf and
10466 cris-axis-linux-gnu targets.
10470 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
10474 This option, recognized for the cris-axis-elf arranges
10475 to link with input-output functions from a simulator library. Code,
10476 initialized data and zero-initialized data are allocated consecutively.
10480 Like @option{-sim}, but pass linker options to locate initialized data at
10481 0x40000000 and zero-initialized data at 0x80000000.
10485 @subsection CRX Options
10486 @cindex CRX Options
10488 These options are defined specifically for the CRX ports.
10494 Enable the use of multiply-accumulate instructions. Disabled by default.
10497 @opindex mpush-args
10498 Push instructions will be used to pass outgoing arguments when functions
10499 are called. Enabled by default.
10502 @node Darwin Options
10503 @subsection Darwin Options
10504 @cindex Darwin options
10506 These options are defined for all architectures running the Darwin operating
10509 FSF GCC on Darwin does not create ``fat'' object files; it will create
10510 an object file for the single architecture that it was built to
10511 target. Apple's GCC on Darwin does create ``fat'' files if multiple
10512 @option{-arch} options are used; it does so by running the compiler or
10513 linker multiple times and joining the results together with
10516 The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
10517 @samp{i686}) is determined by the flags that specify the ISA
10518 that GCC is targetting, like @option{-mcpu} or @option{-march}. The
10519 @option{-force_cpusubtype_ALL} option can be used to override this.
10521 The Darwin tools vary in their behavior when presented with an ISA
10522 mismatch. The assembler, @file{as}, will only permit instructions to
10523 be used that are valid for the subtype of the file it is generating,
10524 so you cannot put 64-bit instructions in a @samp{ppc750} object file.
10525 The linker for shared libraries, @file{/usr/bin/libtool}, will fail
10526 and print an error if asked to create a shared library with a less
10527 restrictive subtype than its input files (for instance, trying to put
10528 a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
10529 for executables, @file{ld}, will quietly give the executable the most
10530 restrictive subtype of any of its input files.
10535 Add the framework directory @var{dir} to the head of the list of
10536 directories to be searched for header files. These directories are
10537 interleaved with those specified by @option{-I} options and are
10538 scanned in a left-to-right order.
10540 A framework directory is a directory with frameworks in it. A
10541 framework is a directory with a @samp{"Headers"} and/or
10542 @samp{"PrivateHeaders"} directory contained directly in it that ends
10543 in @samp{".framework"}. The name of a framework is the name of this
10544 directory excluding the @samp{".framework"}. Headers associated with
10545 the framework are found in one of those two directories, with
10546 @samp{"Headers"} being searched first. A subframework is a framework
10547 directory that is in a framework's @samp{"Frameworks"} directory.
10548 Includes of subframework headers can only appear in a header of a
10549 framework that contains the subframework, or in a sibling subframework
10550 header. Two subframeworks are siblings if they occur in the same
10551 framework. A subframework should not have the same name as a
10552 framework, a warning will be issued if this is violated. Currently a
10553 subframework cannot have subframeworks, in the future, the mechanism
10554 may be extended to support this. The standard frameworks can be found
10555 in @samp{"/System/Library/Frameworks"} and
10556 @samp{"/Library/Frameworks"}. An example include looks like
10557 @code{#include <Framework/header.h>}, where @samp{Framework} denotes
10558 the name of the framework and header.h is found in the
10559 @samp{"PrivateHeaders"} or @samp{"Headers"} directory.
10561 @item -iframework@var{dir}
10562 @opindex iframework
10563 Like @option{-F} except the directory is a treated as a system
10564 directory. The main difference between this @option{-iframework} and
10565 @option{-F} is that with @option{-iframework} the compiler does not
10566 warn about constructs contained within header files found via
10567 @var{dir}. This option is valid only for the C family of languages.
10571 Emit debugging information for symbols that are used. For STABS
10572 debugging format, this enables @option{-feliminate-unused-debug-symbols}.
10573 This is by default ON@.
10577 Emit debugging information for all symbols and types.
10579 @item -mmacosx-version-min=@var{version}
10580 The earliest version of MacOS X that this executable will run on
10581 is @var{version}. Typical values of @var{version} include @code{10.1},
10582 @code{10.2}, and @code{10.3.9}.
10584 If the compiler was built to use the system's headers by default,
10585 then the default for this option is the system version on which the
10586 compiler is running, otherwise the default is to make choices which
10587 are compatible with as many systems and code bases as possible.
10591 Enable kernel development mode. The @option{-mkernel} option sets
10592 @option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
10593 @option{-fno-exceptions}, @option{-fno-non-call-exceptions},
10594 @option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
10595 applicable. This mode also sets @option{-mno-altivec},
10596 @option{-msoft-float}, @option{-fno-builtin} and
10597 @option{-mlong-branch} for PowerPC targets.
10599 @item -mone-byte-bool
10600 @opindex mone-byte-bool
10601 Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
10602 By default @samp{sizeof(bool)} is @samp{4} when compiling for
10603 Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
10604 option has no effect on x86.
10606 @strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
10607 to generate code that is not binary compatible with code generated
10608 without that switch. Using this switch may require recompiling all
10609 other modules in a program, including system libraries. Use this
10610 switch to conform to a non-default data model.
10612 @item -mfix-and-continue
10613 @itemx -ffix-and-continue
10614 @itemx -findirect-data
10615 @opindex mfix-and-continue
10616 @opindex ffix-and-continue
10617 @opindex findirect-data
10618 Generate code suitable for fast turn around development. Needed to
10619 enable gdb to dynamically load @code{.o} files into already running
10620 programs. @option{-findirect-data} and @option{-ffix-and-continue}
10621 are provided for backwards compatibility.
10625 Loads all members of static archive libraries.
10626 See man ld(1) for more information.
10628 @item -arch_errors_fatal
10629 @opindex arch_errors_fatal
10630 Cause the errors having to do with files that have the wrong architecture
10633 @item -bind_at_load
10634 @opindex bind_at_load
10635 Causes the output file to be marked such that the dynamic linker will
10636 bind all undefined references when the file is loaded or launched.
10640 Produce a Mach-o bundle format file.
10641 See man ld(1) for more information.
10643 @item -bundle_loader @var{executable}
10644 @opindex bundle_loader
10645 This option specifies the @var{executable} that will be loading the build
10646 output file being linked. See man ld(1) for more information.
10649 @opindex dynamiclib
10650 When passed this option, GCC will produce a dynamic library instead of
10651 an executable when linking, using the Darwin @file{libtool} command.
10653 @item -force_cpusubtype_ALL
10654 @opindex force_cpusubtype_ALL
10655 This causes GCC's output file to have the @var{ALL} subtype, instead of
10656 one controlled by the @option{-mcpu} or @option{-march} option.
10658 @item -allowable_client @var{client_name}
10659 @itemx -client_name
10660 @itemx -compatibility_version
10661 @itemx -current_version
10663 @itemx -dependency-file
10665 @itemx -dylinker_install_name
10667 @itemx -exported_symbols_list
10669 @itemx -flat_namespace
10670 @itemx -force_flat_namespace
10671 @itemx -headerpad_max_install_names
10674 @itemx -install_name
10675 @itemx -keep_private_externs
10676 @itemx -multi_module
10677 @itemx -multiply_defined
10678 @itemx -multiply_defined_unused
10680 @itemx -no_dead_strip_inits_and_terms
10681 @itemx -nofixprebinding
10682 @itemx -nomultidefs
10684 @itemx -noseglinkedit
10685 @itemx -pagezero_size
10687 @itemx -prebind_all_twolevel_modules
10688 @itemx -private_bundle
10689 @itemx -read_only_relocs
10691 @itemx -sectobjectsymbols
10695 @itemx -sectobjectsymbols
10698 @itemx -segs_read_only_addr
10699 @itemx -segs_read_write_addr
10700 @itemx -seg_addr_table
10701 @itemx -seg_addr_table_filename
10702 @itemx -seglinkedit
10704 @itemx -segs_read_only_addr
10705 @itemx -segs_read_write_addr
10706 @itemx -single_module
10708 @itemx -sub_library
10709 @itemx -sub_umbrella
10710 @itemx -twolevel_namespace
10713 @itemx -unexported_symbols_list
10714 @itemx -weak_reference_mismatches
10715 @itemx -whatsloaded
10716 @opindex allowable_client
10717 @opindex client_name
10718 @opindex compatibility_version
10719 @opindex current_version
10720 @opindex dead_strip
10721 @opindex dependency-file
10722 @opindex dylib_file
10723 @opindex dylinker_install_name
10725 @opindex exported_symbols_list
10727 @opindex flat_namespace
10728 @opindex force_flat_namespace
10729 @opindex headerpad_max_install_names
10730 @opindex image_base
10732 @opindex install_name
10733 @opindex keep_private_externs
10734 @opindex multi_module
10735 @opindex multiply_defined
10736 @opindex multiply_defined_unused
10737 @opindex noall_load
10738 @opindex no_dead_strip_inits_and_terms
10739 @opindex nofixprebinding
10740 @opindex nomultidefs
10742 @opindex noseglinkedit
10743 @opindex pagezero_size
10745 @opindex prebind_all_twolevel_modules
10746 @opindex private_bundle
10747 @opindex read_only_relocs
10749 @opindex sectobjectsymbols
10752 @opindex sectcreate
10753 @opindex sectobjectsymbols
10756 @opindex segs_read_only_addr
10757 @opindex segs_read_write_addr
10758 @opindex seg_addr_table
10759 @opindex seg_addr_table_filename
10760 @opindex seglinkedit
10762 @opindex segs_read_only_addr
10763 @opindex segs_read_write_addr
10764 @opindex single_module
10766 @opindex sub_library
10767 @opindex sub_umbrella
10768 @opindex twolevel_namespace
10771 @opindex unexported_symbols_list
10772 @opindex weak_reference_mismatches
10773 @opindex whatsloaded
10774 These options are passed to the Darwin linker. The Darwin linker man page
10775 describes them in detail.
10778 @node DEC Alpha Options
10779 @subsection DEC Alpha Options
10781 These @samp{-m} options are defined for the DEC Alpha implementations:
10784 @item -mno-soft-float
10785 @itemx -msoft-float
10786 @opindex mno-soft-float
10787 @opindex msoft-float
10788 Use (do not use) the hardware floating-point instructions for
10789 floating-point operations. When @option{-msoft-float} is specified,
10790 functions in @file{libgcc.a} will be used to perform floating-point
10791 operations. Unless they are replaced by routines that emulate the
10792 floating-point operations, or compiled in such a way as to call such
10793 emulations routines, these routines will issue floating-point
10794 operations. If you are compiling for an Alpha without floating-point
10795 operations, you must ensure that the library is built so as not to call
10798 Note that Alpha implementations without floating-point operations are
10799 required to have floating-point registers.
10802 @itemx -mno-fp-regs
10804 @opindex mno-fp-regs
10805 Generate code that uses (does not use) the floating-point register set.
10806 @option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
10807 register set is not used, floating point operands are passed in integer
10808 registers as if they were integers and floating-point results are passed
10809 in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
10810 so any function with a floating-point argument or return value called by code
10811 compiled with @option{-mno-fp-regs} must also be compiled with that
10814 A typical use of this option is building a kernel that does not use,
10815 and hence need not save and restore, any floating-point registers.
10819 The Alpha architecture implements floating-point hardware optimized for
10820 maximum performance. It is mostly compliant with the IEEE floating
10821 point standard. However, for full compliance, software assistance is
10822 required. This option generates code fully IEEE compliant code
10823 @emph{except} that the @var{inexact-flag} is not maintained (see below).
10824 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
10825 defined during compilation. The resulting code is less efficient but is
10826 able to correctly support denormalized numbers and exceptional IEEE
10827 values such as not-a-number and plus/minus infinity. Other Alpha
10828 compilers call this option @option{-ieee_with_no_inexact}.
10830 @item -mieee-with-inexact
10831 @opindex mieee-with-inexact
10832 This is like @option{-mieee} except the generated code also maintains
10833 the IEEE @var{inexact-flag}. Turning on this option causes the
10834 generated code to implement fully-compliant IEEE math. In addition to
10835 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
10836 macro. On some Alpha implementations the resulting code may execute
10837 significantly slower than the code generated by default. Since there is
10838 very little code that depends on the @var{inexact-flag}, you should
10839 normally not specify this option. Other Alpha compilers call this
10840 option @option{-ieee_with_inexact}.
10842 @item -mfp-trap-mode=@var{trap-mode}
10843 @opindex mfp-trap-mode
10844 This option controls what floating-point related traps are enabled.
10845 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
10846 The trap mode can be set to one of four values:
10850 This is the default (normal) setting. The only traps that are enabled
10851 are the ones that cannot be disabled in software (e.g., division by zero
10855 In addition to the traps enabled by @samp{n}, underflow traps are enabled
10859 Like @samp{u}, but the instructions are marked to be safe for software
10860 completion (see Alpha architecture manual for details).
10863 Like @samp{su}, but inexact traps are enabled as well.
10866 @item -mfp-rounding-mode=@var{rounding-mode}
10867 @opindex mfp-rounding-mode
10868 Selects the IEEE rounding mode. Other Alpha compilers call this option
10869 @option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
10874 Normal IEEE rounding mode. Floating point numbers are rounded towards
10875 the nearest machine number or towards the even machine number in case
10879 Round towards minus infinity.
10882 Chopped rounding mode. Floating point numbers are rounded towards zero.
10885 Dynamic rounding mode. A field in the floating point control register
10886 (@var{fpcr}, see Alpha architecture reference manual) controls the
10887 rounding mode in effect. The C library initializes this register for
10888 rounding towards plus infinity. Thus, unless your program modifies the
10889 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
10892 @item -mtrap-precision=@var{trap-precision}
10893 @opindex mtrap-precision
10894 In the Alpha architecture, floating point traps are imprecise. This
10895 means without software assistance it is impossible to recover from a
10896 floating trap and program execution normally needs to be terminated.
10897 GCC can generate code that can assist operating system trap handlers
10898 in determining the exact location that caused a floating point trap.
10899 Depending on the requirements of an application, different levels of
10900 precisions can be selected:
10904 Program precision. This option is the default and means a trap handler
10905 can only identify which program caused a floating point exception.
10908 Function precision. The trap handler can determine the function that
10909 caused a floating point exception.
10912 Instruction precision. The trap handler can determine the exact
10913 instruction that caused a floating point exception.
10916 Other Alpha compilers provide the equivalent options called
10917 @option{-scope_safe} and @option{-resumption_safe}.
10919 @item -mieee-conformant
10920 @opindex mieee-conformant
10921 This option marks the generated code as IEEE conformant. You must not
10922 use this option unless you also specify @option{-mtrap-precision=i} and either
10923 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
10924 is to emit the line @samp{.eflag 48} in the function prologue of the
10925 generated assembly file. Under DEC Unix, this has the effect that
10926 IEEE-conformant math library routines will be linked in.
10928 @item -mbuild-constants
10929 @opindex mbuild-constants
10930 Normally GCC examines a 32- or 64-bit integer constant to
10931 see if it can construct it from smaller constants in two or three
10932 instructions. If it cannot, it will output the constant as a literal and
10933 generate code to load it from the data segment at runtime.
10935 Use this option to require GCC to construct @emph{all} integer constants
10936 using code, even if it takes more instructions (the maximum is six).
10938 You would typically use this option to build a shared library dynamic
10939 loader. Itself a shared library, it must relocate itself in memory
10940 before it can find the variables and constants in its own data segment.
10946 Select whether to generate code to be assembled by the vendor-supplied
10947 assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
10965 Indicate whether GCC should generate code to use the optional BWX,
10966 CIX, FIX and MAX instruction sets. The default is to use the instruction
10967 sets supported by the CPU type specified via @option{-mcpu=} option or that
10968 of the CPU on which GCC was built if none was specified.
10971 @itemx -mfloat-ieee
10972 @opindex mfloat-vax
10973 @opindex mfloat-ieee
10974 Generate code that uses (does not use) VAX F and G floating point
10975 arithmetic instead of IEEE single and double precision.
10977 @item -mexplicit-relocs
10978 @itemx -mno-explicit-relocs
10979 @opindex mexplicit-relocs
10980 @opindex mno-explicit-relocs
10981 Older Alpha assemblers provided no way to generate symbol relocations
10982 except via assembler macros. Use of these macros does not allow
10983 optimal instruction scheduling. GNU binutils as of version 2.12
10984 supports a new syntax that allows the compiler to explicitly mark
10985 which relocations should apply to which instructions. This option
10986 is mostly useful for debugging, as GCC detects the capabilities of
10987 the assembler when it is built and sets the default accordingly.
10990 @itemx -mlarge-data
10991 @opindex msmall-data
10992 @opindex mlarge-data
10993 When @option{-mexplicit-relocs} is in effect, static data is
10994 accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
10995 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
10996 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
10997 16-bit relocations off of the @code{$gp} register. This limits the
10998 size of the small data area to 64KB, but allows the variables to be
10999 directly accessed via a single instruction.
11001 The default is @option{-mlarge-data}. With this option the data area
11002 is limited to just below 2GB@. Programs that require more than 2GB of
11003 data must use @code{malloc} or @code{mmap} to allocate the data in the
11004 heap instead of in the program's data segment.
11006 When generating code for shared libraries, @option{-fpic} implies
11007 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
11010 @itemx -mlarge-text
11011 @opindex msmall-text
11012 @opindex mlarge-text
11013 When @option{-msmall-text} is used, the compiler assumes that the
11014 code of the entire program (or shared library) fits in 4MB, and is
11015 thus reachable with a branch instruction. When @option{-msmall-data}
11016 is used, the compiler can assume that all local symbols share the
11017 same @code{$gp} value, and thus reduce the number of instructions
11018 required for a function call from 4 to 1.
11020 The default is @option{-mlarge-text}.
11022 @item -mcpu=@var{cpu_type}
11024 Set the instruction set and instruction scheduling parameters for
11025 machine type @var{cpu_type}. You can specify either the @samp{EV}
11026 style name or the corresponding chip number. GCC supports scheduling
11027 parameters for the EV4, EV5 and EV6 family of processors and will
11028 choose the default values for the instruction set from the processor
11029 you specify. If you do not specify a processor type, GCC will default
11030 to the processor on which the compiler was built.
11032 Supported values for @var{cpu_type} are
11038 Schedules as an EV4 and has no instruction set extensions.
11042 Schedules as an EV5 and has no instruction set extensions.
11046 Schedules as an EV5 and supports the BWX extension.
11051 Schedules as an EV5 and supports the BWX and MAX extensions.
11055 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
11059 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
11062 Native Linux/GNU toolchains also support the value @samp{native},
11063 which selects the best architecture option for the host processor.
11064 @option{-mcpu=native} has no effect if GCC does not recognize
11067 @item -mtune=@var{cpu_type}
11069 Set only the instruction scheduling parameters for machine type
11070 @var{cpu_type}. The instruction set is not changed.
11072 Native Linux/GNU toolchains also support the value @samp{native},
11073 which selects the best architecture option for the host processor.
11074 @option{-mtune=native} has no effect if GCC does not recognize
11077 @item -mmemory-latency=@var{time}
11078 @opindex mmemory-latency
11079 Sets the latency the scheduler should assume for typical memory
11080 references as seen by the application. This number is highly
11081 dependent on the memory access patterns used by the application
11082 and the size of the external cache on the machine.
11084 Valid options for @var{time} are
11088 A decimal number representing clock cycles.
11094 The compiler contains estimates of the number of clock cycles for
11095 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
11096 (also called Dcache, Scache, and Bcache), as well as to main memory.
11097 Note that L3 is only valid for EV5.
11102 @node DEC Alpha/VMS Options
11103 @subsection DEC Alpha/VMS Options
11105 These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
11108 @item -mvms-return-codes
11109 @opindex mvms-return-codes
11110 Return VMS condition codes from main. The default is to return POSIX
11111 style condition (e.g.@: error) codes.
11113 @item -mdebug-main=@var{prefix}
11114 @opindex mdebug-main=@var{prefix}
11115 Flag the first routine whose name starts with @var{prefix} as the main
11116 routine for the debugger.
11120 Default to 64bit memory allocation routines.
11124 @subsection FR30 Options
11125 @cindex FR30 Options
11127 These options are defined specifically for the FR30 port.
11131 @item -msmall-model
11132 @opindex msmall-model
11133 Use the small address space model. This can produce smaller code, but
11134 it does assume that all symbolic values and addresses will fit into a
11139 Assume that run-time support has been provided and so there is no need
11140 to include the simulator library (@file{libsim.a}) on the linker
11146 @subsection FRV Options
11147 @cindex FRV Options
11153 Only use the first 32 general purpose registers.
11158 Use all 64 general purpose registers.
11163 Use only the first 32 floating point registers.
11168 Use all 64 floating point registers
11171 @opindex mhard-float
11173 Use hardware instructions for floating point operations.
11176 @opindex msoft-float
11178 Use library routines for floating point operations.
11183 Dynamically allocate condition code registers.
11188 Do not try to dynamically allocate condition code registers, only
11189 use @code{icc0} and @code{fcc0}.
11194 Change ABI to use double word insns.
11199 Do not use double word instructions.
11204 Use floating point double instructions.
11207 @opindex mno-double
11209 Do not use floating point double instructions.
11214 Use media instructions.
11219 Do not use media instructions.
11224 Use multiply and add/subtract instructions.
11227 @opindex mno-muladd
11229 Do not use multiply and add/subtract instructions.
11234 Select the FDPIC ABI, that uses function descriptors to represent
11235 pointers to functions. Without any PIC/PIE-related options, it
11236 implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
11237 assumes GOT entries and small data are within a 12-bit range from the
11238 GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
11239 are computed with 32 bits.
11240 With a @samp{bfin-elf} target, this option implies @option{-msim}.
11243 @opindex minline-plt
11245 Enable inlining of PLT entries in function calls to functions that are
11246 not known to bind locally. It has no effect without @option{-mfdpic}.
11247 It's enabled by default if optimizing for speed and compiling for
11248 shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
11249 optimization option such as @option{-O3} or above is present in the
11255 Assume a large TLS segment when generating thread-local code.
11260 Do not assume a large TLS segment when generating thread-local code.
11265 Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
11266 that is known to be in read-only sections. It's enabled by default,
11267 except for @option{-fpic} or @option{-fpie}: even though it may help
11268 make the global offset table smaller, it trades 1 instruction for 4.
11269 With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
11270 one of which may be shared by multiple symbols, and it avoids the need
11271 for a GOT entry for the referenced symbol, so it's more likely to be a
11272 win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
11274 @item -multilib-library-pic
11275 @opindex multilib-library-pic
11277 Link with the (library, not FD) pic libraries. It's implied by
11278 @option{-mlibrary-pic}, as well as by @option{-fPIC} and
11279 @option{-fpic} without @option{-mfdpic}. You should never have to use
11283 @opindex mlinked-fp
11285 Follow the EABI requirement of always creating a frame pointer whenever
11286 a stack frame is allocated. This option is enabled by default and can
11287 be disabled with @option{-mno-linked-fp}.
11290 @opindex mlong-calls
11292 Use indirect addressing to call functions outside the current
11293 compilation unit. This allows the functions to be placed anywhere
11294 within the 32-bit address space.
11296 @item -malign-labels
11297 @opindex malign-labels
11299 Try to align labels to an 8-byte boundary by inserting nops into the
11300 previous packet. This option only has an effect when VLIW packing
11301 is enabled. It doesn't create new packets; it merely adds nops to
11304 @item -mlibrary-pic
11305 @opindex mlibrary-pic
11307 Generate position-independent EABI code.
11312 Use only the first four media accumulator registers.
11317 Use all eight media accumulator registers.
11322 Pack VLIW instructions.
11327 Do not pack VLIW instructions.
11330 @opindex mno-eflags
11332 Do not mark ABI switches in e_flags.
11335 @opindex mcond-move
11337 Enable the use of conditional-move instructions (default).
11339 This switch is mainly for debugging the compiler and will likely be removed
11340 in a future version.
11342 @item -mno-cond-move
11343 @opindex mno-cond-move
11345 Disable the use of conditional-move instructions.
11347 This switch is mainly for debugging the compiler and will likely be removed
11348 in a future version.
11353 Enable the use of conditional set instructions (default).
11355 This switch is mainly for debugging the compiler and will likely be removed
11356 in a future version.
11361 Disable the use of conditional set instructions.
11363 This switch is mainly for debugging the compiler and will likely be removed
11364 in a future version.
11367 @opindex mcond-exec
11369 Enable the use of conditional execution (default).
11371 This switch is mainly for debugging the compiler and will likely be removed
11372 in a future version.
11374 @item -mno-cond-exec
11375 @opindex mno-cond-exec
11377 Disable the use of conditional execution.
11379 This switch is mainly for debugging the compiler and will likely be removed
11380 in a future version.
11382 @item -mvliw-branch
11383 @opindex mvliw-branch
11385 Run a pass to pack branches into VLIW instructions (default).
11387 This switch is mainly for debugging the compiler and will likely be removed
11388 in a future version.
11390 @item -mno-vliw-branch
11391 @opindex mno-vliw-branch
11393 Do not run a pass to pack branches into VLIW instructions.
11395 This switch is mainly for debugging the compiler and will likely be removed
11396 in a future version.
11398 @item -mmulti-cond-exec
11399 @opindex mmulti-cond-exec
11401 Enable optimization of @code{&&} and @code{||} in conditional execution
11404 This switch is mainly for debugging the compiler and will likely be removed
11405 in a future version.
11407 @item -mno-multi-cond-exec
11408 @opindex mno-multi-cond-exec
11410 Disable optimization of @code{&&} and @code{||} in conditional execution.
11412 This switch is mainly for debugging the compiler and will likely be removed
11413 in a future version.
11415 @item -mnested-cond-exec
11416 @opindex mnested-cond-exec
11418 Enable nested conditional execution optimizations (default).
11420 This switch is mainly for debugging the compiler and will likely be removed
11421 in a future version.
11423 @item -mno-nested-cond-exec
11424 @opindex mno-nested-cond-exec
11426 Disable nested conditional execution optimizations.
11428 This switch is mainly for debugging the compiler and will likely be removed
11429 in a future version.
11431 @item -moptimize-membar
11432 @opindex moptimize-membar
11434 This switch removes redundant @code{membar} instructions from the
11435 compiler generated code. It is enabled by default.
11437 @item -mno-optimize-membar
11438 @opindex mno-optimize-membar
11440 This switch disables the automatic removal of redundant @code{membar}
11441 instructions from the generated code.
11443 @item -mtomcat-stats
11444 @opindex mtomcat-stats
11446 Cause gas to print out tomcat statistics.
11448 @item -mcpu=@var{cpu}
11451 Select the processor type for which to generate code. Possible values are
11452 @samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
11453 @samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
11457 @node GNU/Linux Options
11458 @subsection GNU/Linux Options
11460 These @samp{-m} options are defined for GNU/Linux targets:
11465 Use the GNU C library instead of uClibc. This is the default except
11466 on @samp{*-*-linux-*uclibc*} targets.
11470 Use uClibc instead of the GNU C library. This is the default on
11471 @samp{*-*-linux-*uclibc*} targets.
11474 @node H8/300 Options
11475 @subsection H8/300 Options
11477 These @samp{-m} options are defined for the H8/300 implementations:
11482 Shorten some address references at link time, when possible; uses the
11483 linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
11484 ld, Using ld}, for a fuller description.
11488 Generate code for the H8/300H@.
11492 Generate code for the H8S@.
11496 Generate code for the H8S and H8/300H in the normal mode. This switch
11497 must be used either with @option{-mh} or @option{-ms}.
11501 Generate code for the H8S/2600. This switch must be used with @option{-ms}.
11505 Make @code{int} data 32 bits by default.
11508 @opindex malign-300
11509 On the H8/300H and H8S, use the same alignment rules as for the H8/300.
11510 The default for the H8/300H and H8S is to align longs and floats on 4
11512 @option{-malign-300} causes them to be aligned on 2 byte boundaries.
11513 This option has no effect on the H8/300.
11517 @subsection HPPA Options
11518 @cindex HPPA Options
11520 These @samp{-m} options are defined for the HPPA family of computers:
11523 @item -march=@var{architecture-type}
11525 Generate code for the specified architecture. The choices for
11526 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
11527 1.1, and @samp{2.0} for PA 2.0 processors. Refer to
11528 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
11529 architecture option for your machine. Code compiled for lower numbered
11530 architectures will run on higher numbered architectures, but not the
11533 @item -mpa-risc-1-0
11534 @itemx -mpa-risc-1-1
11535 @itemx -mpa-risc-2-0
11536 @opindex mpa-risc-1-0
11537 @opindex mpa-risc-1-1
11538 @opindex mpa-risc-2-0
11539 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
11542 @opindex mbig-switch
11543 Generate code suitable for big switch tables. Use this option only if
11544 the assembler/linker complain about out of range branches within a switch
11547 @item -mjump-in-delay
11548 @opindex mjump-in-delay
11549 Fill delay slots of function calls with unconditional jump instructions
11550 by modifying the return pointer for the function call to be the target
11551 of the conditional jump.
11553 @item -mdisable-fpregs
11554 @opindex mdisable-fpregs
11555 Prevent floating point registers from being used in any manner. This is
11556 necessary for compiling kernels which perform lazy context switching of
11557 floating point registers. If you use this option and attempt to perform
11558 floating point operations, the compiler will abort.
11560 @item -mdisable-indexing
11561 @opindex mdisable-indexing
11562 Prevent the compiler from using indexing address modes. This avoids some
11563 rather obscure problems when compiling MIG generated code under MACH@.
11565 @item -mno-space-regs
11566 @opindex mno-space-regs
11567 Generate code that assumes the target has no space registers. This allows
11568 GCC to generate faster indirect calls and use unscaled index address modes.
11570 Such code is suitable for level 0 PA systems and kernels.
11572 @item -mfast-indirect-calls
11573 @opindex mfast-indirect-calls
11574 Generate code that assumes calls never cross space boundaries. This
11575 allows GCC to emit code which performs faster indirect calls.
11577 This option will not work in the presence of shared libraries or nested
11580 @item -mfixed-range=@var{register-range}
11581 @opindex mfixed-range
11582 Generate code treating the given register range as fixed registers.
11583 A fixed register is one that the register allocator can not use. This is
11584 useful when compiling kernel code. A register range is specified as
11585 two registers separated by a dash. Multiple register ranges can be
11586 specified separated by a comma.
11588 @item -mlong-load-store
11589 @opindex mlong-load-store
11590 Generate 3-instruction load and store sequences as sometimes required by
11591 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
11594 @item -mportable-runtime
11595 @opindex mportable-runtime
11596 Use the portable calling conventions proposed by HP for ELF systems.
11600 Enable the use of assembler directives only GAS understands.
11602 @item -mschedule=@var{cpu-type}
11604 Schedule code according to the constraints for the machine type
11605 @var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
11606 @samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
11607 to @file{/usr/lib/sched.models} on an HP-UX system to determine the
11608 proper scheduling option for your machine. The default scheduling is
11612 @opindex mlinker-opt
11613 Enable the optimization pass in the HP-UX linker. Note this makes symbolic
11614 debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
11615 linkers in which they give bogus error messages when linking some programs.
11618 @opindex msoft-float
11619 Generate output containing library calls for floating point.
11620 @strong{Warning:} the requisite libraries are not available for all HPPA
11621 targets. Normally the facilities of the machine's usual C compiler are
11622 used, but this cannot be done directly in cross-compilation. You must make
11623 your own arrangements to provide suitable library functions for
11626 @option{-msoft-float} changes the calling convention in the output file;
11627 therefore, it is only useful if you compile @emph{all} of a program with
11628 this option. In particular, you need to compile @file{libgcc.a}, the
11629 library that comes with GCC, with @option{-msoft-float} in order for
11634 Generate the predefine, @code{_SIO}, for server IO@. The default is
11635 @option{-mwsio}. This generates the predefines, @code{__hp9000s700},
11636 @code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
11637 options are available under HP-UX and HI-UX@.
11641 Use GNU ld specific options. This passes @option{-shared} to ld when
11642 building a shared library. It is the default when GCC is configured,
11643 explicitly or implicitly, with the GNU linker. This option does not
11644 have any affect on which ld is called, it only changes what parameters
11645 are passed to that ld. The ld that is called is determined by the
11646 @option{--with-ld} configure option, GCC's program search path, and
11647 finally by the user's @env{PATH}. The linker used by GCC can be printed
11648 using @samp{which `gcc -print-prog-name=ld`}. This option is only available
11649 on the 64 bit HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
11653 Use HP ld specific options. This passes @option{-b} to ld when building
11654 a shared library and passes @option{+Accept TypeMismatch} to ld on all
11655 links. It is the default when GCC is configured, explicitly or
11656 implicitly, with the HP linker. This option does not have any affect on
11657 which ld is called, it only changes what parameters are passed to that
11658 ld. The ld that is called is determined by the @option{--with-ld}
11659 configure option, GCC's program search path, and finally by the user's
11660 @env{PATH}. The linker used by GCC can be printed using @samp{which
11661 `gcc -print-prog-name=ld`}. This option is only available on the 64 bit
11662 HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
11665 @opindex mno-long-calls
11666 Generate code that uses long call sequences. This ensures that a call
11667 is always able to reach linker generated stubs. The default is to generate
11668 long calls only when the distance from the call site to the beginning
11669 of the function or translation unit, as the case may be, exceeds a
11670 predefined limit set by the branch type being used. The limits for
11671 normal calls are 7,600,000 and 240,000 bytes, respectively for the
11672 PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
11675 Distances are measured from the beginning of functions when using the
11676 @option{-ffunction-sections} option, or when using the @option{-mgas}
11677 and @option{-mno-portable-runtime} options together under HP-UX with
11680 It is normally not desirable to use this option as it will degrade
11681 performance. However, it may be useful in large applications,
11682 particularly when partial linking is used to build the application.
11684 The types of long calls used depends on the capabilities of the
11685 assembler and linker, and the type of code being generated. The
11686 impact on systems that support long absolute calls, and long pic
11687 symbol-difference or pc-relative calls should be relatively small.
11688 However, an indirect call is used on 32-bit ELF systems in pic code
11689 and it is quite long.
11691 @item -munix=@var{unix-std}
11693 Generate compiler predefines and select a startfile for the specified
11694 UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
11695 and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
11696 is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
11697 11.11 and later. The default values are @samp{93} for HP-UX 10.00,
11698 @samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
11701 @option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
11702 @option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
11703 and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
11704 @option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
11705 @code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
11706 @code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
11708 It is @emph{important} to note that this option changes the interfaces
11709 for various library routines. It also affects the operational behavior
11710 of the C library. Thus, @emph{extreme} care is needed in using this
11713 Library code that is intended to operate with more than one UNIX
11714 standard must test, set and restore the variable @var{__xpg4_extended_mask}
11715 as appropriate. Most GNU software doesn't provide this capability.
11719 Suppress the generation of link options to search libdld.sl when the
11720 @option{-static} option is specified on HP-UX 10 and later.
11724 The HP-UX implementation of setlocale in libc has a dependency on
11725 libdld.sl. There isn't an archive version of libdld.sl. Thus,
11726 when the @option{-static} option is specified, special link options
11727 are needed to resolve this dependency.
11729 On HP-UX 10 and later, the GCC driver adds the necessary options to
11730 link with libdld.sl when the @option{-static} option is specified.
11731 This causes the resulting binary to be dynamic. On the 64-bit port,
11732 the linkers generate dynamic binaries by default in any case. The
11733 @option{-nolibdld} option can be used to prevent the GCC driver from
11734 adding these link options.
11738 Add support for multithreading with the @dfn{dce thread} library
11739 under HP-UX@. This option sets flags for both the preprocessor and
11743 @node i386 and x86-64 Options
11744 @subsection Intel 386 and AMD x86-64 Options
11745 @cindex i386 Options
11746 @cindex x86-64 Options
11747 @cindex Intel 386 Options
11748 @cindex AMD x86-64 Options
11750 These @samp{-m} options are defined for the i386 and x86-64 family of
11754 @item -mtune=@var{cpu-type}
11756 Tune to @var{cpu-type} everything applicable about the generated code, except
11757 for the ABI and the set of available instructions. The choices for
11758 @var{cpu-type} are:
11761 Produce code optimized for the most common IA32/AMD64/EM64T processors.
11762 If you know the CPU on which your code will run, then you should use
11763 the corresponding @option{-mtune} option instead of
11764 @option{-mtune=generic}. But, if you do not know exactly what CPU users
11765 of your application will have, then you should use this option.
11767 As new processors are deployed in the marketplace, the behavior of this
11768 option will change. Therefore, if you upgrade to a newer version of
11769 GCC, the code generated option will change to reflect the processors
11770 that were most common when that version of GCC was released.
11772 There is no @option{-march=generic} option because @option{-march}
11773 indicates the instruction set the compiler can use, and there is no
11774 generic instruction set applicable to all processors. In contrast,
11775 @option{-mtune} indicates the processor (or, in this case, collection of
11776 processors) for which the code is optimized.
11778 This selects the CPU to tune for at compilation time by determining
11779 the processor type of the compiling machine. Using @option{-mtune=native}
11780 will produce code optimized for the local machine under the constraints
11781 of the selected instruction set. Using @option{-march=native} will
11782 enable all instruction subsets supported by the local machine (hence
11783 the result might not run on different machines).
11785 Original Intel's i386 CPU@.
11787 Intel's i486 CPU@. (No scheduling is implemented for this chip.)
11788 @item i586, pentium
11789 Intel Pentium CPU with no MMX support.
11791 Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
11793 Intel PentiumPro CPU@.
11795 Same as @code{generic}, but when used as @code{march} option, PentiumPro
11796 instruction set will be used, so the code will run on all i686 family chips.
11798 Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
11799 @item pentium3, pentium3m
11800 Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
11803 Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
11804 support. Used by Centrino notebooks.
11805 @item pentium4, pentium4m
11806 Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
11808 Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
11811 Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
11812 SSE2 and SSE3 instruction set support.
11814 Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
11815 instruction set support.
11817 Intel Atom CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
11818 instruction set support.
11820 AMD K6 CPU with MMX instruction set support.
11822 Improved versions of AMD K6 CPU with MMX and 3DNow!@: instruction set support.
11823 @item athlon, athlon-tbird
11824 AMD Athlon CPU with MMX, 3dNOW!, enhanced 3DNow!@: and SSE prefetch instructions
11826 @item athlon-4, athlon-xp, athlon-mp
11827 Improved AMD Athlon CPU with MMX, 3DNow!, enhanced 3DNow!@: and full SSE
11828 instruction set support.
11829 @item k8, opteron, athlon64, athlon-fx
11830 AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
11831 MMX, SSE, SSE2, 3DNow!, enhanced 3DNow!@: and 64-bit instruction set extensions.)
11832 @item k8-sse3, opteron-sse3, athlon64-sse3
11833 Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
11834 @item amdfam10, barcelona
11835 AMD Family 10h core based CPUs with x86-64 instruction set support. (This
11836 supersets MMX, SSE, SSE2, SSE3, SSE4A, 3DNow!, enhanced 3DNow!, ABM and 64-bit
11837 instruction set extensions.)
11839 IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
11842 IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3DNow!@:
11843 instruction set support.
11845 Via C3 CPU with MMX and 3DNow!@: instruction set support. (No scheduling is
11846 implemented for this chip.)
11848 Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
11849 implemented for this chip.)
11851 Embedded AMD CPU with MMX and 3DNow!@: instruction set support.
11854 While picking a specific @var{cpu-type} will schedule things appropriately
11855 for that particular chip, the compiler will not generate any code that
11856 does not run on the i386 without the @option{-march=@var{cpu-type}} option
11859 @item -march=@var{cpu-type}
11861 Generate instructions for the machine type @var{cpu-type}. The choices
11862 for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
11863 specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
11865 @item -mcpu=@var{cpu-type}
11867 A deprecated synonym for @option{-mtune}.
11869 @item -mfpmath=@var{unit}
11871 Generate floating point arithmetics for selected unit @var{unit}. The choices
11872 for @var{unit} are:
11876 Use the standard 387 floating point coprocessor present majority of chips and
11877 emulated otherwise. Code compiled with this option will run almost everywhere.
11878 The temporary results are computed in 80bit precision instead of precision
11879 specified by the type resulting in slightly different results compared to most
11880 of other chips. See @option{-ffloat-store} for more detailed description.
11882 This is the default choice for i386 compiler.
11885 Use scalar floating point instructions present in the SSE instruction set.
11886 This instruction set is supported by Pentium3 and newer chips, in the AMD line
11887 by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
11888 instruction set supports only single precision arithmetics, thus the double and
11889 extended precision arithmetics is still done using 387. Later version, present
11890 only in Pentium4 and the future AMD x86-64 chips supports double precision
11893 For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
11894 or @option{-msse2} switches to enable SSE extensions and make this option
11895 effective. For the x86-64 compiler, these extensions are enabled by default.
11897 The resulting code should be considerably faster in the majority of cases and avoid
11898 the numerical instability problems of 387 code, but may break some existing
11899 code that expects temporaries to be 80bit.
11901 This is the default choice for the x86-64 compiler.
11906 Attempt to utilize both instruction sets at once. This effectively double the
11907 amount of available registers and on chips with separate execution units for
11908 387 and SSE the execution resources too. Use this option with care, as it is
11909 still experimental, because the GCC register allocator does not model separate
11910 functional units well resulting in instable performance.
11913 @item -masm=@var{dialect}
11914 @opindex masm=@var{dialect}
11915 Output asm instructions using selected @var{dialect}. Supported
11916 choices are @samp{intel} or @samp{att} (the default one). Darwin does
11917 not support @samp{intel}.
11920 @itemx -mno-ieee-fp
11922 @opindex mno-ieee-fp
11923 Control whether or not the compiler uses IEEE floating point
11924 comparisons. These handle correctly the case where the result of a
11925 comparison is unordered.
11928 @opindex msoft-float
11929 Generate output containing library calls for floating point.
11930 @strong{Warning:} the requisite libraries are not part of GCC@.
11931 Normally the facilities of the machine's usual C compiler are used, but
11932 this can't be done directly in cross-compilation. You must make your
11933 own arrangements to provide suitable library functions for
11936 On machines where a function returns floating point results in the 80387
11937 register stack, some floating point opcodes may be emitted even if
11938 @option{-msoft-float} is used.
11940 @item -mno-fp-ret-in-387
11941 @opindex mno-fp-ret-in-387
11942 Do not use the FPU registers for return values of functions.
11944 The usual calling convention has functions return values of types
11945 @code{float} and @code{double} in an FPU register, even if there
11946 is no FPU@. The idea is that the operating system should emulate
11949 The option @option{-mno-fp-ret-in-387} causes such values to be returned
11950 in ordinary CPU registers instead.
11952 @item -mno-fancy-math-387
11953 @opindex mno-fancy-math-387
11954 Some 387 emulators do not support the @code{sin}, @code{cos} and
11955 @code{sqrt} instructions for the 387. Specify this option to avoid
11956 generating those instructions. This option is the default on FreeBSD,
11957 OpenBSD and NetBSD@. This option is overridden when @option{-march}
11958 indicates that the target cpu will always have an FPU and so the
11959 instruction will not need emulation. As of revision 2.6.1, these
11960 instructions are not generated unless you also use the
11961 @option{-funsafe-math-optimizations} switch.
11963 @item -malign-double
11964 @itemx -mno-align-double
11965 @opindex malign-double
11966 @opindex mno-align-double
11967 Control whether GCC aligns @code{double}, @code{long double}, and
11968 @code{long long} variables on a two word boundary or a one word
11969 boundary. Aligning @code{double} variables on a two word boundary will
11970 produce code that runs somewhat faster on a @samp{Pentium} at the
11971 expense of more memory.
11973 On x86-64, @option{-malign-double} is enabled by default.
11975 @strong{Warning:} if you use the @option{-malign-double} switch,
11976 structures containing the above types will be aligned differently than
11977 the published application binary interface specifications for the 386
11978 and will not be binary compatible with structures in code compiled
11979 without that switch.
11981 @item -m96bit-long-double
11982 @itemx -m128bit-long-double
11983 @opindex m96bit-long-double
11984 @opindex m128bit-long-double
11985 These switches control the size of @code{long double} type. The i386
11986 application binary interface specifies the size to be 96 bits,
11987 so @option{-m96bit-long-double} is the default in 32 bit mode.
11989 Modern architectures (Pentium and newer) would prefer @code{long double}
11990 to be aligned to an 8 or 16 byte boundary. In arrays or structures
11991 conforming to the ABI, this would not be possible. So specifying a
11992 @option{-m128bit-long-double} will align @code{long double}
11993 to a 16 byte boundary by padding the @code{long double} with an additional
11996 In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
11997 its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
11999 Notice that neither of these options enable any extra precision over the x87
12000 standard of 80 bits for a @code{long double}.
12002 @strong{Warning:} if you override the default value for your target ABI, the
12003 structures and arrays containing @code{long double} variables will change
12004 their size as well as function calling convention for function taking
12005 @code{long double} will be modified. Hence they will not be binary
12006 compatible with arrays or structures in code compiled without that switch.
12008 @item -mlarge-data-threshold=@var{number}
12009 @opindex mlarge-data-threshold=@var{number}
12010 When @option{-mcmodel=medium} is specified, the data greater than
12011 @var{threshold} are placed in large data section. This value must be the
12012 same across all object linked into the binary and defaults to 65535.
12016 Use a different function-calling convention, in which functions that
12017 take a fixed number of arguments return with the @code{ret} @var{num}
12018 instruction, which pops their arguments while returning. This saves one
12019 instruction in the caller since there is no need to pop the arguments
12022 You can specify that an individual function is called with this calling
12023 sequence with the function attribute @samp{stdcall}. You can also
12024 override the @option{-mrtd} option by using the function attribute
12025 @samp{cdecl}. @xref{Function Attributes}.
12027 @strong{Warning:} this calling convention is incompatible with the one
12028 normally used on Unix, so you cannot use it if you need to call
12029 libraries compiled with the Unix compiler.
12031 Also, you must provide function prototypes for all functions that
12032 take variable numbers of arguments (including @code{printf});
12033 otherwise incorrect code will be generated for calls to those
12036 In addition, seriously incorrect code will result if you call a
12037 function with too many arguments. (Normally, extra arguments are
12038 harmlessly ignored.)
12040 @item -mregparm=@var{num}
12042 Control how many registers are used to pass integer arguments. By
12043 default, no registers are used to pass arguments, and at most 3
12044 registers can be used. You can control this behavior for a specific
12045 function by using the function attribute @samp{regparm}.
12046 @xref{Function Attributes}.
12048 @strong{Warning:} if you use this switch, and
12049 @var{num} is nonzero, then you must build all modules with the same
12050 value, including any libraries. This includes the system libraries and
12054 @opindex msseregparm
12055 Use SSE register passing conventions for float and double arguments
12056 and return values. You can control this behavior for a specific
12057 function by using the function attribute @samp{sseregparm}.
12058 @xref{Function Attributes}.
12060 @strong{Warning:} if you use this switch then you must build all
12061 modules with the same value, including any libraries. This includes
12062 the system libraries and startup modules.
12071 Set 80387 floating-point precision to 32, 64 or 80 bits. When @option{-mpc32}
12072 is specified, the significands of results of floating-point operations are
12073 rounded to 24 bits (single precision); @option{-mpc64} rounds the
12074 significands of results of floating-point operations to 53 bits (double
12075 precision) and @option{-mpc80} rounds the significands of results of
12076 floating-point operations to 64 bits (extended double precision), which is
12077 the default. When this option is used, floating-point operations in higher
12078 precisions are not available to the programmer without setting the FPU
12079 control word explicitly.
12081 Setting the rounding of floating-point operations to less than the default
12082 80 bits can speed some programs by 2% or more. Note that some mathematical
12083 libraries assume that extended precision (80 bit) floating-point operations
12084 are enabled by default; routines in such libraries could suffer significant
12085 loss of accuracy, typically through so-called "catastrophic cancellation",
12086 when this option is used to set the precision to less than extended precision.
12088 @item -mstackrealign
12089 @opindex mstackrealign
12090 Realign the stack at entry. On the Intel x86, the @option{-mstackrealign}
12091 option will generate an alternate prologue and epilogue that realigns the
12092 runtime stack if necessary. This supports mixing legacy codes that keep
12093 a 4-byte aligned stack with modern codes that keep a 16-byte stack for
12094 SSE compatibility. See also the attribute @code{force_align_arg_pointer},
12095 applicable to individual functions.
12097 @item -mpreferred-stack-boundary=@var{num}
12098 @opindex mpreferred-stack-boundary
12099 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
12100 byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
12101 the default is 4 (16 bytes or 128 bits).
12103 @item -mincoming-stack-boundary=@var{num}
12104 @opindex mincoming-stack-boundary
12105 Assume the incoming stack is aligned to a 2 raised to @var{num} byte
12106 boundary. If @option{-mincoming-stack-boundary} is not specified,
12107 the one specified by @option{-mpreferred-stack-boundary} will be used.
12109 On Pentium and PentiumPro, @code{double} and @code{long double} values
12110 should be aligned to an 8 byte boundary (see @option{-malign-double}) or
12111 suffer significant run time performance penalties. On Pentium III, the
12112 Streaming SIMD Extension (SSE) data type @code{__m128} may not work
12113 properly if it is not 16 byte aligned.
12115 To ensure proper alignment of this values on the stack, the stack boundary
12116 must be as aligned as that required by any value stored on the stack.
12117 Further, every function must be generated such that it keeps the stack
12118 aligned. Thus calling a function compiled with a higher preferred
12119 stack boundary from a function compiled with a lower preferred stack
12120 boundary will most likely misalign the stack. It is recommended that
12121 libraries that use callbacks always use the default setting.
12123 This extra alignment does consume extra stack space, and generally
12124 increases code size. Code that is sensitive to stack space usage, such
12125 as embedded systems and operating system kernels, may want to reduce the
12126 preferred alignment to @option{-mpreferred-stack-boundary=2}.
12170 These switches enable or disable the use of instructions in the MMX,
12171 SSE, SSE2, SSE3, SSSE3, SSE4.1, AVX, AES, PCLMUL, SSE4A, FMA4, XOP,
12172 LWP, ABM or 3DNow!@: extended instruction sets.
12173 These extensions are also available as built-in functions: see
12174 @ref{X86 Built-in Functions}, for details of the functions enabled and
12175 disabled by these switches.
12177 To have SSE/SSE2 instructions generated automatically from floating-point
12178 code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
12180 GCC depresses SSEx instructions when @option{-mavx} is used. Instead, it
12181 generates new AVX instructions or AVX equivalence for all SSEx instructions
12184 These options will enable GCC to use these extended instructions in
12185 generated code, even without @option{-mfpmath=sse}. Applications which
12186 perform runtime CPU detection must compile separate files for each
12187 supported architecture, using the appropriate flags. In particular,
12188 the file containing the CPU detection code should be compiled without
12192 @itemx -mno-fused-madd
12193 @opindex mfused-madd
12194 @opindex mno-fused-madd
12195 Do (don't) generate code that uses the fused multiply/add or multiply/subtract
12196 instructions. The default is to use these instructions.
12200 This option instructs GCC to emit a @code{cld} instruction in the prologue
12201 of functions that use string instructions. String instructions depend on
12202 the DF flag to select between autoincrement or autodecrement mode. While the
12203 ABI specifies the DF flag to be cleared on function entry, some operating
12204 systems violate this specification by not clearing the DF flag in their
12205 exception dispatchers. The exception handler can be invoked with the DF flag
12206 set which leads to wrong direction mode, when string instructions are used.
12207 This option can be enabled by default on 32-bit x86 targets by configuring
12208 GCC with the @option{--enable-cld} configure option. Generation of @code{cld}
12209 instructions can be suppressed with the @option{-mno-cld} compiler option
12214 This option will enable GCC to use CMPXCHG16B instruction in generated code.
12215 CMPXCHG16B allows for atomic operations on 128-bit double quadword (or oword)
12216 data types. This is useful for high resolution counters that could be updated
12217 by multiple processors (or cores). This instruction is generated as part of
12218 atomic built-in functions: see @ref{Atomic Builtins} for details.
12222 This option will enable GCC to use SAHF instruction in generated 64-bit code.
12223 Early Intel CPUs with Intel 64 lacked LAHF and SAHF instructions supported
12224 by AMD64 until introduction of Pentium 4 G1 step in December 2005. LAHF and
12225 SAHF are load and store instructions, respectively, for certain status flags.
12226 In 64-bit mode, SAHF instruction is used to optimize @code{fmod}, @code{drem}
12227 or @code{remainder} built-in functions: see @ref{Other Builtins} for details.
12231 This option will enable GCC to use movbe instruction to implement
12232 @code{__builtin_bswap32} and @code{__builtin_bswap64}.
12236 This option will enable built-in functions, @code{__builtin_ia32_crc32qi},
12237 @code{__builtin_ia32_crc32hi}. @code{__builtin_ia32_crc32si} and
12238 @code{__builtin_ia32_crc32di} to generate the crc32 machine instruction.
12242 This option will enable GCC to use RCPSS and RSQRTSS instructions (and their
12243 vectorized variants RCPPS and RSQRTPS) with an additional Newton-Raphson step
12244 to increase precision instead of DIVSS and SQRTSS (and their vectorized
12245 variants) for single precision floating point arguments. These instructions
12246 are generated only when @option{-funsafe-math-optimizations} is enabled
12247 together with @option{-finite-math-only} and @option{-fno-trapping-math}.
12248 Note that while the throughput of the sequence is higher than the throughput
12249 of the non-reciprocal instruction, the precision of the sequence can be
12250 decreased by up to 2 ulp (i.e. the inverse of 1.0 equals 0.99999994).
12252 Note that GCC implements 1.0f/sqrtf(x) in terms of RSQRTSS (or RSQRTPS)
12253 already with @option{-ffast-math} (or the above option combination), and
12254 doesn't need @option{-mrecip}.
12256 @item -mveclibabi=@var{type}
12257 @opindex mveclibabi
12258 Specifies the ABI type to use for vectorizing intrinsics using an
12259 external library. Supported types are @code{svml} for the Intel short
12260 vector math library and @code{acml} for the AMD math core library style
12261 of interfacing. GCC will currently emit calls to @code{vmldExp2},
12262 @code{vmldLn2}, @code{vmldLog102}, @code{vmldLog102}, @code{vmldPow2},
12263 @code{vmldTanh2}, @code{vmldTan2}, @code{vmldAtan2}, @code{vmldAtanh2},
12264 @code{vmldCbrt2}, @code{vmldSinh2}, @code{vmldSin2}, @code{vmldAsinh2},
12265 @code{vmldAsin2}, @code{vmldCosh2}, @code{vmldCos2}, @code{vmldAcosh2},
12266 @code{vmldAcos2}, @code{vmlsExp4}, @code{vmlsLn4}, @code{vmlsLog104},
12267 @code{vmlsLog104}, @code{vmlsPow4}, @code{vmlsTanh4}, @code{vmlsTan4},
12268 @code{vmlsAtan4}, @code{vmlsAtanh4}, @code{vmlsCbrt4}, @code{vmlsSinh4},
12269 @code{vmlsSin4}, @code{vmlsAsinh4}, @code{vmlsAsin4}, @code{vmlsCosh4},
12270 @code{vmlsCos4}, @code{vmlsAcosh4} and @code{vmlsAcos4} for corresponding
12271 function type when @option{-mveclibabi=svml} is used and @code{__vrd2_sin},
12272 @code{__vrd2_cos}, @code{__vrd2_exp}, @code{__vrd2_log}, @code{__vrd2_log2},
12273 @code{__vrd2_log10}, @code{__vrs4_sinf}, @code{__vrs4_cosf},
12274 @code{__vrs4_expf}, @code{__vrs4_logf}, @code{__vrs4_log2f},
12275 @code{__vrs4_log10f} and @code{__vrs4_powf} for corresponding function type
12276 when @option{-mveclibabi=acml} is used. Both @option{-ftree-vectorize} and
12277 @option{-funsafe-math-optimizations} have to be enabled. A SVML or ACML ABI
12278 compatible library will have to be specified at link time.
12280 @item -mabi=@var{name}
12282 Generate code for the specified calling convention. Permissible values
12283 are: @samp{sysv} for the ABI used on GNU/Linux and other systems and
12284 @samp{ms} for the Microsoft ABI. The default is to use the Microsoft
12285 ABI when targeting Windows. On all other systems, the default is the
12286 SYSV ABI. You can control this behavior for a specific function by
12287 using the function attribute @samp{ms_abi}/@samp{sysv_abi}.
12288 @xref{Function Attributes}.
12291 @itemx -mno-push-args
12292 @opindex mpush-args
12293 @opindex mno-push-args
12294 Use PUSH operations to store outgoing parameters. This method is shorter
12295 and usually equally fast as method using SUB/MOV operations and is enabled
12296 by default. In some cases disabling it may improve performance because of
12297 improved scheduling and reduced dependencies.
12299 @item -maccumulate-outgoing-args
12300 @opindex maccumulate-outgoing-args
12301 If enabled, the maximum amount of space required for outgoing arguments will be
12302 computed in the function prologue. This is faster on most modern CPUs
12303 because of reduced dependencies, improved scheduling and reduced stack usage
12304 when preferred stack boundary is not equal to 2. The drawback is a notable
12305 increase in code size. This switch implies @option{-mno-push-args}.
12309 Support thread-safe exception handling on @samp{Mingw32}. Code that relies
12310 on thread-safe exception handling must compile and link all code with the
12311 @option{-mthreads} option. When compiling, @option{-mthreads} defines
12312 @option{-D_MT}; when linking, it links in a special thread helper library
12313 @option{-lmingwthrd} which cleans up per thread exception handling data.
12315 @item -mno-align-stringops
12316 @opindex mno-align-stringops
12317 Do not align destination of inlined string operations. This switch reduces
12318 code size and improves performance in case the destination is already aligned,
12319 but GCC doesn't know about it.
12321 @item -minline-all-stringops
12322 @opindex minline-all-stringops
12323 By default GCC inlines string operations only when destination is known to be
12324 aligned at least to 4 byte boundary. This enables more inlining, increase code
12325 size, but may improve performance of code that depends on fast memcpy, strlen
12326 and memset for short lengths.
12328 @item -minline-stringops-dynamically
12329 @opindex minline-stringops-dynamically
12330 For string operation of unknown size, inline runtime checks so for small
12331 blocks inline code is used, while for large blocks library call is used.
12333 @item -mstringop-strategy=@var{alg}
12334 @opindex mstringop-strategy=@var{alg}
12335 Overwrite internal decision heuristic about particular algorithm to inline
12336 string operation with. The allowed values are @code{rep_byte},
12337 @code{rep_4byte}, @code{rep_8byte} for expanding using i386 @code{rep} prefix
12338 of specified size, @code{byte_loop}, @code{loop}, @code{unrolled_loop} for
12339 expanding inline loop, @code{libcall} for always expanding library call.
12341 @item -momit-leaf-frame-pointer
12342 @opindex momit-leaf-frame-pointer
12343 Don't keep the frame pointer in a register for leaf functions. This
12344 avoids the instructions to save, set up and restore frame pointers and
12345 makes an extra register available in leaf functions. The option
12346 @option{-fomit-frame-pointer} removes the frame pointer for all functions
12347 which might make debugging harder.
12349 @item -mtls-direct-seg-refs
12350 @itemx -mno-tls-direct-seg-refs
12351 @opindex mtls-direct-seg-refs
12352 Controls whether TLS variables may be accessed with offsets from the
12353 TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
12354 or whether the thread base pointer must be added. Whether or not this
12355 is legal depends on the operating system, and whether it maps the
12356 segment to cover the entire TLS area.
12358 For systems that use GNU libc, the default is on.
12361 @itemx -mno-sse2avx
12363 Specify that the assembler should encode SSE instructions with VEX
12364 prefix. The option @option{-mavx} turns this on by default.
12367 These @samp{-m} switches are supported in addition to the above
12368 on AMD x86-64 processors in 64-bit environments.
12375 Generate code for a 32-bit or 64-bit environment.
12376 The 32-bit environment sets int, long and pointer to 32 bits and
12377 generates code that runs on any i386 system.
12378 The 64-bit environment sets int to 32 bits and long and pointer
12379 to 64 bits and generates code for AMD's x86-64 architecture. For
12380 darwin only the -m64 option turns off the @option{-fno-pic} and
12381 @option{-mdynamic-no-pic} options.
12383 @item -mno-red-zone
12384 @opindex mno-red-zone
12385 Do not use a so called red zone for x86-64 code. The red zone is mandated
12386 by the x86-64 ABI, it is a 128-byte area beyond the location of the
12387 stack pointer that will not be modified by signal or interrupt handlers
12388 and therefore can be used for temporary data without adjusting the stack
12389 pointer. The flag @option{-mno-red-zone} disables this red zone.
12391 @item -mcmodel=small
12392 @opindex mcmodel=small
12393 Generate code for the small code model: the program and its symbols must
12394 be linked in the lower 2 GB of the address space. Pointers are 64 bits.
12395 Programs can be statically or dynamically linked. This is the default
12398 @item -mcmodel=kernel
12399 @opindex mcmodel=kernel
12400 Generate code for the kernel code model. The kernel runs in the
12401 negative 2 GB of the address space.
12402 This model has to be used for Linux kernel code.
12404 @item -mcmodel=medium
12405 @opindex mcmodel=medium
12406 Generate code for the medium model: The program is linked in the lower 2
12407 GB of the address space. Small symbols are also placed there. Symbols
12408 with sizes larger than @option{-mlarge-data-threshold} are put into
12409 large data or bss sections and can be located above 2GB. Programs can
12410 be statically or dynamically linked.
12412 @item -mcmodel=large
12413 @opindex mcmodel=large
12414 Generate code for the large model: This model makes no assumptions
12415 about addresses and sizes of sections.
12418 @node IA-64 Options
12419 @subsection IA-64 Options
12420 @cindex IA-64 Options
12422 These are the @samp{-m} options defined for the Intel IA-64 architecture.
12426 @opindex mbig-endian
12427 Generate code for a big endian target. This is the default for HP-UX@.
12429 @item -mlittle-endian
12430 @opindex mlittle-endian
12431 Generate code for a little endian target. This is the default for AIX5
12437 @opindex mno-gnu-as
12438 Generate (or don't) code for the GNU assembler. This is the default.
12439 @c Also, this is the default if the configure option @option{--with-gnu-as}
12445 @opindex mno-gnu-ld
12446 Generate (or don't) code for the GNU linker. This is the default.
12447 @c Also, this is the default if the configure option @option{--with-gnu-ld}
12452 Generate code that does not use a global pointer register. The result
12453 is not position independent code, and violates the IA-64 ABI@.
12455 @item -mvolatile-asm-stop
12456 @itemx -mno-volatile-asm-stop
12457 @opindex mvolatile-asm-stop
12458 @opindex mno-volatile-asm-stop
12459 Generate (or don't) a stop bit immediately before and after volatile asm
12462 @item -mregister-names
12463 @itemx -mno-register-names
12464 @opindex mregister-names
12465 @opindex mno-register-names
12466 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
12467 the stacked registers. This may make assembler output more readable.
12473 Disable (or enable) optimizations that use the small data section. This may
12474 be useful for working around optimizer bugs.
12476 @item -mconstant-gp
12477 @opindex mconstant-gp
12478 Generate code that uses a single constant global pointer value. This is
12479 useful when compiling kernel code.
12483 Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
12484 This is useful when compiling firmware code.
12486 @item -minline-float-divide-min-latency
12487 @opindex minline-float-divide-min-latency
12488 Generate code for inline divides of floating point values
12489 using the minimum latency algorithm.
12491 @item -minline-float-divide-max-throughput
12492 @opindex minline-float-divide-max-throughput
12493 Generate code for inline divides of floating point values
12494 using the maximum throughput algorithm.
12496 @item -mno-inline-float-divide
12497 @opindex mno-inline-float-divide
12498 Do not generate inline code for divides of floating point values.
12500 @item -minline-int-divide-min-latency
12501 @opindex minline-int-divide-min-latency
12502 Generate code for inline divides of integer values
12503 using the minimum latency algorithm.
12505 @item -minline-int-divide-max-throughput
12506 @opindex minline-int-divide-max-throughput
12507 Generate code for inline divides of integer values
12508 using the maximum throughput algorithm.
12510 @item -mno-inline-int-divide
12511 @opindex mno-inline-int-divide
12512 Do not generate inline code for divides of integer values.
12514 @item -minline-sqrt-min-latency
12515 @opindex minline-sqrt-min-latency
12516 Generate code for inline square roots
12517 using the minimum latency algorithm.
12519 @item -minline-sqrt-max-throughput
12520 @opindex minline-sqrt-max-throughput
12521 Generate code for inline square roots
12522 using the maximum throughput algorithm.
12524 @item -mno-inline-sqrt
12525 @opindex mno-inline-sqrt
12526 Do not generate inline code for sqrt.
12529 @itemx -mno-fused-madd
12530 @opindex mfused-madd
12531 @opindex mno-fused-madd
12532 Do (don't) generate code that uses the fused multiply/add or multiply/subtract
12533 instructions. The default is to use these instructions.
12535 @item -mno-dwarf2-asm
12536 @itemx -mdwarf2-asm
12537 @opindex mno-dwarf2-asm
12538 @opindex mdwarf2-asm
12539 Don't (or do) generate assembler code for the DWARF2 line number debugging
12540 info. This may be useful when not using the GNU assembler.
12542 @item -mearly-stop-bits
12543 @itemx -mno-early-stop-bits
12544 @opindex mearly-stop-bits
12545 @opindex mno-early-stop-bits
12546 Allow stop bits to be placed earlier than immediately preceding the
12547 instruction that triggered the stop bit. This can improve instruction
12548 scheduling, but does not always do so.
12550 @item -mfixed-range=@var{register-range}
12551 @opindex mfixed-range
12552 Generate code treating the given register range as fixed registers.
12553 A fixed register is one that the register allocator can not use. This is
12554 useful when compiling kernel code. A register range is specified as
12555 two registers separated by a dash. Multiple register ranges can be
12556 specified separated by a comma.
12558 @item -mtls-size=@var{tls-size}
12560 Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
12563 @item -mtune=@var{cpu-type}
12565 Tune the instruction scheduling for a particular CPU, Valid values are
12566 itanium, itanium1, merced, itanium2, and mckinley.
12572 Generate code for a 32-bit or 64-bit environment.
12573 The 32-bit environment sets int, long and pointer to 32 bits.
12574 The 64-bit environment sets int to 32 bits and long and pointer
12575 to 64 bits. These are HP-UX specific flags.
12577 @item -mno-sched-br-data-spec
12578 @itemx -msched-br-data-spec
12579 @opindex mno-sched-br-data-spec
12580 @opindex msched-br-data-spec
12581 (Dis/En)able data speculative scheduling before reload.
12582 This will result in generation of the ld.a instructions and
12583 the corresponding check instructions (ld.c / chk.a).
12584 The default is 'disable'.
12586 @item -msched-ar-data-spec
12587 @itemx -mno-sched-ar-data-spec
12588 @opindex msched-ar-data-spec
12589 @opindex mno-sched-ar-data-spec
12590 (En/Dis)able data speculative scheduling after reload.
12591 This will result in generation of the ld.a instructions and
12592 the corresponding check instructions (ld.c / chk.a).
12593 The default is 'enable'.
12595 @item -mno-sched-control-spec
12596 @itemx -msched-control-spec
12597 @opindex mno-sched-control-spec
12598 @opindex msched-control-spec
12599 (Dis/En)able control speculative scheduling. This feature is
12600 available only during region scheduling (i.e.@: before reload).
12601 This will result in generation of the ld.s instructions and
12602 the corresponding check instructions chk.s .
12603 The default is 'disable'.
12605 @item -msched-br-in-data-spec
12606 @itemx -mno-sched-br-in-data-spec
12607 @opindex msched-br-in-data-spec
12608 @opindex mno-sched-br-in-data-spec
12609 (En/Dis)able speculative scheduling of the instructions that
12610 are dependent on the data speculative loads before reload.
12611 This is effective only with @option{-msched-br-data-spec} enabled.
12612 The default is 'enable'.
12614 @item -msched-ar-in-data-spec
12615 @itemx -mno-sched-ar-in-data-spec
12616 @opindex msched-ar-in-data-spec
12617 @opindex mno-sched-ar-in-data-spec
12618 (En/Dis)able speculative scheduling of the instructions that
12619 are dependent on the data speculative loads after reload.
12620 This is effective only with @option{-msched-ar-data-spec} enabled.
12621 The default is 'enable'.
12623 @item -msched-in-control-spec
12624 @itemx -mno-sched-in-control-spec
12625 @opindex msched-in-control-spec
12626 @opindex mno-sched-in-control-spec
12627 (En/Dis)able speculative scheduling of the instructions that
12628 are dependent on the control speculative loads.
12629 This is effective only with @option{-msched-control-spec} enabled.
12630 The default is 'enable'.
12632 @item -mno-sched-prefer-non-data-spec-insns
12633 @itemx -msched-prefer-non-data-spec-insns
12634 @opindex mno-sched-prefer-non-data-spec-insns
12635 @opindex msched-prefer-non-data-spec-insns
12636 If enabled, data speculative instructions will be chosen for schedule
12637 only if there are no other choices at the moment. This will make
12638 the use of the data speculation much more conservative.
12639 The default is 'disable'.
12641 @item -mno-sched-prefer-non-control-spec-insns
12642 @itemx -msched-prefer-non-control-spec-insns
12643 @opindex mno-sched-prefer-non-control-spec-insns
12644 @opindex msched-prefer-non-control-spec-insns
12645 If enabled, control speculative instructions will be chosen for schedule
12646 only if there are no other choices at the moment. This will make
12647 the use of the control speculation much more conservative.
12648 The default is 'disable'.
12650 @item -mno-sched-count-spec-in-critical-path
12651 @itemx -msched-count-spec-in-critical-path
12652 @opindex mno-sched-count-spec-in-critical-path
12653 @opindex msched-count-spec-in-critical-path
12654 If enabled, speculative dependencies will be considered during
12655 computation of the instructions priorities. This will make the use of the
12656 speculation a bit more conservative.
12657 The default is 'disable'.
12659 @item -msched-spec-ldc
12660 @opindex msched-spec-ldc
12661 Use a simple data speculation check. This option is on by default.
12663 @item -msched-control-spec-ldc
12664 @opindex msched-spec-ldc
12665 Use a simple check for control speculation. This option is on by default.
12667 @item -msched-stop-bits-after-every-cycle
12668 @opindex msched-stop-bits-after-every-cycle
12669 Place a stop bit after every cycle when scheduling. This option is on
12672 @item -msched-fp-mem-deps-zero-cost
12673 @opindex msched-fp-mem-deps-zero-cost
12674 Assume that floating-point stores and loads are not likely to cause a conflict
12675 when placed into the same instruction group. This option is disabled by
12678 @item -msel-sched-dont-check-control-spec
12679 @opindex msel-sched-dont-check-control-spec
12680 Generate checks for control speculation in selective scheduling.
12681 This flag is disabled by default.
12683 @item -msched-max-memory-insns=@var{max-insns}
12684 @opindex msched-max-memory-insns
12685 Limit on the number of memory insns per instruction group, giving lower
12686 priority to subsequent memory insns attempting to schedule in the same
12687 instruction group. Frequently useful to prevent cache bank conflicts.
12688 The default value is 1.
12690 @item -msched-max-memory-insns-hard-limit
12691 @opindex msched-max-memory-insns-hard-limit
12692 Disallow more than `msched-max-memory-insns' in instruction group.
12693 Otherwise, limit is `soft' meaning that we would prefer non-memory operations
12694 when limit is reached but may still schedule memory operations.
12698 @node IA-64/VMS Options
12699 @subsection IA-64/VMS Options
12701 These @samp{-m} options are defined for the IA-64/VMS implementations:
12704 @item -mvms-return-codes
12705 @opindex mvms-return-codes
12706 Return VMS condition codes from main. The default is to return POSIX
12707 style condition (e.g.@ error) codes.
12709 @item -mdebug-main=@var{prefix}
12710 @opindex mdebug-main=@var{prefix}
12711 Flag the first routine whose name starts with @var{prefix} as the main
12712 routine for the debugger.
12716 Default to 64bit memory allocation routines.
12720 @subsection LM32 Options
12721 @cindex LM32 options
12723 These @option{-m} options are defined for the Lattice Mico32 architecture:
12726 @item -mbarrel-shift-enabled
12727 @opindex mbarrel-shift-enabled
12728 Enable barrel-shift instructions.
12730 @item -mdivide-enabled
12731 @opindex mdivide-enabled
12732 Enable divide and modulus instructions.
12734 @item -mmultiply-enabled
12735 @opindex multiply-enabled
12736 Enable multiply instructions.
12738 @item -msign-extend-enabled
12739 @opindex msign-extend-enabled
12740 Enable sign extend instructions.
12742 @item -muser-enabled
12743 @opindex muser-enabled
12744 Enable user-defined instructions.
12749 @subsection M32C Options
12750 @cindex M32C options
12753 @item -mcpu=@var{name}
12755 Select the CPU for which code is generated. @var{name} may be one of
12756 @samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
12757 /60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
12758 the M32C/80 series.
12762 Specifies that the program will be run on the simulator. This causes
12763 an alternate runtime library to be linked in which supports, for
12764 example, file I/O@. You must not use this option when generating
12765 programs that will run on real hardware; you must provide your own
12766 runtime library for whatever I/O functions are needed.
12768 @item -memregs=@var{number}
12770 Specifies the number of memory-based pseudo-registers GCC will use
12771 during code generation. These pseudo-registers will be used like real
12772 registers, so there is a tradeoff between GCC's ability to fit the
12773 code into available registers, and the performance penalty of using
12774 memory instead of registers. Note that all modules in a program must
12775 be compiled with the same value for this option. Because of that, you
12776 must not use this option with the default runtime libraries gcc
12781 @node M32R/D Options
12782 @subsection M32R/D Options
12783 @cindex M32R/D options
12785 These @option{-m} options are defined for Renesas M32R/D architectures:
12790 Generate code for the M32R/2@.
12794 Generate code for the M32R/X@.
12798 Generate code for the M32R@. This is the default.
12800 @item -mmodel=small
12801 @opindex mmodel=small
12802 Assume all objects live in the lower 16MB of memory (so that their addresses
12803 can be loaded with the @code{ld24} instruction), and assume all subroutines
12804 are reachable with the @code{bl} instruction.
12805 This is the default.
12807 The addressability of a particular object can be set with the
12808 @code{model} attribute.
12810 @item -mmodel=medium
12811 @opindex mmodel=medium
12812 Assume objects may be anywhere in the 32-bit address space (the compiler
12813 will generate @code{seth/add3} instructions to load their addresses), and
12814 assume all subroutines are reachable with the @code{bl} instruction.
12816 @item -mmodel=large
12817 @opindex mmodel=large
12818 Assume objects may be anywhere in the 32-bit address space (the compiler
12819 will generate @code{seth/add3} instructions to load their addresses), and
12820 assume subroutines may not be reachable with the @code{bl} instruction
12821 (the compiler will generate the much slower @code{seth/add3/jl}
12822 instruction sequence).
12825 @opindex msdata=none
12826 Disable use of the small data area. Variables will be put into
12827 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
12828 @code{section} attribute has been specified).
12829 This is the default.
12831 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
12832 Objects may be explicitly put in the small data area with the
12833 @code{section} attribute using one of these sections.
12835 @item -msdata=sdata
12836 @opindex msdata=sdata
12837 Put small global and static data in the small data area, but do not
12838 generate special code to reference them.
12841 @opindex msdata=use
12842 Put small global and static data in the small data area, and generate
12843 special instructions to reference them.
12847 @cindex smaller data references
12848 Put global and static objects less than or equal to @var{num} bytes
12849 into the small data or bss sections instead of the normal data or bss
12850 sections. The default value of @var{num} is 8.
12851 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
12852 for this option to have any effect.
12854 All modules should be compiled with the same @option{-G @var{num}} value.
12855 Compiling with different values of @var{num} may or may not work; if it
12856 doesn't the linker will give an error message---incorrect code will not be
12861 Makes the M32R specific code in the compiler display some statistics
12862 that might help in debugging programs.
12864 @item -malign-loops
12865 @opindex malign-loops
12866 Align all loops to a 32-byte boundary.
12868 @item -mno-align-loops
12869 @opindex mno-align-loops
12870 Do not enforce a 32-byte alignment for loops. This is the default.
12872 @item -missue-rate=@var{number}
12873 @opindex missue-rate=@var{number}
12874 Issue @var{number} instructions per cycle. @var{number} can only be 1
12877 @item -mbranch-cost=@var{number}
12878 @opindex mbranch-cost=@var{number}
12879 @var{number} can only be 1 or 2. If it is 1 then branches will be
12880 preferred over conditional code, if it is 2, then the opposite will
12883 @item -mflush-trap=@var{number}
12884 @opindex mflush-trap=@var{number}
12885 Specifies the trap number to use to flush the cache. The default is
12886 12. Valid numbers are between 0 and 15 inclusive.
12888 @item -mno-flush-trap
12889 @opindex mno-flush-trap
12890 Specifies that the cache cannot be flushed by using a trap.
12892 @item -mflush-func=@var{name}
12893 @opindex mflush-func=@var{name}
12894 Specifies the name of the operating system function to call to flush
12895 the cache. The default is @emph{_flush_cache}, but a function call
12896 will only be used if a trap is not available.
12898 @item -mno-flush-func
12899 @opindex mno-flush-func
12900 Indicates that there is no OS function for flushing the cache.
12904 @node M680x0 Options
12905 @subsection M680x0 Options
12906 @cindex M680x0 options
12908 These are the @samp{-m} options defined for M680x0 and ColdFire processors.
12909 The default settings depend on which architecture was selected when
12910 the compiler was configured; the defaults for the most common choices
12914 @item -march=@var{arch}
12916 Generate code for a specific M680x0 or ColdFire instruction set
12917 architecture. Permissible values of @var{arch} for M680x0
12918 architectures are: @samp{68000}, @samp{68010}, @samp{68020},
12919 @samp{68030}, @samp{68040}, @samp{68060} and @samp{cpu32}. ColdFire
12920 architectures are selected according to Freescale's ISA classification
12921 and the permissible values are: @samp{isaa}, @samp{isaaplus},
12922 @samp{isab} and @samp{isac}.
12924 gcc defines a macro @samp{__mcf@var{arch}__} whenever it is generating
12925 code for a ColdFire target. The @var{arch} in this macro is one of the
12926 @option{-march} arguments given above.
12928 When used together, @option{-march} and @option{-mtune} select code
12929 that runs on a family of similar processors but that is optimized
12930 for a particular microarchitecture.
12932 @item -mcpu=@var{cpu}
12934 Generate code for a specific M680x0 or ColdFire processor.
12935 The M680x0 @var{cpu}s are: @samp{68000}, @samp{68010}, @samp{68020},
12936 @samp{68030}, @samp{68040}, @samp{68060}, @samp{68302}, @samp{68332}
12937 and @samp{cpu32}. The ColdFire @var{cpu}s are given by the table
12938 below, which also classifies the CPUs into families:
12940 @multitable @columnfractions 0.20 0.80
12941 @item @strong{Family} @tab @strong{@samp{-mcpu} arguments}
12942 @item @samp{51} @tab @samp{51} @samp{51ac} @samp{51cn} @samp{51em} @samp{51qe}
12943 @item @samp{5206} @tab @samp{5202} @samp{5204} @samp{5206}
12944 @item @samp{5206e} @tab @samp{5206e}
12945 @item @samp{5208} @tab @samp{5207} @samp{5208}
12946 @item @samp{5211a} @tab @samp{5210a} @samp{5211a}
12947 @item @samp{5213} @tab @samp{5211} @samp{5212} @samp{5213}
12948 @item @samp{5216} @tab @samp{5214} @samp{5216}
12949 @item @samp{52235} @tab @samp{52230} @samp{52231} @samp{52232} @samp{52233} @samp{52234} @samp{52235}
12950 @item @samp{5225} @tab @samp{5224} @samp{5225}
12951 @item @samp{52259} @tab @samp{52252} @samp{52254} @samp{52255} @samp{52256} @samp{52258} @samp{52259}
12952 @item @samp{5235} @tab @samp{5232} @samp{5233} @samp{5234} @samp{5235} @samp{523x}
12953 @item @samp{5249} @tab @samp{5249}
12954 @item @samp{5250} @tab @samp{5250}
12955 @item @samp{5271} @tab @samp{5270} @samp{5271}
12956 @item @samp{5272} @tab @samp{5272}
12957 @item @samp{5275} @tab @samp{5274} @samp{5275}
12958 @item @samp{5282} @tab @samp{5280} @samp{5281} @samp{5282} @samp{528x}
12959 @item @samp{53017} @tab @samp{53011} @samp{53012} @samp{53013} @samp{53014} @samp{53015} @samp{53016} @samp{53017}
12960 @item @samp{5307} @tab @samp{5307}
12961 @item @samp{5329} @tab @samp{5327} @samp{5328} @samp{5329} @samp{532x}
12962 @item @samp{5373} @tab @samp{5372} @samp{5373} @samp{537x}
12963 @item @samp{5407} @tab @samp{5407}
12964 @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}
12967 @option{-mcpu=@var{cpu}} overrides @option{-march=@var{arch}} if
12968 @var{arch} is compatible with @var{cpu}. Other combinations of
12969 @option{-mcpu} and @option{-march} are rejected.
12971 gcc defines the macro @samp{__mcf_cpu_@var{cpu}} when ColdFire target
12972 @var{cpu} is selected. It also defines @samp{__mcf_family_@var{family}},
12973 where the value of @var{family} is given by the table above.
12975 @item -mtune=@var{tune}
12977 Tune the code for a particular microarchitecture, within the
12978 constraints set by @option{-march} and @option{-mcpu}.
12979 The M680x0 microarchitectures are: @samp{68000}, @samp{68010},
12980 @samp{68020}, @samp{68030}, @samp{68040}, @samp{68060}
12981 and @samp{cpu32}. The ColdFire microarchitectures
12982 are: @samp{cfv1}, @samp{cfv2}, @samp{cfv3}, @samp{cfv4} and @samp{cfv4e}.
12984 You can also use @option{-mtune=68020-40} for code that needs
12985 to run relatively well on 68020, 68030 and 68040 targets.
12986 @option{-mtune=68020-60} is similar but includes 68060 targets
12987 as well. These two options select the same tuning decisions as
12988 @option{-m68020-40} and @option{-m68020-60} respectively.
12990 gcc defines the macros @samp{__mc@var{arch}} and @samp{__mc@var{arch}__}
12991 when tuning for 680x0 architecture @var{arch}. It also defines
12992 @samp{mc@var{arch}} unless either @option{-ansi} or a non-GNU @option{-std}
12993 option is used. If gcc is tuning for a range of architectures,
12994 as selected by @option{-mtune=68020-40} or @option{-mtune=68020-60},
12995 it defines the macros for every architecture in the range.
12997 gcc also defines the macro @samp{__m@var{uarch}__} when tuning for
12998 ColdFire microarchitecture @var{uarch}, where @var{uarch} is one
12999 of the arguments given above.
13005 Generate output for a 68000. This is the default
13006 when the compiler is configured for 68000-based systems.
13007 It is equivalent to @option{-march=68000}.
13009 Use this option for microcontrollers with a 68000 or EC000 core,
13010 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
13014 Generate output for a 68010. This is the default
13015 when the compiler is configured for 68010-based systems.
13016 It is equivalent to @option{-march=68010}.
13022 Generate output for a 68020. This is the default
13023 when the compiler is configured for 68020-based systems.
13024 It is equivalent to @option{-march=68020}.
13028 Generate output for a 68030. This is the default when the compiler is
13029 configured for 68030-based systems. It is equivalent to
13030 @option{-march=68030}.
13034 Generate output for a 68040. This is the default when the compiler is
13035 configured for 68040-based systems. It is equivalent to
13036 @option{-march=68040}.
13038 This option inhibits the use of 68881/68882 instructions that have to be
13039 emulated by software on the 68040. Use this option if your 68040 does not
13040 have code to emulate those instructions.
13044 Generate output for a 68060. This is the default when the compiler is
13045 configured for 68060-based systems. It is equivalent to
13046 @option{-march=68060}.
13048 This option inhibits the use of 68020 and 68881/68882 instructions that
13049 have to be emulated by software on the 68060. Use this option if your 68060
13050 does not have code to emulate those instructions.
13054 Generate output for a CPU32. This is the default
13055 when the compiler is configured for CPU32-based systems.
13056 It is equivalent to @option{-march=cpu32}.
13058 Use this option for microcontrollers with a
13059 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
13060 68336, 68340, 68341, 68349 and 68360.
13064 Generate output for a 520X ColdFire CPU@. This is the default
13065 when the compiler is configured for 520X-based systems.
13066 It is equivalent to @option{-mcpu=5206}, and is now deprecated
13067 in favor of that option.
13069 Use this option for microcontroller with a 5200 core, including
13070 the MCF5202, MCF5203, MCF5204 and MCF5206.
13074 Generate output for a 5206e ColdFire CPU@. The option is now
13075 deprecated in favor of the equivalent @option{-mcpu=5206e}.
13079 Generate output for a member of the ColdFire 528X family.
13080 The option is now deprecated in favor of the equivalent
13081 @option{-mcpu=528x}.
13085 Generate output for a ColdFire 5307 CPU@. The option is now deprecated
13086 in favor of the equivalent @option{-mcpu=5307}.
13090 Generate output for a ColdFire 5407 CPU@. The option is now deprecated
13091 in favor of the equivalent @option{-mcpu=5407}.
13095 Generate output for a ColdFire V4e family CPU (e.g.@: 547x/548x).
13096 This includes use of hardware floating point instructions.
13097 The option is equivalent to @option{-mcpu=547x}, and is now
13098 deprecated in favor of that option.
13102 Generate output for a 68040, without using any of the new instructions.
13103 This results in code which can run relatively efficiently on either a
13104 68020/68881 or a 68030 or a 68040. The generated code does use the
13105 68881 instructions that are emulated on the 68040.
13107 The option is equivalent to @option{-march=68020} @option{-mtune=68020-40}.
13111 Generate output for a 68060, without using any of the new instructions.
13112 This results in code which can run relatively efficiently on either a
13113 68020/68881 or a 68030 or a 68040. The generated code does use the
13114 68881 instructions that are emulated on the 68060.
13116 The option is equivalent to @option{-march=68020} @option{-mtune=68020-60}.
13120 @opindex mhard-float
13122 Generate floating-point instructions. This is the default for 68020
13123 and above, and for ColdFire devices that have an FPU@. It defines the
13124 macro @samp{__HAVE_68881__} on M680x0 targets and @samp{__mcffpu__}
13125 on ColdFire targets.
13128 @opindex msoft-float
13129 Do not generate floating-point instructions; use library calls instead.
13130 This is the default for 68000, 68010, and 68832 targets. It is also
13131 the default for ColdFire devices that have no FPU.
13137 Generate (do not generate) ColdFire hardware divide and remainder
13138 instructions. If @option{-march} is used without @option{-mcpu},
13139 the default is ``on'' for ColdFire architectures and ``off'' for M680x0
13140 architectures. Otherwise, the default is taken from the target CPU
13141 (either the default CPU, or the one specified by @option{-mcpu}). For
13142 example, the default is ``off'' for @option{-mcpu=5206} and ``on'' for
13143 @option{-mcpu=5206e}.
13145 gcc defines the macro @samp{__mcfhwdiv__} when this option is enabled.
13149 Consider type @code{int} to be 16 bits wide, like @code{short int}.
13150 Additionally, parameters passed on the stack are also aligned to a
13151 16-bit boundary even on targets whose API mandates promotion to 32-bit.
13155 Do not consider type @code{int} to be 16 bits wide. This is the default.
13158 @itemx -mno-bitfield
13159 @opindex mnobitfield
13160 @opindex mno-bitfield
13161 Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
13162 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
13166 Do use the bit-field instructions. The @option{-m68020} option implies
13167 @option{-mbitfield}. This is the default if you use a configuration
13168 designed for a 68020.
13172 Use a different function-calling convention, in which functions
13173 that take a fixed number of arguments return with the @code{rtd}
13174 instruction, which pops their arguments while returning. This
13175 saves one instruction in the caller since there is no need to pop
13176 the arguments there.
13178 This calling convention is incompatible with the one normally
13179 used on Unix, so you cannot use it if you need to call libraries
13180 compiled with the Unix compiler.
13182 Also, you must provide function prototypes for all functions that
13183 take variable numbers of arguments (including @code{printf});
13184 otherwise incorrect code will be generated for calls to those
13187 In addition, seriously incorrect code will result if you call a
13188 function with too many arguments. (Normally, extra arguments are
13189 harmlessly ignored.)
13191 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
13192 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
13196 Do not use the calling conventions selected by @option{-mrtd}.
13197 This is the default.
13200 @itemx -mno-align-int
13201 @opindex malign-int
13202 @opindex mno-align-int
13203 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
13204 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
13205 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
13206 Aligning variables on 32-bit boundaries produces code that runs somewhat
13207 faster on processors with 32-bit busses at the expense of more memory.
13209 @strong{Warning:} if you use the @option{-malign-int} switch, GCC will
13210 align structures containing the above types differently than
13211 most published application binary interface specifications for the m68k.
13215 Use the pc-relative addressing mode of the 68000 directly, instead of
13216 using a global offset table. At present, this option implies @option{-fpic},
13217 allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
13218 not presently supported with @option{-mpcrel}, though this could be supported for
13219 68020 and higher processors.
13221 @item -mno-strict-align
13222 @itemx -mstrict-align
13223 @opindex mno-strict-align
13224 @opindex mstrict-align
13225 Do not (do) assume that unaligned memory references will be handled by
13229 Generate code that allows the data segment to be located in a different
13230 area of memory from the text segment. This allows for execute in place in
13231 an environment without virtual memory management. This option implies
13234 @item -mno-sep-data
13235 Generate code that assumes that the data segment follows the text segment.
13236 This is the default.
13238 @item -mid-shared-library
13239 Generate code that supports shared libraries via the library ID method.
13240 This allows for execute in place and shared libraries in an environment
13241 without virtual memory management. This option implies @option{-fPIC}.
13243 @item -mno-id-shared-library
13244 Generate code that doesn't assume ID based shared libraries are being used.
13245 This is the default.
13247 @item -mshared-library-id=n
13248 Specified the identification number of the ID based shared library being
13249 compiled. Specifying a value of 0 will generate more compact code, specifying
13250 other values will force the allocation of that number to the current
13251 library but is no more space or time efficient than omitting this option.
13257 When generating position-independent code for ColdFire, generate code
13258 that works if the GOT has more than 8192 entries. This code is
13259 larger and slower than code generated without this option. On M680x0
13260 processors, this option is not needed; @option{-fPIC} suffices.
13262 GCC normally uses a single instruction to load values from the GOT@.
13263 While this is relatively efficient, it only works if the GOT
13264 is smaller than about 64k. Anything larger causes the linker
13265 to report an error such as:
13267 @cindex relocation truncated to fit (ColdFire)
13269 relocation truncated to fit: R_68K_GOT16O foobar
13272 If this happens, you should recompile your code with @option{-mxgot}.
13273 It should then work with very large GOTs. However, code generated with
13274 @option{-mxgot} is less efficient, since it takes 4 instructions to fetch
13275 the value of a global symbol.
13277 Note that some linkers, including newer versions of the GNU linker,
13278 can create multiple GOTs and sort GOT entries. If you have such a linker,
13279 you should only need to use @option{-mxgot} when compiling a single
13280 object file that accesses more than 8192 GOT entries. Very few do.
13282 These options have no effect unless GCC is generating
13283 position-independent code.
13287 @node M68hc1x Options
13288 @subsection M68hc1x Options
13289 @cindex M68hc1x options
13291 These are the @samp{-m} options defined for the 68hc11 and 68hc12
13292 microcontrollers. The default values for these options depends on
13293 which style of microcontroller was selected when the compiler was configured;
13294 the defaults for the most common choices are given below.
13301 Generate output for a 68HC11. This is the default
13302 when the compiler is configured for 68HC11-based systems.
13308 Generate output for a 68HC12. This is the default
13309 when the compiler is configured for 68HC12-based systems.
13315 Generate output for a 68HCS12.
13317 @item -mauto-incdec
13318 @opindex mauto-incdec
13319 Enable the use of 68HC12 pre and post auto-increment and auto-decrement
13326 Enable the use of 68HC12 min and max instructions.
13329 @itemx -mno-long-calls
13330 @opindex mlong-calls
13331 @opindex mno-long-calls
13332 Treat all calls as being far away (near). If calls are assumed to be
13333 far away, the compiler will use the @code{call} instruction to
13334 call a function and the @code{rtc} instruction for returning.
13338 Consider type @code{int} to be 16 bits wide, like @code{short int}.
13340 @item -msoft-reg-count=@var{count}
13341 @opindex msoft-reg-count
13342 Specify the number of pseudo-soft registers which are used for the
13343 code generation. The maximum number is 32. Using more pseudo-soft
13344 register may or may not result in better code depending on the program.
13345 The default is 4 for 68HC11 and 2 for 68HC12.
13349 @node MCore Options
13350 @subsection MCore Options
13351 @cindex MCore options
13353 These are the @samp{-m} options defined for the Motorola M*Core
13359 @itemx -mno-hardlit
13361 @opindex mno-hardlit
13362 Inline constants into the code stream if it can be done in two
13363 instructions or less.
13369 Use the divide instruction. (Enabled by default).
13371 @item -mrelax-immediate
13372 @itemx -mno-relax-immediate
13373 @opindex mrelax-immediate
13374 @opindex mno-relax-immediate
13375 Allow arbitrary sized immediates in bit operations.
13377 @item -mwide-bitfields
13378 @itemx -mno-wide-bitfields
13379 @opindex mwide-bitfields
13380 @opindex mno-wide-bitfields
13381 Always treat bit-fields as int-sized.
13383 @item -m4byte-functions
13384 @itemx -mno-4byte-functions
13385 @opindex m4byte-functions
13386 @opindex mno-4byte-functions
13387 Force all functions to be aligned to a four byte boundary.
13389 @item -mcallgraph-data
13390 @itemx -mno-callgraph-data
13391 @opindex mcallgraph-data
13392 @opindex mno-callgraph-data
13393 Emit callgraph information.
13396 @itemx -mno-slow-bytes
13397 @opindex mslow-bytes
13398 @opindex mno-slow-bytes
13399 Prefer word access when reading byte quantities.
13401 @item -mlittle-endian
13402 @itemx -mbig-endian
13403 @opindex mlittle-endian
13404 @opindex mbig-endian
13405 Generate code for a little endian target.
13411 Generate code for the 210 processor.
13415 Assume that run-time support has been provided and so omit the
13416 simulator library (@file{libsim.a)} from the linker command line.
13418 @item -mstack-increment=@var{size}
13419 @opindex mstack-increment
13420 Set the maximum amount for a single stack increment operation. Large
13421 values can increase the speed of programs which contain functions
13422 that need a large amount of stack space, but they can also trigger a
13423 segmentation fault if the stack is extended too much. The default
13429 @subsection MeP Options
13430 @cindex MeP options
13436 Enables the @code{abs} instruction, which is the absolute difference
13437 between two registers.
13441 Enables all the optional instructions - average, multiply, divide, bit
13442 operations, leading zero, absolute difference, min/max, clip, and
13448 Enables the @code{ave} instruction, which computes the average of two
13451 @item -mbased=@var{n}
13453 Variables of size @var{n} bytes or smaller will be placed in the
13454 @code{.based} section by default. Based variables use the @code{$tp}
13455 register as a base register, and there is a 128 byte limit to the
13456 @code{.based} section.
13460 Enables the bit operation instructions - bit test (@code{btstm}), set
13461 (@code{bsetm}), clear (@code{bclrm}), invert (@code{bnotm}), and
13462 test-and-set (@code{tas}).
13464 @item -mc=@var{name}
13466 Selects which section constant data will be placed in. @var{name} may
13467 be @code{tiny}, @code{near}, or @code{far}.
13471 Enables the @code{clip} instruction. Note that @code{-mclip} is not
13472 useful unless you also provide @code{-mminmax}.
13474 @item -mconfig=@var{name}
13476 Selects one of the build-in core configurations. Each MeP chip has
13477 one or more modules in it; each module has a core CPU and a variety of
13478 coprocessors, optional instructions, and peripherals. The
13479 @code{MeP-Integrator} tool, not part of GCC, provides these
13480 configurations through this option; using this option is the same as
13481 using all the corresponding command line options. The default
13482 configuration is @code{default}.
13486 Enables the coprocessor instructions. By default, this is a 32-bit
13487 coprocessor. Note that the coprocessor is normally enabled via the
13488 @code{-mconfig=} option.
13492 Enables the 32-bit coprocessor's instructions.
13496 Enables the 64-bit coprocessor's instructions.
13500 Enables IVC2 scheduling. IVC2 is a 64-bit VLIW coprocessor.
13504 Causes constant variables to be placed in the @code{.near} section.
13508 Enables the @code{div} and @code{divu} instructions.
13512 Generate big-endian code.
13516 Generate little-endian code.
13518 @item -mio-volatile
13519 @opindex mio-volatile
13520 Tells the compiler that any variable marked with the @code{io}
13521 attribute is to be considered volatile.
13525 Causes variables to be assigned to the @code{.far} section by default.
13529 Enables the @code{leadz} (leading zero) instruction.
13533 Causes variables to be assigned to the @code{.near} section by default.
13537 Enables the @code{min} and @code{max} instructions.
13541 Enables the multiplication and multiply-accumulate instructions.
13545 Disables all the optional instructions enabled by @code{-mall-opts}.
13549 Enables the @code{repeat} and @code{erepeat} instructions, used for
13550 low-overhead looping.
13554 Causes all variables to default to the @code{.tiny} section. Note
13555 that there is a 65536 byte limit to this section. Accesses to these
13556 variables use the @code{%gp} base register.
13560 Enables the saturation instructions. Note that the compiler does not
13561 currently generate these itself, but this option is included for
13562 compatibility with other tools, like @code{as}.
13566 Link the SDRAM-based runtime instead of the default ROM-based runtime.
13570 Link the simulator runtime libraries.
13574 Link the simulator runtime libraries, excluding built-in support
13575 for reset and exception vectors and tables.
13579 Causes all functions to default to the @code{.far} section. Without
13580 this option, functions default to the @code{.near} section.
13582 @item -mtiny=@var{n}
13584 Variables that are @var{n} bytes or smaller will be allocated to the
13585 @code{.tiny} section. These variables use the @code{$gp} base
13586 register. The default for this option is 4, but note that there's a
13587 65536 byte limit to the @code{.tiny} section.
13592 @subsection MIPS Options
13593 @cindex MIPS options
13599 Generate big-endian code.
13603 Generate little-endian code. This is the default for @samp{mips*el-*-*}
13606 @item -march=@var{arch}
13608 Generate code that will run on @var{arch}, which can be the name of a
13609 generic MIPS ISA, or the name of a particular processor.
13611 @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
13612 @samp{mips32}, @samp{mips32r2}, @samp{mips64} and @samp{mips64r2}.
13613 The processor names are:
13614 @samp{4kc}, @samp{4km}, @samp{4kp}, @samp{4ksc},
13615 @samp{4kec}, @samp{4kem}, @samp{4kep}, @samp{4ksd},
13616 @samp{5kc}, @samp{5kf},
13618 @samp{24kc}, @samp{24kf2_1}, @samp{24kf1_1},
13619 @samp{24kec}, @samp{24kef2_1}, @samp{24kef1_1},
13620 @samp{34kc}, @samp{34kf2_1}, @samp{34kf1_1},
13621 @samp{74kc}, @samp{74kf2_1}, @samp{74kf1_1}, @samp{74kf3_2},
13622 @samp{1004kc}, @samp{1004kf2_1}, @samp{1004kf1_1},
13623 @samp{loongson2e}, @samp{loongson2f},
13627 @samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
13628 @samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
13629 @samp{rm7000}, @samp{rm9000},
13630 @samp{r10000}, @samp{r12000}, @samp{r14000}, @samp{r16000},
13633 @samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
13634 @samp{vr5000}, @samp{vr5400}, @samp{vr5500}
13636 The special value @samp{from-abi} selects the
13637 most compatible architecture for the selected ABI (that is,
13638 @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
13640 Native Linux/GNU toolchains also support the value @samp{native},
13641 which selects the best architecture option for the host processor.
13642 @option{-march=native} has no effect if GCC does not recognize
13645 In processor names, a final @samp{000} can be abbreviated as @samp{k}
13646 (for example, @samp{-march=r2k}). Prefixes are optional, and
13647 @samp{vr} may be written @samp{r}.
13649 Names of the form @samp{@var{n}f2_1} refer to processors with
13650 FPUs clocked at half the rate of the core, names of the form
13651 @samp{@var{n}f1_1} refer to processors with FPUs clocked at the same
13652 rate as the core, and names of the form @samp{@var{n}f3_2} refer to
13653 processors with FPUs clocked a ratio of 3:2 with respect to the core.
13654 For compatibility reasons, @samp{@var{n}f} is accepted as a synonym
13655 for @samp{@var{n}f2_1} while @samp{@var{n}x} and @samp{@var{b}fx} are
13656 accepted as synonyms for @samp{@var{n}f1_1}.
13658 GCC defines two macros based on the value of this option. The first
13659 is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
13660 a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
13661 where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
13662 For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
13663 to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
13665 Note that the @samp{_MIPS_ARCH} macro uses the processor names given
13666 above. In other words, it will have the full prefix and will not
13667 abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
13668 the macro names the resolved architecture (either @samp{"mips1"} or
13669 @samp{"mips3"}). It names the default architecture when no
13670 @option{-march} option is given.
13672 @item -mtune=@var{arch}
13674 Optimize for @var{arch}. Among other things, this option controls
13675 the way instructions are scheduled, and the perceived cost of arithmetic
13676 operations. The list of @var{arch} values is the same as for
13679 When this option is not used, GCC will optimize for the processor
13680 specified by @option{-march}. By using @option{-march} and
13681 @option{-mtune} together, it is possible to generate code that will
13682 run on a family of processors, but optimize the code for one
13683 particular member of that family.
13685 @samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
13686 @samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
13687 @samp{-march} ones described above.
13691 Equivalent to @samp{-march=mips1}.
13695 Equivalent to @samp{-march=mips2}.
13699 Equivalent to @samp{-march=mips3}.
13703 Equivalent to @samp{-march=mips4}.
13707 Equivalent to @samp{-march=mips32}.
13711 Equivalent to @samp{-march=mips32r2}.
13715 Equivalent to @samp{-march=mips64}.
13719 Equivalent to @samp{-march=mips64r2}.
13724 @opindex mno-mips16
13725 Generate (do not generate) MIPS16 code. If GCC is targetting a
13726 MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
13728 MIPS16 code generation can also be controlled on a per-function basis
13729 by means of @code{mips16} and @code{nomips16} attributes.
13730 @xref{Function Attributes}, for more information.
13732 @item -mflip-mips16
13733 @opindex mflip-mips16
13734 Generate MIPS16 code on alternating functions. This option is provided
13735 for regression testing of mixed MIPS16/non-MIPS16 code generation, and is
13736 not intended for ordinary use in compiling user code.
13738 @item -minterlink-mips16
13739 @itemx -mno-interlink-mips16
13740 @opindex minterlink-mips16
13741 @opindex mno-interlink-mips16
13742 Require (do not require) that non-MIPS16 code be link-compatible with
13745 For example, non-MIPS16 code cannot jump directly to MIPS16 code;
13746 it must either use a call or an indirect jump. @option{-minterlink-mips16}
13747 therefore disables direct jumps unless GCC knows that the target of the
13748 jump is not MIPS16.
13760 Generate code for the given ABI@.
13762 Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
13763 generates 64-bit code when you select a 64-bit architecture, but you
13764 can use @option{-mgp32} to get 32-bit code instead.
13766 For information about the O64 ABI, see
13767 @w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
13769 GCC supports a variant of the o32 ABI in which floating-point registers
13770 are 64 rather than 32 bits wide. You can select this combination with
13771 @option{-mabi=32} @option{-mfp64}. This ABI relies on the @samp{mthc1}
13772 and @samp{mfhc1} instructions and is therefore only supported for
13773 MIPS32R2 processors.
13775 The register assignments for arguments and return values remain the
13776 same, but each scalar value is passed in a single 64-bit register
13777 rather than a pair of 32-bit registers. For example, scalar
13778 floating-point values are returned in @samp{$f0} only, not a
13779 @samp{$f0}/@samp{$f1} pair. The set of call-saved registers also
13780 remains the same, but all 64 bits are saved.
13783 @itemx -mno-abicalls
13785 @opindex mno-abicalls
13786 Generate (do not generate) code that is suitable for SVR4-style
13787 dynamic objects. @option{-mabicalls} is the default for SVR4-based
13792 Generate (do not generate) code that is fully position-independent,
13793 and that can therefore be linked into shared libraries. This option
13794 only affects @option{-mabicalls}.
13796 All @option{-mabicalls} code has traditionally been position-independent,
13797 regardless of options like @option{-fPIC} and @option{-fpic}. However,
13798 as an extension, the GNU toolchain allows executables to use absolute
13799 accesses for locally-binding symbols. It can also use shorter GP
13800 initialization sequences and generate direct calls to locally-defined
13801 functions. This mode is selected by @option{-mno-shared}.
13803 @option{-mno-shared} depends on binutils 2.16 or higher and generates
13804 objects that can only be linked by the GNU linker. However, the option
13805 does not affect the ABI of the final executable; it only affects the ABI
13806 of relocatable objects. Using @option{-mno-shared} will generally make
13807 executables both smaller and quicker.
13809 @option{-mshared} is the default.
13815 Assume (do not assume) that the static and dynamic linkers
13816 support PLTs and copy relocations. This option only affects
13817 @samp{-mno-shared -mabicalls}. For the n64 ABI, this option
13818 has no effect without @samp{-msym32}.
13820 You can make @option{-mplt} the default by configuring
13821 GCC with @option{--with-mips-plt}. The default is
13822 @option{-mno-plt} otherwise.
13828 Lift (do not lift) the usual restrictions on the size of the global
13831 GCC normally uses a single instruction to load values from the GOT@.
13832 While this is relatively efficient, it will only work if the GOT
13833 is smaller than about 64k. Anything larger will cause the linker
13834 to report an error such as:
13836 @cindex relocation truncated to fit (MIPS)
13838 relocation truncated to fit: R_MIPS_GOT16 foobar
13841 If this happens, you should recompile your code with @option{-mxgot}.
13842 It should then work with very large GOTs, although it will also be
13843 less efficient, since it will take three instructions to fetch the
13844 value of a global symbol.
13846 Note that some linkers can create multiple GOTs. If you have such a
13847 linker, you should only need to use @option{-mxgot} when a single object
13848 file accesses more than 64k's worth of GOT entries. Very few do.
13850 These options have no effect unless GCC is generating position
13855 Assume that general-purpose registers are 32 bits wide.
13859 Assume that general-purpose registers are 64 bits wide.
13863 Assume that floating-point registers are 32 bits wide.
13867 Assume that floating-point registers are 64 bits wide.
13870 @opindex mhard-float
13871 Use floating-point coprocessor instructions.
13874 @opindex msoft-float
13875 Do not use floating-point coprocessor instructions. Implement
13876 floating-point calculations using library calls instead.
13878 @item -msingle-float
13879 @opindex msingle-float
13880 Assume that the floating-point coprocessor only supports single-precision
13883 @item -mdouble-float
13884 @opindex mdouble-float
13885 Assume that the floating-point coprocessor supports double-precision
13886 operations. This is the default.
13892 Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to
13893 implement atomic memory built-in functions. When neither option is
13894 specified, GCC will use the instructions if the target architecture
13897 @option{-mllsc} is useful if the runtime environment can emulate the
13898 instructions and @option{-mno-llsc} can be useful when compiling for
13899 nonstandard ISAs. You can make either option the default by
13900 configuring GCC with @option{--with-llsc} and @option{--without-llsc}
13901 respectively. @option{--with-llsc} is the default for some
13902 configurations; see the installation documentation for details.
13908 Use (do not use) revision 1 of the MIPS DSP ASE@.
13909 @xref{MIPS DSP Built-in Functions}. This option defines the
13910 preprocessor macro @samp{__mips_dsp}. It also defines
13911 @samp{__mips_dsp_rev} to 1.
13917 Use (do not use) revision 2 of the MIPS DSP ASE@.
13918 @xref{MIPS DSP Built-in Functions}. This option defines the
13919 preprocessor macros @samp{__mips_dsp} and @samp{__mips_dspr2}.
13920 It also defines @samp{__mips_dsp_rev} to 2.
13923 @itemx -mno-smartmips
13924 @opindex msmartmips
13925 @opindex mno-smartmips
13926 Use (do not use) the MIPS SmartMIPS ASE.
13928 @item -mpaired-single
13929 @itemx -mno-paired-single
13930 @opindex mpaired-single
13931 @opindex mno-paired-single
13932 Use (do not use) paired-single floating-point instructions.
13933 @xref{MIPS Paired-Single Support}. This option requires
13934 hardware floating-point support to be enabled.
13940 Use (do not use) MIPS Digital Media Extension instructions.
13941 This option can only be used when generating 64-bit code and requires
13942 hardware floating-point support to be enabled.
13947 @opindex mno-mips3d
13948 Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
13949 The option @option{-mips3d} implies @option{-mpaired-single}.
13955 Use (do not use) MT Multithreading instructions.
13959 Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
13960 an explanation of the default and the way that the pointer size is
13965 Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
13967 The default size of @code{int}s, @code{long}s and pointers depends on
13968 the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
13969 uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
13970 32-bit @code{long}s. Pointers are the same size as @code{long}s,
13971 or the same size as integer registers, whichever is smaller.
13977 Assume (do not assume) that all symbols have 32-bit values, regardless
13978 of the selected ABI@. This option is useful in combination with
13979 @option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
13980 to generate shorter and faster references to symbolic addresses.
13984 Put definitions of externally-visible data in a small data section
13985 if that data is no bigger than @var{num} bytes. GCC can then access
13986 the data more efficiently; see @option{-mgpopt} for details.
13988 The default @option{-G} option depends on the configuration.
13990 @item -mlocal-sdata
13991 @itemx -mno-local-sdata
13992 @opindex mlocal-sdata
13993 @opindex mno-local-sdata
13994 Extend (do not extend) the @option{-G} behavior to local data too,
13995 such as to static variables in C@. @option{-mlocal-sdata} is the
13996 default for all configurations.
13998 If the linker complains that an application is using too much small data,
13999 you might want to try rebuilding the less performance-critical parts with
14000 @option{-mno-local-sdata}. You might also want to build large
14001 libraries with @option{-mno-local-sdata}, so that the libraries leave
14002 more room for the main program.
14004 @item -mextern-sdata
14005 @itemx -mno-extern-sdata
14006 @opindex mextern-sdata
14007 @opindex mno-extern-sdata
14008 Assume (do not assume) that externally-defined data will be in
14009 a small data section if that data is within the @option{-G} limit.
14010 @option{-mextern-sdata} is the default for all configurations.
14012 If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G
14013 @var{num}} @option{-mgpopt}, and @var{Mod} references a variable @var{Var}
14014 that is no bigger than @var{num} bytes, you must make sure that @var{Var}
14015 is placed in a small data section. If @var{Var} is defined by another
14016 module, you must either compile that module with a high-enough
14017 @option{-G} setting or attach a @code{section} attribute to @var{Var}'s
14018 definition. If @var{Var} is common, you must link the application
14019 with a high-enough @option{-G} setting.
14021 The easiest way of satisfying these restrictions is to compile
14022 and link every module with the same @option{-G} option. However,
14023 you may wish to build a library that supports several different
14024 small data limits. You can do this by compiling the library with
14025 the highest supported @option{-G} setting and additionally using
14026 @option{-mno-extern-sdata} to stop the library from making assumptions
14027 about externally-defined data.
14033 Use (do not use) GP-relative accesses for symbols that are known to be
14034 in a small data section; see @option{-G}, @option{-mlocal-sdata} and
14035 @option{-mextern-sdata}. @option{-mgpopt} is the default for all
14038 @option{-mno-gpopt} is useful for cases where the @code{$gp} register
14039 might not hold the value of @code{_gp}. For example, if the code is
14040 part of a library that might be used in a boot monitor, programs that
14041 call boot monitor routines will pass an unknown value in @code{$gp}.
14042 (In such situations, the boot monitor itself would usually be compiled
14043 with @option{-G0}.)
14045 @option{-mno-gpopt} implies @option{-mno-local-sdata} and
14046 @option{-mno-extern-sdata}.
14048 @item -membedded-data
14049 @itemx -mno-embedded-data
14050 @opindex membedded-data
14051 @opindex mno-embedded-data
14052 Allocate variables to the read-only data section first if possible, then
14053 next in the small data section if possible, otherwise in data. This gives
14054 slightly slower code than the default, but reduces the amount of RAM required
14055 when executing, and thus may be preferred for some embedded systems.
14057 @item -muninit-const-in-rodata
14058 @itemx -mno-uninit-const-in-rodata
14059 @opindex muninit-const-in-rodata
14060 @opindex mno-uninit-const-in-rodata
14061 Put uninitialized @code{const} variables in the read-only data section.
14062 This option is only meaningful in conjunction with @option{-membedded-data}.
14064 @item -mcode-readable=@var{setting}
14065 @opindex mcode-readable
14066 Specify whether GCC may generate code that reads from executable sections.
14067 There are three possible settings:
14070 @item -mcode-readable=yes
14071 Instructions may freely access executable sections. This is the
14074 @item -mcode-readable=pcrel
14075 MIPS16 PC-relative load instructions can access executable sections,
14076 but other instructions must not do so. This option is useful on 4KSc
14077 and 4KSd processors when the code TLBs have the Read Inhibit bit set.
14078 It is also useful on processors that can be configured to have a dual
14079 instruction/data SRAM interface and that, like the M4K, automatically
14080 redirect PC-relative loads to the instruction RAM.
14082 @item -mcode-readable=no
14083 Instructions must not access executable sections. This option can be
14084 useful on targets that are configured to have a dual instruction/data
14085 SRAM interface but that (unlike the M4K) do not automatically redirect
14086 PC-relative loads to the instruction RAM.
14089 @item -msplit-addresses
14090 @itemx -mno-split-addresses
14091 @opindex msplit-addresses
14092 @opindex mno-split-addresses
14093 Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
14094 relocation operators. This option has been superseded by
14095 @option{-mexplicit-relocs} but is retained for backwards compatibility.
14097 @item -mexplicit-relocs
14098 @itemx -mno-explicit-relocs
14099 @opindex mexplicit-relocs
14100 @opindex mno-explicit-relocs
14101 Use (do not use) assembler relocation operators when dealing with symbolic
14102 addresses. The alternative, selected by @option{-mno-explicit-relocs},
14103 is to use assembler macros instead.
14105 @option{-mexplicit-relocs} is the default if GCC was configured
14106 to use an assembler that supports relocation operators.
14108 @item -mcheck-zero-division
14109 @itemx -mno-check-zero-division
14110 @opindex mcheck-zero-division
14111 @opindex mno-check-zero-division
14112 Trap (do not trap) on integer division by zero.
14114 The default is @option{-mcheck-zero-division}.
14116 @item -mdivide-traps
14117 @itemx -mdivide-breaks
14118 @opindex mdivide-traps
14119 @opindex mdivide-breaks
14120 MIPS systems check for division by zero by generating either a
14121 conditional trap or a break instruction. Using traps results in
14122 smaller code, but is only supported on MIPS II and later. Also, some
14123 versions of the Linux kernel have a bug that prevents trap from
14124 generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
14125 allow conditional traps on architectures that support them and
14126 @option{-mdivide-breaks} to force the use of breaks.
14128 The default is usually @option{-mdivide-traps}, but this can be
14129 overridden at configure time using @option{--with-divide=breaks}.
14130 Divide-by-zero checks can be completely disabled using
14131 @option{-mno-check-zero-division}.
14136 @opindex mno-memcpy
14137 Force (do not force) the use of @code{memcpy()} for non-trivial block
14138 moves. The default is @option{-mno-memcpy}, which allows GCC to inline
14139 most constant-sized copies.
14142 @itemx -mno-long-calls
14143 @opindex mlong-calls
14144 @opindex mno-long-calls
14145 Disable (do not disable) use of the @code{jal} instruction. Calling
14146 functions using @code{jal} is more efficient but requires the caller
14147 and callee to be in the same 256 megabyte segment.
14149 This option has no effect on abicalls code. The default is
14150 @option{-mno-long-calls}.
14156 Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
14157 instructions, as provided by the R4650 ISA@.
14160 @itemx -mno-fused-madd
14161 @opindex mfused-madd
14162 @opindex mno-fused-madd
14163 Enable (disable) use of the floating point multiply-accumulate
14164 instructions, when they are available. The default is
14165 @option{-mfused-madd}.
14167 When multiply-accumulate instructions are used, the intermediate
14168 product is calculated to infinite precision and is not subject to
14169 the FCSR Flush to Zero bit. This may be undesirable in some
14174 Tell the MIPS assembler to not run its preprocessor over user
14175 assembler files (with a @samp{.s} suffix) when assembling them.
14178 @itemx -mno-fix-r4000
14179 @opindex mfix-r4000
14180 @opindex mno-fix-r4000
14181 Work around certain R4000 CPU errata:
14184 A double-word or a variable shift may give an incorrect result if executed
14185 immediately after starting an integer division.
14187 A double-word or a variable shift may give an incorrect result if executed
14188 while an integer multiplication is in progress.
14190 An integer division may give an incorrect result if started in a delay slot
14191 of a taken branch or a jump.
14195 @itemx -mno-fix-r4400
14196 @opindex mfix-r4400
14197 @opindex mno-fix-r4400
14198 Work around certain R4400 CPU errata:
14201 A double-word or a variable shift may give an incorrect result if executed
14202 immediately after starting an integer division.
14206 @itemx -mno-fix-r10000
14207 @opindex mfix-r10000
14208 @opindex mno-fix-r10000
14209 Work around certain R10000 errata:
14212 @code{ll}/@code{sc} sequences may not behave atomically on revisions
14213 prior to 3.0. They may deadlock on revisions 2.6 and earlier.
14216 This option can only be used if the target architecture supports
14217 branch-likely instructions. @option{-mfix-r10000} is the default when
14218 @option{-march=r10000} is used; @option{-mno-fix-r10000} is the default
14222 @itemx -mno-fix-vr4120
14223 @opindex mfix-vr4120
14224 Work around certain VR4120 errata:
14227 @code{dmultu} does not always produce the correct result.
14229 @code{div} and @code{ddiv} do not always produce the correct result if one
14230 of the operands is negative.
14232 The workarounds for the division errata rely on special functions in
14233 @file{libgcc.a}. At present, these functions are only provided by
14234 the @code{mips64vr*-elf} configurations.
14236 Other VR4120 errata require a nop to be inserted between certain pairs of
14237 instructions. These errata are handled by the assembler, not by GCC itself.
14240 @opindex mfix-vr4130
14241 Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
14242 workarounds are implemented by the assembler rather than by GCC,
14243 although GCC will avoid using @code{mflo} and @code{mfhi} if the
14244 VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
14245 instructions are available instead.
14248 @itemx -mno-fix-sb1
14250 Work around certain SB-1 CPU core errata.
14251 (This flag currently works around the SB-1 revision 2
14252 ``F1'' and ``F2'' floating point errata.)
14254 @item -mr10k-cache-barrier=@var{setting}
14255 @opindex mr10k-cache-barrier
14256 Specify whether GCC should insert cache barriers to avoid the
14257 side-effects of speculation on R10K processors.
14259 In common with many processors, the R10K tries to predict the outcome
14260 of a conditional branch and speculatively executes instructions from
14261 the ``taken'' branch. It later aborts these instructions if the
14262 predicted outcome was wrong. However, on the R10K, even aborted
14263 instructions can have side effects.
14265 This problem only affects kernel stores and, depending on the system,
14266 kernel loads. As an example, a speculatively-executed store may load
14267 the target memory into cache and mark the cache line as dirty, even if
14268 the store itself is later aborted. If a DMA operation writes to the
14269 same area of memory before the ``dirty'' line is flushed, the cached
14270 data will overwrite the DMA-ed data. See the R10K processor manual
14271 for a full description, including other potential problems.
14273 One workaround is to insert cache barrier instructions before every memory
14274 access that might be speculatively executed and that might have side
14275 effects even if aborted. @option{-mr10k-cache-barrier=@var{setting}}
14276 controls GCC's implementation of this workaround. It assumes that
14277 aborted accesses to any byte in the following regions will not have
14282 the memory occupied by the current function's stack frame;
14285 the memory occupied by an incoming stack argument;
14288 the memory occupied by an object with a link-time-constant address.
14291 It is the kernel's responsibility to ensure that speculative
14292 accesses to these regions are indeed safe.
14294 If the input program contains a function declaration such as:
14300 then the implementation of @code{foo} must allow @code{j foo} and
14301 @code{jal foo} to be executed speculatively. GCC honors this
14302 restriction for functions it compiles itself. It expects non-GCC
14303 functions (such as hand-written assembly code) to do the same.
14305 The option has three forms:
14308 @item -mr10k-cache-barrier=load-store
14309 Insert a cache barrier before a load or store that might be
14310 speculatively executed and that might have side effects even
14313 @item -mr10k-cache-barrier=store
14314 Insert a cache barrier before a store that might be speculatively
14315 executed and that might have side effects even if aborted.
14317 @item -mr10k-cache-barrier=none
14318 Disable the insertion of cache barriers. This is the default setting.
14321 @item -mflush-func=@var{func}
14322 @itemx -mno-flush-func
14323 @opindex mflush-func
14324 Specifies the function to call to flush the I and D caches, or to not
14325 call any such function. If called, the function must take the same
14326 arguments as the common @code{_flush_func()}, that is, the address of the
14327 memory range for which the cache is being flushed, the size of the
14328 memory range, and the number 3 (to flush both caches). The default
14329 depends on the target GCC was configured for, but commonly is either
14330 @samp{_flush_func} or @samp{__cpu_flush}.
14332 @item mbranch-cost=@var{num}
14333 @opindex mbranch-cost
14334 Set the cost of branches to roughly @var{num} ``simple'' instructions.
14335 This cost is only a heuristic and is not guaranteed to produce
14336 consistent results across releases. A zero cost redundantly selects
14337 the default, which is based on the @option{-mtune} setting.
14339 @item -mbranch-likely
14340 @itemx -mno-branch-likely
14341 @opindex mbranch-likely
14342 @opindex mno-branch-likely
14343 Enable or disable use of Branch Likely instructions, regardless of the
14344 default for the selected architecture. By default, Branch Likely
14345 instructions may be generated if they are supported by the selected
14346 architecture. An exception is for the MIPS32 and MIPS64 architectures
14347 and processors which implement those architectures; for those, Branch
14348 Likely instructions will not be generated by default because the MIPS32
14349 and MIPS64 architectures specifically deprecate their use.
14351 @item -mfp-exceptions
14352 @itemx -mno-fp-exceptions
14353 @opindex mfp-exceptions
14354 Specifies whether FP exceptions are enabled. This affects how we schedule
14355 FP instructions for some processors. The default is that FP exceptions are
14358 For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
14359 64-bit code, then we can use both FP pipes. Otherwise, we can only use one
14362 @item -mvr4130-align
14363 @itemx -mno-vr4130-align
14364 @opindex mvr4130-align
14365 The VR4130 pipeline is two-way superscalar, but can only issue two
14366 instructions together if the first one is 8-byte aligned. When this
14367 option is enabled, GCC will align pairs of instructions that it
14368 thinks should execute in parallel.
14370 This option only has an effect when optimizing for the VR4130.
14371 It normally makes code faster, but at the expense of making it bigger.
14372 It is enabled by default at optimization level @option{-O3}.
14377 Enable (disable) generation of @code{synci} instructions on
14378 architectures that support it. The @code{synci} instructions (if
14379 enabled) will be generated when @code{__builtin___clear_cache()} is
14382 This option defaults to @code{-mno-synci}, but the default can be
14383 overridden by configuring with @code{--with-synci}.
14385 When compiling code for single processor systems, it is generally safe
14386 to use @code{synci}. However, on many multi-core (SMP) systems, it
14387 will not invalidate the instruction caches on all cores and may lead
14388 to undefined behavior.
14390 @item -mrelax-pic-calls
14391 @itemx -mno-relax-pic-calls
14392 @opindex mrelax-pic-calls
14393 Try to turn PIC calls that are normally dispatched via register
14394 @code{$25} into direct calls. This is only possible if the linker can
14395 resolve the destination at link-time and if the destination is within
14396 range for a direct call.
14398 @option{-mrelax-pic-calls} is the default if GCC was configured to use
14399 an assembler and a linker that supports the @code{.reloc} assembly
14400 directive and @code{-mexplicit-relocs} is in effect. With
14401 @code{-mno-explicit-relocs}, this optimization can be performed by the
14402 assembler and the linker alone without help from the compiler.
14404 @item -mmcount-ra-address
14405 @itemx -mno-mcount-ra-address
14406 @opindex mmcount-ra-address
14407 @opindex mno-mcount-ra-address
14408 Emit (do not emit) code that allows @code{_mcount} to modify the
14409 calling function's return address. When enabled, this option extends
14410 the usual @code{_mcount} interface with a new @var{ra-address}
14411 parameter, which has type @code{intptr_t *} and is passed in register
14412 @code{$12}. @code{_mcount} can then modify the return address by
14413 doing both of the following:
14416 Returning the new address in register @code{$31}.
14418 Storing the new address in @code{*@var{ra-address}},
14419 if @var{ra-address} is nonnull.
14422 The default is @option{-mno-mcount-ra-address}.
14427 @subsection MMIX Options
14428 @cindex MMIX Options
14430 These options are defined for the MMIX:
14434 @itemx -mno-libfuncs
14436 @opindex mno-libfuncs
14437 Specify that intrinsic library functions are being compiled, passing all
14438 values in registers, no matter the size.
14441 @itemx -mno-epsilon
14443 @opindex mno-epsilon
14444 Generate floating-point comparison instructions that compare with respect
14445 to the @code{rE} epsilon register.
14447 @item -mabi=mmixware
14449 @opindex mabi=mmixware
14451 Generate code that passes function parameters and return values that (in
14452 the called function) are seen as registers @code{$0} and up, as opposed to
14453 the GNU ABI which uses global registers @code{$231} and up.
14455 @item -mzero-extend
14456 @itemx -mno-zero-extend
14457 @opindex mzero-extend
14458 @opindex mno-zero-extend
14459 When reading data from memory in sizes shorter than 64 bits, use (do not
14460 use) zero-extending load instructions by default, rather than
14461 sign-extending ones.
14464 @itemx -mno-knuthdiv
14466 @opindex mno-knuthdiv
14467 Make the result of a division yielding a remainder have the same sign as
14468 the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
14469 remainder follows the sign of the dividend. Both methods are
14470 arithmetically valid, the latter being almost exclusively used.
14472 @item -mtoplevel-symbols
14473 @itemx -mno-toplevel-symbols
14474 @opindex mtoplevel-symbols
14475 @opindex mno-toplevel-symbols
14476 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
14477 code can be used with the @code{PREFIX} assembly directive.
14481 Generate an executable in the ELF format, rather than the default
14482 @samp{mmo} format used by the @command{mmix} simulator.
14484 @item -mbranch-predict
14485 @itemx -mno-branch-predict
14486 @opindex mbranch-predict
14487 @opindex mno-branch-predict
14488 Use (do not use) the probable-branch instructions, when static branch
14489 prediction indicates a probable branch.
14491 @item -mbase-addresses
14492 @itemx -mno-base-addresses
14493 @opindex mbase-addresses
14494 @opindex mno-base-addresses
14495 Generate (do not generate) code that uses @emph{base addresses}. Using a
14496 base address automatically generates a request (handled by the assembler
14497 and the linker) for a constant to be set up in a global register. The
14498 register is used for one or more base address requests within the range 0
14499 to 255 from the value held in the register. The generally leads to short
14500 and fast code, but the number of different data items that can be
14501 addressed is limited. This means that a program that uses lots of static
14502 data may require @option{-mno-base-addresses}.
14504 @item -msingle-exit
14505 @itemx -mno-single-exit
14506 @opindex msingle-exit
14507 @opindex mno-single-exit
14508 Force (do not force) generated code to have a single exit point in each
14512 @node MN10300 Options
14513 @subsection MN10300 Options
14514 @cindex MN10300 options
14516 These @option{-m} options are defined for Matsushita MN10300 architectures:
14521 Generate code to avoid bugs in the multiply instructions for the MN10300
14522 processors. This is the default.
14524 @item -mno-mult-bug
14525 @opindex mno-mult-bug
14526 Do not generate code to avoid bugs in the multiply instructions for the
14527 MN10300 processors.
14531 Generate code which uses features specific to the AM33 processor.
14535 Do not generate code which uses features specific to the AM33 processor. This
14538 @item -mreturn-pointer-on-d0
14539 @opindex mreturn-pointer-on-d0
14540 When generating a function which returns a pointer, return the pointer
14541 in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
14542 only in a0, and attempts to call such functions without a prototype
14543 would result in errors. Note that this option is on by default; use
14544 @option{-mno-return-pointer-on-d0} to disable it.
14548 Do not link in the C run-time initialization object file.
14552 Indicate to the linker that it should perform a relaxation optimization pass
14553 to shorten branches, calls and absolute memory addresses. This option only
14554 has an effect when used on the command line for the final link step.
14556 This option makes symbolic debugging impossible.
14559 @node PDP-11 Options
14560 @subsection PDP-11 Options
14561 @cindex PDP-11 Options
14563 These options are defined for the PDP-11:
14568 Use hardware FPP floating point. This is the default. (FIS floating
14569 point on the PDP-11/40 is not supported.)
14572 @opindex msoft-float
14573 Do not use hardware floating point.
14577 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
14581 Return floating-point results in memory. This is the default.
14585 Generate code for a PDP-11/40.
14589 Generate code for a PDP-11/45. This is the default.
14593 Generate code for a PDP-11/10.
14595 @item -mbcopy-builtin
14596 @opindex mbcopy-builtin
14597 Use inline @code{movmemhi} patterns for copying memory. This is the
14602 Do not use inline @code{movmemhi} patterns for copying memory.
14608 Use 16-bit @code{int}. This is the default.
14614 Use 32-bit @code{int}.
14617 @itemx -mno-float32
14619 @opindex mno-float32
14620 Use 64-bit @code{float}. This is the default.
14623 @itemx -mno-float64
14625 @opindex mno-float64
14626 Use 32-bit @code{float}.
14630 Use @code{abshi2} pattern. This is the default.
14634 Do not use @code{abshi2} pattern.
14636 @item -mbranch-expensive
14637 @opindex mbranch-expensive
14638 Pretend that branches are expensive. This is for experimenting with
14639 code generation only.
14641 @item -mbranch-cheap
14642 @opindex mbranch-cheap
14643 Do not pretend that branches are expensive. This is the default.
14647 Generate code for a system with split I&D@.
14651 Generate code for a system without split I&D@. This is the default.
14655 Use Unix assembler syntax. This is the default when configured for
14656 @samp{pdp11-*-bsd}.
14660 Use DEC assembler syntax. This is the default when configured for any
14661 PDP-11 target other than @samp{pdp11-*-bsd}.
14664 @node picoChip Options
14665 @subsection picoChip Options
14666 @cindex picoChip options
14668 These @samp{-m} options are defined for picoChip implementations:
14672 @item -mae=@var{ae_type}
14674 Set the instruction set, register set, and instruction scheduling
14675 parameters for array element type @var{ae_type}. Supported values
14676 for @var{ae_type} are @samp{ANY}, @samp{MUL}, and @samp{MAC}.
14678 @option{-mae=ANY} selects a completely generic AE type. Code
14679 generated with this option will run on any of the other AE types. The
14680 code will not be as efficient as it would be if compiled for a specific
14681 AE type, and some types of operation (e.g., multiplication) will not
14682 work properly on all types of AE.
14684 @option{-mae=MUL} selects a MUL AE type. This is the most useful AE type
14685 for compiled code, and is the default.
14687 @option{-mae=MAC} selects a DSP-style MAC AE. Code compiled with this
14688 option may suffer from poor performance of byte (char) manipulation,
14689 since the DSP AE does not provide hardware support for byte load/stores.
14691 @item -msymbol-as-address
14692 Enable the compiler to directly use a symbol name as an address in a
14693 load/store instruction, without first loading it into a
14694 register. Typically, the use of this option will generate larger
14695 programs, which run faster than when the option isn't used. However, the
14696 results vary from program to program, so it is left as a user option,
14697 rather than being permanently enabled.
14699 @item -mno-inefficient-warnings
14700 Disables warnings about the generation of inefficient code. These
14701 warnings can be generated, for example, when compiling code which
14702 performs byte-level memory operations on the MAC AE type. The MAC AE has
14703 no hardware support for byte-level memory operations, so all byte
14704 load/stores must be synthesized from word load/store operations. This is
14705 inefficient and a warning will be generated indicating to the programmer
14706 that they should rewrite the code to avoid byte operations, or to target
14707 an AE type which has the necessary hardware support. This option enables
14708 the warning to be turned off.
14712 @node PowerPC Options
14713 @subsection PowerPC Options
14714 @cindex PowerPC options
14716 These are listed under @xref{RS/6000 and PowerPC Options}.
14718 @node RS/6000 and PowerPC Options
14719 @subsection IBM RS/6000 and PowerPC Options
14720 @cindex RS/6000 and PowerPC Options
14721 @cindex IBM RS/6000 and PowerPC Options
14723 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
14730 @itemx -mno-powerpc
14731 @itemx -mpowerpc-gpopt
14732 @itemx -mno-powerpc-gpopt
14733 @itemx -mpowerpc-gfxopt
14734 @itemx -mno-powerpc-gfxopt
14736 @itemx -mno-powerpc64
14740 @itemx -mno-popcntb
14742 @itemx -mno-popcntd
14750 @itemx -mno-hard-dfp
14754 @opindex mno-power2
14756 @opindex mno-powerpc
14757 @opindex mpowerpc-gpopt
14758 @opindex mno-powerpc-gpopt
14759 @opindex mpowerpc-gfxopt
14760 @opindex mno-powerpc-gfxopt
14761 @opindex mpowerpc64
14762 @opindex mno-powerpc64
14766 @opindex mno-popcntb
14768 @opindex mno-popcntd
14774 @opindex mno-mfpgpr
14776 @opindex mno-hard-dfp
14777 GCC supports two related instruction set architectures for the
14778 RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
14779 instructions supported by the @samp{rios} chip set used in the original
14780 RS/6000 systems and the @dfn{PowerPC} instruction set is the
14781 architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
14782 the IBM 4xx, 6xx, and follow-on microprocessors.
14784 Neither architecture is a subset of the other. However there is a
14785 large common subset of instructions supported by both. An MQ
14786 register is included in processors supporting the POWER architecture.
14788 You use these options to specify which instructions are available on the
14789 processor you are using. The default value of these options is
14790 determined when configuring GCC@. Specifying the
14791 @option{-mcpu=@var{cpu_type}} overrides the specification of these
14792 options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
14793 rather than the options listed above.
14795 The @option{-mpower} option allows GCC to generate instructions that
14796 are found only in the POWER architecture and to use the MQ register.
14797 Specifying @option{-mpower2} implies @option{-power} and also allows GCC
14798 to generate instructions that are present in the POWER2 architecture but
14799 not the original POWER architecture.
14801 The @option{-mpowerpc} option allows GCC to generate instructions that
14802 are found only in the 32-bit subset of the PowerPC architecture.
14803 Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
14804 GCC to use the optional PowerPC architecture instructions in the
14805 General Purpose group, including floating-point square root. Specifying
14806 @option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
14807 use the optional PowerPC architecture instructions in the Graphics
14808 group, including floating-point select.
14810 The @option{-mmfcrf} option allows GCC to generate the move from
14811 condition register field instruction implemented on the POWER4
14812 processor and other processors that support the PowerPC V2.01
14814 The @option{-mpopcntb} option allows GCC to generate the popcount and
14815 double precision FP reciprocal estimate instruction implemented on the
14816 POWER5 processor and other processors that support the PowerPC V2.02
14818 The @option{-mpopcntd} option allows GCC to generate the popcount
14819 instruction implemented on the POWER7 processor and other processors
14820 that support the PowerPC V2.06 architecture.
14821 The @option{-mfprnd} option allows GCC to generate the FP round to
14822 integer instructions implemented on the POWER5+ processor and other
14823 processors that support the PowerPC V2.03 architecture.
14824 The @option{-mcmpb} option allows GCC to generate the compare bytes
14825 instruction implemented on the POWER6 processor and other processors
14826 that support the PowerPC V2.05 architecture.
14827 The @option{-mmfpgpr} option allows GCC to generate the FP move to/from
14828 general purpose register instructions implemented on the POWER6X
14829 processor and other processors that support the extended PowerPC V2.05
14831 The @option{-mhard-dfp} option allows GCC to generate the decimal floating
14832 point instructions implemented on some POWER processors.
14834 The @option{-mpowerpc64} option allows GCC to generate the additional
14835 64-bit instructions that are found in the full PowerPC64 architecture
14836 and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
14837 @option{-mno-powerpc64}.
14839 If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
14840 will use only the instructions in the common subset of both
14841 architectures plus some special AIX common-mode calls, and will not use
14842 the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
14843 permits GCC to use any instruction from either architecture and to
14844 allow use of the MQ register; specify this for the Motorola MPC601.
14846 @item -mnew-mnemonics
14847 @itemx -mold-mnemonics
14848 @opindex mnew-mnemonics
14849 @opindex mold-mnemonics
14850 Select which mnemonics to use in the generated assembler code. With
14851 @option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
14852 the PowerPC architecture. With @option{-mold-mnemonics} it uses the
14853 assembler mnemonics defined for the POWER architecture. Instructions
14854 defined in only one architecture have only one mnemonic; GCC uses that
14855 mnemonic irrespective of which of these options is specified.
14857 GCC defaults to the mnemonics appropriate for the architecture in
14858 use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
14859 value of these option. Unless you are building a cross-compiler, you
14860 should normally not specify either @option{-mnew-mnemonics} or
14861 @option{-mold-mnemonics}, but should instead accept the default.
14863 @item -mcpu=@var{cpu_type}
14865 Set architecture type, register usage, choice of mnemonics, and
14866 instruction scheduling parameters for machine type @var{cpu_type}.
14867 Supported values for @var{cpu_type} are @samp{401}, @samp{403},
14868 @samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{464}, @samp{464fp},
14869 @samp{476}, @samp{476fp}, @samp{505}, @samp{601}, @samp{602}, @samp{603},
14870 @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{630}, @samp{740},
14871 @samp{7400}, @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
14872 @samp{860}, @samp{970}, @samp{8540}, @samp{a2}, @samp{e300c2},
14873 @samp{e300c3}, @samp{e500mc}, @samp{e500mc64}, @samp{ec603e}, @samp{G3},
14874 @samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
14875 @samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6}, @samp{power6x},
14876 @samp{power7}, @samp{common}, @samp{powerpc}, @samp{powerpc64}, @samp{rios},
14877 @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
14879 @option{-mcpu=common} selects a completely generic processor. Code
14880 generated under this option will run on any POWER or PowerPC processor.
14881 GCC will use only the instructions in the common subset of both
14882 architectures, and will not use the MQ register. GCC assumes a generic
14883 processor model for scheduling purposes.
14885 @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
14886 @option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
14887 PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
14888 types, with an appropriate, generic processor model assumed for
14889 scheduling purposes.
14891 The other options specify a specific processor. Code generated under
14892 those options will run best on that processor, and may not run at all on
14895 The @option{-mcpu} options automatically enable or disable the
14898 @gccoptlist{-maltivec -mfprnd -mhard-float -mmfcrf -mmultiple @gol
14899 -mnew-mnemonics -mpopcntb -mpopcntd -mpower -mpower2 -mpowerpc64 @gol
14900 -mpowerpc-gpopt -mpowerpc-gfxopt -msingle-float -mdouble-float @gol
14901 -msimple-fpu -mstring -mmulhw -mdlmzb -mmfpgpr -mvsx}
14903 The particular options set for any particular CPU will vary between
14904 compiler versions, depending on what setting seems to produce optimal
14905 code for that CPU; it doesn't necessarily reflect the actual hardware's
14906 capabilities. If you wish to set an individual option to a particular
14907 value, you may specify it after the @option{-mcpu} option, like
14908 @samp{-mcpu=970 -mno-altivec}.
14910 On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
14911 not enabled or disabled by the @option{-mcpu} option at present because
14912 AIX does not have full support for these options. You may still
14913 enable or disable them individually if you're sure it'll work in your
14916 @item -mtune=@var{cpu_type}
14918 Set the instruction scheduling parameters for machine type
14919 @var{cpu_type}, but do not set the architecture type, register usage, or
14920 choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
14921 values for @var{cpu_type} are used for @option{-mtune} as for
14922 @option{-mcpu}. If both are specified, the code generated will use the
14923 architecture, registers, and mnemonics set by @option{-mcpu}, but the
14924 scheduling parameters set by @option{-mtune}.
14930 Generate code to compute division as reciprocal estimate and iterative
14931 refinement, creating opportunities for increased throughput. This
14932 feature requires: optional PowerPC Graphics instruction set for single
14933 precision and FRE instruction for double precision, assuming divides
14934 cannot generate user-visible traps, and the domain values not include
14935 Infinities, denormals or zero denominator.
14938 @itemx -mno-altivec
14940 @opindex mno-altivec
14941 Generate code that uses (does not use) AltiVec instructions, and also
14942 enable the use of built-in functions that allow more direct access to
14943 the AltiVec instruction set. You may also need to set
14944 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
14950 @opindex mno-vrsave
14951 Generate VRSAVE instructions when generating AltiVec code.
14953 @item -mgen-cell-microcode
14954 @opindex mgen-cell-microcode
14955 Generate Cell microcode instructions
14957 @item -mwarn-cell-microcode
14958 @opindex mwarn-cell-microcode
14959 Warning when a Cell microcode instruction is going to emitted. An example
14960 of a Cell microcode instruction is a variable shift.
14963 @opindex msecure-plt
14964 Generate code that allows ld and ld.so to build executables and shared
14965 libraries with non-exec .plt and .got sections. This is a PowerPC
14966 32-bit SYSV ABI option.
14970 Generate code that uses a BSS .plt section that ld.so fills in, and
14971 requires .plt and .got sections that are both writable and executable.
14972 This is a PowerPC 32-bit SYSV ABI option.
14978 This switch enables or disables the generation of ISEL instructions.
14980 @item -misel=@var{yes/no}
14981 This switch has been deprecated. Use @option{-misel} and
14982 @option{-mno-isel} instead.
14988 This switch enables or disables the generation of SPE simd
14994 @opindex mno-paired
14995 This switch enables or disables the generation of PAIRED simd
14998 @item -mspe=@var{yes/no}
14999 This option has been deprecated. Use @option{-mspe} and
15000 @option{-mno-spe} instead.
15006 Generate code that uses (does not use) vector/scalar (VSX)
15007 instructions, and also enable the use of built-in functions that allow
15008 more direct access to the VSX instruction set.
15010 @item -mfloat-gprs=@var{yes/single/double/no}
15011 @itemx -mfloat-gprs
15012 @opindex mfloat-gprs
15013 This switch enables or disables the generation of floating point
15014 operations on the general purpose registers for architectures that
15017 The argument @var{yes} or @var{single} enables the use of
15018 single-precision floating point operations.
15020 The argument @var{double} enables the use of single and
15021 double-precision floating point operations.
15023 The argument @var{no} disables floating point operations on the
15024 general purpose registers.
15026 This option is currently only available on the MPC854x.
15032 Generate code for 32-bit or 64-bit environments of Darwin and SVR4
15033 targets (including GNU/Linux). The 32-bit environment sets int, long
15034 and pointer to 32 bits and generates code that runs on any PowerPC
15035 variant. The 64-bit environment sets int to 32 bits and long and
15036 pointer to 64 bits, and generates code for PowerPC64, as for
15037 @option{-mpowerpc64}.
15040 @itemx -mno-fp-in-toc
15041 @itemx -mno-sum-in-toc
15042 @itemx -mminimal-toc
15044 @opindex mno-fp-in-toc
15045 @opindex mno-sum-in-toc
15046 @opindex mminimal-toc
15047 Modify generation of the TOC (Table Of Contents), which is created for
15048 every executable file. The @option{-mfull-toc} option is selected by
15049 default. In that case, GCC will allocate at least one TOC entry for
15050 each unique non-automatic variable reference in your program. GCC
15051 will also place floating-point constants in the TOC@. However, only
15052 16,384 entries are available in the TOC@.
15054 If you receive a linker error message that saying you have overflowed
15055 the available TOC space, you can reduce the amount of TOC space used
15056 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
15057 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
15058 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
15059 generate code to calculate the sum of an address and a constant at
15060 run-time instead of putting that sum into the TOC@. You may specify one
15061 or both of these options. Each causes GCC to produce very slightly
15062 slower and larger code at the expense of conserving TOC space.
15064 If you still run out of space in the TOC even when you specify both of
15065 these options, specify @option{-mminimal-toc} instead. This option causes
15066 GCC to make only one TOC entry for every file. When you specify this
15067 option, GCC will produce code that is slower and larger but which
15068 uses extremely little TOC space. You may wish to use this option
15069 only on files that contain less frequently executed code.
15075 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
15076 @code{long} type, and the infrastructure needed to support them.
15077 Specifying @option{-maix64} implies @option{-mpowerpc64} and
15078 @option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
15079 implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
15082 @itemx -mno-xl-compat
15083 @opindex mxl-compat
15084 @opindex mno-xl-compat
15085 Produce code that conforms more closely to IBM XL compiler semantics
15086 when using AIX-compatible ABI@. Pass floating-point arguments to
15087 prototyped functions beyond the register save area (RSA) on the stack
15088 in addition to argument FPRs. Do not assume that most significant
15089 double in 128-bit long double value is properly rounded when comparing
15090 values and converting to double. Use XL symbol names for long double
15093 The AIX calling convention was extended but not initially documented to
15094 handle an obscure K&R C case of calling a function that takes the
15095 address of its arguments with fewer arguments than declared. IBM XL
15096 compilers access floating point arguments which do not fit in the
15097 RSA from the stack when a subroutine is compiled without
15098 optimization. Because always storing floating-point arguments on the
15099 stack is inefficient and rarely needed, this option is not enabled by
15100 default and only is necessary when calling subroutines compiled by IBM
15101 XL compilers without optimization.
15105 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
15106 application written to use message passing with special startup code to
15107 enable the application to run. The system must have PE installed in the
15108 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
15109 must be overridden with the @option{-specs=} option to specify the
15110 appropriate directory location. The Parallel Environment does not
15111 support threads, so the @option{-mpe} option and the @option{-pthread}
15112 option are incompatible.
15114 @item -malign-natural
15115 @itemx -malign-power
15116 @opindex malign-natural
15117 @opindex malign-power
15118 On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
15119 @option{-malign-natural} overrides the ABI-defined alignment of larger
15120 types, such as floating-point doubles, on their natural size-based boundary.
15121 The option @option{-malign-power} instructs GCC to follow the ABI-specified
15122 alignment rules. GCC defaults to the standard alignment defined in the ABI@.
15124 On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
15128 @itemx -mhard-float
15129 @opindex msoft-float
15130 @opindex mhard-float
15131 Generate code that does not use (uses) the floating-point register set.
15132 Software floating point emulation is provided if you use the
15133 @option{-msoft-float} option, and pass the option to GCC when linking.
15135 @item -msingle-float
15136 @itemx -mdouble-float
15137 @opindex msingle-float
15138 @opindex mdouble-float
15139 Generate code for single or double-precision floating point operations.
15140 @option{-mdouble-float} implies @option{-msingle-float}.
15143 @opindex msimple-fpu
15144 Do not generate sqrt and div instructions for hardware floating point unit.
15148 Specify type of floating point unit. Valid values are @var{sp_lite}
15149 (equivalent to -msingle-float -msimple-fpu), @var{dp_lite} (equivalent
15150 to -mdouble-float -msimple-fpu), @var{sp_full} (equivalent to -msingle-float),
15151 and @var{dp_full} (equivalent to -mdouble-float).
15154 @opindex mxilinx-fpu
15155 Perform optimizations for floating point unit on Xilinx PPC 405/440.
15158 @itemx -mno-multiple
15160 @opindex mno-multiple
15161 Generate code that uses (does not use) the load multiple word
15162 instructions and the store multiple word instructions. These
15163 instructions are generated by default on POWER systems, and not
15164 generated on PowerPC systems. Do not use @option{-mmultiple} on little
15165 endian PowerPC systems, since those instructions do not work when the
15166 processor is in little endian mode. The exceptions are PPC740 and
15167 PPC750 which permit the instructions usage in little endian mode.
15172 @opindex mno-string
15173 Generate code that uses (does not use) the load string instructions
15174 and the store string word instructions to save multiple registers and
15175 do small block moves. These instructions are generated by default on
15176 POWER systems, and not generated on PowerPC systems. Do not use
15177 @option{-mstring} on little endian PowerPC systems, since those
15178 instructions do not work when the processor is in little endian mode.
15179 The exceptions are PPC740 and PPC750 which permit the instructions
15180 usage in little endian mode.
15185 @opindex mno-update
15186 Generate code that uses (does not use) the load or store instructions
15187 that update the base register to the address of the calculated memory
15188 location. These instructions are generated by default. If you use
15189 @option{-mno-update}, there is a small window between the time that the
15190 stack pointer is updated and the address of the previous frame is
15191 stored, which means code that walks the stack frame across interrupts or
15192 signals may get corrupted data.
15194 @item -mavoid-indexed-addresses
15195 @itemx -mno-avoid-indexed-addresses
15196 @opindex mavoid-indexed-addresses
15197 @opindex mno-avoid-indexed-addresses
15198 Generate code that tries to avoid (not avoid) the use of indexed load
15199 or store instructions. These instructions can incur a performance
15200 penalty on Power6 processors in certain situations, such as when
15201 stepping through large arrays that cross a 16M boundary. This option
15202 is enabled by default when targetting Power6 and disabled otherwise.
15205 @itemx -mno-fused-madd
15206 @opindex mfused-madd
15207 @opindex mno-fused-madd
15208 Generate code that uses (does not use) the floating point multiply and
15209 accumulate instructions. These instructions are generated by default if
15210 hardware floating is used.
15216 Generate code that uses (does not use) the half-word multiply and
15217 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
15218 These instructions are generated by default when targetting those
15225 Generate code that uses (does not use) the string-search @samp{dlmzb}
15226 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
15227 generated by default when targetting those processors.
15229 @item -mno-bit-align
15231 @opindex mno-bit-align
15232 @opindex mbit-align
15233 On System V.4 and embedded PowerPC systems do not (do) force structures
15234 and unions that contain bit-fields to be aligned to the base type of the
15237 For example, by default a structure containing nothing but 8
15238 @code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
15239 boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
15240 the structure would be aligned to a 1 byte boundary and be one byte in
15243 @item -mno-strict-align
15244 @itemx -mstrict-align
15245 @opindex mno-strict-align
15246 @opindex mstrict-align
15247 On System V.4 and embedded PowerPC systems do not (do) assume that
15248 unaligned memory references will be handled by the system.
15250 @item -mrelocatable
15251 @itemx -mno-relocatable
15252 @opindex mrelocatable
15253 @opindex mno-relocatable
15254 On embedded PowerPC systems generate code that allows (does not allow)
15255 the program to be relocated to a different address at runtime. If you
15256 use @option{-mrelocatable} on any module, all objects linked together must
15257 be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
15259 @item -mrelocatable-lib
15260 @itemx -mno-relocatable-lib
15261 @opindex mrelocatable-lib
15262 @opindex mno-relocatable-lib
15263 On embedded PowerPC systems generate code that allows (does not allow)
15264 the program to be relocated to a different address at runtime. Modules
15265 compiled with @option{-mrelocatable-lib} can be linked with either modules
15266 compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
15267 with modules compiled with the @option{-mrelocatable} options.
15273 On System V.4 and embedded PowerPC systems do not (do) assume that
15274 register 2 contains a pointer to a global area pointing to the addresses
15275 used in the program.
15278 @itemx -mlittle-endian
15280 @opindex mlittle-endian
15281 On System V.4 and embedded PowerPC systems compile code for the
15282 processor in little endian mode. The @option{-mlittle-endian} option is
15283 the same as @option{-mlittle}.
15286 @itemx -mbig-endian
15288 @opindex mbig-endian
15289 On System V.4 and embedded PowerPC systems compile code for the
15290 processor in big endian mode. The @option{-mbig-endian} option is
15291 the same as @option{-mbig}.
15293 @item -mdynamic-no-pic
15294 @opindex mdynamic-no-pic
15295 On Darwin and Mac OS X systems, compile code so that it is not
15296 relocatable, but that its external references are relocatable. The
15297 resulting code is suitable for applications, but not shared
15300 @item -mprioritize-restricted-insns=@var{priority}
15301 @opindex mprioritize-restricted-insns
15302 This option controls the priority that is assigned to
15303 dispatch-slot restricted instructions during the second scheduling
15304 pass. The argument @var{priority} takes the value @var{0/1/2} to assign
15305 @var{no/highest/second-highest} priority to dispatch slot restricted
15308 @item -msched-costly-dep=@var{dependence_type}
15309 @opindex msched-costly-dep
15310 This option controls which dependences are considered costly
15311 by the target during instruction scheduling. The argument
15312 @var{dependence_type} takes one of the following values:
15313 @var{no}: no dependence is costly,
15314 @var{all}: all dependences are costly,
15315 @var{true_store_to_load}: a true dependence from store to load is costly,
15316 @var{store_to_load}: any dependence from store to load is costly,
15317 @var{number}: any dependence which latency >= @var{number} is costly.
15319 @item -minsert-sched-nops=@var{scheme}
15320 @opindex minsert-sched-nops
15321 This option controls which nop insertion scheme will be used during
15322 the second scheduling pass. The argument @var{scheme} takes one of the
15324 @var{no}: Don't insert nops.
15325 @var{pad}: Pad with nops any dispatch group which has vacant issue slots,
15326 according to the scheduler's grouping.
15327 @var{regroup_exact}: Insert nops to force costly dependent insns into
15328 separate groups. Insert exactly as many nops as needed to force an insn
15329 to a new group, according to the estimated processor grouping.
15330 @var{number}: Insert nops to force costly dependent insns into
15331 separate groups. Insert @var{number} nops to force an insn to a new group.
15334 @opindex mcall-sysv
15335 On System V.4 and embedded PowerPC systems compile code using calling
15336 conventions that adheres to the March 1995 draft of the System V
15337 Application Binary Interface, PowerPC processor supplement. This is the
15338 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
15340 @item -mcall-sysv-eabi
15342 @opindex mcall-sysv-eabi
15343 @opindex mcall-eabi
15344 Specify both @option{-mcall-sysv} and @option{-meabi} options.
15346 @item -mcall-sysv-noeabi
15347 @opindex mcall-sysv-noeabi
15348 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
15350 @item -mcall-aixdesc
15352 On System V.4 and embedded PowerPC systems compile code for the AIX
15356 @opindex mcall-linux
15357 On System V.4 and embedded PowerPC systems compile code for the
15358 Linux-based GNU system.
15362 On System V.4 and embedded PowerPC systems compile code for the
15363 Hurd-based GNU system.
15365 @item -mcall-freebsd
15366 @opindex mcall-freebsd
15367 On System V.4 and embedded PowerPC systems compile code for the
15368 FreeBSD operating system.
15370 @item -mcall-netbsd
15371 @opindex mcall-netbsd
15372 On System V.4 and embedded PowerPC systems compile code for the
15373 NetBSD operating system.
15375 @item -mcall-openbsd
15376 @opindex mcall-netbsd
15377 On System V.4 and embedded PowerPC systems compile code for the
15378 OpenBSD operating system.
15380 @item -maix-struct-return
15381 @opindex maix-struct-return
15382 Return all structures in memory (as specified by the AIX ABI)@.
15384 @item -msvr4-struct-return
15385 @opindex msvr4-struct-return
15386 Return structures smaller than 8 bytes in registers (as specified by the
15389 @item -mabi=@var{abi-type}
15391 Extend the current ABI with a particular extension, or remove such extension.
15392 Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
15393 @var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
15397 Extend the current ABI with SPE ABI extensions. This does not change
15398 the default ABI, instead it adds the SPE ABI extensions to the current
15402 @opindex mabi=no-spe
15403 Disable Booke SPE ABI extensions for the current ABI@.
15405 @item -mabi=ibmlongdouble
15406 @opindex mabi=ibmlongdouble
15407 Change the current ABI to use IBM extended precision long double.
15408 This is a PowerPC 32-bit SYSV ABI option.
15410 @item -mabi=ieeelongdouble
15411 @opindex mabi=ieeelongdouble
15412 Change the current ABI to use IEEE extended precision long double.
15413 This is a PowerPC 32-bit Linux ABI option.
15416 @itemx -mno-prototype
15417 @opindex mprototype
15418 @opindex mno-prototype
15419 On System V.4 and embedded PowerPC systems assume that all calls to
15420 variable argument functions are properly prototyped. Otherwise, the
15421 compiler must insert an instruction before every non prototyped call to
15422 set or clear bit 6 of the condition code register (@var{CR}) to
15423 indicate whether floating point values were passed in the floating point
15424 registers in case the function takes a variable arguments. With
15425 @option{-mprototype}, only calls to prototyped variable argument functions
15426 will set or clear the bit.
15430 On embedded PowerPC systems, assume that the startup module is called
15431 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
15432 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}
15437 On embedded PowerPC systems, assume that the startup module is called
15438 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
15443 On embedded PowerPC systems, assume that the startup module is called
15444 @file{crt0.o} and the standard C libraries are @file{libads.a} and
15447 @item -myellowknife
15448 @opindex myellowknife
15449 On embedded PowerPC systems, assume that the startup module is called
15450 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
15455 On System V.4 and embedded PowerPC systems, specify that you are
15456 compiling for a VxWorks system.
15460 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
15461 header to indicate that @samp{eabi} extended relocations are used.
15467 On System V.4 and embedded PowerPC systems do (do not) adhere to the
15468 Embedded Applications Binary Interface (eabi) which is a set of
15469 modifications to the System V.4 specifications. Selecting @option{-meabi}
15470 means that the stack is aligned to an 8 byte boundary, a function
15471 @code{__eabi} is called to from @code{main} to set up the eabi
15472 environment, and the @option{-msdata} option can use both @code{r2} and
15473 @code{r13} to point to two separate small data areas. Selecting
15474 @option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
15475 do not call an initialization function from @code{main}, and the
15476 @option{-msdata} option will only use @code{r13} to point to a single
15477 small data area. The @option{-meabi} option is on by default if you
15478 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
15481 @opindex msdata=eabi
15482 On System V.4 and embedded PowerPC systems, put small initialized
15483 @code{const} global and static data in the @samp{.sdata2} section, which
15484 is pointed to by register @code{r2}. Put small initialized
15485 non-@code{const} global and static data in the @samp{.sdata} section,
15486 which is pointed to by register @code{r13}. Put small uninitialized
15487 global and static data in the @samp{.sbss} section, which is adjacent to
15488 the @samp{.sdata} section. The @option{-msdata=eabi} option is
15489 incompatible with the @option{-mrelocatable} option. The
15490 @option{-msdata=eabi} option also sets the @option{-memb} option.
15493 @opindex msdata=sysv
15494 On System V.4 and embedded PowerPC systems, put small global and static
15495 data in the @samp{.sdata} section, which is pointed to by register
15496 @code{r13}. Put small uninitialized global and static data in the
15497 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
15498 The @option{-msdata=sysv} option is incompatible with the
15499 @option{-mrelocatable} option.
15501 @item -msdata=default
15503 @opindex msdata=default
15505 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
15506 compile code the same as @option{-msdata=eabi}, otherwise compile code the
15507 same as @option{-msdata=sysv}.
15510 @opindex msdata=data
15511 On System V.4 and embedded PowerPC systems, put small global
15512 data in the @samp{.sdata} section. Put small uninitialized global
15513 data in the @samp{.sbss} section. Do not use register @code{r13}
15514 to address small data however. This is the default behavior unless
15515 other @option{-msdata} options are used.
15519 @opindex msdata=none
15521 On embedded PowerPC systems, put all initialized global and static data
15522 in the @samp{.data} section, and all uninitialized data in the
15523 @samp{.bss} section.
15527 @cindex smaller data references (PowerPC)
15528 @cindex .sdata/.sdata2 references (PowerPC)
15529 On embedded PowerPC systems, put global and static items less than or
15530 equal to @var{num} bytes into the small data or bss sections instead of
15531 the normal data or bss section. By default, @var{num} is 8. The
15532 @option{-G @var{num}} switch is also passed to the linker.
15533 All modules should be compiled with the same @option{-G @var{num}} value.
15536 @itemx -mno-regnames
15538 @opindex mno-regnames
15539 On System V.4 and embedded PowerPC systems do (do not) emit register
15540 names in the assembly language output using symbolic forms.
15543 @itemx -mno-longcall
15545 @opindex mno-longcall
15546 By default assume that all calls are far away so that a longer more
15547 expensive calling sequence is required. This is required for calls
15548 further than 32 megabytes (33,554,432 bytes) from the current location.
15549 A short call will be generated if the compiler knows
15550 the call cannot be that far away. This setting can be overridden by
15551 the @code{shortcall} function attribute, or by @code{#pragma
15554 Some linkers are capable of detecting out-of-range calls and generating
15555 glue code on the fly. On these systems, long calls are unnecessary and
15556 generate slower code. As of this writing, the AIX linker can do this,
15557 as can the GNU linker for PowerPC/64. It is planned to add this feature
15558 to the GNU linker for 32-bit PowerPC systems as well.
15560 On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
15561 callee, L42'', plus a ``branch island'' (glue code). The two target
15562 addresses represent the callee and the ``branch island''. The
15563 Darwin/PPC linker will prefer the first address and generate a ``bl
15564 callee'' if the PPC ``bl'' instruction will reach the callee directly;
15565 otherwise, the linker will generate ``bl L42'' to call the ``branch
15566 island''. The ``branch island'' is appended to the body of the
15567 calling function; it computes the full 32-bit address of the callee
15570 On Mach-O (Darwin) systems, this option directs the compiler emit to
15571 the glue for every direct call, and the Darwin linker decides whether
15572 to use or discard it.
15574 In the future, we may cause GCC to ignore all longcall specifications
15575 when the linker is known to generate glue.
15577 @item -mtls-markers
15578 @itemx -mno-tls-markers
15579 @opindex mtls-markers
15580 @opindex mno-tls-markers
15581 Mark (do not mark) calls to @code{__tls_get_addr} with a relocation
15582 specifying the function argument. The relocation allows ld to
15583 reliably associate function call with argument setup instructions for
15584 TLS optimization, which in turn allows gcc to better schedule the
15589 Adds support for multithreading with the @dfn{pthreads} library.
15590 This option sets flags for both the preprocessor and linker.
15595 @subsection RX Options
15598 These command line options are defined for RX targets:
15601 @item -m64bit-doubles
15602 @itemx -m32bit-doubles
15603 @opindex m64bit-doubles
15604 @opindex m32bit-doubles
15605 Make the @code{double} data type be 64-bits (@option{-m64bit-doubles})
15606 or 32-bits (@option{-m32bit-doubles}) in size. The default is
15607 @option{-m32bit-doubles}. @emph{Note} RX floating point hardware only
15608 works on 32-bit values, which is why the default is
15609 @option{-m32bit-doubles}.
15615 Enables (@option{-fpu}) or disables (@option{-nofpu}) the use of RX
15616 floating point hardware. The default is enabled for the @var{RX600}
15617 series and disabled for the @var{RX200} series.
15619 Floating point instructions will only be generated for 32-bit floating
15620 point values however, so if the @option{-m64bit-doubles} option is in
15621 use then the FPU hardware will not be used for doubles.
15623 @emph{Note} If the @option{-fpu} option is enabled then
15624 @option{-funsafe-math-optimizations} is also enabled automatically.
15625 This is because the RX FPU instructions are themselves unsafe.
15627 @item -mcpu=@var{name}
15628 @itemx -patch=@var{name}
15631 Selects the type of RX CPU to be targeted. Currently three types are
15632 supported, the generic @var{RX600} and @var{RX200} series hardware and
15633 the specific @var{RX610} cpu. The default is @var{RX600}.
15635 The only difference between @var{RX600} and @var{RX610} is that the
15636 @var{RX610} does not support the @code{MVTIPL} instruction.
15638 The @var{RX200} series does not have a hardware floating point unit
15639 and so @option{-nofpu} is enabled by default when this type is
15642 @item -mbig-endian-data
15643 @itemx -mlittle-endian-data
15644 @opindex mbig-endian-data
15645 @opindex mlittle-endian-data
15646 Store data (but not code) in the big-endian format. The default is
15647 @option{-mlittle-endian-data}, ie to store data in the little endian
15650 @item -msmall-data-limit=@var{N}
15651 @opindex msmall-data-limit
15652 Specifies the maximum size in bytes of global and static variables
15653 which can be placed into the small data area. Using the small data
15654 area can lead to smaller and faster code, but the size of area is
15655 limited and it is up to the programmer to ensure that the area does
15656 not overflow. Also when the small data area is used one of the RX's
15657 registers (@code{r13}) is reserved for use pointing to this area, so
15658 it is no longer available for use by the compiler. This could result
15659 in slower and/or larger code if variables which once could have been
15660 held in @code{r13} are now pushed onto the stack.
15662 Note, common variables (variables which have not been initialised) and
15663 constants are not placed into the small data area as they are assigned
15664 to other sections in the output executable.
15666 The default value is zero, which disables this feature. Note, this
15667 feature is not enabled by default with higher optimization levels
15668 (@option{-O2} etc) because of the potentially detrimental effects of
15669 reserving register @code{r13}. It is up to the programmer to
15670 experiment and discover whether this feature is of benefit to their
15677 Use the simulator runtime. The default is to use the libgloss board
15680 @item -mas100-syntax
15681 @itemx -mno-as100-syntax
15682 @opindex mas100-syntax
15683 @opindex mno-as100-syntax
15684 When generating assembler output use a syntax that is compatible with
15685 Renesas's AS100 assembler. This syntax can also be handled by the GAS
15686 assembler but it has some restrictions so generating it is not the
15689 @item -mmax-constant-size=@var{N}
15690 @opindex mmax-constant-size
15691 Specifies the maximum size, in bytes, of a constant that can be used as
15692 an operand in a RX instruction. Although the RX instruction set does
15693 allow constants of up to 4 bytes in length to be used in instructions,
15694 a longer value equates to a longer instruction. Thus in some
15695 circumstances it can be beneficial to restrict the size of constants
15696 that are used in instructions. Constants that are too big are instead
15697 placed into a constant pool and referenced via register indirection.
15699 The value @var{N} can be between 0 and 4. A value of 0 (the default)
15700 or 4 means that constants of any size are allowed.
15704 Enable linker relaxation. Linker relaxation is a process whereby the
15705 linker will attempt to reduce the size of a program by finding shorter
15706 versions of various instructions. Disabled by default.
15708 @item -mint-register=@var{N}
15709 @opindex mint-register
15710 Specify the number of registers to reserve for fast interrupt handler
15711 functions. The value @var{N} can be between 0 and 4. A value of 1
15712 means that register @code{r13} will be reserved for the exclusive use
15713 of fast interrupt handlers. A value of 2 reserves @code{r13} and
15714 @code{r12}. A value of 3 reserves @code{r13}, @code{r12} and
15715 @code{r11}, and a value of 4 reserves @code{r13} through @code{r10}.
15716 A value of 0, the default, does not reserve any registers.
15718 @item -msave-acc-in-interrupts
15719 @opindex msave-acc-in-interrupts
15720 Specifies that interrupt handler functions should preserve the
15721 accumulator register. This is only necessary if normal code might use
15722 the accumulator register, for example because it performs 64-bit
15723 multiplications. The default is to ignore the accumulator as this
15724 makes the interrupt handlers faster.
15728 @emph{Note:} The generic GCC command line @option{-ffixed-@var{reg}}
15729 has special significance to the RX port when used with the
15730 @code{interrupt} function attribute. This attribute indicates a
15731 function intended to process fast interrupts. GCC will will ensure
15732 that it only uses the registers @code{r10}, @code{r11}, @code{r12}
15733 and/or @code{r13} and only provided that the normal use of the
15734 corresponding registers have been restricted via the
15735 @option{-ffixed-@var{reg}} or @option{-mint-register} command line
15738 @node S/390 and zSeries Options
15739 @subsection S/390 and zSeries Options
15740 @cindex S/390 and zSeries Options
15742 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
15746 @itemx -msoft-float
15747 @opindex mhard-float
15748 @opindex msoft-float
15749 Use (do not use) the hardware floating-point instructions and registers
15750 for floating-point operations. When @option{-msoft-float} is specified,
15751 functions in @file{libgcc.a} will be used to perform floating-point
15752 operations. When @option{-mhard-float} is specified, the compiler
15753 generates IEEE floating-point instructions. This is the default.
15756 @itemx -mno-hard-dfp
15758 @opindex mno-hard-dfp
15759 Use (do not use) the hardware decimal-floating-point instructions for
15760 decimal-floating-point operations. When @option{-mno-hard-dfp} is
15761 specified, functions in @file{libgcc.a} will be used to perform
15762 decimal-floating-point operations. When @option{-mhard-dfp} is
15763 specified, the compiler generates decimal-floating-point hardware
15764 instructions. This is the default for @option{-march=z9-ec} or higher.
15766 @item -mlong-double-64
15767 @itemx -mlong-double-128
15768 @opindex mlong-double-64
15769 @opindex mlong-double-128
15770 These switches control the size of @code{long double} type. A size
15771 of 64bit makes the @code{long double} type equivalent to the @code{double}
15772 type. This is the default.
15775 @itemx -mno-backchain
15776 @opindex mbackchain
15777 @opindex mno-backchain
15778 Store (do not store) the address of the caller's frame as backchain pointer
15779 into the callee's stack frame.
15780 A backchain may be needed to allow debugging using tools that do not understand
15781 DWARF-2 call frame information.
15782 When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
15783 at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
15784 the backchain is placed into the topmost word of the 96/160 byte register
15787 In general, code compiled with @option{-mbackchain} is call-compatible with
15788 code compiled with @option{-mmo-backchain}; however, use of the backchain
15789 for debugging purposes usually requires that the whole binary is built with
15790 @option{-mbackchain}. Note that the combination of @option{-mbackchain},
15791 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
15792 to build a linux kernel use @option{-msoft-float}.
15794 The default is to not maintain the backchain.
15796 @item -mpacked-stack
15797 @itemx -mno-packed-stack
15798 @opindex mpacked-stack
15799 @opindex mno-packed-stack
15800 Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
15801 specified, the compiler uses the all fields of the 96/160 byte register save
15802 area only for their default purpose; unused fields still take up stack space.
15803 When @option{-mpacked-stack} is specified, register save slots are densely
15804 packed at the top of the register save area; unused space is reused for other
15805 purposes, allowing for more efficient use of the available stack space.
15806 However, when @option{-mbackchain} is also in effect, the topmost word of
15807 the save area is always used to store the backchain, and the return address
15808 register is always saved two words below the backchain.
15810 As long as the stack frame backchain is not used, code generated with
15811 @option{-mpacked-stack} is call-compatible with code generated with
15812 @option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
15813 S/390 or zSeries generated code that uses the stack frame backchain at run
15814 time, not just for debugging purposes. Such code is not call-compatible
15815 with code compiled with @option{-mpacked-stack}. Also, note that the
15816 combination of @option{-mbackchain},
15817 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
15818 to build a linux kernel use @option{-msoft-float}.
15820 The default is to not use the packed stack layout.
15823 @itemx -mno-small-exec
15824 @opindex msmall-exec
15825 @opindex mno-small-exec
15826 Generate (or do not generate) code using the @code{bras} instruction
15827 to do subroutine calls.
15828 This only works reliably if the total executable size does not
15829 exceed 64k. The default is to use the @code{basr} instruction instead,
15830 which does not have this limitation.
15836 When @option{-m31} is specified, generate code compliant to the
15837 GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
15838 code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
15839 particular to generate 64-bit instructions. For the @samp{s390}
15840 targets, the default is @option{-m31}, while the @samp{s390x}
15841 targets default to @option{-m64}.
15847 When @option{-mzarch} is specified, generate code using the
15848 instructions available on z/Architecture.
15849 When @option{-mesa} is specified, generate code using the
15850 instructions available on ESA/390. Note that @option{-mesa} is
15851 not possible with @option{-m64}.
15852 When generating code compliant to the GNU/Linux for S/390 ABI,
15853 the default is @option{-mesa}. When generating code compliant
15854 to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
15860 Generate (or do not generate) code using the @code{mvcle} instruction
15861 to perform block moves. When @option{-mno-mvcle} is specified,
15862 use a @code{mvc} loop instead. This is the default unless optimizing for
15869 Print (or do not print) additional debug information when compiling.
15870 The default is to not print debug information.
15872 @item -march=@var{cpu-type}
15874 Generate code that will run on @var{cpu-type}, which is the name of a system
15875 representing a certain processor type. Possible values for
15876 @var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, @samp{z990},
15877 @samp{z9-109}, @samp{z9-ec} and @samp{z10}.
15878 When generating code using the instructions available on z/Architecture,
15879 the default is @option{-march=z900}. Otherwise, the default is
15880 @option{-march=g5}.
15882 @item -mtune=@var{cpu-type}
15884 Tune to @var{cpu-type} everything applicable about the generated code,
15885 except for the ABI and the set of available instructions.
15886 The list of @var{cpu-type} values is the same as for @option{-march}.
15887 The default is the value used for @option{-march}.
15890 @itemx -mno-tpf-trace
15891 @opindex mtpf-trace
15892 @opindex mno-tpf-trace
15893 Generate code that adds (does not add) in TPF OS specific branches to trace
15894 routines in the operating system. This option is off by default, even
15895 when compiling for the TPF OS@.
15898 @itemx -mno-fused-madd
15899 @opindex mfused-madd
15900 @opindex mno-fused-madd
15901 Generate code that uses (does not use) the floating point multiply and
15902 accumulate instructions. These instructions are generated by default if
15903 hardware floating point is used.
15905 @item -mwarn-framesize=@var{framesize}
15906 @opindex mwarn-framesize
15907 Emit a warning if the current function exceeds the given frame size. Because
15908 this is a compile time check it doesn't need to be a real problem when the program
15909 runs. It is intended to identify functions which most probably cause
15910 a stack overflow. It is useful to be used in an environment with limited stack
15911 size e.g.@: the linux kernel.
15913 @item -mwarn-dynamicstack
15914 @opindex mwarn-dynamicstack
15915 Emit a warning if the function calls alloca or uses dynamically
15916 sized arrays. This is generally a bad idea with a limited stack size.
15918 @item -mstack-guard=@var{stack-guard}
15919 @itemx -mstack-size=@var{stack-size}
15920 @opindex mstack-guard
15921 @opindex mstack-size
15922 If these options are provided the s390 back end emits additional instructions in
15923 the function prologue which trigger a trap if the stack size is @var{stack-guard}
15924 bytes above the @var{stack-size} (remember that the stack on s390 grows downward).
15925 If the @var{stack-guard} option is omitted the smallest power of 2 larger than
15926 the frame size of the compiled function is chosen.
15927 These options are intended to be used to help debugging stack overflow problems.
15928 The additionally emitted code causes only little overhead and hence can also be
15929 used in production like systems without greater performance degradation. The given
15930 values have to be exact powers of 2 and @var{stack-size} has to be greater than
15931 @var{stack-guard} without exceeding 64k.
15932 In order to be efficient the extra code makes the assumption that the stack starts
15933 at an address aligned to the value given by @var{stack-size}.
15934 The @var{stack-guard} option can only be used in conjunction with @var{stack-size}.
15937 @node Score Options
15938 @subsection Score Options
15939 @cindex Score Options
15941 These options are defined for Score implementations:
15946 Compile code for big endian mode. This is the default.
15950 Compile code for little endian mode.
15954 Disable generate bcnz instruction.
15958 Enable generate unaligned load and store instruction.
15962 Enable the use of multiply-accumulate instructions. Disabled by default.
15966 Specify the SCORE5 as the target architecture.
15970 Specify the SCORE5U of the target architecture.
15974 Specify the SCORE7 as the target architecture. This is the default.
15978 Specify the SCORE7D as the target architecture.
15982 @subsection SH Options
15984 These @samp{-m} options are defined for the SH implementations:
15989 Generate code for the SH1.
15993 Generate code for the SH2.
15996 Generate code for the SH2e.
16000 Generate code for the SH2a without FPU, or for a SH2a-FPU in such a way
16001 that the floating-point unit is not used.
16003 @item -m2a-single-only
16004 @opindex m2a-single-only
16005 Generate code for the SH2a-FPU, in such a way that no double-precision
16006 floating point operations are used.
16009 @opindex m2a-single
16010 Generate code for the SH2a-FPU assuming the floating-point unit is in
16011 single-precision mode by default.
16015 Generate code for the SH2a-FPU assuming the floating-point unit is in
16016 double-precision mode by default.
16020 Generate code for the SH3.
16024 Generate code for the SH3e.
16028 Generate code for the SH4 without a floating-point unit.
16030 @item -m4-single-only
16031 @opindex m4-single-only
16032 Generate code for the SH4 with a floating-point unit that only
16033 supports single-precision arithmetic.
16037 Generate code for the SH4 assuming the floating-point unit is in
16038 single-precision mode by default.
16042 Generate code for the SH4.
16046 Generate code for the SH4al-dsp, or for a SH4a in such a way that the
16047 floating-point unit is not used.
16049 @item -m4a-single-only
16050 @opindex m4a-single-only
16051 Generate code for the SH4a, in such a way that no double-precision
16052 floating point operations are used.
16055 @opindex m4a-single
16056 Generate code for the SH4a assuming the floating-point unit is in
16057 single-precision mode by default.
16061 Generate code for the SH4a.
16065 Same as @option{-m4a-nofpu}, except that it implicitly passes
16066 @option{-dsp} to the assembler. GCC doesn't generate any DSP
16067 instructions at the moment.
16071 Compile code for the processor in big endian mode.
16075 Compile code for the processor in little endian mode.
16079 Align doubles at 64-bit boundaries. Note that this changes the calling
16080 conventions, and thus some functions from the standard C library will
16081 not work unless you recompile it first with @option{-mdalign}.
16085 Shorten some address references at link time, when possible; uses the
16086 linker option @option{-relax}.
16090 Use 32-bit offsets in @code{switch} tables. The default is to use
16095 Enable the use of bit manipulation instructions on SH2A.
16099 Enable the use of the instruction @code{fmovd}. Check @option{-mdalign} for
16100 alignment constraints.
16104 Comply with the calling conventions defined by Renesas.
16108 Comply with the calling conventions defined by Renesas.
16112 Comply with the calling conventions defined for GCC before the Renesas
16113 conventions were available. This option is the default for all
16114 targets of the SH toolchain except for @samp{sh-symbianelf}.
16117 @opindex mnomacsave
16118 Mark the @code{MAC} register as call-clobbered, even if
16119 @option{-mhitachi} is given.
16123 Increase IEEE-compliance of floating-point code.
16124 At the moment, this is equivalent to @option{-fno-finite-math-only}.
16125 When generating 16 bit SH opcodes, getting IEEE-conforming results for
16126 comparisons of NANs / infinities incurs extra overhead in every
16127 floating point comparison, therefore the default is set to
16128 @option{-ffinite-math-only}.
16130 @item -minline-ic_invalidate
16131 @opindex minline-ic_invalidate
16132 Inline code to invalidate instruction cache entries after setting up
16133 nested function trampolines.
16134 This option has no effect if -musermode is in effect and the selected
16135 code generation option (e.g. -m4) does not allow the use of the icbi
16137 If the selected code generation option does not allow the use of the icbi
16138 instruction, and -musermode is not in effect, the inlined code will
16139 manipulate the instruction cache address array directly with an associative
16140 write. This not only requires privileged mode, but it will also
16141 fail if the cache line had been mapped via the TLB and has become unmapped.
16145 Dump instruction size and location in the assembly code.
16148 @opindex mpadstruct
16149 This option is deprecated. It pads structures to multiple of 4 bytes,
16150 which is incompatible with the SH ABI@.
16154 Optimize for space instead of speed. Implied by @option{-Os}.
16157 @opindex mprefergot
16158 When generating position-independent code, emit function calls using
16159 the Global Offset Table instead of the Procedure Linkage Table.
16163 Don't generate privileged mode only code; implies -mno-inline-ic_invalidate
16164 if the inlined code would not work in user mode.
16165 This is the default when the target is @code{sh-*-linux*}.
16167 @item -multcost=@var{number}
16168 @opindex multcost=@var{number}
16169 Set the cost to assume for a multiply insn.
16171 @item -mdiv=@var{strategy}
16172 @opindex mdiv=@var{strategy}
16173 Set the division strategy to use for SHmedia code. @var{strategy} must be
16174 one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
16175 inv:call2, inv:fp .
16176 "fp" performs the operation in floating point. This has a very high latency,
16177 but needs only a few instructions, so it might be a good choice if
16178 your code has enough easily exploitable ILP to allow the compiler to
16179 schedule the floating point instructions together with other instructions.
16180 Division by zero causes a floating point exception.
16181 "inv" uses integer operations to calculate the inverse of the divisor,
16182 and then multiplies the dividend with the inverse. This strategy allows
16183 cse and hoisting of the inverse calculation. Division by zero calculates
16184 an unspecified result, but does not trap.
16185 "inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
16186 have been found, or if the entire operation has been hoisted to the same
16187 place, the last stages of the inverse calculation are intertwined with the
16188 final multiply to reduce the overall latency, at the expense of using a few
16189 more instructions, and thus offering fewer scheduling opportunities with
16191 "call" calls a library function that usually implements the inv:minlat
16193 This gives high code density for m5-*media-nofpu compilations.
16194 "call2" uses a different entry point of the same library function, where it
16195 assumes that a pointer to a lookup table has already been set up, which
16196 exposes the pointer load to cse / code hoisting optimizations.
16197 "inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
16198 code generation, but if the code stays unoptimized, revert to the "call",
16199 "call2", or "fp" strategies, respectively. Note that the
16200 potentially-trapping side effect of division by zero is carried by a
16201 separate instruction, so it is possible that all the integer instructions
16202 are hoisted out, but the marker for the side effect stays where it is.
16203 A recombination to fp operations or a call is not possible in that case.
16204 "inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
16205 that the inverse calculation was nor separated from the multiply, they speed
16206 up division where the dividend fits into 20 bits (plus sign where applicable),
16207 by inserting a test to skip a number of operations in this case; this test
16208 slows down the case of larger dividends. inv20u assumes the case of a such
16209 a small dividend to be unlikely, and inv20l assumes it to be likely.
16211 @item -maccumulate-outgoing-args
16212 @opindex maccumulate-outgoing-args
16213 Reserve space once for outgoing arguments in the function prologue rather
16214 than around each call. Generally beneficial for performance and size. Also
16215 needed for unwinding to avoid changing the stack frame around conditional code.
16217 @item -mdivsi3_libfunc=@var{name}
16218 @opindex mdivsi3_libfunc=@var{name}
16219 Set the name of the library function used for 32 bit signed division to
16220 @var{name}. This only affect the name used in the call and inv:call
16221 division strategies, and the compiler will still expect the same
16222 sets of input/output/clobbered registers as if this option was not present.
16224 @item -mfixed-range=@var{register-range}
16225 @opindex mfixed-range
16226 Generate code treating the given register range as fixed registers.
16227 A fixed register is one that the register allocator can not use. This is
16228 useful when compiling kernel code. A register range is specified as
16229 two registers separated by a dash. Multiple register ranges can be
16230 specified separated by a comma.
16232 @item -madjust-unroll
16233 @opindex madjust-unroll
16234 Throttle unrolling to avoid thrashing target registers.
16235 This option only has an effect if the gcc code base supports the
16236 TARGET_ADJUST_UNROLL_MAX target hook.
16238 @item -mindexed-addressing
16239 @opindex mindexed-addressing
16240 Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
16241 This is only safe if the hardware and/or OS implement 32 bit wrap-around
16242 semantics for the indexed addressing mode. The architecture allows the
16243 implementation of processors with 64 bit MMU, which the OS could use to
16244 get 32 bit addressing, but since no current hardware implementation supports
16245 this or any other way to make the indexed addressing mode safe to use in
16246 the 32 bit ABI, the default is -mno-indexed-addressing.
16248 @item -mgettrcost=@var{number}
16249 @opindex mgettrcost=@var{number}
16250 Set the cost assumed for the gettr instruction to @var{number}.
16251 The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
16255 Assume pt* instructions won't trap. This will generally generate better
16256 scheduled code, but is unsafe on current hardware. The current architecture
16257 definition says that ptabs and ptrel trap when the target anded with 3 is 3.
16258 This has the unintentional effect of making it unsafe to schedule ptabs /
16259 ptrel before a branch, or hoist it out of a loop. For example,
16260 __do_global_ctors, a part of libgcc that runs constructors at program
16261 startup, calls functions in a list which is delimited by @minus{}1. With the
16262 -mpt-fixed option, the ptabs will be done before testing against @minus{}1.
16263 That means that all the constructors will be run a bit quicker, but when
16264 the loop comes to the end of the list, the program crashes because ptabs
16265 loads @minus{}1 into a target register. Since this option is unsafe for any
16266 hardware implementing the current architecture specification, the default
16267 is -mno-pt-fixed. Unless the user specifies a specific cost with
16268 @option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
16269 this deters register allocation using target registers for storing
16272 @item -minvalid-symbols
16273 @opindex minvalid-symbols
16274 Assume symbols might be invalid. Ordinary function symbols generated by
16275 the compiler will always be valid to load with movi/shori/ptabs or
16276 movi/shori/ptrel, but with assembler and/or linker tricks it is possible
16277 to generate symbols that will cause ptabs / ptrel to trap.
16278 This option is only meaningful when @option{-mno-pt-fixed} is in effect.
16279 It will then prevent cross-basic-block cse, hoisting and most scheduling
16280 of symbol loads. The default is @option{-mno-invalid-symbols}.
16283 @node SPARC Options
16284 @subsection SPARC Options
16285 @cindex SPARC options
16287 These @samp{-m} options are supported on the SPARC:
16290 @item -mno-app-regs
16292 @opindex mno-app-regs
16294 Specify @option{-mapp-regs} to generate output using the global registers
16295 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
16298 To be fully SVR4 ABI compliant at the cost of some performance loss,
16299 specify @option{-mno-app-regs}. You should compile libraries and system
16300 software with this option.
16303 @itemx -mhard-float
16305 @opindex mhard-float
16306 Generate output containing floating point instructions. This is the
16310 @itemx -msoft-float
16312 @opindex msoft-float
16313 Generate output containing library calls for floating point.
16314 @strong{Warning:} the requisite libraries are not available for all SPARC
16315 targets. Normally the facilities of the machine's usual C compiler are
16316 used, but this cannot be done directly in cross-compilation. You must make
16317 your own arrangements to provide suitable library functions for
16318 cross-compilation. The embedded targets @samp{sparc-*-aout} and
16319 @samp{sparclite-*-*} do provide software floating point support.
16321 @option{-msoft-float} changes the calling convention in the output file;
16322 therefore, it is only useful if you compile @emph{all} of a program with
16323 this option. In particular, you need to compile @file{libgcc.a}, the
16324 library that comes with GCC, with @option{-msoft-float} in order for
16327 @item -mhard-quad-float
16328 @opindex mhard-quad-float
16329 Generate output containing quad-word (long double) floating point
16332 @item -msoft-quad-float
16333 @opindex msoft-quad-float
16334 Generate output containing library calls for quad-word (long double)
16335 floating point instructions. The functions called are those specified
16336 in the SPARC ABI@. This is the default.
16338 As of this writing, there are no SPARC implementations that have hardware
16339 support for the quad-word floating point instructions. They all invoke
16340 a trap handler for one of these instructions, and then the trap handler
16341 emulates the effect of the instruction. Because of the trap handler overhead,
16342 this is much slower than calling the ABI library routines. Thus the
16343 @option{-msoft-quad-float} option is the default.
16345 @item -mno-unaligned-doubles
16346 @itemx -munaligned-doubles
16347 @opindex mno-unaligned-doubles
16348 @opindex munaligned-doubles
16349 Assume that doubles have 8 byte alignment. This is the default.
16351 With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
16352 alignment only if they are contained in another type, or if they have an
16353 absolute address. Otherwise, it assumes they have 4 byte alignment.
16354 Specifying this option avoids some rare compatibility problems with code
16355 generated by other compilers. It is not the default because it results
16356 in a performance loss, especially for floating point code.
16358 @item -mno-faster-structs
16359 @itemx -mfaster-structs
16360 @opindex mno-faster-structs
16361 @opindex mfaster-structs
16362 With @option{-mfaster-structs}, the compiler assumes that structures
16363 should have 8 byte alignment. This enables the use of pairs of
16364 @code{ldd} and @code{std} instructions for copies in structure
16365 assignment, in place of twice as many @code{ld} and @code{st} pairs.
16366 However, the use of this changed alignment directly violates the SPARC
16367 ABI@. Thus, it's intended only for use on targets where the developer
16368 acknowledges that their resulting code will not be directly in line with
16369 the rules of the ABI@.
16371 @item -mimpure-text
16372 @opindex mimpure-text
16373 @option{-mimpure-text}, used in addition to @option{-shared}, tells
16374 the compiler to not pass @option{-z text} to the linker when linking a
16375 shared object. Using this option, you can link position-dependent
16376 code into a shared object.
16378 @option{-mimpure-text} suppresses the ``relocations remain against
16379 allocatable but non-writable sections'' linker error message.
16380 However, the necessary relocations will trigger copy-on-write, and the
16381 shared object is not actually shared across processes. Instead of
16382 using @option{-mimpure-text}, you should compile all source code with
16383 @option{-fpic} or @option{-fPIC}.
16385 This option is only available on SunOS and Solaris.
16387 @item -mcpu=@var{cpu_type}
16389 Set the instruction set, register set, and instruction scheduling parameters
16390 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
16391 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
16392 @samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
16393 @samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
16394 @samp{ultrasparc3}, @samp{niagara} and @samp{niagara2}.
16396 Default instruction scheduling parameters are used for values that select
16397 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
16398 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
16400 Here is a list of each supported architecture and their supported
16405 v8: supersparc, hypersparc
16406 sparclite: f930, f934, sparclite86x
16408 v9: ultrasparc, ultrasparc3, niagara, niagara2
16411 By default (unless configured otherwise), GCC generates code for the V7
16412 variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
16413 additionally optimizes it for the Cypress CY7C602 chip, as used in the
16414 SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
16415 SPARCStation 1, 2, IPX etc.
16417 With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
16418 architecture. The only difference from V7 code is that the compiler emits
16419 the integer multiply and integer divide instructions which exist in SPARC-V8
16420 but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
16421 optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
16424 With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
16425 the SPARC architecture. This adds the integer multiply, integer divide step
16426 and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
16427 With @option{-mcpu=f930}, the compiler additionally optimizes it for the
16428 Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
16429 @option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
16430 MB86934 chip, which is the more recent SPARClite with FPU@.
16432 With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
16433 the SPARC architecture. This adds the integer multiply, multiply/accumulate,
16434 integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
16435 but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
16436 optimizes it for the TEMIC SPARClet chip.
16438 With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
16439 architecture. This adds 64-bit integer and floating-point move instructions,
16440 3 additional floating-point condition code registers and conditional move
16441 instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
16442 optimizes it for the Sun UltraSPARC I/II/IIi chips. With
16443 @option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
16444 Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
16445 @option{-mcpu=niagara}, the compiler additionally optimizes it for
16446 Sun UltraSPARC T1 chips. With @option{-mcpu=niagara2}, the compiler
16447 additionally optimizes it for Sun UltraSPARC T2 chips.
16449 @item -mtune=@var{cpu_type}
16451 Set the instruction scheduling parameters for machine type
16452 @var{cpu_type}, but do not set the instruction set or register set that the
16453 option @option{-mcpu=@var{cpu_type}} would.
16455 The same values for @option{-mcpu=@var{cpu_type}} can be used for
16456 @option{-mtune=@var{cpu_type}}, but the only useful values are those
16457 that select a particular cpu implementation. Those are @samp{cypress},
16458 @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
16459 @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
16460 @samp{ultrasparc3}, @samp{niagara}, and @samp{niagara2}.
16465 @opindex mno-v8plus
16466 With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
16467 difference from the V8 ABI is that the global and out registers are
16468 considered 64-bit wide. This is enabled by default on Solaris in 32-bit
16469 mode for all SPARC-V9 processors.
16475 With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
16476 Visual Instruction Set extensions. The default is @option{-mno-vis}.
16479 These @samp{-m} options are supported in addition to the above
16480 on SPARC-V9 processors in 64-bit environments:
16483 @item -mlittle-endian
16484 @opindex mlittle-endian
16485 Generate code for a processor running in little-endian mode. It is only
16486 available for a few configurations and most notably not on Solaris and Linux.
16492 Generate code for a 32-bit or 64-bit environment.
16493 The 32-bit environment sets int, long and pointer to 32 bits.
16494 The 64-bit environment sets int to 32 bits and long and pointer
16497 @item -mcmodel=medlow
16498 @opindex mcmodel=medlow
16499 Generate code for the Medium/Low code model: 64-bit addresses, programs
16500 must be linked in the low 32 bits of memory. Programs can be statically
16501 or dynamically linked.
16503 @item -mcmodel=medmid
16504 @opindex mcmodel=medmid
16505 Generate code for the Medium/Middle code model: 64-bit addresses, programs
16506 must be linked in the low 44 bits of memory, the text and data segments must
16507 be less than 2GB in size and the data segment must be located within 2GB of
16510 @item -mcmodel=medany
16511 @opindex mcmodel=medany
16512 Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
16513 may be linked anywhere in memory, the text and data segments must be less
16514 than 2GB in size and the data segment must be located within 2GB of the
16517 @item -mcmodel=embmedany
16518 @opindex mcmodel=embmedany
16519 Generate code for the Medium/Anywhere code model for embedded systems:
16520 64-bit addresses, the text and data segments must be less than 2GB in
16521 size, both starting anywhere in memory (determined at link time). The
16522 global register %g4 points to the base of the data segment. Programs
16523 are statically linked and PIC is not supported.
16526 @itemx -mno-stack-bias
16527 @opindex mstack-bias
16528 @opindex mno-stack-bias
16529 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
16530 frame pointer if present, are offset by @minus{}2047 which must be added back
16531 when making stack frame references. This is the default in 64-bit mode.
16532 Otherwise, assume no such offset is present.
16535 These switches are supported in addition to the above on Solaris:
16540 Add support for multithreading using the Solaris threads library. This
16541 option sets flags for both the preprocessor and linker. This option does
16542 not affect the thread safety of object code produced by the compiler or
16543 that of libraries supplied with it.
16547 Add support for multithreading using the POSIX threads library. This
16548 option sets flags for both the preprocessor and linker. This option does
16549 not affect the thread safety of object code produced by the compiler or
16550 that of libraries supplied with it.
16554 This is a synonym for @option{-pthreads}.
16558 @subsection SPU Options
16559 @cindex SPU options
16561 These @samp{-m} options are supported on the SPU:
16565 @itemx -merror-reloc
16566 @opindex mwarn-reloc
16567 @opindex merror-reloc
16569 The loader for SPU does not handle dynamic relocations. By default, GCC
16570 will give an error when it generates code that requires a dynamic
16571 relocation. @option{-mno-error-reloc} disables the error,
16572 @option{-mwarn-reloc} will generate a warning instead.
16575 @itemx -munsafe-dma
16577 @opindex munsafe-dma
16579 Instructions which initiate or test completion of DMA must not be
16580 reordered with respect to loads and stores of the memory which is being
16581 accessed. Users typically address this problem using the volatile
16582 keyword, but that can lead to inefficient code in places where the
16583 memory is known to not change. Rather than mark the memory as volatile
16584 we treat the DMA instructions as potentially effecting all memory. With
16585 @option{-munsafe-dma} users must use the volatile keyword to protect
16588 @item -mbranch-hints
16589 @opindex mbranch-hints
16591 By default, GCC will generate a branch hint instruction to avoid
16592 pipeline stalls for always taken or probably taken branches. A hint
16593 will not be generated closer than 8 instructions away from its branch.
16594 There is little reason to disable them, except for debugging purposes,
16595 or to make an object a little bit smaller.
16599 @opindex msmall-mem
16600 @opindex mlarge-mem
16602 By default, GCC generates code assuming that addresses are never larger
16603 than 18 bits. With @option{-mlarge-mem} code is generated that assumes
16604 a full 32 bit address.
16609 By default, GCC links against startup code that assumes the SPU-style
16610 main function interface (which has an unconventional parameter list).
16611 With @option{-mstdmain}, GCC will link your program against startup
16612 code that assumes a C99-style interface to @code{main}, including a
16613 local copy of @code{argv} strings.
16615 @item -mfixed-range=@var{register-range}
16616 @opindex mfixed-range
16617 Generate code treating the given register range as fixed registers.
16618 A fixed register is one that the register allocator can not use. This is
16619 useful when compiling kernel code. A register range is specified as
16620 two registers separated by a dash. Multiple register ranges can be
16621 specified separated by a comma.
16627 Compile code assuming that pointers to the PPU address space accessed
16628 via the @code{__ea} named address space qualifier are either 32 or 64
16629 bits wide. The default is 32 bits. As this is an ABI changing option,
16630 all object code in an executable must be compiled with the same setting.
16632 @item -maddress-space-conversion
16633 @itemx -mno-address-space-conversion
16634 @opindex maddress-space-conversion
16635 @opindex mno-address-space-conversion
16636 Allow/disallow treating the @code{__ea} address space as superset
16637 of the generic address space. This enables explicit type casts
16638 between @code{__ea} and generic pointer as well as implicit
16639 conversions of generic pointers to @code{__ea} pointers. The
16640 default is to allow address space pointer conversions.
16642 @item -mcache-size=@var{cache-size}
16643 @opindex mcache-size
16644 This option controls the version of libgcc that the compiler links to an
16645 executable and selects a software-managed cache for accessing variables
16646 in the @code{__ea} address space with a particular cache size. Possible
16647 options for @var{cache-size} are @samp{8}, @samp{16}, @samp{32}, @samp{64}
16648 and @samp{128}. The default cache size is 64KB.
16650 @item -matomic-updates
16651 @itemx -mno-atomic-updates
16652 @opindex matomic-updates
16653 @opindex mno-atomic-updates
16654 This option controls the version of libgcc that the compiler links to an
16655 executable and selects whether atomic updates to the software-managed
16656 cache of PPU-side variables are used. If you use atomic updates, changes
16657 to a PPU variable from SPU code using the @code{__ea} named address space
16658 qualifier will not interfere with changes to other PPU variables residing
16659 in the same cache line from PPU code. If you do not use atomic updates,
16660 such interference may occur; however, writing back cache lines will be
16661 more efficient. The default behavior is to use atomic updates.
16664 @itemx -mdual-nops=@var{n}
16665 @opindex mdual-nops
16666 By default, GCC will insert nops to increase dual issue when it expects
16667 it to increase performance. @var{n} can be a value from 0 to 10. A
16668 smaller @var{n} will insert fewer nops. 10 is the default, 0 is the
16669 same as @option{-mno-dual-nops}. Disabled with @option{-Os}.
16671 @item -mhint-max-nops=@var{n}
16672 @opindex mhint-max-nops
16673 Maximum number of nops to insert for a branch hint. A branch hint must
16674 be at least 8 instructions away from the branch it is effecting. GCC
16675 will insert up to @var{n} nops to enforce this, otherwise it will not
16676 generate the branch hint.
16678 @item -mhint-max-distance=@var{n}
16679 @opindex mhint-max-distance
16680 The encoding of the branch hint instruction limits the hint to be within
16681 256 instructions of the branch it is effecting. By default, GCC makes
16682 sure it is within 125.
16685 @opindex msafe-hints
16686 Work around a hardware bug which causes the SPU to stall indefinitely.
16687 By default, GCC will insert the @code{hbrp} instruction to make sure
16688 this stall won't happen.
16692 @node System V Options
16693 @subsection Options for System V
16695 These additional options are available on System V Release 4 for
16696 compatibility with other compilers on those systems:
16701 Create a shared object.
16702 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
16706 Identify the versions of each tool used by the compiler, in a
16707 @code{.ident} assembler directive in the output.
16711 Refrain from adding @code{.ident} directives to the output file (this is
16714 @item -YP,@var{dirs}
16716 Search the directories @var{dirs}, and no others, for libraries
16717 specified with @option{-l}.
16719 @item -Ym,@var{dir}
16721 Look in the directory @var{dir} to find the M4 preprocessor.
16722 The assembler uses this option.
16723 @c This is supposed to go with a -Yd for predefined M4 macro files, but
16724 @c the generic assembler that comes with Solaris takes just -Ym.
16728 @subsection V850 Options
16729 @cindex V850 Options
16731 These @samp{-m} options are defined for V850 implementations:
16735 @itemx -mno-long-calls
16736 @opindex mlong-calls
16737 @opindex mno-long-calls
16738 Treat all calls as being far away (near). If calls are assumed to be
16739 far away, the compiler will always load the functions address up into a
16740 register, and call indirect through the pointer.
16746 Do not optimize (do optimize) basic blocks that use the same index
16747 pointer 4 or more times to copy pointer into the @code{ep} register, and
16748 use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
16749 option is on by default if you optimize.
16751 @item -mno-prolog-function
16752 @itemx -mprolog-function
16753 @opindex mno-prolog-function
16754 @opindex mprolog-function
16755 Do not use (do use) external functions to save and restore registers
16756 at the prologue and epilogue of a function. The external functions
16757 are slower, but use less code space if more than one function saves
16758 the same number of registers. The @option{-mprolog-function} option
16759 is on by default if you optimize.
16763 Try to make the code as small as possible. At present, this just turns
16764 on the @option{-mep} and @option{-mprolog-function} options.
16766 @item -mtda=@var{n}
16768 Put static or global variables whose size is @var{n} bytes or less into
16769 the tiny data area that register @code{ep} points to. The tiny data
16770 area can hold up to 256 bytes in total (128 bytes for byte references).
16772 @item -msda=@var{n}
16774 Put static or global variables whose size is @var{n} bytes or less into
16775 the small data area that register @code{gp} points to. The small data
16776 area can hold up to 64 kilobytes.
16778 @item -mzda=@var{n}
16780 Put static or global variables whose size is @var{n} bytes or less into
16781 the first 32 kilobytes of memory.
16785 Specify that the target processor is the V850.
16788 @opindex mbig-switch
16789 Generate code suitable for big switch tables. Use this option only if
16790 the assembler/linker complain about out of range branches within a switch
16795 This option will cause r2 and r5 to be used in the code generated by
16796 the compiler. This setting is the default.
16798 @item -mno-app-regs
16799 @opindex mno-app-regs
16800 This option will cause r2 and r5 to be treated as fixed registers.
16804 Specify that the target processor is the V850E1. The preprocessor
16805 constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
16806 this option is used.
16810 Specify that the target processor is the V850E@. The preprocessor
16811 constant @samp{__v850e__} will be defined if this option is used.
16813 If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
16814 are defined then a default target processor will be chosen and the
16815 relevant @samp{__v850*__} preprocessor constant will be defined.
16817 The preprocessor constants @samp{__v850} and @samp{__v851__} are always
16818 defined, regardless of which processor variant is the target.
16820 @item -mdisable-callt
16821 @opindex mdisable-callt
16822 This option will suppress generation of the CALLT instruction for the
16823 v850e and v850e1 flavors of the v850 architecture. The default is
16824 @option{-mno-disable-callt} which allows the CALLT instruction to be used.
16829 @subsection VAX Options
16830 @cindex VAX options
16832 These @samp{-m} options are defined for the VAX:
16837 Do not output certain jump instructions (@code{aobleq} and so on)
16838 that the Unix assembler for the VAX cannot handle across long
16843 Do output those jump instructions, on the assumption that you
16844 will assemble with the GNU assembler.
16848 Output code for g-format floating point numbers instead of d-format.
16851 @node VxWorks Options
16852 @subsection VxWorks Options
16853 @cindex VxWorks Options
16855 The options in this section are defined for all VxWorks targets.
16856 Options specific to the target hardware are listed with the other
16857 options for that target.
16862 GCC can generate code for both VxWorks kernels and real time processes
16863 (RTPs). This option switches from the former to the latter. It also
16864 defines the preprocessor macro @code{__RTP__}.
16867 @opindex non-static
16868 Link an RTP executable against shared libraries rather than static
16869 libraries. The options @option{-static} and @option{-shared} can
16870 also be used for RTPs (@pxref{Link Options}); @option{-static}
16877 These options are passed down to the linker. They are defined for
16878 compatibility with Diab.
16881 @opindex Xbind-lazy
16882 Enable lazy binding of function calls. This option is equivalent to
16883 @option{-Wl,-z,now} and is defined for compatibility with Diab.
16887 Disable lazy binding of function calls. This option is the default and
16888 is defined for compatibility with Diab.
16891 @node x86-64 Options
16892 @subsection x86-64 Options
16893 @cindex x86-64 options
16895 These are listed under @xref{i386 and x86-64 Options}.
16897 @node i386 and x86-64 Windows Options
16898 @subsection i386 and x86-64 Windows Options
16899 @cindex i386 and x86-64 Windows Options
16901 These additional options are available for Windows targets:
16906 This option is available for Cygwin and MinGW targets. It
16907 specifies that a console application is to be generated, by
16908 instructing the linker to set the PE header subsystem type
16909 required for console applications.
16910 This is the default behavior for Cygwin and MinGW targets.
16914 This option is available for Cygwin targets. It specifies that
16915 the Cygwin internal interface is to be used for predefined
16916 preprocessor macros, C runtime libraries and related linker
16917 paths and options. For Cygwin targets this is the default behavior.
16918 This option is deprecated and will be removed in a future release.
16921 @opindex mno-cygwin
16922 This option is available for Cygwin targets. It specifies that
16923 the MinGW internal interface is to be used instead of Cygwin's, by
16924 setting MinGW-related predefined macros and linker paths and default
16926 This option is deprecated and will be removed in a future release.
16930 This option is available for Cygwin and MinGW targets. It
16931 specifies that a DLL - a dynamic link library - is to be
16932 generated, enabling the selection of the required runtime
16933 startup object and entry point.
16935 @item -mnop-fun-dllimport
16936 @opindex mnop-fun-dllimport
16937 This option is available for Cygwin and MinGW targets. It
16938 specifies that the dllimport attribute should be ignored.
16942 This option is available for MinGW targets. It specifies
16943 that MinGW-specific thread support is to be used.
16947 This option is available for mingw-w64 targets. It specifies
16948 that the UNICODE macro is getting pre-defined and that the
16949 unicode capable runtime startup code is chosen.
16953 This option is available for Cygwin and MinGW targets. It
16954 specifies that the typical Windows pre-defined macros are to
16955 be set in the pre-processor, but does not influence the choice
16956 of runtime library/startup code.
16960 This option is available for Cygwin and MinGW targets. It
16961 specifies that a GUI application is to be generated by
16962 instructing the linker to set the PE header subsystem type
16965 @item -fno-set-stack-executable
16966 @opindex fno-set-stack-executable
16967 This option is available for MinGW targets. It specifies that
16968 the executable flag for stack used by nested functions isn't
16969 set. This is necessary for binaries running in kernel mode of
16970 Windows, as there the user32 API, which is used to set executable
16971 privileges, isn't available.
16973 @item -mpe-aligned-commons
16974 @opindex mpe-aligned-commons
16975 This option is available for Cygwin and MinGW targets. It
16976 specifies that the GNU extension to the PE file format that
16977 permits the correct alignment of COMMON variables should be
16978 used when generating code. It will be enabled by default if
16979 GCC detects that the target assembler found during configuration
16980 supports the feature.
16983 See also under @ref{i386 and x86-64 Options} for standard options.
16985 @node Xstormy16 Options
16986 @subsection Xstormy16 Options
16987 @cindex Xstormy16 Options
16989 These options are defined for Xstormy16:
16994 Choose startup files and linker script suitable for the simulator.
16997 @node Xtensa Options
16998 @subsection Xtensa Options
16999 @cindex Xtensa Options
17001 These options are supported for Xtensa targets:
17005 @itemx -mno-const16
17007 @opindex mno-const16
17008 Enable or disable use of @code{CONST16} instructions for loading
17009 constant values. The @code{CONST16} instruction is currently not a
17010 standard option from Tensilica. When enabled, @code{CONST16}
17011 instructions are always used in place of the standard @code{L32R}
17012 instructions. The use of @code{CONST16} is enabled by default only if
17013 the @code{L32R} instruction is not available.
17016 @itemx -mno-fused-madd
17017 @opindex mfused-madd
17018 @opindex mno-fused-madd
17019 Enable or disable use of fused multiply/add and multiply/subtract
17020 instructions in the floating-point option. This has no effect if the
17021 floating-point option is not also enabled. Disabling fused multiply/add
17022 and multiply/subtract instructions forces the compiler to use separate
17023 instructions for the multiply and add/subtract operations. This may be
17024 desirable in some cases where strict IEEE 754-compliant results are
17025 required: the fused multiply add/subtract instructions do not round the
17026 intermediate result, thereby producing results with @emph{more} bits of
17027 precision than specified by the IEEE standard. Disabling fused multiply
17028 add/subtract instructions also ensures that the program output is not
17029 sensitive to the compiler's ability to combine multiply and add/subtract
17032 @item -mserialize-volatile
17033 @itemx -mno-serialize-volatile
17034 @opindex mserialize-volatile
17035 @opindex mno-serialize-volatile
17036 When this option is enabled, GCC inserts @code{MEMW} instructions before
17037 @code{volatile} memory references to guarantee sequential consistency.
17038 The default is @option{-mserialize-volatile}. Use
17039 @option{-mno-serialize-volatile} to omit the @code{MEMW} instructions.
17041 @item -mtext-section-literals
17042 @itemx -mno-text-section-literals
17043 @opindex mtext-section-literals
17044 @opindex mno-text-section-literals
17045 Control the treatment of literal pools. The default is
17046 @option{-mno-text-section-literals}, which places literals in a separate
17047 section in the output file. This allows the literal pool to be placed
17048 in a data RAM/ROM, and it also allows the linker to combine literal
17049 pools from separate object files to remove redundant literals and
17050 improve code size. With @option{-mtext-section-literals}, the literals
17051 are interspersed in the text section in order to keep them as close as
17052 possible to their references. This may be necessary for large assembly
17055 @item -mtarget-align
17056 @itemx -mno-target-align
17057 @opindex mtarget-align
17058 @opindex mno-target-align
17059 When this option is enabled, GCC instructs the assembler to
17060 automatically align instructions to reduce branch penalties at the
17061 expense of some code density. The assembler attempts to widen density
17062 instructions to align branch targets and the instructions following call
17063 instructions. If there are not enough preceding safe density
17064 instructions to align a target, no widening will be performed. The
17065 default is @option{-mtarget-align}. These options do not affect the
17066 treatment of auto-aligned instructions like @code{LOOP}, which the
17067 assembler will always align, either by widening density instructions or
17068 by inserting no-op instructions.
17071 @itemx -mno-longcalls
17072 @opindex mlongcalls
17073 @opindex mno-longcalls
17074 When this option is enabled, GCC instructs the assembler to translate
17075 direct calls to indirect calls unless it can determine that the target
17076 of a direct call is in the range allowed by the call instruction. This
17077 translation typically occurs for calls to functions in other source
17078 files. Specifically, the assembler translates a direct @code{CALL}
17079 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
17080 The default is @option{-mno-longcalls}. This option should be used in
17081 programs where the call target can potentially be out of range. This
17082 option is implemented in the assembler, not the compiler, so the
17083 assembly code generated by GCC will still show direct call
17084 instructions---look at the disassembled object code to see the actual
17085 instructions. Note that the assembler will use an indirect call for
17086 every cross-file call, not just those that really will be out of range.
17089 @node zSeries Options
17090 @subsection zSeries Options
17091 @cindex zSeries options
17093 These are listed under @xref{S/390 and zSeries Options}.
17095 @node Code Gen Options
17096 @section Options for Code Generation Conventions
17097 @cindex code generation conventions
17098 @cindex options, code generation
17099 @cindex run-time options
17101 These machine-independent options control the interface conventions
17102 used in code generation.
17104 Most of them have both positive and negative forms; the negative form
17105 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
17106 one of the forms is listed---the one which is not the default. You
17107 can figure out the other form by either removing @samp{no-} or adding
17111 @item -fbounds-check
17112 @opindex fbounds-check
17113 For front-ends that support it, generate additional code to check that
17114 indices used to access arrays are within the declared range. This is
17115 currently only supported by the Java and Fortran front-ends, where
17116 this option defaults to true and false respectively.
17120 This option generates traps for signed overflow on addition, subtraction,
17121 multiplication operations.
17125 This option instructs the compiler to assume that signed arithmetic
17126 overflow of addition, subtraction and multiplication wraps around
17127 using twos-complement representation. This flag enables some optimizations
17128 and disables others. This option is enabled by default for the Java
17129 front-end, as required by the Java language specification.
17132 @opindex fexceptions
17133 Enable exception handling. Generates extra code needed to propagate
17134 exceptions. For some targets, this implies GCC will generate frame
17135 unwind information for all functions, which can produce significant data
17136 size overhead, although it does not affect execution. If you do not
17137 specify this option, GCC will enable it by default for languages like
17138 C++ which normally require exception handling, and disable it for
17139 languages like C that do not normally require it. However, you may need
17140 to enable this option when compiling C code that needs to interoperate
17141 properly with exception handlers written in C++. You may also wish to
17142 disable this option if you are compiling older C++ programs that don't
17143 use exception handling.
17145 @item -fnon-call-exceptions
17146 @opindex fnon-call-exceptions
17147 Generate code that allows trapping instructions to throw exceptions.
17148 Note that this requires platform-specific runtime support that does
17149 not exist everywhere. Moreover, it only allows @emph{trapping}
17150 instructions to throw exceptions, i.e.@: memory references or floating
17151 point instructions. It does not allow exceptions to be thrown from
17152 arbitrary signal handlers such as @code{SIGALRM}.
17154 @item -funwind-tables
17155 @opindex funwind-tables
17156 Similar to @option{-fexceptions}, except that it will just generate any needed
17157 static data, but will not affect the generated code in any other way.
17158 You will normally not enable this option; instead, a language processor
17159 that needs this handling would enable it on your behalf.
17161 @item -fasynchronous-unwind-tables
17162 @opindex fasynchronous-unwind-tables
17163 Generate unwind table in dwarf2 format, if supported by target machine. The
17164 table is exact at each instruction boundary, so it can be used for stack
17165 unwinding from asynchronous events (such as debugger or garbage collector).
17167 @item -fpcc-struct-return
17168 @opindex fpcc-struct-return
17169 Return ``short'' @code{struct} and @code{union} values in memory like
17170 longer ones, rather than in registers. This convention is less
17171 efficient, but it has the advantage of allowing intercallability between
17172 GCC-compiled files and files compiled with other compilers, particularly
17173 the Portable C Compiler (pcc).
17175 The precise convention for returning structures in memory depends
17176 on the target configuration macros.
17178 Short structures and unions are those whose size and alignment match
17179 that of some integer type.
17181 @strong{Warning:} code compiled with the @option{-fpcc-struct-return}
17182 switch is not binary compatible with code compiled with the
17183 @option{-freg-struct-return} switch.
17184 Use it to conform to a non-default application binary interface.
17186 @item -freg-struct-return
17187 @opindex freg-struct-return
17188 Return @code{struct} and @code{union} values in registers when possible.
17189 This is more efficient for small structures than
17190 @option{-fpcc-struct-return}.
17192 If you specify neither @option{-fpcc-struct-return} nor
17193 @option{-freg-struct-return}, GCC defaults to whichever convention is
17194 standard for the target. If there is no standard convention, GCC
17195 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
17196 the principal compiler. In those cases, we can choose the standard, and
17197 we chose the more efficient register return alternative.
17199 @strong{Warning:} code compiled with the @option{-freg-struct-return}
17200 switch is not binary compatible with code compiled with the
17201 @option{-fpcc-struct-return} switch.
17202 Use it to conform to a non-default application binary interface.
17204 @item -fshort-enums
17205 @opindex fshort-enums
17206 Allocate to an @code{enum} type only as many bytes as it needs for the
17207 declared range of possible values. Specifically, the @code{enum} type
17208 will be equivalent to the smallest integer type which has enough room.
17210 @strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
17211 code that is not binary compatible with code generated without that switch.
17212 Use it to conform to a non-default application binary interface.
17214 @item -fshort-double
17215 @opindex fshort-double
17216 Use the same size for @code{double} as for @code{float}.
17218 @strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
17219 code that is not binary compatible with code generated without that switch.
17220 Use it to conform to a non-default application binary interface.
17222 @item -fshort-wchar
17223 @opindex fshort-wchar
17224 Override the underlying type for @samp{wchar_t} to be @samp{short
17225 unsigned int} instead of the default for the target. This option is
17226 useful for building programs to run under WINE@.
17228 @strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
17229 code that is not binary compatible with code generated without that switch.
17230 Use it to conform to a non-default application binary interface.
17233 @opindex fno-common
17234 In C code, controls the placement of uninitialized global variables.
17235 Unix C compilers have traditionally permitted multiple definitions of
17236 such variables in different compilation units by placing the variables
17238 This is the behavior specified by @option{-fcommon}, and is the default
17239 for GCC on most targets.
17240 On the other hand, this behavior is not required by ISO C, and on some
17241 targets may carry a speed or code size penalty on variable references.
17242 The @option{-fno-common} option specifies that the compiler should place
17243 uninitialized global variables in the data section of the object file,
17244 rather than generating them as common blocks.
17245 This has the effect that if the same variable is declared
17246 (without @code{extern}) in two different compilations,
17247 you will get a multiple-definition error when you link them.
17248 In this case, you must compile with @option{-fcommon} instead.
17249 Compiling with @option{-fno-common} is useful on targets for which
17250 it provides better performance, or if you wish to verify that the
17251 program will work on other systems which always treat uninitialized
17252 variable declarations this way.
17256 Ignore the @samp{#ident} directive.
17258 @item -finhibit-size-directive
17259 @opindex finhibit-size-directive
17260 Don't output a @code{.size} assembler directive, or anything else that
17261 would cause trouble if the function is split in the middle, and the
17262 two halves are placed at locations far apart in memory. This option is
17263 used when compiling @file{crtstuff.c}; you should not need to use it
17266 @item -fverbose-asm
17267 @opindex fverbose-asm
17268 Put extra commentary information in the generated assembly code to
17269 make it more readable. This option is generally only of use to those
17270 who actually need to read the generated assembly code (perhaps while
17271 debugging the compiler itself).
17273 @option{-fno-verbose-asm}, the default, causes the
17274 extra information to be omitted and is useful when comparing two assembler
17277 @item -frecord-gcc-switches
17278 @opindex frecord-gcc-switches
17279 This switch causes the command line that was used to invoke the
17280 compiler to be recorded into the object file that is being created.
17281 This switch is only implemented on some targets and the exact format
17282 of the recording is target and binary file format dependent, but it
17283 usually takes the form of a section containing ASCII text. This
17284 switch is related to the @option{-fverbose-asm} switch, but that
17285 switch only records information in the assembler output file as
17286 comments, so it never reaches the object file.
17290 @cindex global offset table
17292 Generate position-independent code (PIC) suitable for use in a shared
17293 library, if supported for the target machine. Such code accesses all
17294 constant addresses through a global offset table (GOT)@. The dynamic
17295 loader resolves the GOT entries when the program starts (the dynamic
17296 loader is not part of GCC; it is part of the operating system). If
17297 the GOT size for the linked executable exceeds a machine-specific
17298 maximum size, you get an error message from the linker indicating that
17299 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
17300 instead. (These maximums are 8k on the SPARC and 32k
17301 on the m68k and RS/6000. The 386 has no such limit.)
17303 Position-independent code requires special support, and therefore works
17304 only on certain machines. For the 386, GCC supports PIC for System V
17305 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
17306 position-independent.
17308 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
17313 If supported for the target machine, emit position-independent code,
17314 suitable for dynamic linking and avoiding any limit on the size of the
17315 global offset table. This option makes a difference on the m68k,
17316 PowerPC and SPARC@.
17318 Position-independent code requires special support, and therefore works
17319 only on certain machines.
17321 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
17328 These options are similar to @option{-fpic} and @option{-fPIC}, but
17329 generated position independent code can be only linked into executables.
17330 Usually these options are used when @option{-pie} GCC option will be
17331 used during linking.
17333 @option{-fpie} and @option{-fPIE} both define the macros
17334 @code{__pie__} and @code{__PIE__}. The macros have the value 1
17335 for @option{-fpie} and 2 for @option{-fPIE}.
17337 @item -fno-jump-tables
17338 @opindex fno-jump-tables
17339 Do not use jump tables for switch statements even where it would be
17340 more efficient than other code generation strategies. This option is
17341 of use in conjunction with @option{-fpic} or @option{-fPIC} for
17342 building code which forms part of a dynamic linker and cannot
17343 reference the address of a jump table. On some targets, jump tables
17344 do not require a GOT and this option is not needed.
17346 @item -ffixed-@var{reg}
17348 Treat the register named @var{reg} as a fixed register; generated code
17349 should never refer to it (except perhaps as a stack pointer, frame
17350 pointer or in some other fixed role).
17352 @var{reg} must be the name of a register. The register names accepted
17353 are machine-specific and are defined in the @code{REGISTER_NAMES}
17354 macro in the machine description macro file.
17356 This flag does not have a negative form, because it specifies a
17359 @item -fcall-used-@var{reg}
17360 @opindex fcall-used
17361 Treat the register named @var{reg} as an allocable register that is
17362 clobbered by function calls. It may be allocated for temporaries or
17363 variables that do not live across a call. Functions compiled this way
17364 will not save and restore the register @var{reg}.
17366 It is an error to used this flag with the frame pointer or stack pointer.
17367 Use of this flag for other registers that have fixed pervasive roles in
17368 the machine's execution model will produce disastrous results.
17370 This flag does not have a negative form, because it specifies a
17373 @item -fcall-saved-@var{reg}
17374 @opindex fcall-saved
17375 Treat the register named @var{reg} as an allocable register saved by
17376 functions. It may be allocated even for temporaries or variables that
17377 live across a call. Functions compiled this way will save and restore
17378 the register @var{reg} if they use it.
17380 It is an error to used this flag with the frame pointer or stack pointer.
17381 Use of this flag for other registers that have fixed pervasive roles in
17382 the machine's execution model will produce disastrous results.
17384 A different sort of disaster will result from the use of this flag for
17385 a register in which function values may be returned.
17387 This flag does not have a negative form, because it specifies a
17390 @item -fpack-struct[=@var{n}]
17391 @opindex fpack-struct
17392 Without a value specified, pack all structure members together without
17393 holes. When a value is specified (which must be a small power of two), pack
17394 structure members according to this value, representing the maximum
17395 alignment (that is, objects with default alignment requirements larger than
17396 this will be output potentially unaligned at the next fitting location.
17398 @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
17399 code that is not binary compatible with code generated without that switch.
17400 Additionally, it makes the code suboptimal.
17401 Use it to conform to a non-default application binary interface.
17403 @item -finstrument-functions
17404 @opindex finstrument-functions
17405 Generate instrumentation calls for entry and exit to functions. Just
17406 after function entry and just before function exit, the following
17407 profiling functions will be called with the address of the current
17408 function and its call site. (On some platforms,
17409 @code{__builtin_return_address} does not work beyond the current
17410 function, so the call site information may not be available to the
17411 profiling functions otherwise.)
17414 void __cyg_profile_func_enter (void *this_fn,
17416 void __cyg_profile_func_exit (void *this_fn,
17420 The first argument is the address of the start of the current function,
17421 which may be looked up exactly in the symbol table.
17423 This instrumentation is also done for functions expanded inline in other
17424 functions. The profiling calls will indicate where, conceptually, the
17425 inline function is entered and exited. This means that addressable
17426 versions of such functions must be available. If all your uses of a
17427 function are expanded inline, this may mean an additional expansion of
17428 code size. If you use @samp{extern inline} in your C code, an
17429 addressable version of such functions must be provided. (This is
17430 normally the case anyways, but if you get lucky and the optimizer always
17431 expands the functions inline, you might have gotten away without
17432 providing static copies.)
17434 A function may be given the attribute @code{no_instrument_function}, in
17435 which case this instrumentation will not be done. This can be used, for
17436 example, for the profiling functions listed above, high-priority
17437 interrupt routines, and any functions from which the profiling functions
17438 cannot safely be called (perhaps signal handlers, if the profiling
17439 routines generate output or allocate memory).
17441 @item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
17442 @opindex finstrument-functions-exclude-file-list
17444 Set the list of functions that are excluded from instrumentation (see
17445 the description of @code{-finstrument-functions}). If the file that
17446 contains a function definition matches with one of @var{file}, then
17447 that function is not instrumented. The match is done on substrings:
17448 if the @var{file} parameter is a substring of the file name, it is
17449 considered to be a match.
17452 @code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
17453 will exclude any inline function defined in files whose pathnames
17454 contain @code{/bits/stl} or @code{include/sys}.
17456 If, for some reason, you want to include letter @code{','} in one of
17457 @var{sym}, write @code{'\,'}. For example,
17458 @code{-finstrument-functions-exclude-file-list='\,\,tmp'}
17459 (note the single quote surrounding the option).
17461 @item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
17462 @opindex finstrument-functions-exclude-function-list
17464 This is similar to @code{-finstrument-functions-exclude-file-list},
17465 but this option sets the list of function names to be excluded from
17466 instrumentation. The function name to be matched is its user-visible
17467 name, such as @code{vector<int> blah(const vector<int> &)}, not the
17468 internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
17469 match is done on substrings: if the @var{sym} parameter is a substring
17470 of the function name, it is considered to be a match. For C99 and C++
17471 extended identifiers, the function name must be given in UTF-8, not
17472 using universal character names.
17474 @item -fstack-check
17475 @opindex fstack-check
17476 Generate code to verify that you do not go beyond the boundary of the
17477 stack. You should specify this flag if you are running in an
17478 environment with multiple threads, but only rarely need to specify it in
17479 a single-threaded environment since stack overflow is automatically
17480 detected on nearly all systems if there is only one stack.
17482 Note that this switch does not actually cause checking to be done; the
17483 operating system or the language runtime must do that. The switch causes
17484 generation of code to ensure that they see the stack being extended.
17486 You can additionally specify a string parameter: @code{no} means no
17487 checking, @code{generic} means force the use of old-style checking,
17488 @code{specific} means use the best checking method and is equivalent
17489 to bare @option{-fstack-check}.
17491 Old-style checking is a generic mechanism that requires no specific
17492 target support in the compiler but comes with the following drawbacks:
17496 Modified allocation strategy for large objects: they will always be
17497 allocated dynamically if their size exceeds a fixed threshold.
17500 Fixed limit on the size of the static frame of functions: when it is
17501 topped by a particular function, stack checking is not reliable and
17502 a warning is issued by the compiler.
17505 Inefficiency: because of both the modified allocation strategy and the
17506 generic implementation, the performances of the code are hampered.
17509 Note that old-style stack checking is also the fallback method for
17510 @code{specific} if no target support has been added in the compiler.
17512 @item -fstack-limit-register=@var{reg}
17513 @itemx -fstack-limit-symbol=@var{sym}
17514 @itemx -fno-stack-limit
17515 @opindex fstack-limit-register
17516 @opindex fstack-limit-symbol
17517 @opindex fno-stack-limit
17518 Generate code to ensure that the stack does not grow beyond a certain value,
17519 either the value of a register or the address of a symbol. If the stack
17520 would grow beyond the value, a signal is raised. For most targets,
17521 the signal is raised before the stack overruns the boundary, so
17522 it is possible to catch the signal without taking special precautions.
17524 For instance, if the stack starts at absolute address @samp{0x80000000}
17525 and grows downwards, you can use the flags
17526 @option{-fstack-limit-symbol=__stack_limit} and
17527 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
17528 of 128KB@. Note that this may only work with the GNU linker.
17530 @item -fleading-underscore
17531 @opindex fleading-underscore
17532 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
17533 change the way C symbols are represented in the object file. One use
17534 is to help link with legacy assembly code.
17536 @strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
17537 generate code that is not binary compatible with code generated without that
17538 switch. Use it to conform to a non-default application binary interface.
17539 Not all targets provide complete support for this switch.
17541 @item -ftls-model=@var{model}
17542 @opindex ftls-model
17543 Alter the thread-local storage model to be used (@pxref{Thread-Local}).
17544 The @var{model} argument should be one of @code{global-dynamic},
17545 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
17547 The default without @option{-fpic} is @code{initial-exec}; with
17548 @option{-fpic} the default is @code{global-dynamic}.
17550 @item -fvisibility=@var{default|internal|hidden|protected}
17551 @opindex fvisibility
17552 Set the default ELF image symbol visibility to the specified option---all
17553 symbols will be marked with this unless overridden within the code.
17554 Using this feature can very substantially improve linking and
17555 load times of shared object libraries, produce more optimized
17556 code, provide near-perfect API export and prevent symbol clashes.
17557 It is @strong{strongly} recommended that you use this in any shared objects
17560 Despite the nomenclature, @code{default} always means public ie;
17561 available to be linked against from outside the shared object.
17562 @code{protected} and @code{internal} are pretty useless in real-world
17563 usage so the only other commonly used option will be @code{hidden}.
17564 The default if @option{-fvisibility} isn't specified is
17565 @code{default}, i.e., make every
17566 symbol public---this causes the same behavior as previous versions of
17569 A good explanation of the benefits offered by ensuring ELF
17570 symbols have the correct visibility is given by ``How To Write
17571 Shared Libraries'' by Ulrich Drepper (which can be found at
17572 @w{@uref{http://people.redhat.com/~drepper/}})---however a superior
17573 solution made possible by this option to marking things hidden when
17574 the default is public is to make the default hidden and mark things
17575 public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
17576 and @code{__attribute__ ((visibility("default")))} instead of
17577 @code{__declspec(dllexport)} you get almost identical semantics with
17578 identical syntax. This is a great boon to those working with
17579 cross-platform projects.
17581 For those adding visibility support to existing code, you may find
17582 @samp{#pragma GCC visibility} of use. This works by you enclosing
17583 the declarations you wish to set visibility for with (for example)
17584 @samp{#pragma GCC visibility push(hidden)} and
17585 @samp{#pragma GCC visibility pop}.
17586 Bear in mind that symbol visibility should be viewed @strong{as
17587 part of the API interface contract} and thus all new code should
17588 always specify visibility when it is not the default ie; declarations
17589 only for use within the local DSO should @strong{always} be marked explicitly
17590 as hidden as so to avoid PLT indirection overheads---making this
17591 abundantly clear also aids readability and self-documentation of the code.
17592 Note that due to ISO C++ specification requirements, operator new and
17593 operator delete must always be of default visibility.
17595 Be aware that headers from outside your project, in particular system
17596 headers and headers from any other library you use, may not be
17597 expecting to be compiled with visibility other than the default. You
17598 may need to explicitly say @samp{#pragma GCC visibility push(default)}
17599 before including any such headers.
17601 @samp{extern} declarations are not affected by @samp{-fvisibility}, so
17602 a lot of code can be recompiled with @samp{-fvisibility=hidden} with
17603 no modifications. However, this means that calls to @samp{extern}
17604 functions with no explicit visibility will use the PLT, so it is more
17605 effective to use @samp{__attribute ((visibility))} and/or
17606 @samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
17607 declarations should be treated as hidden.
17609 Note that @samp{-fvisibility} does affect C++ vague linkage
17610 entities. This means that, for instance, an exception class that will
17611 be thrown between DSOs must be explicitly marked with default
17612 visibility so that the @samp{type_info} nodes will be unified between
17615 An overview of these techniques, their benefits and how to use them
17616 is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
17622 @node Environment Variables
17623 @section Environment Variables Affecting GCC
17624 @cindex environment variables
17626 @c man begin ENVIRONMENT
17627 This section describes several environment variables that affect how GCC
17628 operates. Some of them work by specifying directories or prefixes to use
17629 when searching for various kinds of files. Some are used to specify other
17630 aspects of the compilation environment.
17632 Note that you can also specify places to search using options such as
17633 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
17634 take precedence over places specified using environment variables, which
17635 in turn take precedence over those specified by the configuration of GCC@.
17636 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
17637 GNU Compiler Collection (GCC) Internals}.
17642 @c @itemx LC_COLLATE
17644 @c @itemx LC_MONETARY
17645 @c @itemx LC_NUMERIC
17650 @c @findex LC_COLLATE
17651 @findex LC_MESSAGES
17652 @c @findex LC_MONETARY
17653 @c @findex LC_NUMERIC
17657 These environment variables control the way that GCC uses
17658 localization information that allow GCC to work with different
17659 national conventions. GCC inspects the locale categories
17660 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
17661 so. These locale categories can be set to any value supported by your
17662 installation. A typical value is @samp{en_GB.UTF-8} for English in the United
17663 Kingdom encoded in UTF-8.
17665 The @env{LC_CTYPE} environment variable specifies character
17666 classification. GCC uses it to determine the character boundaries in
17667 a string; this is needed for some multibyte encodings that contain quote
17668 and escape characters that would otherwise be interpreted as a string
17671 The @env{LC_MESSAGES} environment variable specifies the language to
17672 use in diagnostic messages.
17674 If the @env{LC_ALL} environment variable is set, it overrides the value
17675 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
17676 and @env{LC_MESSAGES} default to the value of the @env{LANG}
17677 environment variable. If none of these variables are set, GCC
17678 defaults to traditional C English behavior.
17682 If @env{TMPDIR} is set, it specifies the directory to use for temporary
17683 files. GCC uses temporary files to hold the output of one stage of
17684 compilation which is to be used as input to the next stage: for example,
17685 the output of the preprocessor, which is the input to the compiler
17688 @item GCC_EXEC_PREFIX
17689 @findex GCC_EXEC_PREFIX
17690 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
17691 names of the subprograms executed by the compiler. No slash is added
17692 when this prefix is combined with the name of a subprogram, but you can
17693 specify a prefix that ends with a slash if you wish.
17695 If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
17696 an appropriate prefix to use based on the pathname it was invoked with.
17698 If GCC cannot find the subprogram using the specified prefix, it
17699 tries looking in the usual places for the subprogram.
17701 The default value of @env{GCC_EXEC_PREFIX} is
17702 @file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to
17703 the installed compiler. In many cases @var{prefix} is the value
17704 of @code{prefix} when you ran the @file{configure} script.
17706 Other prefixes specified with @option{-B} take precedence over this prefix.
17708 This prefix is also used for finding files such as @file{crt0.o} that are
17711 In addition, the prefix is used in an unusual way in finding the
17712 directories to search for header files. For each of the standard
17713 directories whose name normally begins with @samp{/usr/local/lib/gcc}
17714 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
17715 replacing that beginning with the specified prefix to produce an
17716 alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
17717 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
17718 These alternate directories are searched first; the standard directories
17719 come next. If a standard directory begins with the configured
17720 @var{prefix} then the value of @var{prefix} is replaced by
17721 @env{GCC_EXEC_PREFIX} when looking for header files.
17723 @item COMPILER_PATH
17724 @findex COMPILER_PATH
17725 The value of @env{COMPILER_PATH} is a colon-separated list of
17726 directories, much like @env{PATH}. GCC tries the directories thus
17727 specified when searching for subprograms, if it can't find the
17728 subprograms using @env{GCC_EXEC_PREFIX}.
17731 @findex LIBRARY_PATH
17732 The value of @env{LIBRARY_PATH} is a colon-separated list of
17733 directories, much like @env{PATH}. When configured as a native compiler,
17734 GCC tries the directories thus specified when searching for special
17735 linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
17736 using GCC also uses these directories when searching for ordinary
17737 libraries for the @option{-l} option (but directories specified with
17738 @option{-L} come first).
17742 @cindex locale definition
17743 This variable is used to pass locale information to the compiler. One way in
17744 which this information is used is to determine the character set to be used
17745 when character literals, string literals and comments are parsed in C and C++.
17746 When the compiler is configured to allow multibyte characters,
17747 the following values for @env{LANG} are recognized:
17751 Recognize JIS characters.
17753 Recognize SJIS characters.
17755 Recognize EUCJP characters.
17758 If @env{LANG} is not defined, or if it has some other value, then the
17759 compiler will use mblen and mbtowc as defined by the default locale to
17760 recognize and translate multibyte characters.
17764 Some additional environments variables affect the behavior of the
17767 @include cppenv.texi
17771 @node Precompiled Headers
17772 @section Using Precompiled Headers
17773 @cindex precompiled headers
17774 @cindex speed of compilation
17776 Often large projects have many header files that are included in every
17777 source file. The time the compiler takes to process these header files
17778 over and over again can account for nearly all of the time required to
17779 build the project. To make builds faster, GCC allows users to
17780 `precompile' a header file; then, if builds can use the precompiled
17781 header file they will be much faster.
17783 To create a precompiled header file, simply compile it as you would any
17784 other file, if necessary using the @option{-x} option to make the driver
17785 treat it as a C or C++ header file. You will probably want to use a
17786 tool like @command{make} to keep the precompiled header up-to-date when
17787 the headers it contains change.
17789 A precompiled header file will be searched for when @code{#include} is
17790 seen in the compilation. As it searches for the included file
17791 (@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
17792 compiler looks for a precompiled header in each directory just before it
17793 looks for the include file in that directory. The name searched for is
17794 the name specified in the @code{#include} with @samp{.gch} appended. If
17795 the precompiled header file can't be used, it is ignored.
17797 For instance, if you have @code{#include "all.h"}, and you have
17798 @file{all.h.gch} in the same directory as @file{all.h}, then the
17799 precompiled header file will be used if possible, and the original
17800 header will be used otherwise.
17802 Alternatively, you might decide to put the precompiled header file in a
17803 directory and use @option{-I} to ensure that directory is searched
17804 before (or instead of) the directory containing the original header.
17805 Then, if you want to check that the precompiled header file is always
17806 used, you can put a file of the same name as the original header in this
17807 directory containing an @code{#error} command.
17809 This also works with @option{-include}. So yet another way to use
17810 precompiled headers, good for projects not designed with precompiled
17811 header files in mind, is to simply take most of the header files used by
17812 a project, include them from another header file, precompile that header
17813 file, and @option{-include} the precompiled header. If the header files
17814 have guards against multiple inclusion, they will be skipped because
17815 they've already been included (in the precompiled header).
17817 If you need to precompile the same header file for different
17818 languages, targets, or compiler options, you can instead make a
17819 @emph{directory} named like @file{all.h.gch}, and put each precompiled
17820 header in the directory, perhaps using @option{-o}. It doesn't matter
17821 what you call the files in the directory, every precompiled header in
17822 the directory will be considered. The first precompiled header
17823 encountered in the directory that is valid for this compilation will
17824 be used; they're searched in no particular order.
17826 There are many other possibilities, limited only by your imagination,
17827 good sense, and the constraints of your build system.
17829 A precompiled header file can be used only when these conditions apply:
17833 Only one precompiled header can be used in a particular compilation.
17836 A precompiled header can't be used once the first C token is seen. You
17837 can have preprocessor directives before a precompiled header; you can
17838 even include a precompiled header from inside another header, so long as
17839 there are no C tokens before the @code{#include}.
17842 The precompiled header file must be produced for the same language as
17843 the current compilation. You can't use a C precompiled header for a C++
17847 The precompiled header file must have been produced by the same compiler
17848 binary as the current compilation is using.
17851 Any macros defined before the precompiled header is included must
17852 either be defined in the same way as when the precompiled header was
17853 generated, or must not affect the precompiled header, which usually
17854 means that they don't appear in the precompiled header at all.
17856 The @option{-D} option is one way to define a macro before a
17857 precompiled header is included; using a @code{#define} can also do it.
17858 There are also some options that define macros implicitly, like
17859 @option{-O} and @option{-Wdeprecated}; the same rule applies to macros
17862 @item If debugging information is output when using the precompiled
17863 header, using @option{-g} or similar, the same kind of debugging information
17864 must have been output when building the precompiled header. However,
17865 a precompiled header built using @option{-g} can be used in a compilation
17866 when no debugging information is being output.
17868 @item The same @option{-m} options must generally be used when building
17869 and using the precompiled header. @xref{Submodel Options},
17870 for any cases where this rule is relaxed.
17872 @item Each of the following options must be the same when building and using
17873 the precompiled header:
17875 @gccoptlist{-fexceptions}
17878 Some other command-line options starting with @option{-f},
17879 @option{-p}, or @option{-O} must be defined in the same way as when
17880 the precompiled header was generated. At present, it's not clear
17881 which options are safe to change and which are not; the safest choice
17882 is to use exactly the same options when generating and using the
17883 precompiled header. The following are known to be safe:
17885 @gccoptlist{-fmessage-length= -fpreprocessed -fsched-interblock @gol
17886 -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous @gol
17887 -fsched-verbose=<number> -fschedule-insns -fvisibility= @gol
17892 For all of these except the last, the compiler will automatically
17893 ignore the precompiled header if the conditions aren't met. If you
17894 find an option combination that doesn't work and doesn't cause the
17895 precompiled header to be ignored, please consider filing a bug report,
17898 If you do use differing options when generating and using the
17899 precompiled header, the actual behavior will be a mixture of the
17900 behavior for the options. For instance, if you use @option{-g} to
17901 generate the precompiled header but not when using it, you may or may
17902 not get debugging information for routines in the precompiled header.